create-yss-spec 2.2.10 → 3.0.1

package/template/.trae/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/AGENTS.md

@@ -22,7 +22,7 @@
 | 影响面触发与 `not-applicable` | `docs/process/harness-process-tailoring.md` |
 | 模板维护强度触发与最低等级 | `docs/process/maintenance-intensity.yaml` |
 | 技能清单、来源、版本、哈希和投影目标      | `skills-lock.json`                          |
-| 技能分层、别名、默认可发现性和运行时入口 | `docs/agents/yss-skill-registry.yaml`（当前 `status: active`；Router / 生命周期必须消费） |
+| 技能分层、别名、默认可发现性和运行时入口 | `docs/agents/yss-skill-registry.yaml`（当前 `status: active`；实现合同编译器 / 生命周期必须消费） |
 | 数字人角色、阶段协作组、运行时绑定与生命周期会签 | `docs/agents/digital-human-roles.yaml`；`docs/agents/digital-human-roles.md` 为操作说明 |
 | 视觉令牌与组件视觉变体规范 | 根目录 `DESIGN.md`；`docs/design/design.md` 为中文治理与生命周期适配，`docs/design/tokens/*` 为派生快照 |
 
@@ -41,7 +41,7 @@ README、用户指南、根目录 `CLAUDE.md` 和其他说明文档只引用或
 按“影响面 → 单一事实来源 → 投影 / 派生资产 → 分级证据”维护。强度分级、最低证据和 checkpoint 合同见 `docs/process/harness-process-tailoring.md`。
 
 - 创建、修改或退役 skill 时使用 `maintaining-skills`，并先按 `docs/process/harness-process-tailoring.md` 判定 L1 / L2 / L3；L3 日常记录维护者自检与 fresh verification，正式发布前执行完整模板门禁。
-- `.agents/skills` 是跨 Agent 共享技能的权威内容；`.claude/skills`、`.codex/skills`、`.cursor/skills`、`.hermes/skills`、`.pi/skills`、`.qoder/skills`、`.trae/skills` 中的共享技能是生成投影，禁止分别手工修改。Cursor 的契约运行时入口是 `.cursor/skills`；不得把 canonical `.agents/skills` 与某个平台投影当作同权双入口。
+- `.agents/skills` 是跨 Agent 共享技能的权威内容；`.claude/skills`、`.codex/skills`、`.cursor/skills`、`.pi/skills`、`.qoder/skills`、`.trae/skills` 中的共享技能是生成投影，禁止分别手工修改。Cursor 的契约运行时入口是 `.cursor/skills`；不得把 canonical `.agents/skills` 与某个平台投影当作同权双入口。
 - 模板维护默认以 `scripts/verify-template-fast` 完成 `implementation-ready`；显式晋级审查时用 `scripts/verify-template-candidate`，首次冻结前和最终发布前仍必须执行完整 `scripts/verify-template`。后者是不可裁剪的模板发布阻断门禁。模板与外部 `create-yss-spec` 的跨仓库契约未完成集成验证时，不得声称可发布。
 
 ## 5. `project-instance` 产品研发路由
@@ -53,12 +53,12 @@ README、用户指南、根目录 `CLAUDE.md` 和其他说明文档只引用或
 | 主阶段（registry） | 原生工作单元 | 技能入口（按影响面裁剪） | 关键产物 / 门禁 |
 |---|---|---|---|
 | 入口分诊 `stage.entry-triage` | `work-unit.entry-triage` | `yss-product-lifecycle` | 仓库身份、影响面、最近可信阶段；`gate.repository-identity-valid` |
-| Discovery `stage.discovery` | `work-unit.discovery-opportunity`、`work-unit.discovery-requirements`、`work-unit.domain-strategy-design`、`work-unit.stage-decision` | `yss-product-lifecycle`；按事实 / 领域影响使用 `competitive-intelligence`、`research`、`grilling`、`domain-modeling`、`yss-stage-decision` | Discovery、用户/MVP/非目标/成功标准、测试 seam；必要时 DDD 战略设计与阶段决策包；`gate.domain-strategy-approved`、`gate.stage-decision-package-approved` |
+| Discovery `stage.discovery` | `work-unit.discovery-opportunity`、`work-unit.discovery-requirements`、`work-unit.domain-strategy-design`、`work-unit.stage-decision` | `yss-product-lifecycle`；按事实 / 领域影响使用 `competitive-intelligence`、`yss-research`、`grilling`、`domain-modeling`、`yss-stage-decision` | Discovery、用户/MVP/非目标/成功标准、测试 seam；必要时 DDD 战略设计与阶段决策包；`gate.domain-strategy-approved`、`gate.stage-decision-package-approved` |
 | Spec / 功能架构 `stage.spec-architecture` | `work-unit.spec-synthesis` | `yss-product-lifecycle`；`to-spec` 仅为显式兼容入口 | Spec、产品总体设计、功能架构；必要时 Spec Delta；`gate.spec-baseline-approved` |
-| 产品设计 `stage.product-design` | `work-unit.prototype-design` | `yss-prototype-stage` 为主合同，内部依次消费 `yss-design-system`、低保真、独立 `prototype-review`、`yss-antd-design` pre-build facts、Codex `product-design:index` focused workflow、post-build/浏览器/无障碍验证；前端落地改用 `yss-ui` | 交互说明、低 / 高保真原型、状态矩阵；`gate.prototype-reviewed`、`gate.prototype-verified`、`gate.user-confirmation` |
-| 系统 / 数据架构与工程契约 `stage.system-data-engineering` | `work-unit.technical-analysis` | `yss-router`；按影响使用 `yss-openapi-governance`、`yss-openapi-draft-review`、`codebase-design`、`implementation-repo-onboarding`、`yss-tactical-design` | OpenAPI Draft / Freeze、数据架构、工程基线、架构审查；无 API 影响记录；必要时 Tactical DDD Check；`gate.openapi-draft-reviewed`、`gate.design-reviewed`、`gate.openapi-frozen`、`gate.engineering-baseline-accepted`、`gate.architecture-reviewed` |
-| Ticket 正式化 `stage.ticket-formalization` | `work-unit.ticket-decomposition` | `yss-product-lifecycle` + `yss-router`；`to-tickets` 仅为显式兼容入口 | 功能父 Ticket、垂直切片、Slice Implementation Contract；切片初始 `ready-for-human`；`gate.slice-contract-approved`、`gate.slice-ready-for-agent` |
-| 垂直切片实现 `stage.vertical-slice-implementation` | `work-unit.slice-implementation` | `yss-router` + `tdd`；UI 影响追加 `yss-ui`、`yss-page-module-development` 及条件专项 skill；`implement` 仅为显式兼容入口 | 前后端代码、TDD、YSS Skill Execution Result；仅允许 `ready-for-agent` 且合同当前 |
+| 产品设计 `stage.product-design` | `work-unit.prototype-design` | `yss-prototype-stage` 为主合同：`yss-design-system` → 低保真 / 状态矩阵 → 独立 `prototype-review` → H1/H2 档位路由 → 档位适配器 → 浏览器 / Design QA / 无障碍验证；`yss-antd-design` 只用于相关 H2，原型阶段禁止调用生产实现技能 `yss-ui` | 交互说明、低保真、状态矩阵、原型交付物；`gate.prototype-reviewed`、`gate.prototype-verified`、`gate.user-confirmation` |
+| 系统 / 数据架构与工程契约 `stage.system-data-engineering` | `work-unit.technical-analysis` | `yss-implementation-contract-compiler`；按影响使用 `yss-openapi-governance`、`yss-openapi-draft-review`、`codebase-design`、`implementation-repo-onboarding`、`yss-tactical-design` | OpenAPI Draft / Freeze、数据架构、工程基线、架构审查；无 API 影响记录；必要时 Tactical DDD Check；`gate.openapi-draft-reviewed`、`gate.design-reviewed`、`gate.openapi-frozen`、`gate.engineering-baseline-accepted`、`gate.architecture-reviewed` |
+| Ticket 正式化 `stage.ticket-formalization` | `work-unit.ticket-decomposition` | `yss-product-lifecycle` + `yss-implementation-contract-compiler`；`to-tickets` 仅为显式兼容入口 | 功能父 Ticket、垂直切片、Slice Implementation Contract；切片初始 `ready-for-human`；`gate.slice-contract-approved`、`gate.slice-ready-for-agent` |
+| 垂直切片实现 `stage.vertical-slice-implementation` | `work-unit.slice-implementation` | `yss-implementation-contract-compiler` + `tdd`；UI 影响追加 `yss-ui`、`yss-page-module-development` 及条件专项 skill；`implement` 仅为显式兼容入口 | 前后端代码、TDD、YSS Skill Execution Result；仅允许 `ready-for-agent` 且合同当前 |
 | 验证 / 发布 / 复盘 `stage.verification-release-retrospective` | `work-unit.frontend-implementation-verification`、`work-unit.code-review`、`work-unit.release-and-retrospective` | `code-review`（唯一入口，Standards 消费 YSS / Alibaba 专项检查输入）；UI 影响追加 `yss-ui` + `yss-design-system`；发布 / 复盘由 `yss-product-lifecycle` 持有 | 不可变候选快照、独立审查、findings 按合同分流、fresh verification、发布 / 回滚证据、复盘；UI 影响追加 `gate.frontend-implementation-verified`；`gate.release-ready` |
 
 - 生命周期注册表中的条件门禁全部按影响面强制。命中触发条件时必须完成；未命中时只记录 `not-applicable` 及原因，不生成空文档；不得把产物、工作单元或证据统称为门禁。
@@ -78,11 +78,11 @@ README、用户指南、根目录 `CLAUDE.md` 和其他说明文档只引用或
 
 ## 7. 实现与 YSS 路由硬门禁
 
-进入实现时先读 `docs/process/implementation-repo-integration.md`，登记实现仓库、项目根、分支、CI、验证命令和回滚点；再使用 `yss-router` 编译最小 skill 集合与当前实现合同。
+进入实现时先读 `docs/process/implementation-repo-integration.md`，登记实现仓库、项目根、分支、CI、验证命令和回滚点；再使用 `yss-implementation-contract-compiler` 编译最小 skill 集合与当前实现合同。
 
 - 无可复用工程时，先确认外部目标仓库或输出目录，再使用 `yss-ddd-scaffold-generator` / `yss-frontend-scaffold-generator`；当前仓库缺少 frontend / backend 目录不改变此路由。
-- 脚手架只在 `scaffold_status=required` 且受控生成合同已持久化、获得生命周期批准后运行；它只产生机械骨架，业务行为回到 Router 并使用 `behavior-tdd`。
-- 正式垂直切片必须消费已批准、已持久化且版本当前的 Slice Implementation Contract。Router 只生成草案，不批准合同、不设置 `ready-for-agent`、不宣布完成。合同 schema、Backend 子合同和证据字段以 `yss-router` references 为准。
+- 脚手架只在 `scaffold_status=required` 且受控生成合同已持久化、获得生命周期批准后运行；它只产生机械骨架，业务行为回到 实现合同编译器 并使用 `behavior-tdd`。
+- 正式垂直切片必须消费已批准、已持久化且版本当前的 Slice Implementation Contract。实现合同编译器 只生成草案，不批准合同、不设置 `ready-for-agent`、不宣布完成。合同 schema、Backend 子合同和证据字段以 `yss-implementation-contract-compiler` references 为准。
 - UI 影响切片必须在 `ready-for-agent` 前具备通过校验的 `frontend_implementation_plan`，实现完成后补齐 `frontend_implementation_verification`；截图 / 视觉回归、状态与交互、console warning 和实际 `pnpm` 退出码均须有证据，不能只做 type-check 或声称“已对齐”。
 - 前端测试、type-check 与构建优先使用 `pnpm`；后端校验、测试与编译优先使用项目根 `./mvnw`。不要默认 `npm` / `yarn` 或裸 `mvn`。既有仓库确实没有 pnpm 或 Maven Wrapper 时，必须记录受控例外和实际命令。登记字段见 `docs/process/implementation-repo-integration.md`。
 - 路径越界、证据缺失、未执行验证、`drift`、`violation` 或 `new_impacts` 时停止实现并重新路由。
@@ -95,9 +95,9 @@ README、用户指南、根目录 `CLAUDE.md` 和其他说明文档只引用或
 
 | 触发情形 | 必须使用 |
 |---|---|
-| 技术事实、标准、第三方 API 或框架行为影响决策 | `research` 或等价的一手资料记录 |
+| 技术事实、标准、第三方 API 或框架行为影响决策，或外部证据进入领域战略 / 阶段决策 | `yss-research`；技术事实使用 `technical-evidence`，战略决策证据使用 `strategy-evidence`；旧名 `research` 仅为 deprecated alias |
 | 竞品、市场或用户口碑事实 | `competitive-intelligence` |
-| UI 设计、原型、组件或主题 | `yss-prototype-stage` 持有阶段合同：`yss-design-system` → 低保真 → 独立 `prototype-review` → `yss-antd-design` pre-build facts → Codex `product-design:index` focused workflow → post-build/浏览器/无障碍验证；其他 Agent 交付等价合同资产。前端代码落地改用 `yss-ui`，不要继续调用 `yss-antd-design` |
+| UI 设计、原型、组件或主题 | `yss-prototype-stage` 持有阶段合同：`yss-design-system` → 低保真 / 状态矩阵 → 独立 `prototype-review` → 确定性选择 H1 视觉或 H2 流程 → 档位适配器 → 浏览器 / 统一 Design QA / 无障碍验证。`yss-antd-design` 仅用于相关 H2；原型阶段不得调用 `yss-ui`。真实 YSS/AntDV 组件与 lockfile 事实只在前端实现计划、已批准切片的实现和实现还原验证中消费 |
 | Bug、测试失败或性能回退 | `diagnosing-bugs` 建立可复现反馈，再用 `tdd` |
 | merge / rebase 冲突 | `resolving-merge-conflicts` |
 | 架构治理、难测模块或深模块设计 | `codebase-design`；`improve-codebase-architecture` 仅作为用户显式兼容入口 |
@@ -115,7 +115,7 @@ README、用户指南、根目录 `CLAUDE.md` 和其他说明文档只引用或
 
 ## 10. 独立审查、验证和追踪
 
-- 实现者不能承担命中的独立审查（含数字人）。模板维护的 L3 日常路径使用维护者自检；L2 仍按需使用聚焦独立审查，正式发布仍执行完整模板门禁。模板发布、代码切片和高风险变更仍必须满足各自独立审查要求。产品切片与模板维护共用同一 finding 闭环：`violation` 由实现者在原合同路径修复后重新捕获并全轴复审；`drift` / `new_impacts` 使合同 `stale` 并回 Router。审查者不得写实现。命中后的 mandatory 不得豁免；未命中才 `not-applicable`。
+- 实现者不能承担命中的独立审查（含数字人）。模板维护的 L3 日常路径使用维护者自检；L2 仍按需使用聚焦独立审查，正式发布仍执行完整模板门禁。模板发布、代码切片和高风险变更仍必须满足各自独立审查要求。产品切片与模板维护共用同一 finding 闭环：`violation` 由实现者在原合同路径修复后重新捕获并全轴复审；`drift` / `new_impacts` 使合同 `stale` 并回 实现合同编译器。审查者不得写实现。命中后的 mandatory 不得豁免；未命中才 `not-applicable`。
 - 任何“完成 / 可合并 / 可发布”结论必须基于 fresh verification，不接受“之前跑过”或实现者自述。
 - 会签门禁按 `docs/agents/digital-human-roles.yaml` 的 `gate_policy` 关闭，会签文件经 `scripts/verify-approval-record` 核验；`gate.release-ready`、对外商务承诺和运行时外部副作用仍须生物人。
 - 在会签暂停、handoff、进入实现、合并或发布边界集中同步范围、验证证据、风险、会签点、Ticket 状态和下一步；阻塞、责任人变化或资产单独批准时立即同步。

package/template/CONTEXT.md

@@ -45,11 +45,12 @@
 | DTO wire shape | DTO 在 HTTP/JSON 边界实际暴露的字段、类型、可空性和方向性；与 Java 字段、getter 或内部协作字段区分。 | — | 以目标 mapper / contract evidence 为准，不从 getter、Lombok 或 `@JsonIgnore` 机械推断。 |
 | UI 影响 | 会改变用户可见页面、导航、交互流程、状态呈现或权限体验的功能影响。 | — | 纯后端、API、批处理或数据变更不自动构成 UI 影响。 |
 | 产品设计影响 | UI 变化触及主流程、导航、权限体验、异常 / 恢复状态、状态流转或 API 反推，需要页面流、状态矩阵和原型校准。 | — | 文案、token、颜色、间距和无行为变化的孤立视觉修复属于 UI 影响，但不自动构成产品设计影响。 |
-| 高保真 HTML 原型 | 低保真原型评审通过后，用于在浏览器中审查真实视觉密度、交互状态和页面流的产品设计资产。 | — | 不等同于生产前端实现，也不替代 OpenAPI、Spec 校准或垂直切片。 |
+| 原型交付物 | 低保真原型评审通过后，按当前决策风险选择 H1 视觉评审或 H2 流程评审档位，并在浏览器中复验的产品设计资产。 | — | `高保真 HTML 原型` 仅用于历史资产迁移；原型交付物不等同于生产前端实现，不消费 `yss-ui`，也不替代 OpenAPI、Spec 校准或垂直切片。 |
+| 原型档位 | 用 H1 `visual-review`、H2 `flow-review` 表达原型需要回答的问题与最低证据强度。 | — | 不是实现技术栈分级，也不是成熟度评分；真实 YSS/AntDV 组件验证属于前端实现计划与实现还原验证，不属于第三种原型档位。 |
 | Visual Baseline Contract | 为生产前端还原冻结页面、视口、交互状态、参考图像和允许差异的可验收合同。 | — | 不是仅有一张原型截图或绝对像素匹配；每个基线必须可定位到同一视口和同一状态复验。 |
 | 垂直切片（Vertical Slice） | 贯穿所有受影响层、可独立验证的窄功能路径。 | — | 优先使用垂直切片，避免只按层拆分的横向任务。 |
-| Slice Implementation Contract | 阶段 7 进入实现前，由 `yss-router` 根据冻结资产和垂直切片编译、再由生命周期编排器批准的实现合同，包含 Common、Frontend、Backend、Contract 和 Cross-repo 子合同。 | — | Router 只能生成草案，不能自行批准、设置 `ready-for-agent` 或宣布完成；Backend 子合同仍保留额外强约束。 |
-| YSS Skill Execution Result | YSS 专项 skill 完成工作单元后返回的结构化执行证据，记录合同版本、变更文件、证据文件、实际验证、延期 seam、偏离和新增影响。 | — | 实现者自报 `implemented` 不构成最终通过，必须由 Router、生命周期编排器和独立 Reviewer 复核。 |
+| Slice Implementation Contract | 阶段 7 进入实现前，由 `yss-implementation-contract-compiler` 根据冻结资产和垂直切片编译、再由生命周期编排器批准的实现合同，包含 Common、Frontend、Backend、Contract 和 Cross-repo 子合同。 | — | 实现合同编译器 只能生成草案，不能自行批准、设置 `ready-for-agent` 或宣布完成；Backend 子合同仍保留额外强约束。 |
+| YSS Skill Execution Result | YSS 专项 skill 完成工作单元后返回的结构化执行证据，记录合同版本、变更文件、证据文件、实际验证、延期 seam、偏离和新增影响。 | — | 实现者自报 `implemented` 不构成最终通过，必须由 实现合同编译器、生命周期编排器和独立 Reviewer 复核。 |
 | ADR | 架构决策记录，用于沉淀难以回滚、非显而易见且存在真实取舍的技术决策。 | — | 常规实现选择不要写 ADR。 |
 | Fresh Verification | 完成前重新执行的验证证据，包括测试命令、契约校验、关键路径检查或人工审查结论。 | — | 不等同于“之前跑过”或实现者自述。 |
 | `implementation-ready` | 模板维护实现和命中影响面的快速核验已经完成，但尚未冻结正式审查候选。 | — | 是模板维护默认出口；不等同于 `ready-for-agent`、已审查或可发布。 |
@@ -70,16 +71,16 @@
 | YSS 研发操作系统 | 由生命周期控制、通用工作流、YSS 专项技能、证据反馈和技能供应链共同构成的可版本化研发治理体系。 | — | 不等同于单个主控 skill、某个 Agent 客户端或运行时代码平台。 |
 | 生命周期注册表 | 结构化定义主阶段、门禁、产物、工作单元、证据及其稳定标识和关系的机器可读权威资产。 | — | Markdown 地图、数量说明和验证 fixture 是其派生产物，不应分别维护同一结构事实。 |
 | 生命周期编排器 | 持有阶段、影响面、产物状态、门禁裁决、工作单元路由和恢复条件的研发流程控制平面。 | — | 不替代专项技能执行业务实现，也不以文件存在或执行者自述宣布完成。 |
-| 前端实现还原验证 | 证明生产前端相对冻结 Spec、交互说明、状态矩阵和高保真原型不存在未解释差异的独立验证。 | — | 不是绝对像素复刻、普通 type-check 或原型评审；UI 影响切片需覆盖关键视觉、状态、交互和工程证据。 |
+| 前端实现还原验证 | 证明生产前端相对冻结 Spec、交互说明、状态矩阵和原型交付物不存在未解释差异的独立验证。 | — | 不是绝对像素复刻、普通 type-check 或原型评审；UI 影响切片需覆盖关键视觉、状态、交互和工程证据。 |
 | 生命周期稳定 ID | 以对象类型命名空间和英文标识唯一指向一个生命周期对象的兼容身份。 | — | 中文名称、展示顺序和数量可以变化；已发布 ID 不得复用来表达另一种语义。 |
 | 派生产物 | 根据生命周期注册表确定性生成的结构表、数量、索引、依赖图或测试 fixture。 | — | 不承载需要人工解释的原理、取舍或实践建议，禁止脱离注册表分别维护。 |
 | 核心技能（Core Skill） | 默认可发现、负责生命周期控制或通用研发入口的稳定技能。 | — | 不包含只在特定技术影响下才需要的专项实现规则。 |
-| 专项技能（Specialist Skill） | 由 Router 根据影响面和实现合同按需选择的前端、后端、OpenAPI 或组件技能。 | — | 不作为所有任务的平级默认入口。 |
-| 试验技能 | 尚未达到项目默认支持成熟度的技能。 | — | 只在明确试验范围内使用，不进入 Router 默认技能闭包。 |
+| 专项技能（Specialist Skill） | 由 实现合同编译器 根据影响面和实现合同按需选择的前端、后端、OpenAPI 或组件技能。 | — | 不作为所有任务的平级默认入口。 |
+| 试验技能 | 尚未达到项目默认支持成熟度的技能。 | — | 只在明确试验范围内使用，不进入 实现合同编译器 默认技能闭包。 |
 | 显式兼容入口 | 为已有用户操作习惯保留的 user-invoked 工作流入口，写入前由生命周期编排器预检，结果回交其验收。 | — | 不是默认路径、过时别名或可以越过门禁的第二套生命周期。 |
 | 技能成熟度 | 描述技能从 `draft`、`verified`、`supported` 到 `deprecated` 的治理状态。 | — | 不等同于文件存在、已被投影或能够安装。 |
-| 技能注册表 | 记录技能身份、别名、分层、适用影响面、成熟度、默认可发现性和 Agent 运行时入口的机器可读路由资产。 | — | 不替代 `skills-lock.json` 的来源、hash 和投影完整性职责。当前 `docs/agents/yss-skill-registry.yaml` 为 `active`，Router、生命周期编排器和实例发现面必须消费通过校验的 canonical 技能及其 alias 解析结果。 |
-| LLM Wiki | 由 `raw/`、`wiki/` 与 `.wiki-manifest.json` 组成的本地持久知识库。 | — | 不是 `research` 一次性笔记，也不替代权威源。`ingest` 只把用户点名的外源或已落盘研究笔记编进 IR，不改 live 权威文件。 |
+| 技能注册表 | 记录技能身份、别名、分层、适用影响面、成熟度、默认可发现性和 Agent 运行时入口的机器可读路由资产。 | — | 不替代 `skills-lock.json` 的来源、hash 和投影完整性职责。当前 `docs/agents/yss-skill-registry.yaml` 为 `active`，实现合同编译器、生命周期编排器和实例发现面必须消费通过校验的 canonical 技能及其 alias 解析结果。 |
+| LLM Wiki | 由 `raw/`、`wiki/` 与 `.wiki-manifest.json` 组成的本地持久知识库。 | — | 不是 `yss-research` 一次性研究包，也不替代权威源。`ingest` 只把用户点名的外源或已落盘研究笔记编进 IR，不改 live 权威文件。 |
 | 生态发布清单 | 关联模板 schema 与 commit、CLI 版本与快照、公开技能来源与导出 hash 的跨仓发布证据。 | — | 不要求尚未生成的仓库 commit 互相循环引用。 |
 | 研发管理仓库 | 承载 Spec、OpenAPI、架构、Ticket、验证、发布和复盘等研发管理资产的仓库。 | — | 不等同于前端 / 后端代码 monorepo。 |
 | 实现仓库 | 承载前端、后端或其他运行时代码及其 Git、CI、MR / PR、测试命令和发布流水线的仓库。 | — | 不要把实现仓库的源码所有权混入研发管理仓库。 |

package/template/README.md

@@ -13,7 +13,6 @@
 ├── .claude/                 ← Claude skills 投影与平台专属 skills
 ├── .codex/                  ← Codex skills 投影与平台专属 skills
 ├── .cursor/                 ← Cursor skills 投影
-├── .hermes/                 ← Hermes skills 投影与平台专属 skills
 ├── .pi/                     ← Pi skills 投影与平台专属 skills
 ├── .qoder/                  ← Qoder skills 投影与平台专属 skills
 ├── .trae/                   ← Trae skills 投影与平台专属 skills

package/template/docs/agents/digital-human-roles.md

@@ -1,6 +1,6 @@
 # 数字人角色
 
-结构化事实源是 `docs/agents/digital-human-roles.yaml`。角色、技能、协作组和会签级别与运行时无关。Claude Code、Cursor、Codex、Hermes、Grok Bot 等只通过 YAML `runtimes` 绑定。冲突时以 YAML 为准。
+结构化事实源是 `docs/agents/digital-human-roles.yaml`。角色、技能、协作组和会签级别与运行时无关。Claude Code、Cursor、Codex、Grok Bot 等只通过 YAML `runtimes` 绑定。冲突时以 YAML 为准。
 
 ## 何时读本文
 
@@ -16,7 +16,7 @@
 | 执行态 | Explorer / Drafter / Worker / Reviewer / Verifier | 数字人角色 |
 | 运行时绑定 | 如何在 Cursor / Claude / Grok 等落地 | 角色职责本身 |
 
-一次数字人任务包同时写明 `task_id`、`work_unit_id`、`actor_id`、数字人角色、执行态、当前 `runtime_id`，以及从角色表复制的 `core_skills` / `forbidden_skills`。可用 `taskPackageDefaults(roleId)`（`scripts/lib/digital-human-roles.mjs`）读取，禁止手写第二套技能包。`role.test-engineer` 的 core_skills 含 YSS / Alibaba 专项 skill，仅作为 `code-review` Standards 只读输入，不得写实现；finding 交实现者修复或回 Router，审查者不得当场改代码。任务包 canonical Schema 为 `docs/process/schemas/digital-human-task-package.schema.json`，按 `contract.kind` 选择生命周期、切片实现或模板维护合同。
+一次数字人任务包同时写明 `task_id`、`work_unit_id`、`actor_id`、数字人角色、执行态、当前 `runtime_id`，以及从角色表复制的 `core_skills` / `forbidden_skills`。可用 `taskPackageDefaults(roleId)`（`scripts/lib/digital-human-roles.mjs`）读取，禁止手写第二套技能包。`role.test-engineer` 的 core_skills 含 YSS / Alibaba 专项 skill，仅作为 `code-review` Standards 只读输入，不得写实现；finding 交实现者修复或回 实现合同编译器，审查者不得当场改代码。任务包 canonical Schema 为 `docs/process/schemas/digital-human-task-package.schema.json`，按 `contract.kind` 选择生命周期、切片实现或模板维护合同。
 
 ## 会签人
 
@@ -57,7 +57,7 @@
 | ID | 覆盖 | 落地方式 |
 |---|---|---|
 | `runtime.generic` | 任何能加载 `core_skills` 并接受任务包的 Agent | 通用会话 / 人设 / system prompt |
-| `runtime.skill-projection` | `yss-skill-registry.yaml` 的 `agent_runtime_roots`（claude、codex、cursor、hermes、pi、qoder、trae） | 投影技能 + subagent 任务包 |
+| `runtime.skill-projection` | `yss-skill-registry.yaml` 的 `agent_runtime_roots`（claude、codex、cursor、pi、qoder、trae） | 投影技能 + subagent 任务包 |
 | `runtime.grok` | Grok Bot | 持久 Bot、群聊或 1:1 交接；群超过 6 人改 1:1，不改逻辑协作组 |
 
 新增平台：先加 `runtimes` 条目，再写适配说明。不要把平台限制写进 `roles`。

package/template/docs/agents/digital-human-roles.yaml

@@ -44,7 +44,7 @@ runtimes:
     side_effect_approval: biological-human
     notes: >-
       覆盖 docs/agents/yss-skill-registry.yaml 的 agent_runtime_roots
-      （claude / codex / cursor / hermes / pi / qoder / trae）。
+      （claude / codex / cursor / pi / qoder / trae）。
       技能仍从 .agents/skills 投影，不按职称再维护一份。
   - id: runtime.grok
     kind: grok-bot
@@ -68,7 +68,7 @@ orchestrator:
   title: YSS 生命周期主控
   default_dual_hat: [role.project-manager]
   stages: [stage.entry-triage, stage.discovery, stage.spec-architecture, stage.product-design, stage.system-data-engineering, stage.ticket-formalization, stage.vertical-slice-implementation, stage.verification-release-retrospective]
-  core_skills: [yss-product-lifecycle, yss-router]
+  core_skills: [yss-product-lifecycle, yss-implementation-contract-compiler]
   forbidden_skills: [yss-domain, yss-ui, yss-page-module-development, yss-web-controller, yss-repository, implement]
   description: >-
     Own YSS lifecycle routing. Read yss-project.yaml and CONTEXT.md first.
@@ -86,7 +86,7 @@ roles:
     title: YSS 需求经理
     stages: [stage.discovery, stage.spec-architecture]
     draft_artifact_ids: [artifact.discovery-record, artifact.spec]
-    core_skills: [grilling, domain-modeling, research, competitive-intelligence, grill-with-docs]
+    core_skills: [grilling, domain-modeling, yss-research, competitive-intelligence, grill-with-docs]
     forbidden_skills: [yss-ui, yss-domain, yss-web-controller, yss-repository, yss-ddd-scaffold-generator, yss-frontend-scaffold-generator, implement, tdd]
     description: >-
       Own Discovery language, users, MVP, non-goals, success criteria, test
@@ -101,7 +101,7 @@ roles:
     title: YSS 产品经理
     stages: [stage.discovery, stage.spec-architecture, stage.product-design, stage.verification-release-retrospective]
     draft_artifact_ids: [artifact.product-overview, artifact.functional-architecture, artifact.interaction-spec, artifact.state-matrix, artifact.prototype-confirmation]
-    core_skills: [yss-design-system, yss-prototype-stage, prototype-review, yss-antd-design, research, competitive-intelligence]
+    core_skills: [yss-design-system, yss-prototype-stage, prototype-review, yss-antd-design, yss-research, competitive-intelligence]
     forbidden_skills: [yss-ui, yss-domain, yss-repository, yss-web-controller, yss-ddd-scaffold-generator, implement, tdd]
     description: >-
       Own priority, product-design impact, interaction, state matrix, prototype
@@ -152,7 +152,7 @@ roles:
     title: YSS 后端工程师
     stages: [stage.system-data-engineering, stage.ticket-formalization, stage.vertical-slice-implementation, stage.verification-release-retrospective]
     draft_artifact_ids: [artifact.openapi-draft, artifact.data-architecture]
-    core_skills: [yss-router, yss-tactical-design, yss-domain, yss-application, yss-repository, yss-mybatis, yss-web-controller, yss-dto, mapstruct, lombok, alibaba-java-code-style, yss-exception, yss-validation, tdd, yss-ddd-scaffold-generator]
+    core_skills: [yss-implementation-contract-compiler, yss-tactical-design, yss-domain, yss-application, yss-repository, yss-mybatis, yss-web-controller, yss-dto, mapstruct, lombok, alibaba-java-code-style, yss-exception, yss-validation, tdd, yss-ddd-scaffold-generator]
     forbidden_skills: [yss-ui, yss-page-module-development, yss-formily, yss-frontend-scaffold-generator, yss-antd-design, page-list-module, page-form-module]
     description: >-
       Own OpenAPI Draft, data-architecture contributions, and backend tests.

package/template/docs/agents/skill-migrations.md

@@ -2,15 +2,28 @@
 
 本文记录已退役技能入口的迁移路径。退役技能不保留物理目录、投影或 lock 条目；本文件是历史名称的唯一持久兼容说明。
 
+## 实现合同与源码索引技能硬替换（2026-09-04）
+
+`yss-router` 已由 `yss-implementation-contract-compiler` 硬替换；`yss-source-index` 已由 `yss-skill-source-index-refresh` 硬替换。两个旧 ID 不保留 alias、兼容目录、投影或 lock 条目，也不能作为 Recipe、合同、模板或脚本的正向输入。
+
+同步升级内容：
+
+- 技能注册表和调用者使用新 canonical ID；Registry、编译器合同、Slice Implementation Contract 与 YSS Skill Execution Result 使用 schema v2。
+- Recipe 只引用 dotted capability；类型化依赖只由 `docs/agents/yss-skill-registry.yaml` 持有。
+- 旧 schema v1 输入明确拒绝并返回迁移提示，不自动升级。
+- 历史冻结证据和不可变候选快照不改写。旧 ID 仅可继续出现在本迁移记录、`OBSOLETE` 阻断集合及负向测试中。
+
 ## high-fidelity-html-prototype
 
-`high-fidelity-html-prototype` 已退役，不再作为 Router alias、默认发现入口或独立物理技能存在。
+`high-fidelity-html-prototype` 已退役，不再作为 实现合同编译器 alias、默认发现入口或独立物理技能存在。
 
-迁移到：
+新工作迁移到：
 
 - 阶段合同：`yss-prototype-stage`
-- Codex 产品设计主入口：`product-design:index`
-- Ant Design v6 事实与 CLI 证据：`yss-antd-design`
+- 原型档位与主入口：`yss-prototype-stage` 的 H1/H2 路由
+- Codex 产品设计能力：按档位条件使用 `product-design:index`
+- Ant Design v6 事实与 CLI：仅相关 H2 使用 `yss-antd-design`
+- 真实组件核验：不属于原型档位；进入已批准切片后由 `yss-ui` 基于目标 lockfile 执行，并写入前端实现验证
 - 独立低保真评审：`prototype-review`
 
-迁移时保留原型评审记录、AntD CLI 验证、浏览器验证和用户确认，并由 `yss-product-lifecycle` 裁决 `gate.prototype-reviewed`、`gate.prototype-verified` 和 `gate.user-confirmation`。不得创建同名兼容目录。
+已关闭的 schema v1/v2、旧 artifact ID、AntD CLI、浏览器验证和确认记录只读保留。在途工作迁移到 schema v3 与 `artifact.prototype-deliverable` 后再关闭门禁；不得创建同名兼容目录或删除历史证据。

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

@@ -5,9 +5,9 @@
 ## 权威内容与投影
 
 - `.agents/skills` 是跨 Agent 共享技能的唯一权威内容。
-- `.claude/skills`、`.codex/skills`、`.cursor/skills`、`.hermes/skills`、`.pi/skills`、`.qoder/skills`、`.trae/skills` 中的同名共享技能是生成投影，不得分别手工修改。
+- `.claude/skills`、`.codex/skills`、`.cursor/skills`、`.pi/skills`、`.qoder/skills`、`.trae/skills` 中的同名共享技能是生成投影，不得分别手工修改。
 - Cursor 的契约运行时入口是 `.cursor/skills`。若客户端同时枚举 `.claude/skills`，仍以 `.cursor/skills` 为 Cursor 投影契约，不得把两套同名 skill 解释为两个来源。
-- 分层、别名和默认可发现性以 `docs/agents/yss-skill-registry.yaml` 为准；当前 registry 为 `active`，Router、生命周期编排器和实例发现面必须消费通过校验的 canonical 技能及其 alias 解析结果。
+- 分层、别名和默认可发现性以 `docs/agents/yss-skill-registry.yaml` 为准；当前 registry 为 `active`，实现合同编译器、生命周期编排器和实例发现面必须消费通过校验的 canonical 技能及其 alias 解析结果。
 - 只属于某个平台的 skill 继续保留在对应 root，并由 `skills-lock.json` 的 `platform` 分组记录。
 - 共享技能投影可以是指向权威目录的符号链接，也可以是完整同步副本；`scripts/sync-skills --check` 会检查链接目标或完整目录哈希。
 
@@ -31,7 +31,7 @@
 
 当前 Matt 快照为 `0ab1b63a410a03d3627979a109c8695de27af954`。`ask-matt` 的关联入口包括 `to-questionnaire`、`wait-what`、`writing-for-agents` 和 `PHASE-BOUNDARIES.md`；这些支持文件随共享 skill 目录一起计算 `effectiveHash`，不得单独投影或维护。
 
-本轮升级还将生命周期适配固定为：阶段边界只写可选 `phase_boundary` 证据；`to-questionnaire` 使用 `external-input-required` 暂停并在答案回流后重新分类影响面；Matt `prototype` 使用 `prototype/<name>` 分支和单文件 HTML，YSS 高保真原型继续执行 Prototype Review、AntD CLI 校验和用户确认。人工 checkpoint 与 `diagnosing-bugs` 的输出必须脱敏，`wait-what` 不改变生命周期状态。
+本轮升级还将生命周期适配固定为：阶段边界只写可选 `phase_boundary` 证据；`to-questionnaire` 使用 `external-input-required` 暂停并在答案回流后重新分类影响面；Matt `prototype` 的单文件 HTML 只作为回流输入，YSS 原型仍须完成低保真评审、H1/H2 档位路由、schema v3 验证和用户确认。人工 checkpoint 与 `diagnosing-bugs` 的输出必须脱敏，`wait-what` 不改变生命周期状态。
 
 ## 维护流程
 

package/template/docs/agents/strategic-design-skills-integration.md

@@ -0,0 +1,41 @@
+# 战略设计技能集成合同
+
+`iloveZzz/yss-harness-design-agent` 是以下公共技能 ID 的上游业务 profile：
+
+- `prototype-review`
+- `yss-prototype-stage`
+- `yss-design-system`
+- `yss-antd-design`
+- `yss-stage-decision`
+
+父模板通过 `.agents/skills/.strategic-design-skills-manifest.json` 固定上游 Git revision、路径和 tree hash。公共 ID 不因 profile 改名；共享规则先在战略设计源仓演进，再由父模板同步。
+
+## 父模板薄适配
+
+父模板承载完整产品研发生命周期，只允许在以下位置保留最小语境差异：
+
+| 技能 | 父模板适配 |
+|---|---|
+| `prototype-review` | 将评审结论回交 `yss-product-lifecycle`，通过后可进入实现合同编译准备 |
+| `yss-prototype-stage` | 用户确认后由完整生命周期判断 API 影响和实现准备 |
+| `yss-stage-decision` | 门禁状态由 `yss-product-lifecycle` 维护 |
+
+`yss-design-system` 与 `yss-antd-design` 当前不需要父模板内容适配，必须与锁定的上游 tree hash 一致。任何有效内容差异都必须保留本文件为 `adaptationRef`，不得复制成第二套公共技能身份。
+
+## 更新与验证
+
+1. 先在战略设计源仓形成并推送固定 commit。
+2. 更新 manifest 的 `source_revision` 和每项 `upstream_hash`。
+3. 同步父模板 canonical 内容，仅重放上表允许的薄适配。
+4. 运行 `scripts/update-skill-lock`、`scripts/sync-skills`。
+5. 运行：
+
+   ```bash
+   scripts/verify-upstream-skill-source \
+     --source=iloveZzz/yss-harness-design-agent \
+     --source-root=submodules/yss-harness-design-agent
+   scripts/verify-skill-governance
+   scripts/verify-template-fast
+   ```
+
+父模板、战略设计源仓与 CLI 快照必须按源仓 → 父模板 → CLI 顺序固定 revision；旧实例不回填，也不提供迁移检查器。