create-yss-spec 2.1.10 → 2.1.13

package/template/.hermes/skills/llm-wiki/scripts/lint-wikilinks.test.mjs

@@ -0,0 +1,212 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { sha256 } from "./inventory.mjs";
+import { lintWiki } from "./lint-wikilinks.mjs";
+
+const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const broken = path.join(skillRoot, "assets/fixtures/broken-wiki");
+
+test("broken fixture fails on dangling wikilink", async () => {
+  const result = await lintWiki(broken);
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((line) => line.includes("[[不存在的页]]")));
+});
+
+test("complete wiki passes wikilink, index, and source-section checks", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "llm-wiki-lint-"));
+  const wiki = path.join(root, "wiki");
+  await mkdir(wiki, { recursive: true });
+  await writeFile(
+    path.join(wiki, "index.md"),
+    "# index\n\n## 分类\n\n- [[Alpha]]\n",
+    "utf8",
+  );
+  await writeFile(
+    path.join(wiki, "Alpha.md"),
+    "# Alpha\n\nSee [[Alpha]].\n\n## 来源\n\n- live\n",
+    "utf8",
+  );
+  await writeFile(path.join(wiki, "CLAUDE.md"), "# schema\n", "utf8");
+  const result = await lintWiki(root);
+  assert.equal(result.ok, true, result.errors.join("\n"));
+  assert.equal(result.counts.articles, 1);
+});
+
+test("cross-path wikilink fails instead of being ignored", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "llm-wiki-cross-"));
+  const wiki = path.join(root, "wiki");
+  await mkdir(wiki, { recursive: true });
+  await writeFile(path.join(wiki, "index.md"), "# index\n\n## 分类\n\n- [[Alpha]]\n", "utf8");
+  await writeFile(
+    path.join(wiki, "Alpha.md"),
+    "# Alpha\n\nSee [[../other]]\n\n## 来源\n\n- live\n",
+    "utf8",
+  );
+  const result = await lintWiki(root);
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((line) => line.includes("CROSS-WIKI") && line.includes("[[../other]]")));
+});
+
+test("manifest sha256 mismatch is stale", async () => {
+  const repo = await mkdtemp(path.join(tmpdir(), "llm-wiki-hash-"));
+  const wikiRoot = path.join(repo, "wiki-root");
+  const wiki = path.join(wikiRoot, "wiki");
+  await mkdir(wiki, { recursive: true });
+  await mkdir(path.join(wikiRoot, "raw"), { recursive: true });
+  await mkdir(path.join(repo, "docs"), { recursive: true });
+  const liveRel = "docs/api.md";
+  await writeFile(path.join(repo, liveRel), "v2\n", "utf8");
+  await writeFile(path.join(wikiRoot, "raw", "api.md"), "v1\n", "utf8");
+  await writeFile(path.join(wiki, "index.md"), "# index\n\n## 分类\n\n- [[API]]\n", "utf8");
+  await writeFile(path.join(wiki, "API.md"), "# API\n\nSummary.\n\n## 来源\n\n- live\n", "utf8");
+  await writeFile(
+    path.join(wikiRoot, ".wiki-manifest.json"),
+    JSON.stringify({
+      schemaVersion: 1,
+      sources: [
+        {
+          id: "api.md",
+          kind: "document",
+          livePath: liveRel,
+          rawPath: "raw/api.md",
+          sha256: sha256(Buffer.from("v1\n")),
+        },
+      ],
+      articles: [{ id: "API", file: "wiki/API.md", sourceIds: ["api.md"] }],
+    }),
+    "utf8",
+  );
+  const result = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((line) => line.includes("STALE HASH") && line.includes("api.md")));
+});
+
+async function seedClosedWiki() {
+  const repo = await mkdtemp(path.join(tmpdir(), "llm-wiki-closed-"));
+  const wikiRoot = path.join(repo, "wiki-root");
+  const wiki = path.join(wikiRoot, "wiki");
+  await mkdir(wiki, { recursive: true });
+  await mkdir(path.join(wikiRoot, "raw"), { recursive: true });
+  await mkdir(path.join(repo, "docs"), { recursive: true });
+  const liveRel = "docs/api.md";
+  await writeFile(path.join(repo, liveRel), "v1\n", "utf8");
+  await writeFile(path.join(wikiRoot, "raw", "api.md"), "v1\n", "utf8");
+  await writeFile(path.join(wiki, "index.md"), "# index\n\n## 分类\n\n- [[Alpha]]\n", "utf8");
+  await writeFile(
+    path.join(wiki, "Alpha.md"),
+    "# Alpha\n\nSee [[Alpha]].\n\n## 来源\n\n- live\n",
+    "utf8",
+  );
+  const manifest = {
+    schemaVersion: 1,
+    profile: "documents",
+    sources: [
+      {
+        id: "api.md",
+        kind: "document",
+        livePath: liveRel,
+        rawPath: "raw/api.md",
+        sha256: sha256(Buffer.from("v1\n")),
+      },
+    ],
+    articles: [{ id: "Alpha", file: "wiki/Alpha.md", sourceIds: ["api.md"] }],
+  };
+  await writeFile(path.join(wikiRoot, ".wiki-manifest.json"), JSON.stringify(manifest), "utf8");
+  return { repo, wikiRoot, wiki, manifest };
+}
+
+test("closed manifest passes listing, id, sourceIds, profile, and rawPath checks", async () => {
+  const { repo, wikiRoot } = await seedClosedWiki();
+  const result = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(result.ok, true, result.errors.join("\n"));
+});
+
+test("open manifest fails unlisted article, id mismatch, unknown source, profile kind, and rawPath", async () => {
+  const repo = await mkdtemp(path.join(tmpdir(), "llm-wiki-open-"));
+  const wikiRoot = path.join(repo, "wiki-root");
+  const wiki = path.join(wikiRoot, "wiki");
+  await mkdir(wiki, { recursive: true });
+  await mkdir(path.join(repo, "docs"), { recursive: true });
+  await writeFile(path.join(repo, "docs", "api.md"), "v1\n", "utf8");
+  await writeFile(path.join(wiki, "index.md"), "# index\n\n## 分类\n\n- [[Alpha]]\n- [[Beta]]\n", "utf8");
+  await writeFile(path.join(wiki, "Alpha.md"), "# Alpha\n\nSee [[Beta]].\n\n## 来源\n\n- live\n", "utf8");
+  await writeFile(path.join(wiki, "Beta.md"), "# Beta\n\nSee [[Alpha]].\n\n## 来源\n\n- live\n", "utf8");
+  await writeFile(
+    path.join(wikiRoot, ".wiki-manifest.json"),
+    JSON.stringify({
+      schemaVersion: 1,
+      profile: "documents",
+      sources: [
+        {
+          id: "api.md",
+          kind: "code-surface",
+          livePath: "docs/api.md",
+          rawPath: "raw/should-not-exist.md",
+          sha256: sha256(Buffer.from("v1\n")),
+        },
+        {
+          id: "note",
+          kind: "document",
+          livePath: "docs/api.md",
+          rawPath: "",
+          sha256: sha256(Buffer.from("v1\n")),
+        },
+      ],
+      articles: [
+        {
+          id: "WrongId",
+          file: "wiki/Alpha.md",
+          sourceIds: ["api.md", "ghost"],
+        },
+      ],
+    }),
+    "utf8",
+  );
+  const result = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((line) => line.includes("UNLISTED ARTICLE") && line.includes("Beta.md")));
+  assert.ok(result.errors.some((line) => line.includes("MANIFEST ID MISMATCH") && line.includes("WrongId")));
+  assert.ok(result.errors.some((line) => line.includes("UNKNOWN SOURCE ID") && line.includes("ghost")));
+  assert.ok(result.errors.some((line) => line.includes("PROFILE KIND") && line.includes("code-surface")));
+  assert.ok(result.errors.some((line) => line.includes("RAW PATH REQUIRED") && line.includes("note")));
+  assert.ok(result.errors.some((line) => line.includes("RAW PATH FORBIDDEN") && line.includes("api.md")));
+});
+
+test("derived source requires a known extract.kind", async () => {
+  const { repo, wikiRoot, manifest } = await seedClosedWiki();
+  manifest.sources.push({
+    id: "lock",
+    kind: "derived",
+    livePath: "docs/api.md",
+    rawPath: "raw/api.md",
+    sha256: sha256(Buffer.from("v1\n")),
+  });
+  await writeFile(path.join(wikiRoot, ".wiki-manifest.json"), JSON.stringify(manifest), "utf8");
+  const missing = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(missing.ok, false);
+  assert.ok(missing.errors.some((line) => line.includes("EXTRACT REQUIRED") && line.includes("lock")));
+
+  manifest.sources.at(-1).extract = { kind: "whole-file" };
+  await writeFile(path.join(wikiRoot, ".wiki-manifest.json"), JSON.stringify(manifest), "utf8");
+  const unknown = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(unknown.ok, false);
+  assert.ok(unknown.errors.some((line) => line.includes("EXTRACT KIND") && line.includes("whole-file")));
+
+  manifest.sources.at(-1).extract = { kind: "skill-names" };
+  await writeFile(path.join(wikiRoot, ".wiki-manifest.json"), JSON.stringify(manifest), "utf8");
+  const ok = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(ok.ok, true, ok.errors.join("\n"));
+});
+
+test("document rawPath must exist on disk", async () => {
+  const { repo, wikiRoot, manifest } = await seedClosedWiki();
+  manifest.sources[0].rawPath = "raw/missing.md";
+  await writeFile(path.join(wikiRoot, ".wiki-manifest.json"), JSON.stringify(manifest), "utf8");
+  const result = await lintWiki(wikiRoot, { repoRoot: repo });
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((line) => line.includes("RAW MISSING") && line.includes("raw/missing.md")));
+});

package/template/.hermes/skills/to-spec/SKILL.md

@@ -16,7 +16,7 @@ If the issue tracker or triage label vocabulary is missing, tell the user to run
 
 Check with the user that these seams match their expectations.
 
-3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage.
+3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-human` triage label. Spec drafts need a human baseline approval before they are `approved`, and before implementation tickets may become `ready-for-agent`. Do not label the Spec itself `ready-for-agent`.
 
 <spec-template>
 

package/template/.hermes/skills/yss-antd-design/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: yss-antd-design
+description: Use when 原型设计或高保真构建需要查询 Ant Design v6 设计语言、组件 API/demo/token/semantic，或落盘 AntD CLI 证据。不用于前端代码落地（改用 yss-ui）、Vue 生产 API、生命周期批准、安装官方 antd skill，或替代 yss-prototype-stage。
+---
+
+# YSS Ant Design 事实
+
+只服务原型设计与高保真构建。把官方 `@ant-design/cli`、`design.md`、MCP 与 LLMs.txt 收成可追溯的事实引擎。阶段合同仍是 `yss-prototype-stage`。前端代码落地一律改用 `yss-ui`，不要继续调用本技能。
+
+## 何时使用
+
+- 已进入 `yss-prototype-stage` 的高保真产出前后，需要 Ant Design v6 组件 / token / demo / semantic / 上游 `design.md` 事实。
+- 需要写入 `prototype-evidence.yaml` 的 AntD 段。
+
+不要用本技能：前端实现、Vue / Ant Design Vue 生产代码、批准门禁、生成页面流、安装官方 `antd` skill，或运行 `antd setup`。进入实现切片后停用本技能，改走 `yss-ui`。
+
+## 步骤
+
+1. 检测 CLI：优先已安装的 `antd`，否则用 `npx -y @ant-design/cli`。记录实际 CLI 版本。不要在模板源执行 `npm install -g`。
+2. 读项目 `docs/design/design.md` 与 `docs/design/tokens/*`。
+3. 选定 `<target_antd_version>`（项目已选的 v6；未选则先查再记录，不得依赖空仓库自动检测）。此后每次知识查询都传同一版本。
+4. 设置 `ANTD_NO_AUTO_REPORT=1`。一律 `--format json`，对外说明用 `--lang zh`。
+5. 查询官方 `design.md`，再按选用组件跑 `info` / `demo` / `token` / `semantic`。命令矩阵见 `references/cli-matrix.md`。
+6. 把 JSON 路径写入证据清单。字段与 lint 适用范围见 `references/evidence.md`。
+7. 上游默认与项目 token 冲突时，以项目覆盖为准，并标记 `project_override_reviewed`。
+
+## 硬规则
+
+- 禁止凭记忆写 Ant Design v6 API。
+- 禁止 `antd setup`、`npx skills add ant-design/ant-design-cli`，以及把官方 `skills/antd` 拷进 `.agents/skills`。
+- 禁止把官方 `design.md` 的默认色、圆角、间距写回项目实现或覆盖项目 token。
+- 禁止在前端代码落地、垂直切片实现或 `yss-ui` 任务中调用本技能。
+- 禁止把 React props / demo / hook 当作 `yss-ui` 或 Ant Design Vue API。
+- MCP 与 `llms-full.txt` 不是门禁证据。边界见 `references/boundaries.md`。

package/template/.hermes/skills/yss-antd-design/references/boundaries.md

@@ -0,0 +1,30 @@
+# 边界与官方资料
+
+官方文档只提供 React `antd` 事实，不提供 YSS 阶段合同。入口对照：
+
+| 官方资料 | 本技能用法 |
+|---|---|
+| https://ant.design/docs/react/for-agents-cn | 了解 CLI / skill / MCP / LLMs 分层。不要把其中的 “安装 skill” prompt 写进 `AGENTS.md` |
+| https://ant.design/docs/react/cli-cn | 命令与参数的权威说明 |
+| https://ant.design/docs/react/design-md-cn | 上游 `design.md` 定位。项目覆盖是 `docs/design/design.md` |
+| https://ant.design/docs/react/mcp-cn | MCP 是 IDE 加速，8 个知识工具不含 `lint` |
+| https://ant.design/docs/react/llms-cn | CLI 不可用时的降级目录。不要默认注入 `llms-full.txt` |
+| https://ant.design/design.md | 与 `antd design.md` 同一份 v6 上游默认 |
+
+## 与其他技能
+
+- `yss-prototype-stage`：阶段顺序、评审、浏览器验证、用户确认。本技能只回写 AntD 事实段。
+- `yss-design-system`：项目风格与 token 规范。本技能查询上游事实，不得改项目 token。
+- `product-design:index`：Codex 视觉产出。本技能不替代它，也不使用 `antd-page-generator`。
+- `yss-ui`：前端代码落地的唯一 UI 入口。进入实现后不得再查本技能或 `@ant-design/cli` 的 React API。
+- 官方 `antd` skill：不安装、不锁定、不投影。
+
+## MCP 与 LLMs.txt
+
+开发者本机可以运行 `npx -y @ant-design/cli mcp --version <target_antd_version> --lang zh`，但：
+
+- 不把 `.cursor/mcp.json` 提交为模板默认。
+- 不把 MCP 调用记录当成 `evidence.antd-cli-validation`。
+- `antd-page-generator` 不是原型阶段入口。
+
+CLI 不可用时，可用 `https://ant.design/llms.txt` 定位单组件 `.md`，并在证据里写明降级原因。恢复 CLI 后补 JSON 落盘。

package/template/.hermes/skills/yss-antd-design/references/cli-matrix.md

@@ -0,0 +1,38 @@
+# CLI 命令矩阵
+
+运行时入口：已安装的 `antd`，或 `npx -y @ant-design/cli`。记录实际 CLI 版本。知识查询必须带 `--format json`、`--lang zh` 和同一 `<target_antd_version>`。
+
+官方命令说明：https://ant.design/docs/react/cli-cn
+
+## 允许（原型 / 设计事实）
+
+| 命令 | 用途 |
+|---|---|
+| `antd design.md --version <target_antd_version> --lang zh --format json` | 上游默认 Light 主题。只对 antd v6 发布 |
+| `antd list --version <target_antd_version> --format json` | 组件选型 |
+| `antd info <Component> --version <target_antd_version> --format json` | props / 类型 / 默认值 |
+| `antd demo <Component> [name] --version <target_antd_version> --format json` | 可运行 demo 源码（React/TSX） |
+| `antd token <Component> --version <target_antd_version> --format json` | 组件或全局 token |
+| `antd semantic <Component> --version <target_antd_version> --format json` | `classNames` / `styles` 结构 |
+| `antd doc <Component> --version <target_antd_version> --lang zh --format json` | 需要完整文档时 |
+| `antd changelog <v1> <v2> [Component] --format json` | 仅当版本差异影响当前决策 |
+
+`design.md` 对 v5 返回 `UNSUPPORTED_VERSION_FEATURE`。空仓库不传 `--version` 时的回退版本不要假设；必须写进证据。
+
+## 条件允许
+
+| 命令 | 条件 |
+|---|---|
+| `antd lint <tsx-or-src> --format json` | 产物是 React/TSX 源码。HTML 原型不得当作通过 |
+| `antd doctor` / `antd usage` / `antd migrate` | 仅已登记的 React + `antd` 实现仓 |
+| `antd env --format json` | 排障需要环境快照时 |
+
+## 默认禁止
+
+| 命令 | 原因 |
+|---|---|
+| `antd setup` | 会写入 `.agents/skills/antd` 和 `AGENTS.md`，绕过 `skills-lock.json` |
+| `npx skills add ant-design/ant-design-cli` | 同上，安装官方 skill |
+| `antd bug` / `antd bug-cli` | 与 YSS Ticket 无关。保持 `ANTD_NO_AUTO_REPORT=1` |
+| `antd upgrade` | 不得在模板源或未授权时改动全局 CLI |
+| `antd mcp` 作为证据采集 | MCP 调用默认不落盘，见 `boundaries.md` |

package/template/.hermes/skills/yss-antd-design/references/evidence.md

@@ -0,0 +1,26 @@
+# AntD 事实证据
+
+目标文件：`docs/.scratch/<feature>/verification/prototype-evidence.yaml`，字段以 `docs/design/templates/prototype-evidence-template.yaml` 为准。本文件只说明如何填 AntD 段。
+
+## 必填
+
+- `antd.cli_command`：实际调用的可执行文件，`antd` 或 `npx -y @ant-design/cli`。
+- `antd.cli_version`：本轮 `antd -V` 或等价输出，禁止写死模板默认值。
+- `antd.target_antd_version`：本轮全部知识查询使用的同一 v6 版本。
+- `antd.queries.design_md`：`antd design.md ... --format json` 的落盘路径。
+- `antd.queries.components[]`：每个选用组件的 `info_ref` / `demo_ref` / `token_ref` / `semantic_ref`。
+- `design_baseline.project_design_ref`：`docs/design/design.md`。
+- `design_baseline.project_override_reviewed`：上游默认与项目 token 已对照。
+
+JSON 输出存为相邻文件，证据清单只引用路径。不要把整份 `llms-full.txt` 或 MCP 对话贴进清单。
+
+## lint
+
+`antd lint` 只对可解析的 React/TSX 源码有规则命中。HTML 原型会出现空 issues（假绿）或 `skippedFiles` / `parse-error` / `partial: true`。
+
+| 产物 | `lint_applicable` | 做法 |
+|---|---|---|
+| `docs/.scratch/<feature>/design/prototypes/index.html` | `not-applicable` | 写 `lint_reason: html-prototype`；`lint_ref` 可空；`lint_passed` 保持 `false`，不得改成 `true` |
+| React/TSX 原型源 | `true` | 对变更文件跑 `antd lint --format json`，保存输出；无 issue 才把 `lint_passed` 设为 `true` |
+
+浏览器验证仍由 `yss-prototype-stage` 采集，不在本技能宣布 `gate.prototype-verified` 通过。

package/template/.hermes/skills/yss-antd-design/scripts/validate-frontmatter.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function validateFrontmatter(text) {
+  const match = /^---\n([\s\S]*?)\n---/.exec(text);
+  if (!match) throw new Error("Invalid SKILL.md frontmatter block");
+  const fields = new Map();
+  for (const line of match[1].split("\n")) {
+    if (!line.trim()) continue;
+    const index = line.indexOf(":");
+    if (index < 0) throw new Error(`Invalid frontmatter line: ${line}`);
+    fields.set(line.slice(0, index).trim(), line.slice(index + 1).trim());
+  }
+  const keys = [...fields.keys()].sort();
+  if (keys.join(",") !== "description,name") throw new Error(`Expected keys ['description', 'name'], got ${JSON.stringify(keys)}`);
+  const name = fields.get("name");
+  const description = fields.get("description");
+  if (name !== "yss-antd-design") throw new Error("Invalid skill name: " + name);
+  if (!description || description.length > 1024) throw new Error("Description must be present and <= 1024 chars");
+  if (!/yss-ui|官方 antd skill|yss-prototype-stage/.test(description)) {
+    throw new Error("Description must exclude frontend landing via yss-ui, official antd skill, and stage-contract takeover");
+  }
+  return name;
+}
+
+export function validateSetupBan(text) {
+  if (!/禁止 `antd setup`/.test(text)) throw new Error("SKILL.md must forbid antd setup");
+  if (!/npx skills add ant-design\/ant-design-cli/.test(text)) throw new Error("SKILL.md must forbid official skill installer");
+}
+
+async function main() {
+  const skill = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "SKILL.md");
+  try {
+    const text = await readFile(skill, "utf8");
+    const name = validateFrontmatter(text);
+    validateSetupBan(text);
+    console.log(`${name} frontmatter ok`);
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main();

package/template/.hermes/skills/yss-antd-design/scripts/validate-frontmatter.test.mjs

@@ -0,0 +1,27 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { validateFrontmatter, validateSetupBan } from "./validate-frontmatter.mjs";
+
+const valid = `---
+name: yss-antd-design
+description: Use when 原型设计。不用于前端代码落地（改用 yss-ui）、安装官方 antd skill，或替代 yss-prototype-stage。
+---
+
+# body
+- 禁止 \`antd setup\`、\`npx skills add ant-design/ant-design-cli\`
+`;
+
+test("accepts the required skill frontmatter", () => {
+  assert.equal(validateFrontmatter(valid), "yss-antd-design");
+});
+
+test("rejects missing exclusion branches in description", () => {
+  assert.throws(
+    () => validateFrontmatter("---\nname: yss-antd-design\ndescription: Use when querying antd.\n---\n"),
+    /exclude frontend landing/
+  );
+});
+
+test("rejects a skill that does not forbid official setup", () => {
+  assert.throws(() => validateSetupBan("# no setup ban"), /forbid antd setup/);
+});

package/template/.hermes/skills/yss-api-integration/SKILL.md

@@ -5,6 +5,8 @@ description: Guide AI to correctly use Orval-generated API clients in Vue 3 micr
 
 # API 集成 Skill
 
+目录与锁文件身份是 `yss-api-integration`；Agent 发现名与 Router 闭包键是 `api-integration`。二者指向同一技能，注册表以 alias 对齐。
+
 ## 📋 目标
 
 帮助 AI 正确使用基于 **Orval** 生成的 API 客户端：

package/template/.hermes/skills/yss-application/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: yss-application
+description: Use when implementing YSS application use cases, transaction boundaries, cross-aggregate orchestration, idempotency, or application-level DTO conversion.
+---
+
+# yss-application
+
+Application 层用例编排 skill。负责协调 Domain 与 Gateway，定义事务边界和跨聚合流程，不承载核心领域规则。
+
+## 何时使用
+
+- 用户要实现 Application Service、用例编排或 `@Transactional` 边界。
+- 用户要补 App 层 MapStruct Convertor 或跨聚合协调逻辑。
+- 脚手架生成完成后进入业务实现，Router 按 `backend_impact` 加载本 skill。
+
+## 不适用
+
+- 只做领域建模时，优先 `yss-domain`。
+- 只做持久层时，优先 `yss-repository`。
+- 只做 Controller 时，优先 `yss-web-controller`。
+
+## 工作方式
+
+1. 先探测工程是新 DDD `application/domain/infrastructure/adapter` 还是 legacy `core/client/repository` profile。
+2. 确认 Use Case、Application 边界、事务边界已在批准合同中写明。
+3. 实现 AppService 时调用 Domain Service / Gateway，核心规则下沉 Domain。
+4. 涉及 POJO 样板加载 `lombok`；涉及 App 层转换加载 `mapstruct`。
+5. 详细包结构、注解、示例和 legacy 兼容说明见 `references/application-layer-guide.md`。
+
+## 产物范围
+
+- `application/.../service/*Service.java`（或 legacy `core/service`）
+- `application/.../service/impl/*ServiceImpl.java`
+- `application/.../service/convertor/*Convertor.java`（MapStruct）
+
+## 协同顺序
+
+- 领域建模：`yss-domain`
+- 持久层：`yss-repository`
+- Web 适配：`yss-web-controller`
+- DTO 契约：`yss-dto`
+
+## 阶段 7 合同
+
+- 只消费批准后的 `Slice Implementation Contract` 和当前 `work_unit`。
+- AppService 骨架可 `controlled-generation`；用例编排、事务、幂等、权限和失败行为必须 `behavior-tdd`。
+- 按 `yss-router/references/yss-skill-execution-result.md` 返回统一 `YSS Skill Execution Result`。
+- 发现新 API、权限、状态机或跨上下文影响时填入 `new_impacts` 并暂停。
+
+## 按需读取
+
+- 分层开发规范：`references/application-layer-guide.md`

package/template/.hermes/skills/yss-application/agents/openai.yaml

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS Application Layer"
+  short_description: "YSS Application 层用例编排、事务边界与跨聚合协调规范"
+  default_prompt: "Use $yss-application to implement the application layer for a YSS backend module."

package/template/.hermes/skills/yss-application/references/application-layer-guide.md

@@ -0,0 +1,132 @@
+本 Skill 约束 Application 层的用例边界。它是目标 DDD 架构规则，不等同于现有 YSS 组件仓库中所有 `core/service` 的历史实现；先探测工程布局并记录兼容 profile。
+
+## 1. 核心职责 (Core Responsibilities)
+
+- **业务用例编排 (Use Case Orchestration)**: 协调 Domain Service 和 Gateway 完成复杂的业务流程。
+- **服务接口实现 (Service Implementation)**: 实现 Application Service 接口，对外提供业务能力。
+- **DTO 转换 (DTO Conversion)**: 只在合同指定时负责 Domain/Application model 与 client/web DTO/VO 的转换；不得把 Repository PO 带入 Application。
+- **事务控制 (Transaction Management)**: 在应用层进行 `@Transactional` 事务管理。
+
+## 2. 代码结构 (Code Structure)
+
+```
+com.yss.{module}.core
+├── service                 # 应用服务接口
+│   ├── impl                # 应用服务实现
+│   └── convertor           # MapStruct 转换器 (App 层专用)
+├── component               # 业务组件 (Exporter, Handler)
+└── job                     # 任务执行逻辑 (Runner, Func)
+```
+
+## 3. 开发规范 (Development Guidelines)
+
+### 3.1 应用服务实现 (AppServiceImpl)
+
+- **位置**: 新 DDD 工程优先 `application/.../service/impl`；legacy profile 才使用 `core/service/impl`。
+- **注解**: `@Service`，通常配合 `@RequiredArgsConstructor` 进行构造器注入。
+- **事务**: 只在已确认的用例边界添加 `@Transactional(rollbackFor = Exception.class)`；读用例明确 `readOnly` 与总数策略。
+- **逻辑**: 主要负责调用 Domain Service 或 Gateway，**不应包含核心领域逻辑**（应下沉到 Domain 层）。
+
+### 3.2 对象转换 (Convertor)
+
+- **工具**: MapStruct。
+- **位置**: `com.yss.{module}.core.service.convertor`。
+- **职责**: 将 `Domain Object` (VO/Entity) 转换为 `Application VO` 或 `Client VO`。
+- **规范**: 定义 `INSTANCE` 常量，使用 `Mappers.getMapper(...)` 获取实例。
+
+### 3.3 异常处理
+
+- **业务异常**: 使用 `ExceptionFactory.bizException(...)` 或项目已批准的 `BizException` 错误码。
+- **已知系统异常**: 使用 `ExceptionFactory.sysException(...)` 并保留 cause；未知异常交由全局处理器兜底，不在 Application 吞并或改写。
+
+## 4. Legacy 参考形状（不可复制）
+
+以下 `QualityTemplate*` 代码只是说明 legacy `core/service` 形状的占位示例，不是当前参考源码中已验证存在的通用模块，也不定义新模块的包名、接口或返回模型。新 DDD profile 必须由批准合同生成中性 Application 接口，不能复制这些名称或 DTO/VO Gateway 泄漏。
+
+### 4.1 Application Service Implementation
+
+```java
+package com.yss.quality.core.service.impl;
+
+import com.yss.cloud.dto.result.PageResult;
+import com.yss.quality.client.dto.cmd.QualityTemplateAddCmd;
+import com.yss.quality.client.dto.query.QualityTemplatePage;
+import com.yss.quality.client.vo.QualityTemplateVO;
+import com.yss.quality.domain.template.gateway.QualityTemplateGateway;
+import com.yss.quality.domain.template.service.QualityTemplateService;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.List;
+
+/**
+ * 数据质量规则模板应用服务实现类
+ */
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class QualityTemplateServiceImpl implements QualityTemplateService {
+
+    private final QualityTemplateGateway qualityTemplateGateway;
+
+    @Override
+    public PageResult<QualityTemplateVO> pageQualityTemplate(QualityTemplatePage query) {
+        // 直接调用 Domain Gateway
+        return qualityTemplateGateway.pageQualityTemplate(query);
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public Long addQualityTemplate(QualityTemplateAddCmd cmd) {
+        // 可以在此进行简单的应用层校验或编排
+        log.info("Adding quality template");
+        return qualityTemplateGateway.addQualityTemplate(cmd);
+    }
+}
+```
+
+### 4.2 Convertor (MapStruct)
+
+```java
+package com.yss.quality.core.service.convertor;
+
+import com.yss.quality.client.vo.QualityTechTemplateVO;
+import com.yss.quality.client.vo.QualityTemplateVO;
+import com.yss.quality.params.base.PluginParams;
+import org.mapstruct.Mapper;
+import org.mapstruct.NullValueCheckStrategy;
+import org.mapstruct.NullValuePropertyMappingStrategy;
+import org.mapstruct.factory.Mappers;
+
+import java.util.List;
+
+@Mapper(
+    nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE,
+    nullValueCheckStrategy = NullValueCheckStrategy.ALWAYS
+)
+public interface QualityTechTemplateConvertor {
+    QualityTechTemplateConvertor INSTANCE = Mappers.getMapper(QualityTechTemplateConvertor.class);
+
+    // 将 Domain VO 和 PluginParams 组合转换为 TechTemplateVO
+    QualityTechTemplateVO useQualityTechTemplateVO(QualityTemplateVO qualityTemplateVO, List<PluginParams> pluginParams);
+}
+```
+
+## 5. 注意事项 (Notes)
+
+1.  **职责分离**: Application 层关注“做什么”（流程编排），Domain 层关注“怎么做”（业务规则）。
+2.  **依赖方向**: Application 层依赖 Domain 层，不应依赖 Adapter 层（Web/Job）。
+3.  **事务边界**: 一个用例一个边界；跨聚合写入、幂等键、事件发布时点必须写入合同并用 `behavior-tdd` 验证。
+4.  **上下文能力**: 当前用户、审计、普通技术日志、校验和异常是条件依赖，按 `yss-router` 影响闭包加载，不在 AppService 内手工解析 Header/JWT。
+
+## 6. 架构探测门禁
+
+先确认工程是新 DDD `application/domain/infrastructure/adapter`，还是 legacy `core/client/repository`。没有 `backend_repository`、Maven Wrapper 和已批准合同版本时输出 `blocked`；不得用示例包名推断真实接口。
+
+## 7. 阶段 7 合同
+
+- 明确当前 Use Case、Application 边界、事务边界、跨聚合协调和异常映射，只消费批准后的合同版本。
+- AppService 骨架可受控生成；用例编排、事务、幂等、权限和失败行为必须使用 `behavior-tdd`。
+- 返回统一 `YSS Skill Execution Result`，证据至少包含 Application 代码、测试、MapStruct/Lombok 条件和实际 `./mvnw ...` 结果。

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

@@ -67,7 +67,7 @@ node scripts/generate_scaffold.mjs \
 - Harness 内多项目布局必须使用 `apps/backend/<project>/`；`apps/backend/` 只能是生成器的父容器，`app/backend/`、`app/frontend/` 及其子路径一律拒绝。
 - 不要在 skill 里硬编码用户业务字段或真实连接信息。
 - 生成后要检查依赖关系是否仍符合分层约束。
-- 生成后必须继续使用 `yss-backend-scaffold-parent` 校验工程基线，再按垂直切片加载 `yss-domain`、`yss-repository`、`yss-web-controller` 等局部技能。
+- 生成后必须继续使用 `yss-backend-scaffold-parent` 校验工程基线，再按垂直切片加载 `yss-domain`、`yss-application`、`yss-repository`、`yss-web-controller` 等行为 skill；各 skill 的 `references/*-layer-guide.md` 承载分层开发规范。
 - 当前脚手架第一阶段仅支持经过验证的 `mysql`；未提供完整模板和验证的数据库类型不得伪装成已支持。
 - 生成后的后端工程必须使用项目根目录 `./mvnw ...` 执行构建、测试、运行和 CI 验证；不得在 README、实施记录、Ticket、Review 或 Release 中默认写裸 `mvn ...`。既有仓库确实无法使用 wrapper 时，必须记录受控例外。
 - 原型确认后，`scaffold_status=required` 才能进入本 skill；本 skill 的生成边界是工程结构、POM、配置、Wrapper 和机械模板，不是业务实现。

package/template/.hermes/skills/yss-ddd-scaffold-generator/references/ARCHITECTURE.md

@@ -188,7 +188,7 @@ Controller -> Service -> Gateway -> Repository -> Database
 ## 7. 参考资料
 
 - [YSS 后端开发规范](./yss-backend-scaffold-parent/SKILL.md)
-- [Domain 层开发指南](./yss-backend-scaffold-domain/SKILL.md)
-- [Application 层开发指南](./yss-backend-scaffold-application/SKILL.md)
-- [Infrastructure 层开发指南](./yss-backend-scaffold-infrastructure/SKILL.md)
-- [Web Adapter 开发指南](./yss-backend-scaffold-web/SKILL.md)
+- [Domain 层开发指南](./yss-backend-scaffold-domain/SKILL.md) → `yss-domain`
+- [Application 层开发指南](./yss-backend-scaffold-application/SKILL.md) → `yss-application`
+- [Infrastructure 层开发指南](./yss-backend-scaffold-infrastructure/SKILL.md) → `yss-repository`
+- [Web Adapter 开发指南](./yss-backend-scaffold-web/SKILL.md) → `yss-web-controller`