create-yss-spec 2.1.10 → 2.1.13

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

@@ -0,0 +1,78 @@
+---
+name: yss-web-controller
+description: Use when generating or refactoring YSS Web Adapter Controllers, request DTOs, response VOs, validation, result wrappers, or Web Convertors from frozen contracts and stable Application interfaces.
+---
+
+# yss-web-controller
+
+这是一个 Web 适配层生成型 skill。优先复用脚本 `scripts/generate_controller.mjs` 和模板，不手写重复 CRUD。
+
+## 何时使用
+
+- 用户要批量生成 Controller。
+- 用户要根据 metadata 或已有 Domain Gateway 生成 `AddCmd / UpdateCmd / PageQuery / VO / Controller / WebConvertor`。
+- 用户要求统一 Web Adapter 风格、返回值和接口路径。
+
+## 不适用
+
+- 用户只是要新增一个手写复杂接口，不一定要用脚本。
+- 用户还没有稳定的领域模型或 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. 运行 `node scripts/generate_controller.mjs`。
+5. 生成后检查路径、命名、返回值包装、Application Service 引用、`@Valid`、Lombok 注解和 MapStruct WebConvertor 是否对齐项目。
+6. 对复杂接口做少量手工修正，不在 skill 中承诺自动覆盖全部业务逻辑。
+
+## 推荐命令
+
+```bash
+node scripts/generate_controller.mjs \
+  --metadata-file /path/metadata.json \
+  --base-package com.yss.demo \
+  --module-name demo \
+  --domain-segment example \
+  --domain-project-dir /path/demo-domain \
+  --web-project-dir /path/demo-adapter/demo-web \
+  --application-service-package com.yss.demo.application.service \
+  --validation-namespace javax \
+  --force
+```
+
+## 输出预期
+
+- `client/dto/cmd/*AddCmd.java`
+- `client/dto/cmd/*UpdateCmd.java`
+- `client/dto/query/*PageQuery.java`
+- `client/vo/*VO.java`
+- `rest/*Controller.java`
+- `rest/convertor/*WebConvertor.java`
+
+## 约束
+
+- 生成代码默认依赖既有 Application Service。只有批准合同明确标记的纯查询 CQRS 工作单元才允许直接读 Gateway；写操作禁止绕过 Application。
+- 返回结构保持项目既有 `SingleResult`、`PageResult`、`MultiResult` 体系。
+- DTO / VO / CMD / Query 默认用 Lombok 处理 getter/setter、constructor、builder 和日志样板；不要在 Controller 内部类或非约定包临时定义主要 DTO / VO。
+- `WebConvertor` 默认使用 MapStruct；禁止在 Controller / Application 中大段手写字段赋值、使用 `BeanUtils.copyProperties` 或反射式通用拷贝，除非有受控例外和测试证据。
+- 先跑脚本，再按项目规范做少量手调。
+- `javax` / `jakarta` validation namespace 必须来自工程基线，不得按记忆选择。
+- 若用户只是要改单个 Controller，先看现有代码，不要盲覆盖整个目录。
+
+## 按需读取
+
+- 分层开发规范：`references/web-adapter-layer-guide.md`
+- 生成脚本：`scripts/generate_controller.mjs`
+- Controller 模板：`assets/templates/Controller.java.template`
+- Convertor 模板：`assets/templates/WebConvertor.java.template`
+- POJO 样板代码：`lombok`
+- 对象转换：`mapstruct`
+
+## 阶段 7 合同
+
+- 只消费已批准合同和冻结 OpenAPI/no-impact record；不得用 Controller 或半成品 backend 反向定义产品契约。
+- DTO/VO/WebConvertor 机械骨架可用 `controlled-generation`；权限、错误映射、校验语义和接口行为必须使用 `behavior-tdd`。
+- 写入必须位于合同 `allowed_write_paths`，并提供 Controller、DTO/VO、WebConvertor、契约/API 测试和实际验证结果。
+- 按统一 `YSS Skill Execution Result` 返回偏离与新增影响；出现新 API/schema、权限或响应包装变化时暂停并回到 Router/生命周期。

package/template/.cursor/skills/yss-web-controller/agents/openai.yaml

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS Web Controller"
+  short_description: "Web Controller、DTO、VO 与响应封装规范"
+  default_prompt: "Use $yss-web-controller to generate or refactor a YSS REST controller, request DTO, and response VO."

package/template/.cursor/skills/yss-web-controller/assets/templates/Controller.java.template

@@ -0,0 +1,73 @@
+package ${base_package}.rest;
+
+${application_service_import}
+${dto_imports}
+${domain_import}
+${web_convertor_import}
+import com.yss.cloud.dto.result.PageResult;
+import com.yss.cloud.dto.result.SingleResult;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.*;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
+import ${validation_namespace}.validation.Valid;
+
+/**
+ * ${domain_desc} 管理
+ *
+ * @author ${author}
+ */
+@RestController
+@RequestMapping("/api/${module_name}/${domain_url_path}")
+@RequiredArgsConstructor
+@Api(tags = "${domain_desc}管理")
+public class ${domain_class}Controller {
+
+    ${application_service_field}
+    private static final ${web_convertor_class} CONVERTOR = ${web_convertor_class}.INSTANCE;
+
+    /**
+     * 分页查询 ${domain_desc}
+     */
+    @PostMapping("/page")
+    @ApiOperation("分页查询")
+    public PageResult<${vo_class}> page(@Valid @RequestBody ${query_class} query) {
+        return CONVERTOR.toVOPage(${query_call});
+    }
+
+    /**
+     * 根据ID查询 ${domain_desc}
+     */
+    @GetMapping("/{id}")
+    @ApiOperation("详情查询")
+    public SingleResult<${vo_class}> detail(@PathVariable Long id) {
+        return SingleResult.of(CONVERTOR.toVO(${detail_call}));
+    }
+
+    /**
+     * 新增 ${domain_desc}
+     */
+    @PostMapping
+    @ApiOperation("新增")
+    public SingleResult<Long> add(@Valid @RequestBody ${add_cmd_class} cmd) {
+        return SingleResult.of(${add_call});
+    }
+
+    /**
+     * 更新 ${domain_desc}
+     */
+    @PutMapping
+    @ApiOperation("更新")
+    public SingleResult<Boolean> update(@Valid @RequestBody ${update_cmd_class} cmd) {
+        return SingleResult.of(${update_call});
+    }
+
+    /**
+     * 删除 ${domain_desc}
+     */
+    @DeleteMapping("/{id}")
+    @ApiOperation("删除")
+    public SingleResult<Boolean> delete(@PathVariable Long id) {
+        return SingleResult.of(${delete_call});
+    }
+}

package/template/.cursor/skills/yss-web-controller/assets/templates/WebConvertor.java.template

@@ -0,0 +1,23 @@
+package ${base_package}.rest.convertor;
+
+import com.yss.cloud.dto.result.PageResult;
+import ${base_package}.client.dto.cmd.${domain_class}AddCmd;
+import ${base_package}.client.dto.cmd.${domain_class}UpdateCmd;
+import ${base_package}.client.vo.${domain_class}VO;
+import ${base_package}.domain.${domain_pkg_name}.model.${domain_class};
+import org.mapstruct.Mapper;
+import org.mapstruct.factory.Mappers;
+
+@Mapper
+public interface ${web_convertor_class} {
+
+    ${web_convertor_class} INSTANCE = Mappers.getMapper(${web_convertor_class}.class);
+
+    ${domain_class} toDomain(${domain_class}AddCmd source);
+
+    ${domain_class} toDomain(${domain_class}UpdateCmd source);
+
+    ${domain_class}VO toVO(${domain_class} source);
+
+    PageResult<${domain_class}VO> toVOPage(PageResult<${domain_class}> source);
+}

package/template/.cursor/skills/yss-web-controller/assets/templates/domain/dto/cmd/AddCmd.java.template

@@ -0,0 +1,23 @@
+package ${base_package}.client.dto.cmd;
+
+import com.yss.cloud.dto.CommandDTO;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import ${validation_namespace}.validation.constraints.NotBlank;
+import ${validation_namespace}.validation.constraints.NotNull;
+import java.util.Date;
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+import java.time.LocalDate;
+
+/**
+ * ${domain_desc} 新增命令
+ *
+ * @author ${author}
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+public class ${domain_class}AddCmd extends CommandDTO {
+
+${field_declarations}
+}

package/template/.cursor/skills/yss-web-controller/assets/templates/domain/dto/cmd/UpdateCmd.java.template

@@ -0,0 +1,23 @@
+package ${base_package}.client.dto.cmd;
+
+import com.yss.cloud.dto.CommandDTO;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import ${validation_namespace}.validation.constraints.NotBlank;
+import ${validation_namespace}.validation.constraints.NotNull;
+import java.util.Date;
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+import java.time.LocalDate;
+
+/**
+ * ${domain_desc} 更新命令
+ *
+ * @author ${author}
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+public class ${domain_class}UpdateCmd extends CommandDTO {
+
+${field_declarations}
+}

package/template/.cursor/skills/yss-web-controller/assets/templates/domain/dto/query/PageQuery.java.template

@@ -0,0 +1,21 @@
+package ${base_package}.client.dto.query;
+
+import com.yss.cloud.dto.page.PageQuery;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import java.util.Date;
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+import java.time.LocalDate;
+
+/**
+ * ${domain_desc} 分页查询
+ *
+ * @author ${author}
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+public class ${domain_class}PageQuery extends PageQuery {
+
+${field_declarations}
+}

package/template/.cursor/skills/yss-web-controller/assets/templates/domain/vo/VO.java.template

@@ -0,0 +1,20 @@
+package ${base_package}.client.vo;
+
+import lombok.Data;
+import java.io.Serializable;
+import java.util.Date;
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+import java.time.LocalDate;
+
+/**
+ * ${domain_desc} VO
+ *
+ * @author ${author}
+ */
+@Data
+public class ${domain_class}VO implements Serializable {
+    private static final long serialVersionUID = 1L;
+
+${field_declarations}
+}

package/template/{.claude/skills/yss-backend-scaffold-web/SKILL.md → .cursor/skills/yss-web-controller/references/web-adapter-layer-guide.md}

@@ -1,10 +1,3 @@
----
-name: "yss-backend-scaffold-web"
-description: "YSS 管理服务的 Web Adapter 开发框架和技术指南。在实现 REST API 控制器、请求处理和响应格式化时需要用到。"
----
-
-# Web Adapter Layer Development Guide
-
 本技能为开发 YSS 服务的**Web 适配器层**（REST API）提供指导和框架。
 Web 适配器负责通过 HTTP 公开业务功能、处理输入验证和格式化响应。
 

package/template/.cursor/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/.cursor/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/.hermes/skills/ask-matt/SKILL.md

@@ -8,9 +8,15 @@ disable-model-invocation: true
 
 You don't remember every skill, so ask.
 
+## YSS default (read this first)
+
+In this template, **`yss-product-lifecycle` is the default orchestrator**. Native work-units own Spec, tickets, implementation authorization, and gates.
+
+This skill is a **Matt compatibility map**. Use `/grill-with-docs`, `/to-spec`, `/to-tickets`, and `/implement` only when the user **explicitly** names them. Do not treat the idea→ship list below as the YSS default. `/implement` does not grant git commit/push. Spec drafts from `/to-spec` stay `ready-for-human` until a human approves the Spec baseline.
+
 A **flow** is a path through the skills. Most paths run along one **main flow**, and two **on-ramps** merge onto it. Everything else is standalone, or a vocabulary layer that runs underneath.
 
-## The main flow: idea → ship
+## Matt compatibility flow: idea → ship
 
 The route most work travels. You have an idea and want it built.
 
@@ -23,7 +29,7 @@ The route most work travels. You have an idea and want it built.
    - **Yes** → **`/to-spec`** (turn the thread into a spec), then **`/to-tickets`** to split it into tracer-bullet tickets, each declaring its **blocking edges**. On a local tracker that's one file per ticket under `docs/.scratch/<feature>/issues/`, worked blockers-first by hand; on a real tracker the edges become native blocking links, so any ticket whose blockers are done can be grabbed — kick off **`/implement`** per ticket, **`/clear`ing context between each one**. Each ticket is self-contained, so the last one's context is disposable.
    - **No** → **`/implement`** right here, in the same context window.
 
-   Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`**, a two-axis review (Standards + Spec) of the diff, before committing. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point.
+   Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`** (Standards + Spec, plus UI fidelity when UI is in scope). Do not commit or push from `/implement`. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point.
 
 ### Context hygiene
 

package/template/.hermes/skills/code-review/SKILL.md

@@ -3,12 +3,13 @@ name: code-review
 description: Use when the user wants to review a branch, PR, committed candidate, uncommitted work-in-progress changes, or changes since a fixed point.
 ---
 
-Two-axis review of a pinned candidate against a fixed point:
+Review of a pinned candidate against a fixed point on two core axes, plus UI fidelity when UI is in scope:
 
 - **Standards** — does the code conform to this repo's documented coding standards?
 - **Spec** — does the code faithfully implement the originating issue / spec?
+- **UI fidelity** (only when the change has UI impact) — does the candidate match the confirmed prototype and `yss-design-system` / `yss-ui`? Type-check or claiming "already aligned" is not a pass. Invoke those skills' verification notes; do not collapse this axis into Standards or Spec.
 
-Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
+Standards and Spec run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings. When UI is in scope, add a separate UI fidelity pass after those two reports (do not merge it into either axis).
 
 If `docs/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
@@ -99,17 +100,18 @@ If the spec is missing, skip the Spec sub-agent and note this in the final repor
 
 ### 5. Aggregate
 
-Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see _Why two axes_).
+Present the reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. If UI is in scope, add `## UI fidelity` from the separate pass. Do **not** merge or rerank findings — the axes are deliberately separate (see _Why separate axes_).
 
 For Worktree mode, recapture the candidate digest after both reports return. If it differs from `candidate_digest`, mark both reports as reviewing a **stale candidate** and return `blocked`; the caller may start a new review against a new capture, but this invocation must not aggregate findings from different bytes. Recheck the same digest again at the completion/checkpoint boundary.
 
 State the reviewed `review_mode`, fixed point, candidate digest and coverage before the two reports. End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
 
-## Why two axes
+## Why separate axes
 
 A change can pass one axis and fail the other:
 
 - Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**
 - Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**
+- Code that implements the spec but diverges from the confirmed prototype or design system → **Spec pass, UI fidelity fail.**
 
 Reporting them separately stops one axis from masking the other.

package/template/.hermes/skills/high-fidelity-html-prototype/SKILL.md

@@ -24,24 +24,7 @@ If low-fidelity `prototype-review` is blocked or missing, stop and return to `ys
 
 ## Ant Design Official Agent Baseline
 
-Use the official Ant Design agent guidance as the fact baseline through `yss-prototype-stage`:
-
-- Read or reference `https://ant.design/docs/react/for-agents` when the task starts.
-- Use `@ant-design/cli` before choosing unfamiliar components, props, tokens, or migration-sensitive APIs.
-- Prefer direct CLI subcommands because `--help` may fail in some Node environments while subcommands still work.
-
-Record the installed CLI version and the target AntD version in `prototype-evidence.yaml`. Use `--format json`; pass the recorded target version to version-sensitive queries:
-
-```bash
-antd design.md --format json
-antd info Button --version <target_antd_version> --format json
-antd token Button --version <target_antd_version> --format json
-antd demo Select basic --version <target_antd_version> --format json
-antd semantic Button --version <target_antd_version> --format json
-antd lint <prototype-path> --format json
-```
-
-Use the project-selected version when one exists; otherwise record the CLI's actual default version before making version-sensitive decisions. Record every queried component in the evidence manifest.
+Ant Design v6 事实由 `yss-antd-design` 执行并回写 `prototype-evidence.yaml`。本兼容入口不并列调用官方 `antd` skill，也不在前端代码落地时使用；实现改走 `yss-ui`。
 
 ## Core Rules
 
@@ -102,5 +85,5 @@ High-fidelity HTML prototype
 - <yes/no; list blocking gaps>
 
 ### 下一步
-- <Spec calibration / return to high-fidelity prototype / return to product-design-prototype>
+- <Spec calibration / return to high-fidelity prototype / return to yss-prototype-stage>
 ```

package/template/.hermes/skills/implement/SKILL.md

@@ -12,4 +12,4 @@ Run typechecking regularly, single test files regularly, and the full test suite
 
 Once done, use /code-review to review the work.
 
-Commit your work to the current branch.
+Do not commit or push. Implementation authorization does not include git commit/push. Natural language such as "do it and commit" is not structured Git authorization. Stop after review unless a structured Git authorization is already present.

package/template/.hermes/skills/llm-wiki/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: llm-wiki
+description: >
+  Compile and maintain a Karpathy-pattern LLM wiki (raw + wiki + schema) with
+  init, incremental refresh, global rebuild, lint, and narrow ingest. Use when
+  the user wants a local knowledge wiki, incremental wiki refresh, wiki rebuild,
+  compiling a named research note into the wiki, `/llm-wiki`, or an answer from
+  an existing wiki.
+---
+
+# llm-wiki
+
+Compile a persistent wiki from live documents and code. The wiki is the IR; live sources are the truth. Read [schema](references/schema.md), then the matching mode file.
+
+One-off notes are out of scope. Use this skill to compile or lint a persistent wiki (`raw/` + `wiki/` + `.wiki-manifest.json`), or to answer from an existing wiki per [query.md](references/query.md).
+
+## Mode
+
+| User intent | Mode | Completion |
+|---|---|---|
+| 从零构建知识库 | `init` | 三层目录 + schema + index + log + 文章 + `.wiki-manifest.json`，lint 退出 0 |
+| 源变了，更新受影响页 | `refresh` | 只改漂移命中的文章；human-owned 不改；lint 0；log 有 REFRESH |
+| 全局按新源重编译 | `rebuild` | raw 对齐 live；稳定 ID 与 human-owned 保留；LLM 页全量重写；lint 0；log 有 REBUILD |
+| 健康检查 | `lint` | 结构脚本 exit 0 + 已跑 advise 并报告条数；对变更页做 live 源抽查 |
+| 把点名外源或已落盘 research 笔记编进 wiki | `ingest` | raw 登记 + manifest 源 + 四态候选经确认后写页；lint 0；log 有 `INGEST` |
+
+Ambiguous → ask. Existing wiki + "构建" → ask refresh vs rebuild, do not init over it.
+
+Query is not a mode. Follow [query.md](references/query.md). Query never writes and never ingests.
+
+## Layout
+
+```
+<wiki-root>/
+  raw/                  # immutable copies + labelled extracts
+  wiki/                 # articles + index.md + log.md + CLAUDE.md
+  .wiki-manifest.json   # compile graph (sources ↔ articles)
+```
+
+Scripts live in this skill's `scripts/` directory (the folder that contains this `SKILL.md`). Run them from the repo root so `--wiki` / `--repo` resolve correctly:
+
+```bash
+node <skill-root>/scripts/inventory.mjs hash --wiki <wiki-root>
+node <skill-root>/scripts/inventory.mjs status --wiki <wiki-root>
+node <skill-root>/scripts/lint-wikilinks.mjs <wiki-root>
+node <skill-root>/scripts/advise.mjs <wiki-root>
+node <skill-root>/scripts/extract.mjs skill-names --in <live-lock.json> --out <wiki-root>/<rawPath>
+```
+
+`status` is a stable alias of `drift`. `<skill-root>` is the canonical skill directory or a projection that points at it. Do not hard-code `.agents/skills/llm-wiki`.
+
+## Steps
+
+1. Detect: `wiki/index.md` + `CLAUDE.md` (or `AGENTS.md`) means a wiki exists.
+2. If the user is asking a repository question, load [query.md](references/query.md) and stop. Do not lint, ingest, or append `log.md`.
+3. Load the mode algorithm: [compile.md](references/compile.md) for init/refresh/rebuild, [ingest.md](references/ingest.md) for ingest. For init/rebuild corpus choice, load [discover.md](discover.md). For writing, load [writing.md](references/writing.md). For checks, load [lint.md](references/lint.md).
+4. **Fact order:** called code > table comments / config defaults > stale raw copies. After writing, re-read live sources for a sample of claims (`N = min(5, changed pages)`).
+5. Run structural lint and advise. Append `log.md`. Stop.
+
+`refresh` without a manifest: stop. Rebuild, or reconstruct the manifest from existing「来源」sections — do not guess `sourceIds`.

package/template/.hermes/skills/llm-wiki/assets/CLAUDE.md.template

@@ -0,0 +1,26 @@
+# CLAUDE.md — Wiki schema
+
+本文档是本 wiki 的 schema（结构契约）。正文语言遵循宿主项目的文档语言规则；英文专有名词、类名、枚举值、表名与 API 路径保持原样。
+
+## 三层结构
+
+- **`raw/`** — 不可变原始源。从 live 文档拷贝，或从 live 源提取且标明出处的派生摘要。只读，不靠改 raw 来「修正」事实。
+- **文章（`wiki/*.md`）** — LLM 生成的知识文章。文件名（不含 `.md`）即文章 ID，必须全局唯一。使用 `[[wikilink]]` 互引。
+- **`index.md`** — 内容目录。`##` 节标题定义分类；节下列出该分类下的 `[[wikilink]]`。
+
+## 文章写作约定
+
+- 首行为 `# H1`，随后紧跟首段摘要。
+- 正文使用 `[[目标文章名]]`；目标必须是本 wiki 内存在的文章文件名（不含 `.md`）。
+- 论断必须能追溯到 `raw/` 或 live 代码路径。文末使用 `## 来源`。
+- 分类归属由 `index.md` 决定。
+- 可选 frontmatter：`human-owned: true` 时 refresh / rebuild 不得重写正文。
+- 仅当多个来源冲突，或 live 与旧 raw 不一致时写可选 `## Status`（`Disputed` / `Outdated`）。单一 live 正确则不写。
+
+## 基础设施文件
+
+`index.md`、`log.md`、`CLAUDE.md`、`AGENTS.md`、`soul.md`、`concept-table.md` 为基础设施文件，不视为文章。
+
+## 操作日志
+
+`log.md` 只追加。格式：`## [YYYY-MM-DD] OPERATION | 描述`（CREATE / UPDATE / LINK / FIX / REFRESH / REBUILD / RETIRE / LINT / INGEST）。

package/template/.hermes/skills/llm-wiki/assets/fixtures/broken-wiki/wiki/CLAUDE.md

@@ -0,0 +1,3 @@
+# CLAUDE.md
+
+fixture schema

package/template/.hermes/skills/llm-wiki/assets/fixtures/broken-wiki/wiki/index.md

@@ -0,0 +1,5 @@
+# broken fixture
+
+## 分类
+
+- [[存在的页]]

package/template/.hermes/skills/llm-wiki/assets/fixtures/broken-wiki/wiki/log.md

@@ -0,0 +1 @@
+# 操作日志

package/template/.hermes/skills/llm-wiki/assets/fixtures/broken-wiki/wiki//345/255/230/345/234/250/347/232/204/351/241/265.md

@@ -0,0 +1,7 @@
+# 存在的页
+
+摘要。引用了 [[不存在的页]]。
+
+## 来源
+
+- fixture