create-yss-spec 2.2.10 → 3.0.1

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

@@ -1,60 +1,156 @@
 import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
 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 { fileURLToPath } from "node:url";
 import { generate, parseArgs } from "./generate_controller.mjs";
 
-test("generates application-service controller with requested validation profile", async () => {
+const scripts = path.dirname(fileURLToPath(import.meta.url));
+const dtoWireProfileFile = path.resolve(scripts, "../../yss-dto/references/openapi-wire-profile.yaml");
+const dtoWireProfileDigest = createHash("sha256").update(await readFile(dtoWireProfileFile)).digest("hex");
+
+const metadataValue = {
+  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 }
+    ]
+  }]
+};
+
+function webContract(root, overrides = {}) {
+  return {
+    schema_version: 2,
+    contract_id: "slice-quality-web-1",
+    contract_version: 1,
+    current_version: 1,
+    slice_id: "quality-rule-create",
+    status: "approved",
+    integration_mode: "existing-project",
+    implementation_project_root: root,
+    base_package: "com.yss.demo",
+    module_name: "demo",
+    domain_segment: "quality",
+    application_service_package: "com.yss.demo.application.service",
+    architecture_profile: "target-domain-model",
+    platform_profile: "spring-boot-3-jdk17",
+    validation_namespace: "jakarta",
+    dto_placement: "web",
+    dto_wire_profile_ref: dtoWireProfileFile,
+    dto_wire_profile_digest: dtoWireProfileDigest,
+    openapi_freeze_ref: "openapi://quality-rule@1",
+    allowed_write_paths: [root],
+    expected_evidence_files: ["evidence/web-generation.json"],
+    verification_commands: ["./mvnw test", "./mvnw package"],
+    fields: {
+      quality_rule: {
+        create: ["rule_name"],
+        update: ["id", "rule_name"],
+        query: ["rule_name"],
+        pagination: ["pageIndex", "pageSize"],
+        response: ["id", "rule_name"]
+      }
+    },
+    ...overrides
+  };
+}
+
+async function fixture(overrides = {}) {
   const root = await mkdtemp(path.join(tmpdir(), "yss-controller-"));
   const metadata = path.join(root, "metadata.json");
   const contract = path.join(root, "web-contract.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 writeFile(contract, JSON.stringify({ schema_version: 1, status: "approved", base_package: "com.yss.demo", module_name: "demo", domain_segment: "quality", architecture_profile: "target-domain-model", platform_profile: "spring-boot-3-jdk17", validation_namespace: "jakarta", dto_placement: "web", openapi_freeze_ref: "openapi://quality-rule@1", fields: { quality_rule: { create: ["rule_name"], update: ["id", "rule_name"], query: ["rule_name"], response: ["id", "rule_name"] } } }));
-  await generate(parseArgs(["--metadata-file", metadata, "--contract-file", contract, "--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");
-  const convertor = await readFile(path.join(root, "out", "com", "yss", "demo", "rest", "convertor", "QualityRuleWebConvertor.java"), "utf8");
-  const createRequest = await readFile(path.join(root, "out", "com", "yss", "demo", "rest", "dto", "request", "QualityRuleCreateRequest.java"), "utf8");
+  const output = path.join(root, "out");
+  await writeFile(metadata, JSON.stringify(metadataValue));
+  await writeFile(contract, JSON.stringify(webContract(root, overrides)));
+  const args = ["--metadata-file", metadata, "--contract-file", contract, "--dto-wire-profile-file", dtoWireProfileFile, "--base-package", "com.yss.demo", "--module-name", "demo", "--domain-segment", "quality", "--output-dir", output, "--application-service-package", "com.yss.demo.application.service", "--validation-namespace", overrides.validation_namespace ?? "jakarta"];
+  return { root, metadata, contract, output, args };
+}
+
+test("generates approved standalone Web code and exposes only approved pagination fields", async () => {
+  const data = await fixture();
+  await generate(parseArgs(data.args), { log() {}, warn() {} });
+  const rest = path.join(data.output, "com", "yss", "demo", "rest");
+  const controller = await readFile(path.join(rest, "QualityRuleController.java"), "utf8");
+  const convertor = await readFile(path.join(rest, "convertor", "QualityRuleWebConvertor.java"), "utf8");
+  const createRequest = await readFile(path.join(rest, "dto", "request", "QualityRuleCreateRequest.java"), "utf8");
+  const pageRequest = await readFile(path.join(rest, "dto", "request", "QualityRulePageRequest.java"), "utf8");
   assert.match(controller, /import com\.yss\.demo\.application\.service\.QualityRuleService;/);
+  assert.match(controller, /SingleResult\.of\(/);
   assert.match(controller, /import jakarta\.validation\.Valid;/);
-  assert.match(controller, /webConvertor\.toCreateCommand\(request\)/);
   assert.match(convertor, /@Mapper\(componentModel = "spring"\)/);
-  assert.match(convertor, /application\.command\.QualityRuleCreateCommand/);
-  assert.match(convertor, /application\.result\.QualityRuleResult/);
+  assert.match(convertor, /PageResult\.of\(\s*toResponses\(source\.getData\(\)\),\s*source\.getTotalCount\(\),\s*source\.getPageSize\(\),\s*source\.getPageIndex\(\)/s);
   assert.doesNotMatch(`${controller}\n${convertor}`, /Gateway|\.domain\.|Mappers\.getMapper|INSTANCE/);
   assert.match(createRequest, /private String ruleName;/);
   assert.doesNotMatch(createRequest, /private Long id;|@Data/);
+  assert.match(pageRequest, /private int pageIndex = 1;/);
+  assert.match(pageRequest, /private int pageSize = 10;/);
+  assert.doesNotMatch(pageRequest, /orderBy|orderDirection|groupBy|offset|needTotalCount|tempTotalCount|extends PageQuery/);
 });
 
-test("rejects missing required CLI arguments", () => assert.throws(() => parseArgs(["--module-name", "demo"]), /required/));
+test("rejects a yss-dto wire profile whose digest differs from the approved contract", async () => {
+  const data = await fixture({ dto_wire_profile_digest: "0".repeat(64) });
+  await assert.rejects(() => generate(parseArgs(data.args), { log() {}, warn() {} }), /yss-dto wire profile digest/);
+});
 
-test("requires an approved target-profile field contract and refuses force overwrite", async () => {
-  const root = await mkdtemp(path.join(tmpdir(), "yss-controller-contract-"));
-  const metadata = path.join(root, "metadata.json");
-  const contract = path.join(root, "web-contract.json");
-  await writeFile(metadata, JSON.stringify({ tables: [{ table_name: "quality_rule", columns: [{ name: "id", sql_type: "bigint", primary: true, nullable: false }] }] }));
-  await writeFile(contract, JSON.stringify({ schema_version: 1, status: "draft", base_package: "com.yss.demo", module_name: "demo", domain_segment: "quality", architecture_profile: "target-domain-model", platform_profile: "spring-boot-2.7-jdk8", validation_namespace: "javax", dto_placement: "web", openapi_freeze_ref: "openapi://quality-rule@1", fields: { quality_rule: { create: [], update: ["id"], query: [], response: ["id"] } } }));
-  const base = ["--metadata-file", metadata, "--contract-file", contract, "--base-package", "com.yss.demo", "--module-name", "demo", "--domain-segment", "quality", "--output-dir", path.join(root, "out")];
-  await assert.rejects(() => generate(parseArgs(base), { log() {}, warn() {} }), /approved/);
-  await writeFile(contract, JSON.stringify({ schema_version: 1, status: "approved", base_package: "com.yss.demo", module_name: "demo", domain_segment: "quality", architecture_profile: "target-domain-model", platform_profile: "spring-boot-2.7-jdk8", validation_namespace: "javax", dto_placement: "web", openapi_freeze_ref: "openapi://quality-rule@1", fields: { quality_rule: { create: [], update: ["id"], query: [], response: ["id"] } } }));
-  await writeFile(contract, JSON.stringify({ schema_version: 1, status: "approved", base_package: "com.yss.demo", module_name: "demo", domain_segment: "quality", architecture_profile: "target-domain-model", platform_profile: "spring-boot-3-jdk17", validation_namespace: "javax", dto_placement: "web", openapi_freeze_ref: "openapi://quality-rule@1", fields: { quality_rule: { create: [], update: ["id"], query: [], response: ["id"] } } }));
-  await assert.rejects(() => generate(parseArgs(base), { log() {}, warn() {} }), /platform_profile and validation_namespace/);
-  assert.throws(() => parseArgs([...base, "--force"]), /initialize-only/);
+test("rejects missing CLI arguments, schema v1, draft contracts, and inconsistent platform profiles", async () => {
+  assert.throws(() => parseArgs(["--module-name", "demo"]), /required/);
+  const v1 = await fixture({ schema_version: 1 });
+  await assert.rejects(() => generate(parseArgs(v1.args), { log() {}, warn() {} }), /schema_version=1.*unsupported/);
+  const draft = await fixture({ status: "draft" });
+  await assert.rejects(() => generate(parseArgs(draft.args), { log() {}, warn() {} }), /approved/);
+  const mismatch = await fixture({ platform_profile: "spring-boot-3-jdk17", validation_namespace: "javax" });
+  await assert.rejects(() => generate(parseArgs(mismatch.args), { log() {}, warn() {} }), /platform_profile and validation_namespace/);
+  assert.throws(() => parseArgs([...draft.args, "--force"]), /initialize-only/);
 });
 
-test("binds generation identity to the approved contract and fails before writing when any target exists", async () => {
-  const root = await mkdtemp(path.join(tmpdir(), "yss-controller-initialize-only-"));
-  const metadata = path.join(root, "metadata.json");
-  const contract = path.join(root, "web-contract.json");
-  const output = path.join(root, "out");
-  await writeFile(metadata, JSON.stringify({ tables: [{ table_name: "quality_rule", columns: [{ name: "id", sql_type: "bigint", nullable: false }] }] }));
-  await writeFile(contract, JSON.stringify({ schema_version: 1, status: "approved", base_package: "com.yss.demo", module_name: "demo", domain_segment: "quality", architecture_profile: "target-domain-model", platform_profile: "spring-boot-2.7-jdk8", validation_namespace: "javax", dto_placement: "web", openapi_freeze_ref: "openapi://quality-rule@1", fields: { quality_rule: { create: [], update: ["id"], query: [], response: ["id"] } } }));
-  const args = ["--metadata-file", metadata, "--contract-file", contract, "--base-package", "com.yss.demo", "--module-name", "demo", "--domain-segment", "quality", "--output-dir", output];
-  await assert.rejects(() => generate(parseArgs(args.map((value) => value === "demo" ? "other" : value)), { log() {}, warn() {} }), /approved web generation contract/);
-  const existing = path.join(output, "com/yss/demo/rest/QualityRuleController.java");
+test("binds identity and every target to the approved write scope before writing", async () => {
+  const data = await fixture();
+  await assert.rejects(() => generate(parseArgs(data.args.map((value) => value === "demo" ? "other" : value)), { log() {}, warn() {} }), /approved web generation contract/);
+  await writeFile(data.contract, JSON.stringify(webContract(data.root, { allowed_write_paths: [path.join(data.root, "different-root")] })));
+  await assert.rejects(() => generate(parseArgs(data.args), { log() {}, warn() {} }), /allowed_write_paths/);
+  await writeFile(data.contract, JSON.stringify(webContract(data.root)));
+  const existing = path.join(data.output, "com/yss/demo/rest/QualityRuleController.java");
   await mkdir(path.dirname(existing), { recursive: true });
   await writeFile(existing, "user-owned\n");
-  await assert.rejects(() => generate(parseArgs(args), { log() {}, warn() {} }), /initialize-only/);
+  await assert.rejects(() => generate(parseArgs(data.args), { log() {}, warn() {} }), /initialize-only/);
   assert.equal(await readFile(existing, "utf8"), "user-owned\n");
-  await assert.rejects(() => readFile(path.join(output, "com/yss/demo/rest/convertor/QualityRuleWebConvertor.java"), "utf8"), /ENOENT/);
+  await assert.rejects(() => readFile(path.join(data.output, "com/yss/demo/rest/convertor/QualityRuleWebConvertor.java"), "utf8"), /ENOENT/);
+});
+
+test("scaffold-v2 mode requires an empty-scaffold-verified manifest with matching profile and project layout", async () => {
+  const data = await fixture({ platform_profile: "spring-boot-2.7-jdk8", validation_namespace: "javax" });
+  const projectRoot = path.join(data.root, "demo-service");
+  const webProject = path.join(projectRoot, "demo-service-adapter", "demo-service-web");
+  const manifest = path.join(projectRoot, ".yss", "scaffold-generation.json");
+  await mkdir(path.dirname(manifest), { recursive: true });
+  await writeFile(manifest, JSON.stringify({ schema_version: 2, project_name: "demo-service", base_package: "com.yss.demo", completion_level: "empty-scaffold-verified", profiles: { architecture: "target-domain-model", platform: "spring-boot-2.7-jdk8", validation_namespace: "javax", dto_placement: "web" } }));
+  const contractValue = webContract(projectRoot, {
+    integration_mode: "scaffold-v2",
+    implementation_project_root: projectRoot,
+    scaffold_manifest_ref: manifest,
+    platform_profile: "spring-boot-3-jdk17",
+    validation_namespace: "jakarta",
+    allowed_write_paths: [path.join(webProject, "src/main/java/com/yss/demo/rest")]
+  });
+  await writeFile(data.contract, JSON.stringify(contractValue));
+  const args = ["--metadata-file", data.metadata, "--contract-file", data.contract, "--dto-wire-profile-file", dtoWireProfileFile, "--scaffold-manifest-file", manifest, "--base-package", "com.yss.demo", "--module-name", "demo", "--domain-segment", "quality", "--web-project-dir", webProject, "--application-service-package", "com.yss.demo.application.service", "--validation-namespace", "jakarta"];
+  await assert.rejects(() => generate(parseArgs(args), { log() {}, warn() {} }), /scaffold manifest.*platform/i);
+  contractValue.platform_profile = "spring-boot-2.7-jdk8";
+  contractValue.validation_namespace = "javax";
+  await writeFile(data.contract, JSON.stringify(contractValue));
+  await generate(parseArgs(args.map((value) => value === "jakarta" ? "javax" : value)), { log() {}, warn() {} });
+});
+
+test("rolls back files written before a filesystem failure", async () => {
+  const data = await fixture();
+  const rest = path.join(data.output, "com/yss/demo/rest");
+  await mkdir(rest, { recursive: true });
+  await writeFile(path.join(rest, "convertor"), "blocking-file\n");
+  await assert.rejects(() => generate(parseArgs(data.args), { log() {}, warn() {} }));
+  await assert.rejects(() => readFile(path.join(rest, "QualityRuleController.java"), "utf8"), /ENOENT/);
+  assert.equal(await readFile(path.join(rest, "convertor"), "utf8"), "blocking-file\n");
 });

package/template/.cursor/skills/ask-matt/SKILL.md

@@ -84,7 +84,7 @@ Off the main flow entirely.
 - **`/grilling`** — the interview primitive itself: rounds, the frontier, facts are the agent's job and decisions are yours. `/grill-me` and `/grill-with-docs` are the two named ways in, and `/triage`, `/wayfinder` and `/improve-codebase-architecture` all run it internally. Reach for it directly only when you want the interview with no wrapper around it.
 - **`/resolving-merge-conflicts`** — work an in-progress merge or rebase conflict hunk by hunk, resolving by **intent** traced to each side's primary source rather than by picking lines, then finish the operation. It never runs `--abort`. Standalone and off every flow: reach for it when you are already mid-conflict.
 - **`/prototype`** — a small, throwaway program that answers one design question: does this state model feel right, or what should this UI look like. Throwaway is a constraint on how the code is written, not a promise to destroy it: the answer folds into the real code, and the prototype itself is kept as a **primary source** on a `prototype/<name>` branch out of main, pointed at from the implementation issue. It's the detour in step 2 of the main flow, but reach for it any time a design question is hard to settle on paper.
-- **`/research`** — delegate reading legwork to a **background agent**: it investigates a question against **primary sources**, then leaves a cited Markdown file in the repo. Keep working while it reads. The file it produces is something to take *into* the main flow at `/grill-with-docs` — research feeds the thinking, it doesn't replace it.
+- **`/yss-research`** — investigate technical or strategy evidence using `technical-evidence` / `strategy-evidence` and `quick` / `evidence-audited` modes. Use a background agent when the runtime supports it and parallel reading is useful; delegation is not a trust guarantee. The old `/research` name is a deprecated alias. Research feeds `/grill-with-docs` and lifecycle decisions; it does not approve them.
 - **`/to-questionnaire`** — when the thing blocking you isn't in your head or the codebase but in **someone else's**, this writes them a questionnaire to fill in. It's the inverse of `/grill-me`: instead of interviewing you about the subject, it interviews you about the **send** — who it's going to, what you need back — and aims the questions at the gap. What comes back is material for `/grill-with-docs` or `/to-spec`.
 - **`/wait-what`** — the corrective for a message that didn't land. Use it mid-conversation, inside any other skill, and the agent re-pitches what it just said with the context you were missing, in plain English, using the `CONTEXT.md` vocabulary. It works after the fact; `/grill-with-docs` is the upfront cure, because a shared language agreed early is what stops the jargon arriving at all.
 - **`/teach`** — learn a concept over multiple sessions, using the current directory as a stateful workspace.

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

@@ -105,7 +105,7 @@ If the spec is missing, skip the Spec sub-agent and note this in the final repor
 
 For template-maintenance task packages carrying `review_round`, preserve the frozen scope and apply the two-round convergence contract. A hard requirement added during review must cite a rule that already applied when the candidate was frozen; otherwise report it as `judgement-call` for the backlog. Round 1 blocking findings return to the implementer and require a new digest plus all review axes. If Round 2 still has an open `violation`, `drift`, or `new_impacts`, return `needs-human` and stop; do not silently start Round 3. Candidate byte changes invalidate every earlier axis report.
 
-Present the reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. If UI is in scope, add `## UI fidelity` from the separate pass. Fill `docs/templates/review-report-template.md` specialist tables as part of Standards evidence, not a fourth axis. Do **not** merge or rerank findings — the axes are deliberately separate (see _Why separate axes_). A YSS candidate with blank applicable specialist rows, skipped `required_skills`, or unaddressed mandatory violations is `blocked`, not `completed`. Do not close findings by writing implementation in the review session. `violation` / machine-check failure / blank applicable rows go back to the implementer on the original contract path, then recapture the candidate and rerun every axis. `drift` / `new_impacts` / `required_skills` mismatch mark the contract `stale` and return to Router; do not keep coding on the old contract. `not-applicable` is only for untriggered impacts; mandatory gates have no waiver, only repair or a complete `seam-deferred` record.
+Present the reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. If UI is in scope, add `## UI fidelity` from the separate pass. Fill `docs/templates/review-report-template.md` specialist tables as part of Standards evidence, not a fourth axis. Do **not** merge or rerank findings — the axes are deliberately separate (see _Why separate axes_). A YSS candidate with blank applicable specialist rows, skipped `required_skills`, or unaddressed mandatory violations is `blocked`, not `completed`. Do not close findings by writing implementation in the review session. `violation` / machine-check failure / blank applicable rows go back to the implementer on the original contract path, then recapture the candidate and rerun every axis. `drift` / `new_impacts` / `required_skills` mismatch mark the contract `stale` and return to 实现合同编译器; do not keep coding on the old contract. `not-applicable` is only for untriggered impacts; mandatory gates have no waiver, only repair or a complete `seam-deferred` record.
 
 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.
 

package/template/.cursor/skills/code-review/references/yss-review-standards.md

@@ -49,6 +49,6 @@ YSS 页面模块约定（YTable、YFormily、页面骨架等）走 Standards，
 | 类型 | 动作 |
 |---|---|
 | `violation`、机器检查失败、适用行空白、`missing_evidence` | 实现者在**原合同允许路径**内修复；任何修复使候选失效，必须重新捕获并重跑 Standards、Spec、UI fidelity（若命中）和 fresh verification |
-| `drift`、`new_impacts`、`required_skills` 与真实影响不一致 | 合同标 `stale`，回 Router 或更早生命周期阶段；禁止在旧合同上继续编码 |
+| `drift`、`new_impacts`、`required_skills` 与真实影响不一致 | 合同标 `stale`，回 实现合同编译器 或更早生命周期阶段；禁止在旧合同上继续编码 |
 
 `not-applicable` 仅当影响面未命中。命中后的 mandatory 不得豁免；只允许修复，或写完整 `seam-deferred`（风险、责任人、后续 Ticket、验证计划、目标版本或发布日期）。禁止为日常 Alibaba / YSS 新增生物人豁免门禁；安全 / 公共 API 仍走既有 `TODO-HUMAN-REVIEW` 与生物人门禁。

package/template/.cursor/skills/lombok/SKILL.md

@@ -21,7 +21,7 @@ allowed-tools: Read, Grep, Glob, Write, Edit
 
 - 消费批准后的 Slice Contract/work unit，只在允许路径内调整 POJO 样板和注解处理器配置。
 - 受控生成必须记录对象类型、选用/排除注解、实体关系和敏感字段风险、编译/测试实际结果。
-- 按 `yss-router` 的统一 Execution Result 返回 changed files、证据、偏离和新增影响；`@Data` 实体风险、处理器配置缺失或越界路径返回 `violation`。
+- 按 `yss-implementation-contract-compiler` 的统一 Execution Result 返回 changed files、证据、偏离和新增影响；`@Data` 实体风险、处理器配置缺失或越界路径返回 `violation`。
 
 ## Maven Configuration
 

package/template/.cursor/skills/mapstruct/SKILL.md

@@ -21,7 +21,7 @@ allowed-tools: Read, Grep, Glob, Write, Edit
 
 - 消费批准后的 Slice Contract/work unit，只为合同中的 DTO/VO/PO/Domain 转换生成 Mapper/Convertor。
 - 受控生成必须记录 source/target、忽略字段、更新语义、Lombok processor 配置和 mapper 行为测试。
-- 按 `yss-router` 的统一 Execution Result 返回生成/源文件、测试和实际验证；未映射字段、反射/BeanUtils 退化或越界路径返回 `violation`。
+- 按 `yss-implementation-contract-compiler` 的统一 Execution Result 返回生成/源文件、测试和实际验证；未映射字段、反射/BeanUtils 退化或越界路径返回 `violation`。
 
 ## Basic Mapper
 

package/template/.cursor/skills/prototype-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prototype-review
-description: Use when reviewing low-fidelity UI design, wireframes, prototype links, interaction specs, or state matrices before high-fidelity HTML prototype work, Spec calibration, OpenAPI Draft, vertical slicing, or implementation.
+description: Use when independently reviewing low-fidelity UI, interaction specs, or state matrices before choosing an H1/H2 prototype profile, calibrating Spec/OpenAPI, slicing, or implementation.
 ---
 
 # Prototype Review
@@ -17,7 +17,7 @@ Run this independent gate only when UI changes affect a primary user flow, navig
 - `docs/.scratch/<feature>/design/<feature>-interaction-spec.md` or prototype link.
 - State matrix, preferably based on `docs/design/templates/state-matrix-template.md`.
 - Existing OpenAPI Draft only if the review is checking alignment; do not require OpenAPI before product design.
-- `docs/.scratch/<feature>/verification/prototype-evidence.yaml` may be created as a pending evidence record, but CLI/browser validation belongs to the following high-fidelity verification gate.
+- `docs/.scratch/<feature>/verification/prototype-evidence.yaml` may be created as a pending schema v3 record, but档位构建与浏览器验证属于后续 `gate.prototype-verified`。
 
 ## Review Gates
 
@@ -26,6 +26,7 @@ Run this independent gate only when UI changes affect a primary user flow, navig
 | Page coverage | All primary pages, entry points, and navigation exits are named |
 | Flow coverage | Main path, cancel/back, failure, retry, and completion paths are explicit |
 | State coverage | loading, empty, error, readonly, disabled, no-permission, conflict, and dirty-form states are addressed or explicitly not applicable |
+| State transition coverage | 每个状态列出进入事件、允许转换、guard、动作和退出路径；不存在只能进入不能退出的状态 |
 | Permission coverage | Hidden vs disabled vs rejected actions are clear |
 | Data coverage | Visible fields, filters, sort, pagination, forms, tables, drawers, modals, and audit/version data are listed |
 | API implication | Request/response fields, error structure, pagination/filtering, permissions, and concurrency implications can be drafted |
@@ -36,12 +37,12 @@ Run this independent gate only when UI changes affect a primary user flow, navig
 
 ## Decision Rules
 
-- If a feature has UI impact and lacks page map, user flow, prototype/wireframe, or state matrix, block high-fidelity HTML prototype work, Spec calibration, and OpenAPI Draft.
+- If a feature has UI impact and lacks page map, user flow, prototype/wireframe, or state matrix, block prototype profile selection, Spec calibration, and OpenAPI Draft.
 - If the prototype hides business rules behind generic text such as "校验失败", require field-level errors and recovery behavior.
-- If a page shows a user action but the OpenAPI implication list lacks endpoint/non-goal mapping, block high-fidelity HTML prototype work, Spec calibration, or OpenAPI Draft.
+- If a page shows a user action but the OpenAPI implication list lacks endpoint/non-goal mapping, block prototype profile selection, Spec calibration, or OpenAPI Draft.
 - If Spec P0 scope says a user can manage or configure an object but the design only shows read-only data, block until the write path or scope downgrade is explicit.
 - If a state is intentionally out of scope, record why and who owns the decision.
-- If implementation dependencies are unclear, route to `yss-router` only after the prototype passes this review.
+- If implementation dependencies are unclear, route to `yss-implementation-contract-compiler` only after the prototype passes this review.
 
 ## Output Contract
 
@@ -62,7 +63,7 @@ Run this independent gate only when UI changes affect a primary user flow, navig
 - <requirements gaps, acceptance criteria updates, non-goals, pending decisions>
 
 ### Frontend Prototype Readiness
-- <component states, data dependencies, frontend acceptance notes>
+- <component states, data dependencies, profile triggers, frontend acceptance notes>
 
 ### Lifecycle Evidence
 - <persistent review path; blockers; `gate.prototype-reviewed` candidate result>

package/template/.cursor/skills/wayfinder/SKILL.md

@@ -74,7 +74,7 @@ The answer isn't part of the body — it's recorded on resolution (see [Work thr
 
 Every ticket is either **HITL** — human in the loop, worked _with_ a human who speaks for themselves — or **AFK**, driven by the agent alone. A HITL ticket only resolves through that live exchange; the agent never stands in for the human's side of it (a grilling agent that answers its own questions has broken this).
 
-- **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases to surface a fact a decision waits on. Resolved by a `/research` **subagent**. Use when knowledge outside the current working directory is required.
+- **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases to surface a fact a decision waits on. Resolved by a `/yss-research` **subagent** (`/research` is a deprecated alias). Use when knowledge outside the current working directory is required.
 - **Prototype** (HITL): Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code via the /prototype skill. Links the prototype as an asset. Use when "how should it look" or "how should it behave" is the key question.
 - **Grilling** (HITL): Conversation. The default case. Always invoke the /grilling and /domain-modeling skills.
 - **Task** (HITL or AFK): Manual work that must happen before a _decision_ can be made — nothing to decide, prototype, or research, but the discussion is blocked until it's done. Signing up for a service so its API can be judged, provisioning access, moving data so its shape can be seen. This is the one type that _does_ rather than decides — and it earns its place by unblocking a decision, not by delivering the destination. The agent drives it alone where it can (AFK); otherwise it hands the human a precise checklist (HITL). Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on.
@@ -112,7 +112,7 @@ User invokes with a loose idea.
 2. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. **If this surfaces no fog** — the way to the destination is already clear, the whole journey small enough for one session — you don't need a map. Stop and ask the user how they'd like to proceed.
 3. **Create the map** (label `wayfinder:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into **Not yet specified**.
 4. **Create the tickets you can specify now** as child issues of the map — then wire blocking edges in a **second pass** (issues need ids before they can reference each other). Wiring sorts them into the frontier and the blocked; everything you can't yet specify stays in the fog — the **Not yet specified** section.
-5. **Fire the research subagents.** For each `research` ticket you just created, spin up a `/research` subagent to resolve it in parallel, capturing its findings on a throwaway `research/<name>` branch with a context pointer from the ticket.
+5. **Fire the research subagents.** For each `research` ticket you just created, spin up a `/yss-research` subagent to resolve it in parallel, capturing its findings on a throwaway `research/<name>` branch with a context pointer from the ticket. `/research` remains only as a deprecated compatibility alias.
 6. Stop — charting is one session's work; it hand-resolves nothing.
 
 ### Work through the map

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

@@ -1,27 +1,27 @@
 ---
 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。
+description: Use when an H2 React/AntD prototype needs versioned Ant Design v6 facts or an incremental fact-pack refresh. Not for H1, frontend implementation, lifecycle approval, or replacing yss-prototype-stage.
 ---
 
 # YSS Ant Design 事实
 
-只服务原型设计与高保真构建。把官方 `@ant-design/cli`、`design.md`、MCP 与 LLMs.txt 收成可追溯的事实引擎。阶段合同仍是 `yss-prototype-stage`。前端代码落地一律改用 `yss-ui`，不要继续调用本技能。
+只服务 H2 `flow-review` 中实际采用 React AntD 的原型，把官方 `@ant-design/cli` 与 `design.md` 收成可追溯的条件事实源。阶段合同仍是 `yss-prototype-stage`。H1 不适用；前端代码落地一律改用 `yss-ui`。
 
 ## 何时使用
 
-- 已进入 `yss-prototype-stage` 的高保真产出前后，需要 Ant Design v6 组件 / token / demo / semantic / 上游 `design.md` 事实。
-- 需要写入 `prototype-evidence.yaml` 的 AntD 段。
+- 已进入 `yss-prototype-stage` 且档位为 H2、实际采用 React AntD，需要组件 / token / demo / semantic 事实。
+- 现有 fact pack 不满足精确版本、组件覆盖、项目 Token digest 与无新 API 疑问四项 freshness 条件，需要增量补齐。
 
-不要用本技能：前端实现、Vue / Ant Design Vue 生产代码、批准门禁、生成页面流、安装官方 `antd` skill，或运行 `antd setup`。进入实现切片后停用本技能，改走 `yss-ui`。
+不要用本技能：H1、H2 非 AntD 原型、前端实现、Vue / Ant Design Vue 生产代码、批准门禁、生成页面流、安装官方 `antd` skill，或运行 `antd setup`。
 
 ## 步骤
 
-1. 检测 CLI：优先已安装的 `antd`，否则用 `npx -y @ant-design/cli`。记录实际 CLI 版本。不要在模板源执行 `npm install -g`。
+1. 先检查 `docs/design/facts/antd/<exact-version>/manifest.json`。fresh 时直接引用；不 fresh 才检测 CLI，优先已安装的 `antd`，否则用 `npx -y @ant-design/cli`。记录实际 CLI 版本，不执行全局安装。
 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`。
+6. 把 fact-pack manifest 或增量 JSON 路径写入证据清单。字段与 lint 适用范围见 `references/evidence.md`。
 7. 上游默认与项目 token 冲突时，以项目覆盖为准，并标记 `project_override_reviewed`。
 
 ## 硬规则
@@ -31,4 +31,5 @@ description: Use when 原型设计或高保真构建需要查询 Ant Design v6
 - 禁止把官方 `design.md` 的默认色、圆角、间距写回项目实现或覆盖项目 token。
 - 禁止在前端代码落地、垂直切片实现或 `yss-ui` 任务中调用本技能。
 - 禁止把 React props / demo / hook 当作 `yss-ui` 或 Ant Design Vue API。
+- 禁止为 H1 伪造 AntD 字段，或用 React CLI 证据宣称生产 YSS/AntDV 组件已经验证。
 - MCP 与 `llms-full.txt` 不是门禁证据。边界见 `references/boundaries.md`。

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

@@ -1,8 +1,12 @@
 # AntD 事实证据
 
-目标文件：`docs/.scratch/<feature>/verification/prototype-evidence.yaml`，字段以 `docs/design/templates/prototype-evidence-template.yaml` 为准。本文件只说明如何填 AntD 段。
+目标文件：schema v3 `docs/.scratch/<feature>/verification/prototype-evidence.yaml`。本文件只说明 H2 实际使用 React AntD 时如何填 `profile_evidence.flow_review.prototype_library_facts`；H1 不得出现 AntD CLI 段，任何原型证据都不得冒充生产 YSS/AntDV 组件验证。
 
-## 必填
+## fact pack 优先
+
+优先引用 `docs/design/facts/antd/<exact-version>/manifest.json`。只有 exact version、组件集合和项目 Token baseline digest 相同，且不存在新 API 疑问时，`source: fact-pack` 才有效；否则用 `source: cli-run` 补充增量查询。不要为模板创建空目录或 placeholder manifest。
+
+## CLI 增量查询必填
 
 - `antd.cli_command`：实际调用的可执行文件，`antd` 或 `npx -y @ant-design/cli`。
 - `antd.cli_version`：本轮 `antd -V` 或等价输出，禁止写死模板默认值。
@@ -11,8 +15,9 @@
 - `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 已对照。
-- `prototype_stack.actual_antd_version`：原型 lockfile 中的实际 React `antd@6.x`，必须与 `antd.target_antd_version` 一致。
-- `visual_semantic_mapping.components[]`：记录 v6 semantic role、项目 Token、React 原型组件、生产 YSS/Ant Design Vue 4.x 目标与 React-only API 隔离结论。
+- `actual_antd_version`：原型 lockfile 中的实际 React `antd@6.x`，必须与查询版本一致。
+- `manifest_ref` / `manifest_digest`：可复验的事实包或本轮查询清单。
+- `components_covered` 与 `project_token_baseline_digest`：支持 freshness 判断。
 
 JSON 输出存为相邻文件，证据清单只引用路径。不要把整份 `llms-full.txt` 或 MCP 对话贴进清单。
 
@@ -20,11 +25,11 @@ JSON 输出存为相邻文件，证据清单只引用路径。不要把整份 `l
 
 `antd lint` 只对可解析的 React/TSX 源码有规则命中。HTML 原型会出现空 issues（假绿）或 `skippedFiles` / `parse-error` / `partial: true`。
 
-CLI JSON 只能证明查询事实，不能单独证明原型消费了目标版本或完成了 Vue/YSS 映射。`gate.prototype-verified` 还必须通过 `yss-prototype-stage/scripts/prototype-contract.mjs` 的项目与 schema v2 证据校验、Design QA、浏览器和无障碍验证。
+CLI JSON 只能证明查询事实，不能单独证明原型消费了目标版本或完成了 Vue/YSS 映射。`gate.prototype-verified` 还必须通过 schema v3 档位证据、Design QA、浏览器和无障碍验证。
 
 | 产物 | `lint_applicable` | 做法 |
 |---|---|---|
-| `docs/.scratch/<feature>/design/prototypes/index.html` | `not-applicable` | 写 `lint_reason: html-prototype`；`lint_ref` 可空；`lint_passed` 保持 `false`，不得改成 `true` |
+| 静态 HTML / H1 | `not-applicable` | 不创建 AntD 段；由 H1 合同验证 HTML |
 | React/TSX 原型源 | `true` | 对变更文件跑 `antd lint --format json`，保存输出；无 issue 才把 `lint_passed` 设为 `true` |
 
 浏览器验证仍由 `yss-prototype-stage` 采集，不在本技能宣布 `gate.prototype-verified` 通过。

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

@@ -5,9 +5,9 @@ description: 指导在 Vue3 业务列表、表单、详情和操作 Hook 中集
 
 # API 集成 Skill
 
-本目录是 API 集成的 canonical 技能；历史名称 `api-integration` 仅通过注册表和 Router alias 解析，不再维护第二份内容。
+本目录是 API 集成的 canonical 技能；历史名称 `api-integration` 仅通过注册表和 实现合同编译器 alias 解析，不再维护第二份内容。
 
-目录、frontmatter、注册表 ID 和 Router canonical 闭包键均为 `yss-api-integration`；历史名称 `api-integration` 只在注册表和 Router alias 表中解析为本技能。
+目录、frontmatter、注册表 ID 和 实现合同编译器 canonical 闭包键均为 `yss-api-integration`；历史名称 `api-integration` 只在注册表和 实现合同编译器 alias 表中解析为本技能。
 
 ## 📋 目标
 

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

@@ -11,7 +11,7 @@ Application 层用例编排 skill。负责协调 Domain 与 Gateway，定义事
 
 - 用户要实现 Application Service、用例编排或 `@Transactional` 边界。
 - 用户要补 App 层 MapStruct Convertor 或跨聚合协调逻辑。
-- 脚手架生成完成后进入业务实现，Router 按 `backend_impact` 加载本 skill。
+- 脚手架生成完成后进入业务实现，实现合同编译器 按 `backend_impact` 加载本 skill。
 
 ## 不适用
 
@@ -46,7 +46,7 @@ Application 层用例编排 skill。负责协调 Domain 与 Gateway，定义事
 
 - 只消费批准后的 `Slice Implementation Contract` 和当前 `work_unit`。
 - AppService 骨架可 `controlled-generation`；用例编排、事务、幂等、权限和失败行为必须 `behavior-tdd`。
-- 按 `yss-router/references/yss-skill-execution-result.md` 返回统一 `YSS Skill Execution Result`。
+- 按 `yss-implementation-contract-compiler/references/yss-skill-execution-result.md` 返回统一 `YSS Skill Execution Result`。
 - 发现新 API、权限、状态机或跨上下文影响时填入 `new_impacts` 并暂停。
 
 ## 按需读取

package/template/.cursor/skills/yss-audit-log/SKILL.md

@@ -23,11 +23,11 @@ description: Use when YSS `AuditLog`, `EnableAuditLog`, audit SpEL summaries, as
 
 ## 源码索引
 
-- 源码位置不要假设固定目录；先按 `yss-source-index/references/source-location.md` 定位。
+- 源码位置不要假设固定目录；先按 `yss-skill-source-index-refresh/references/source-location.md` 定位。
 - 当前技能索引：`references/source-index.md`
 - 重点源码入口通常包括审计注解、启用注解、切面、发布服务、事件模型、默认订阅器。
 
-当组件源码变化后，用 `yss-source-index` 刷新索引；刷新或读取前先按源码定位策略确认真实位置。
+当组件源码变化后，用 `yss-skill-source-index-refresh` 刷新索引；刷新或读取前先按源码定位策略确认真实位置。
 
 ## 接入检查清单
 

package/template/.cursor/skills/yss-audit-log/references/source-index.md

@@ -5,7 +5,7 @@ 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.mjs`. Do not hand-edit generated sections.
+This file is generated by `yss-skill-source-index-refresh/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/.cursor/skills/yss-cache/SKILL.md

@@ -9,7 +9,7 @@ description: 用于 YSS 缓存框架的接入、配置、代码修改和故障
 
 ## 工作流
 
-1. 按 `yss-source-index/references/source-location.md` 定位真实源码。当前工作区有 `.codegraph/` 时先用 CodeGraph；否则读取 [source-index.md](references/source-index.md) 后用符号或 Maven 模块搜索。
+1. 按 `yss-skill-source-index-refresh/references/source-location.md` 定位真实源码。当前工作区有 `.codegraph/` 时先用 CodeGraph；否则读取 [source-index.md](references/source-index.md) 后用符号或 Maven 模块搜索。
 2. 识别使用模型：Spring Cache 单后端路由、Redis 故障降级，或 JetCache local + remote。不要混用三者的行为假设。
 3. 明确缓存名、key、TTL、更新/删除路径、跨节点一致性和序列化兼容要求。
 4. 先检查现有依赖、启动注解、配置和注解用法，再决定修改业务代码、配置还是组件。
@@ -41,4 +41,4 @@ description: 用于 YSS 缓存框架的接入、配置、代码修改和故障
 - `scripts/verify-cache-component.sh [--source-root PATH] [--consumer-root PATH --consumer-module MODULE]`：验证组件、真实 Redis、Java 8 字节码及可选消费模块。
 - `scripts/check-skill-freshness.sh [source-root]`：比较技能契约与当前组件源码；发现漂移返回 1。
 
-当组件源码变化后，用 `yss-source-index` 刷新 [source-index.md](references/source-index.md)，再运行 freshness 检查。不要手工修改生成索引。
+当组件源码变化后，用 `yss-skill-source-index-refresh` 刷新 [source-index.md](references/source-index.md)，再运行 freshness 检查。不要手工修改生成索引。

package/template/.cursor/skills/yss-cache/references/source-index.md

@@ -5,7 +5,7 @@ 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.mjs`. Do not hand-edit generated sections.
+This file is generated by `yss-skill-source-index-refresh/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/.cursor/skills/yss-cache/scripts/check-skill-freshness.sh

@@ -76,7 +76,7 @@ if [ "$annotation" -nt "$index" ] || [ "$properties" -nt "$index" ] || [ "$conne
 fi
 
 if [ "$fail" -ne 0 ]; then
-  echo "RESULT: skill/source contract drift detected; refresh with yss-source-index and review semantic references"
+  echo "RESULT: skill/source contract drift detected; refresh with yss-skill-source-index-refresh and review semantic references"
   exit 1
 fi