create-yss-spec 2.1.5 → 2.1.7

package/template/.trae/skills/yss-source-index/scripts/refresh-yss-skill-index.test.mjs

@@ -0,0 +1,15 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { refresh } from "./refresh-yss-skill-index.mjs";
+
+test("writes Node-labelled generated indexes", async () => {
+  const root=await mkdtemp(path.join(tmpdir(),"yss-index-")); const source=path.join(root,"source"); const skills=path.join(root,"skills");
+  await mkdir(path.join(source,"yss-microservice-components/yss-component-cache-parent/src/main/java/demo"),{recursive:true}); await writeFile(path.join(source,"yss-microservice-components/yss-component-cache-parent/src/main/java/demo/CacheConfiguration.java"),"class CacheConfiguration {}");
+  for(const name of ["yss-cache","yss-ui"])await mkdir(path.join(skills,name),{recursive:true});
+  await refresh({skillsRoot:skills,source,now:"2026-01-01T00:00:00Z"});
+  assert.match(await readFile(path.join(skills,"yss-cache/references/source-index.md"),"utf8"),/refresh-yss-skill-index\.mjs/);
+  assert.match(await readFile(path.join(skills,"yss-ui/references/frontend-docs.md"),"utf8"),/components/);
+});

package/template/.trae/skills/yss-taskflow/references/source-index.md

@@ -1,11 +1,11 @@
 # yss-taskflow Source Index
 
-Generated: 2026-08-08T15:43:04+00:00
-Source commit: `a34644e2dfc4eb2bfa2b0a1c69dc6b61cc98539a`
+Generated: 2026-08-17T12:03:37.436Z
+Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
 Source worktree: `dirty`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
 
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.py`. Do not hand-edit generated sections.
+This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
 
 Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.
 

package/template/.trae/skills/yss-ui/references/frontend-docs.md

@@ -1,6 +1,6 @@
 # yss-ui Frontend Documentation
 
-Generated: 2026-06-29T16:11:14+00:00
+Generated: 2026-08-17T12:03:37.436Z
 
 Use these YSS UI documentation entry points as authoritative references when local repo examples are insufficient.
 

package/template/.trae/skills/yss-use-table-height/references/frontend-docs.md

@@ -1,6 +1,6 @@
 # yss-use-table-height Frontend Documentation
 
-Generated: 2026-06-29T16:11:14+00:00
+Generated: 2026-08-17T12:03:37.436Z
 
 Use these YSS UI documentation entry points as authoritative references when local repo examples are insufficient.
 

package/template/.trae/skills/yss-use-tree-height/references/frontend-docs.md

@@ -1,6 +1,6 @@
 # yss-use-tree-height Frontend Documentation
 
-Generated: 2026-06-29T16:11:14+00:00
+Generated: 2026-08-17T12:03:37.436Z
 
 Use these YSS UI documentation entry points as authoritative references when local repo examples are insufficient.
 

package/template/.trae/skills/yss-userinfo/references/source-index.md

@@ -1,11 +1,11 @@
 # yss-userinfo Source Index
 
-Generated: 2026-08-08T15:43:04+00:00
-Source commit: `a34644e2dfc4eb2bfa2b0a1c69dc6b61cc98539a`
+Generated: 2026-08-17T12:03:37.436Z
+Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
 Source worktree: `dirty`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
 
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.py`. Do not hand-edit generated sections.
+This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
 
 Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.
 

package/template/.trae/skills/yss-validation/references/source-index.md

@@ -1,17 +1,17 @@
 # yss-validation Source Index
 
-Generated: 2026-08-08T15:43:04+00:00
-Source commit: `a34644e2dfc4eb2bfa2b0a1c69dc6b61cc98539a`
+Generated: 2026-08-17T12:03:37.436Z
+Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
 Source worktree: `dirty`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
 
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.py`. Do not hand-edit generated sections.
+This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
 
 Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.
 
 ## Component Path Hints
 
-- `yss-microservice-components/yss-component-validation-engine-parent` (existed when indexed)
+- `yss-microservice-components/yss-component-validation-engine-parent` (missing when indexed)
 - `yss-microservice-components/yss-component-validation-jsr303` (existed when indexed)
 
 ## Documentation Files
@@ -20,30 +20,11 @@ Paths below are source path hints captured at refresh time. If they do not exist
 
 ## Maven Modules
 
-- `yss-microservice-components/yss-component-validation-engine-parent`
-- `yss-microservice-components/yss-component-validation-engine-parent/validation-el-parser`
 - `yss-microservice-components/yss-component-validation-jsr303`
 
 ## Key Java Entry Points
 
-- `yss-microservice-components/yss-component-validation-engine-parent/validation-el-parser/src/main/java/com/dogsong/liteflow/editor/bean/Properties.java`
-- `yss-microservice-components/yss-component-validation-engine-parent/validation-el-parser/src/main/java/com/dogsong/liteflow/editor/enums/ExpressParserEnum.java`
-- `yss-microservice-components/yss-component-validation-engine-parent/validation-el-parser/src/main/java/com/dogsong/liteflow/editor/parser/base/AbstractAndOrNotExpressParser.java`
-- `yss-microservice-components/yss-component-validation-engine-parent/validation-el-parser/src/main/java/com/dogsong/liteflow/editor/parser/base/AbstractExpressParser.java`
-- `yss-microservice-components/yss-component-validation-engine-parent/validation-el-parser/src/main/java/com/dogsong/liteflow/editor/parser/base/AbstractLoopExpressParser.java`
-- `yss-microservice-components/yss-component-validation-engine-parent/validation-el-parser/src/main/java/com/dogsong/liteflow/editor/parser/base/ExpressParser.java`
-- `yss-microservice-components/yss-component-validation-engine-parent/validation-el-parser/src/main/java/com/dogsong/liteflow/editor/parser/el/AndOrConditionParser.java`
-- `yss-microservice-components/yss-component-validation-engine-parent/validation-el-parser/src/main/java/com/dogsong/liteflow/editor/parser/el/CatchConditionParser.java`
-- `yss-microservice-components/yss-component-validation-engine-parent/validation-el-parser/src/main/java/com/dogsong/liteflow/editor/parser/el/ForConditionParser.java`
-- `yss-microservice-components/yss-component-validation-engine-parent/validation-el-parser/src/main/java/com/dogsong/liteflow/editor/parser/el/IfConditionParser.java`
-- `yss-microservice-components/yss-component-validation-engine-parent/validation-el-parser/src/main/java/com/dogsong/liteflow/editor/parser/el/NotConditionParser.java`
-- `yss-microservice-components/yss-component-validation-engine-parent/validation-el-parser/src/main/java/com/dogsong/liteflow/editor/parser/el/SwitchConditionParser.java`
-- `yss-microservice-components/yss-component-validation-engine-parent/validation-el-parser/src/main/java/com/dogsong/liteflow/editor/parser/el/ThenConditionParser.java`
-- `yss-microservice-components/yss-component-validation-engine-parent/validation-el-parser/src/main/java/com/dogsong/liteflow/editor/parser/el/WhenConditionParser.java`
-- `yss-microservice-components/yss-component-validation-engine-parent/validation-el-parser/src/main/java/com/dogsong/liteflow/editor/parser/el/WhileConditionParser.java`
-- `yss-microservice-components/yss-component-validation-engine-parent/validation-el-parser/src/main/java/com/dogsong/liteflow/editor/parser/factory/ExpressParserFactory.java`
-- `yss-microservice-components/yss-component-validation-engine-parent/validation-el-parser/src/main/java/com/dogsong/liteflow/editor/parser/generator/ExpressGenerator.java`
-- `yss-microservice-components/yss-component-validation-engine-parent/validation-el-parser/src/main/java/com/dogsong/liteflow/editor/parser/selector/ParserSelector.java`
+- No key Java entry points matched the configured name patterns.
 
 ## Recommended Next Reads
 

package/template/.trae/skills/yss-web-controller/SKILL.md

@@ -5,7 +5,7 @@ description: Use when generating or refactoring YSS Web Adapter Controllers, req
 
 # yss-web-controller
 
-这是一个 Web 适配层生成型 skill。优先复用脚本 `scripts/generate_controller.py` 和模板，不手写重复 CRUD。
+这是一个 Web 适配层生成型 skill。优先复用脚本 `scripts/generate_controller.mjs` 和模板，不手写重复 CRUD。
 
 ## 何时使用
 
@@ -16,21 +16,21 @@ description: Use when generating or refactoring YSS Web Adapter Controllers, req
 ## 不适用
 
 - 用户只是要新增一个手写复杂接口，不一定要用脚本。
-- 用户还没有稳定的领域模型或 metadata，先补 `yss-domain` 或 `yss-db2mybatis`。
+- 用户还没有稳定的领域模型或 metadata，先补 `yss-domain` 并准备完整的 metadata 输入。
 
 ## 优先流程
 
 1. 先确认冻结 OpenAPI/no-impact record、Application Service 接口、metadata、基础包、模块名、领域 segment、domain/web 落盘目录。
 2. 涉及 DTO / VO / CMD / Query POJO 样板代码时，加载并遵守 `lombok`。
 3. 涉及 Domain / Application Result 到 VO / DTO 或 CMD / Query 到输入模型的转换时，加载并遵守 `mapstruct`。
-4. 运行 `scripts/generate_controller.py`。
+4. 运行 `node scripts/generate_controller.mjs`。
 5. 生成后检查路径、命名、返回值包装、Application Service 引用、`@Valid`、Lombok 注解和 MapStruct WebConvertor 是否对齐项目。
 6. 对复杂接口做少量手工修正，不在 skill 中承诺自动覆盖全部业务逻辑。
 
 ## 推荐命令
 
 ```bash
-python3 scripts/generate_controller.py \
+node scripts/generate_controller.mjs \
   --metadata-file /path/metadata.json \
   --base-package com.yss.demo \
   --module-name demo \
@@ -63,7 +63,7 @@ python3 scripts/generate_controller.py \
 
 ## 按需读取
 
-- 生成脚本：`scripts/generate_controller.py`
+- 生成脚本：`scripts/generate_controller.mjs`
 - Controller 模板：`assets/templates/Controller.java.template`
 - Convertor 模板：`assets/templates/WebConvertor.java.template`
 - POJO 样板代码：`lombok`

package/template/.trae/skills/yss-web-controller/scripts/generate_controller.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const TYPE_MAPPING = { bigint: "Long", int: "Integer", integer: "Integer", smallint: "Integer", tinyint: "Integer", number: "Long", numeric: "BigDecimal", decimal: "BigDecimal", float: "Float", double: "Double", real: "Float", varchar: "String", varchar2: "String", nvarchar2: "String", char: "String", nchar: "String", text: "String", clob: "String", nclob: "String", date: "LocalDateTime", datetime: "LocalDateTime", timestamp: "LocalDateTime", "timestamp with time zone": "LocalDateTime", boolean: "Boolean", bool: "Boolean", bit: "Boolean", json: "String", jsonb: "String", uuid: "String" };
+const required = ["metadata-file", "base-package", "module-name", "domain-segment"];
+const valued = new Set([...required, "output-dir", "domain-project-dir", "web-project-dir", "domain-output-dir", "web-output-dir", "author", "application-service-package", "validation-namespace"]);
+
+function usage() {
+  return "Usage: node generate_controller.mjs --metadata-file FILE --base-package PACKAGE --module-name NAME --domain-segment SEGMENT [--output-dir DIR] [--domain-project-dir DIR] [--web-project-dir DIR] [--domain-output-dir DIR] [--web-output-dir DIR] [--author NAME] [--force] [--application-service-package PACKAGE] [--validation-namespace javax|jakarta]";
+}
+export function parseArgs(argv) {
+  const args = { "output-dir": "./output", author: "System", "validation-namespace": "javax", force: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--help" || token === "-h") return { help: true };
+    if (token === "--force") { args.force = true; continue; }
+    if (!token.startsWith("--") || !valued.has(token.slice(2))) throw new Error(`unrecognized argument: ${token}`);
+    const value = argv[++index];
+    if (!value || value.startsWith("--")) throw new Error(`argument ${token} requires a value`);
+    args[token.slice(2)] = value;
+  }
+  for (const key of required) if (!args[key]) throw new Error(`the following arguments are required: --${key}`);
+  if (!new Set(["javax", "jakarta"]).has(args["validation-namespace"])) throw new Error("--validation-namespace must be javax or jakarta");
+  return args;
+}
+const pascal = (value) => value.toLowerCase().split("_").map((part) => part ? part[0].toUpperCase() + part.slice(1) : "").join("");
+const lowerCamel = (value) => { const output = pascal(value); return output ? output[0].toLowerCase() + output.slice(1) : ""; };
+const kebab = (value) => value.toLowerCase().replaceAll("_", "-");
+const packagePath = (value) => value.replaceAll(".", path.sep);
+const ensureSubdir = (root, name) => path.basename(path.normalize(root)) === name ? root : path.join(root, name);
+const javaType = (sqlType = "") => TYPE_MAPPING[sqlType.toLowerCase().split("(")[0]] || "String";
+
+function fields(columns, { skipPk = false, command = false, skipAudit = true } = {}) {
+  const audit = new Set(["create_time", "update_time", "create_by", "update_by", "deleted", "version"]);
+  return columns.filter((column) => !(skipPk && column.primary) && !(skipAudit && audit.has(String(column.name).toLowerCase()))).map((column) => {
+    const type = javaType(column.sql_type);
+    const name = lowerCamel(column.name);
+    const comment = column.comment || "";
+    const documentation = comment ? `    /**\n     * ${comment}\n     */\n` : "";
+    const validation = command && !column.nullable ? `    @${type === "String" ? "NotBlank" : "NotNull"}(message = \"${comment || name}不能为空\")\n` : "";
+    return `${documentation}${validation}    private ${type} ${name};`;
+  }).join("\n\n");
+}
+function render(template, context) { return template.replace(/\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g, (_, braced, plain) => { const key = braced || plain; if (!(key in context)) throw new Error(`missing template field: ${key}`); return context[key]; }); }
+async function exists(target) { try { await access(target); return true; } catch { return false; } }
+
+export async function generate(args, logger = console) {
+  if (!await exists(args["metadata-file"])) throw new Error(`Metadata file not found: ${args["metadata-file"]}`);
+  let metadata;
+  try { metadata = JSON.parse(await readFile(args["metadata-file"], "utf8")); } catch (error) { throw new Error(`Error reading metadata file: ${error.message}`); }
+  const tables = metadata.tables || [];
+  if (!tables.length) { logger.warn("Warning: No tables found in metadata."); return []; }
+  const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+  const templatesDir = path.resolve(scriptDir, "../assets/templates");
+  const template = async (name) => { const target = path.join(templatesDir, name); if (!await exists(target)) throw new Error(`Template not found: ${target}`); return readFile(target, "utf8"); };
+  const templates = Object.fromEntries(await Promise.all(["Controller.java.template", "WebConvertor.java.template", "domain/vo/VO.java.template", "domain/dto/cmd/AddCmd.java.template", "domain/dto/cmd/UpdateCmd.java.template", "domain/dto/query/PageQuery.java.template"].map(async (name) => [name, await template(name)])));
+  const basePath = packagePath(args["base-package"]);
+  const domainBase = args["domain-output-dir"] || (args["domain-project-dir"] ? path.join(args["domain-project-dir"], "src", "main", "java", basePath) : path.join(args["output-dir"], basePath));
+  const webBase = args["web-output-dir"] || (args["web-project-dir"] ? path.join(args["web-project-dir"], "src", "main", "java", basePath) : path.join(args["output-dir"], basePath));
+  const domainRoot = ensureSubdir(domainBase, "client");
+  const webRoot = ensureSubdir(webBase, "rest");
+  const written = [];
+  const write = async (target, contents) => { await mkdir(path.dirname(target), { recursive: true }); if (!await exists(target) || args.force) { await writeFile(target, contents, "utf8"); logger.log(`Generated: ${target}`); written.push(target); } else logger.log(`Skipped (exists): ${target}`); };
+  for (const table of tables) {
+    const domainClass = pascal(table.table_name); const domainVar = lowerCamel(table.table_name); const domainDesc = String(table.table_comment || domainClass).trim().replaceAll("\n", " ");
+    const applicationPackage = args["application-service-package"] || `${args["base-package"]}.application.service`;
+    const context = { base_package: args["base-package"], module_name: args["module-name"], domain_class: domainClass, domain_var: domainVar, domain_desc: domainDesc, domain_url_path: kebab(table.table_name), domain_pkg_name: args["domain-segment"], author: args.author, dto_imports: [`import ${args["base-package"]}.client.dto.cmd.${domainClass}AddCmd;`, `import ${args["base-package"]}.client.dto.cmd.${domainClass}UpdateCmd;`, `import ${args["base-package"]}.client.dto.query.${domainClass}PageQuery;`, `import ${args["base-package"]}.client.vo.${domainClass}VO;`].join("\n"), application_service_import: `import ${applicationPackage}.${domainClass}Service;`, domain_import: `import ${args["base-package"]}.domain.${args["domain-segment"]}.model.${domainClass};`, web_convertor_import: `import ${args["base-package"]}.rest.convertor.${domainClass}WebConvertor;`, web_convertor_class: `${domainClass}WebConvertor`, application_service_field: `private final ${domainClass}Service ${domainVar}Service;`, query_call: `${domainVar}Service.page(query)`, detail_call: `${domainVar}Service.detail(id)`, add_call: `${domainVar}Service.add(cmd)`, update_call: `${domainVar}Service.update(cmd)`, delete_call: `${domainVar}Service.delete(id)`, vo_class: `${domainClass}VO`, add_cmd_class: `${domainClass}AddCmd`, update_cmd_class: `${domainClass}UpdateCmd`, query_class: `${domainClass}PageQuery`, validation_namespace: args["validation-namespace"] };
+    await write(path.join(webRoot, `${domainClass}Controller.java`), render(templates["Controller.java.template"], context));
+    await write(path.join(webRoot, "convertor", `${domainClass}WebConvertor.java`), render(templates["WebConvertor.java.template"], context));
+    for (const [templateName, target, declaration] of [["domain/vo/VO.java.template", path.join(domainRoot, "vo", `${domainClass}VO.java`), fields(table.columns || [], { skipAudit: false })], ["domain/dto/cmd/AddCmd.java.template", path.join(domainRoot, "dto/cmd", `${domainClass}AddCmd.java`), fields(table.columns || [], { skipPk: true, command: true })], ["domain/dto/cmd/UpdateCmd.java.template", path.join(domainRoot, "dto/cmd", `${domainClass}UpdateCmd.java`), fields(table.columns || [], { command: true })], ["domain/dto/query/PageQuery.java.template", path.join(domainRoot, "dto/query", `${domainClass}PageQuery.java`), fields(table.columns || [])]]) await write(target, render(templates[templateName], { ...context, field_declarations: declaration }));
+  }
+  return written;
+}
+async function main() { try { const args = parseArgs(process.argv.slice(2)); if (args.help) { console.log(usage()); return; } await generate(args); } catch (error) { console.error(`Error: ${error.message}`); process.exitCode = 1; } }
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main();

package/template/.trae/skills/yss-web-controller/scripts/generate_controller.test.mjs

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { generate, parseArgs } from "./generate_controller.mjs";
+
+test("generates application-service controller with requested validation profile", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "yss-controller-"));
+  const metadata = path.join(root, "metadata.json");
+  await writeFile(metadata, JSON.stringify({ tables: [{ table_name: "quality_rule", table_comment: "质量规则", columns: [{ name: "id", sql_type: "bigint", primary: true, nullable: false }, { name: "rule_name", sql_type: "varchar(64)", nullable: false }] }] }));
+  await generate(parseArgs(["--metadata-file", metadata, "--base-package", "com.yss.demo", "--module-name", "demo", "--domain-segment", "quality", "--output-dir", path.join(root, "out"), "--application-service-package", "com.yss.demo.application.service", "--validation-namespace", "jakarta"]), { log() {}, warn() {} });
+  const controller = await readFile(path.join(root, "out", "com", "yss", "demo", "rest", "QualityRuleController.java"), "utf8");
+  assert.match(controller, /import com\.yss\.demo\.application\.service\.QualityRuleService;/);
+  assert.match(controller, /import jakarta\.validation\.Valid;/);
+  assert.doesNotMatch(controller, /Gateway/);
+});
+
+test("rejects missing required CLI arguments", () => assert.throws(() => parseArgs(["--module-name", "demo"]), /required/));

package/template/CONTEXT.md

@@ -21,6 +21,8 @@
 | `ready-for-agent` | 表示垂直切片已通过必要门禁并具备直接实现条件的流程状态。 | 不得用于 Spec 初稿、原型、OpenAPI Draft 或其他未冻结资产。 |
 | OpenAPI Draft | review-only 的 OpenAPI 3.1 契约草案。 | Freeze 前不得作为前后端稳定实现契约。 |
 | OpenAPI Freeze | 已通过评审、可作为前后端实现和契约测试输入的 OpenAPI 3.1 契约。 | Freeze 后变更必须回到 API 影响分析和设计审查。 |
+| YSS 响应包装 | 对外 API 使用 `Result` 基础字段及 `SingleResult`、`MultiResult`、`PageResult` 表达单对象、非分页列表和分页查询结果的统一返回结构。 | Java 泛型记法是语义简称；公开 schema 必须落成具体 endpoint wire shape。 |
+| DTO wire shape | DTO 在 HTTP/JSON 边界实际暴露的字段、类型、可空性和方向性；与 Java 字段、getter 或内部协作字段区分。 | 以目标 mapper / contract evidence 为准，不从 getter、Lombok 或 `@JsonIgnore` 机械推断。 |
 | UI 影响 | 会改变用户可见页面、导航、交互流程、状态呈现或权限体验的功能影响。 | 纯后端、API、批处理或数据变更不自动构成 UI 影响。 |
 | 产品设计影响 | UI 变化触及主流程、导航、权限体验、异常 / 恢复状态、状态流转或 API 反推，需要页面流、状态矩阵和原型校准。 | 文案、token、颜色、间距和无行为变化的孤立视觉修复属于 UI 影响，但不自动构成产品设计影响。 |
 | 高保真 HTML 原型 | 低保真原型评审通过后，用于在浏览器中审查真实视觉密度、交互状态和页面流的产品设计资产。 | 不等同于生产前端实现，也不替代 OpenAPI、Spec 校准或垂直切片。 |
@@ -55,6 +57,10 @@
 | 跨仓库契约变更 | 需要两个或多个独立仓库协同实现、验证和按顺序发布的共享契约变化。 | 任一参与仓库未完成契约对齐和集成验证时，不得单独声称整体可发布。 |
 | 模板源仓库（`template-source`） | 承载 `yss-spec-project-template` 权威模板资产及其演进规则的仓库身份。 | 只管理可复用模板，不承载某个具体产品的研发生命周期资产。 |
 | 模板实例仓库（`project-instance`） | 由模板初始化后生成、承载某个具体产品研发生命周期资产的仓库身份。 | 不作为通用流程模板的权威来源。 |
+| 模板实例分发面 | 模板源中应随 CLI 快照进入 `project-instance` 的共享生命周期、模板、用户指南和验证资产集合。 | 不包含模板源审查、研究、发布路线或源仓库专属 ADR。 |
+| 模板源治理区 | 仅供 `template-source` 使用、保存审查证据、研究记录、跨仓契约、发布路线和源仓库治理决策的归档区域。 | 不随 CLI 分发；不等于产品实例的研发管理资产。 |
+| 目标平台单文件二进制 | 随模板快照分发、只适用于一个受支持 OS/架构组合的可执行文件。 | 不等同于跨平台通用文件，也不等同于运行时下载或 `cargo install`。 |
+| 原生模板实例运行时 | 在模板实例中执行原有治理和验证公共操作、且不依赖 Node.js 的目标平台原生运行时。 | 不等同于模板维护侧的构建工具，也不等同于仅创建模板的安装器。 |
 | 仓库身份清单 | 显式声明仓库身份和清单结构版本的机器可读资产。 | 不承载项目名称、团队规模、Tracker 或其他易变业务配置。 |
 
 只有在计划、分诊、调试或架构讨论中明确沉淀出稳定语言时，才新增术语。

package/template/README.md

@@ -106,10 +106,8 @@ scripts/verify-template
 | [docs/process/PDCA-SCRUM.md](./docs/process/PDCA-SCRUM.md) | PDCA × Scrum × AI |
 | [docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md](./docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md) | Matt Pocock Engineering Skills 集成与使用 |
 | [docs/process/lifecycle-registry.yaml](./docs/process/lifecycle-registry.yaml) | 生命周期结构事实源：主阶段、门禁、产物、工作单元、证据与稳定 ID |
-| [docs/process/harness-work-unit-map.md](./docs/process/harness-work-unit-map.md) | 由生命周期注册表派生的 Harness 工作单元地图 |
 | [docs/process/harness-process-tailoring.md](./docs/process/harness-process-tailoring.md) | 小改动 / 中等变更 / 新模块的流程裁剪指南 |
 | [docs/process/harness-executive-blueprint.md](./docs/process/harness-executive-blueprint.md) | 面向业务方和管理者的 Harness 一页式蓝图 |
-| [docs/process/harness-optimization-backlog.md](./docs/process/harness-optimization-backlog.md) | Harness 工程优化调整待办 |
 | [docs/process/implementation-repo-integration.md](./docs/process/implementation-repo-integration.md) | 外部前端 / 后端实现仓库接入与跨仓库切片绑定 |
 | [docs/agents/README.md](./docs/agents/README.md) | Agent 协作文档目录说明 |
 | [docs/agents/skills-maintenance.md](./docs/agents/skills-maintenance.md) | Agent skills 安装与维护 |

package/template/__yss_dotfile__.gitignore

@@ -36,21 +36,6 @@ htmlcov/
 Excalidraw
 .obsidian
 .ua
-docs/process/*
-!docs/process/
-!docs/process/templates/
-!docs/process/templates/stage-checkpoint-template.md
-!docs/process/lifecycle-artifact-map.md
-!docs/process/lifecycle-registry.yaml
-!docs/process/lifecycle-registry-baseline.json
-!docs/process/schemas/
-!docs/process/schemas/lifecycle-registry.schema.json
-!docs/process/harness-process-tailoring.md
-!docs/process/implementation-repo-integration.md
-!docs/process/subagent-collaboration.md
-!docs/process/PDCA-SCRUM.md
-!docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md
-!docs/process/harness-executive-blueprint.md
-!docs/process/harness-optimization-backlog.md
-!docs/process/harness-work-unit-map.md
+docs/process/presentations/
+docs/process/yss-product-lifecycle-team-guide.md
 docs/graphify-out

package/template/docs/agents/skills-maintenance.md

@@ -49,6 +49,8 @@
    scripts/verify-template
    ```
 
+   若模板维护引入或更新分发到实例的 Node 工具，先在 `.template-source/tooling/node/` 使用 `pnpm install --frozen-lockfile`，再运行 `pnpm build:vendor` 与 `pnpm check:vendor`；实例门禁不得安装依赖或重建 vendor。运行时、公开入口和跨仓回滚规则以 `.template-source/adr/0009-zero-install-node-tooling-runtime.md` 及对应契约为准。
+
 6. 需要重新加载技能的客户端在变更落地后重启或刷新项目。
 
 ## 单独检查

package/template/docs/api/templates/openapi-draft-review-checklist.md

@@ -20,6 +20,7 @@
 | AntD CLI 校验证据 | `docs/.scratch/<feature>/design/<feature>-prototype-confirmation.md` 或评审记录 | 有 UI 时必需；记录 design.md / info / demo / token / semantic 查询 |
 | 用户确认记录 | `docs/.scratch/<feature>/design/<feature>-prototype-confirmation.md` | 有 UI 时必需；未确认前不得进入 OpenAPI Draft 评审 |
 | YSS 工程基线 | `.codex/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-parent/SKILL.md` |  |
+| YSS DTO wire profile | `.agents/skills/yss-dto/references/openapi-wire-profile.yaml`；`scripts/verify-yss-dto-openapi-profile` |  |
 
 ## P0 追踪矩阵
 
@@ -41,6 +42,11 @@
 | 页面动作覆盖 | 每个按钮 / 抽屉 / 弹窗动作有 endpoint/non-goal、`actionKey` 和错误码；Spec 明确认认证 / 授权变化时同时映射该行为 |  |  |
 | 对象生命周期 | manage/maintain/configure/create/update/archive/retry/cancel/publish/export/create-draft 语义闭环 |  |  |
 | YSS 响应包装 | 单对象 `SingleResult<T>`；列表 `MultiResult<T>`；分页 `PageResult<T>` |  |  |
+| DTO wire shape | `com.yss.cloud.dto.result` 为新契约 canonical；`data` 落成 endpoint-specific schema，Java 泛型文字不得成为 OAS type / `$ref`；响应使用 `x-yss-response-wrapper`、`YssResultMeta` 和 `allOf` |  |  |
+| 公共响应字段 | `success:boolean`；`dataType:string|null`；`code:string|integer|null`；`message/tips` 显式 nullable；不得把全局 `code` 放宽为 arbitrary object |  |  |
+| 分页输入 | 只允许 `pageIndex/pageSize/orderBy/orderDirection/groupBy`；`orderDirection` 为 `ASC|DESC`；`orderBy/groupBy` 有 endpoint whitelist |  |  |
+| 分页负向字段 | `offset`、`needTotalCount`、`tempTotalCount` 不得成为客户端输入；`totalPages` 仅在目标 mapper / fixture 证据存在时纳入 |  |  |
+| Wire 证据 | mapper identity、代表性序列化 fixture、contract-test / 等价 HTTP 证据已记录；不能从 getter、Lombok 或 `@JsonIgnore` 直接推断 |  |  |
 | 显式认证 / 授权行为 | 仅当 Spec 明确改变相关行为时，`401` / `403`、资源过滤和错误语义有契约表示 |  | 未明确改变时不适用且无需额外记录 |
 | 错误结构 | 模型级、字段级、行级错误可定位；关键 422 有 examples |  |  |
 | 乐观锁 / 幂等 | 草稿写入有 draftVersion；关键命令有幂等键 |  |  |

package/template/docs/architecture/README.md

@@ -17,16 +17,7 @@
 
 对于数据模型、元数据管理、ER 设计、版本管理或血缘分析类产品，数据架构是核心产品能力，必须在 Repository / MyBatis / 持久化开发前完成；如果 OpenAPI schema 依赖元模型，也必须在 OpenAPI Freeze 前完成。
 
-推荐配套图：
-
-```text
-docs/.scratch/<feature>/architecture/diagrams/<feature>-business-capability.excalidraw
-docs/.scratch/<feature>/architecture/diagrams/<feature>-functional-modules.excalidraw
-docs/.scratch/<feature>/architecture/diagrams/<feature>-system-architecture.excalidraw
-docs/.scratch/<feature>/architecture/diagrams/<feature>-data-model.excalidraw
-```
-
-使用 `excalidraw-diagram-generator` 生成图时，图只作为审查辅助；发现的问题必须回写到 Spec、OpenAPI、ADR、系统 / 数据架构设计 或对应架构文档。
+图表只作为审查辅助；发现的问题必须回写到 Spec、OpenAPI、ADR、系统 / 数据架构设计或对应架构文档。
 
 推荐模板：
 
@@ -61,14 +52,6 @@ delegate_task(
 )
 ```
 
-### 图表生成者
-```python
-delegate_task(
-    goal="使用 excalidraw-diagram-generator 生成架构图",
-    context="根据阶段选择：业务能力图/功能模块图/系统架构图/ER 图/血缘图/数据流图"
-)
-```
-
 ---
 
 ## 六维度审查清单 (39项)

package/template/docs/design/README.md

@@ -16,7 +16,7 @@
 - 页面清单和信息架构。
 - 用户主路径和异常路径。
 - 低保真线框图，或 Figma / 即时设计 / Axure 等原型工具链接。
-- Excalidraw 流程图、泳道图、页面地图、状态流或架构辅助图。
+- 流程图、泳道图、页面地图、状态流或架构辅助图。
 - 表单、表格、弹窗、抽屉、步骤流等交互说明。
 - loading、empty、error、readonly、disabled、no-permission、conflict 等状态矩阵。
 - 页面字段、筛选条件、操作按钮和权限规则。
@@ -42,7 +42,6 @@
 - `antd`：Ant Design v6 组件、demo、token、semantic 和 design.md 查询工具；生成或修改高保真 HTML 原型前后必须留下 CLI 校验证据。
 - `prototype-review`：原型阶段评审门禁；未通过则不要进入 Spec 校准 / API 影响分析 / 契约草案。
 - 兼容入口：`product-design-prototype`、`wireframe-prototype`、`high-fidelity-html-prototype` 仅作为历史兼容或产物门禁名称保留；新的产品原型产出默认使用 `product-design:index`。
-- `excalidraw-diagram-generator`：根据已形成的 Discovery、Spec、OpenAPI Draft、Architecture 或 系统 / 数据架构设计 生成 `.excalidraw` 图；用于说明和审查，不替代文本规格。
 
 推荐目录：
 

package/template/docs/user-guide//345/244/226/351/203/250/345/221/275/344/273/244/350/241/214/345/267/245/345/205/267/345/256/236/350/267/265/346/214/207/345/215/227.md

@@ -114,4 +114,4 @@ YSS_SPEC_TEMPLATE_REF=<pinned-commit> npm test
 YSS_SPEC_TEMPLATE_REF=<pinned-commit> npm pack --dry-run
 ```
 
-发布顺序为：模板修复与验证 → CLI 绑定 commit 并完成跨仓库测试 → 独立审查 → 发布 CLI `2.1.4`。任一仓库未通过共同验证时，不声明整体可发布。
+发布顺序为：模板修复与验证 → CLI 绑定 commit 并完成跨仓库测试 → 独立审查 → 发布 CLI `2.1.6`。任一仓库未通过共同验证时，不声明整体可发布。

package/template/docs/user-guide//350/247/204/346/240/274/344/270/216/344/273/273/345/212/241/350/277/201/347/247/273/346/214/207/345/215/227.md

@@ -35,6 +35,10 @@ Local Markdown 项目不再使用上述旧目录作为主 tracker：新的完整
 6. 运行 `scripts/update-skill-lock` 更新完整树哈希。
 7. 运行 `scripts/verify-template`；修复全部结构、语义、压力场景和链接错误后再进入发布审查。
 
+## 模板工具运行时迁移
+
+从包含 Ruby 模板治理脚本的历史快照升级时，新的受管 Node 脚本直接随模板快照分发，项目实例不执行依赖安装。实例需要 Node `>=22 <27`；缺失或不兼容时先停止同步并恢复原 metadata。历史 `.rb` 文件由 CLI 的模板删除规则以 `remove-report` 告知，默认不静默删除。升级后运行三个固定门禁；失败时按 CLI 操作日志回滚。
+
 ## 外部初始化 CLI
 
 `create-yss-spec` 必须在初始化和升级时写入正确的 `repository_mode`，并执行等价的路径迁移与集成测试。模板仓库与 CLI 仓库未共同通过集成验证前，不得单独声明新版模板可发布。