create-yss-spec 2.2.9 → 3.0.0

package/template/docs/agents/yss-ui-skills-integration.md

@@ -0,0 +1,24 @@
+# YSS UI 前端 Skills 集成合同
+
+本模板以 `iloveZzz/yss-ui` 的 `packages/skills` 为上游来源，以 `.agents/skills/.yss-skills-manifest.json` 冻结来源 revision、包版本、目录映射和上游树哈希。`.agents/skills` 仍是模板内跨 Agent 共享内容的唯一权威目录；其他 Agent root 只接收生成投影。
+
+## 范围
+
+- 只集成 yss-ui `skills.config.json` 中 `categories.app` 的业务项目 skills，并排除后端 `java-backend-commit`，当前共 22 个。
+- `categories.library` 的 10 个组件库内部维护 skills 全部不进入模板；该分组同时位于上游 `excludeFromDefaultSync`。
+- `api-integration`、`page-module-development`、`use-table-height`、`use-tree-height` 在模板中分别映射为 `yss-api-integration`、`yss-page-module-development`、`yss-use-table-height`、`yss-use-tree-height`，旧名称只作为 registry alias。
+- `java-backend-commit` 明确不属于本合同；其内容、路由与锁定信息不随本前端同步更新。
+- 允许模板基于生命周期、组件路由和证据门禁做受控适配；适配后的 `effectiveHash` 与上游 `upstreamHash` 同时进入 `skills-lock.json`。
+
+## 更新步骤
+
+1. 在临时 checkout 中确认 `iloveZzz/yss-ui` 的目标 revision，并更新 `.agents/skills/.yss-skills-manifest.json`。
+2. 将新增或替换内容只写入 `.agents/skills/<canonical-name>`，不得直接编辑平台投影。
+3. 新增 skill 使用 `scripts/update-skill-lock --add=<canonical-name>` 显式登记。
+4. 运行 `scripts/sync-skills` 与 `scripts/update-skill-lock`。
+5. 使用 `scripts/verify-upstream-skill-source --source=iloveZzz/yss-ui --source-root=<checkout>` 验证 revision、清单和树哈希。
+6. 执行 `scripts/verify-template-fast`；首次冻结或正式发布前执行 `scripts/verify-template`。
+
+## MCP
+
+项目级 MCP 配置路径和容器字段同样由 manifest 固定，配置内容必须使用 `npx -y @yss-ui/mcp`。需要全局配置的运行时只提供人工安装说明，模板不得自动修改用户主目录。

package/template/docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md

@@ -7,4 +7,5 @@ Matt Pocock Engineering Skills 提供轻量的澄清、实现、TDD、诊断和
 - Matt user-invoked 的 `grill-with-docs`、`to-spec`、`to-tickets` 和 `implement` 必须由用户显式启动，任何 skill 不得自动调用它们；YSS 生命周期只准备、校验和验收其结果。所有 Matt model-invoked skill 仍须遵守 `AGENTS.md` 的阶段、门禁和证据要求，并只能在生命周期允许的工作单元中调用。
 - `code-review` 保持唯一默认审查入口。YSS 适配把 Slice `required_skills`、`alibaba-java-code-style` 与命中的 `yss-ui` / `yss-domain` 等专项 skill 编译为 Standards 检查输入，并要求实现仓已有的 `pnpm` / `./mvnw` 机器检查；禁止再增加第二个通用审查 skill 或专用审查 Cloud 环境来代替这条接线。审查 finding 按编排合同分流：实现者修复后全轴复审，或合同 `stale` 后回 Router；审查者不得写实现。
 - `template-source` 只执行模板维护流程，不生成具体产品 Spec、原型、OpenAPI 或垂直切片 Ticket。
+- Matt 的 `research` 已适配为 canonical `yss-research`，旧名只作为 deprecated alias。YSS 版本提供 `technical-evidence` / `strategy-evidence` profile、`quick` / `evidence-audited` 模式、证据合同和确定性校验，同时保留上游 revision 与原始 hash 以便追溯。
 - Agent 完成工作单元后返回可核验的 evidence refs、变更资产、验证命令、残余风险和下一路由。

package/template/docs/process/template-verification-profiles.yaml

@@ -38,7 +38,16 @@ required_files:
   - AGENTS.md
   - CONTEXT.md
   - skills-lock.json
+  - .agents/skills/.yss-skills-manifest.json
+  - .mcp.json
+  - .agents/mcp_config.json
+  - .cursor/mcp.json
+  - .gemini/settings.json
+  - .kiro/settings/mcp.json
+  - .vscode/mcp.json
   - docs/agents/yss-skill-registry.yaml
+  - docs/agents/yss-ui-skills-integration.md
+  - docs/user-guide/yss-ui-mcp.md
   - docs/agents/digital-human-roles.yaml
   - docs/process/lifecycle-registry.yaml
   - docs/process/lifecycle-registry-baseline.json
@@ -138,6 +147,8 @@ routing:
     groups: [governance-release]
   - patterns: [skills-lock.json, ".agents/skills/**", ".claude/skills/**", ".codex/skills/**", ".cursor/skills/**", ".hermes/skills/**", ".pi/skills/**", ".qoder/skills/**", ".trae/skills/**", "docs/agents/yss-skill-registry.yaml", "docs/agents/skills-maintenance.md", "scripts/*skill*"]
     groups: [skills]
+  - patterns: [.mcp.json, .agents/mcp_config.json, .cursor/mcp.json, .gemini/settings.json, .kiro/settings/mcp.json, .vscode/mcp.json, docs/user-guide/yss-ui-mcp.md, docs/agents/yss-ui-skills-integration.md]
+    groups: [skills]
   - patterns: ["docs/process/maintenance-*", "docs/process/harness-process-tailoring.md", "docs/process/schemas/maintenance-*", "scripts/*maintenance*", "scripts/lib/maintenance-*"]
     groups: [maintenance]
   - patterns: ["docs/process/lifecycle-*", "docs/process/templates/lifecycle-*", "scripts/*lifecycle*", "scripts/lib/lifecycle-*"]

package/template/docs/templates/implementation-routing-template.md

@@ -40,7 +40,7 @@ owner: ai
 | Harness 内项目根路径符合 `apps/<backend|frontend>/<project>/` | 是 / 否 / 不适用 | `apps/backend/`、`apps/frontend/` 仅为容器 |
 | 未使用 `app/backend/`、`app/frontend/` 及其子路径 | 是 / 否 / 不适用 | 命中即阻断生成和实现 |
 | 原型确认后先完成后端脚手架，再进入业务代码路由 | 是 / 否 / 不适用 | `backend_scaffold_policy_satisfied` |
-| 后端脚手架合同字段完整且版本当前 | 是 / 否 / 不适用 | `contract_id`、`contract_version`、Router draft、生命周期批准、持久化引用、允许写路径、预期证据、验证命令 |
+| 后端脚手架合同字段完整且版本当前 | 是 / 否 / 不适用 | schema v2：`scaffold_request_id`、项目/输出目录、Router draft、生命周期批准、base package、Maven 坐标、target DDD/Profile、initialize-only、允许写路径、预期证据、验证命令 |
 | 后端构建 / 测试 / OpenAPI / CI 命令均使用项目根目录 `./mvnw ...`，或已记录受控例外 | 是 / 否 / 不适用 | 裸 `mvn ...` 默认为规范偏离 |
 | 持久化文档正文和章节标题已转换为中文，仅保留必要英文技术标识 / metadata | 是 / 否 | 英文 skill / 模板不得原样落地为交付文档 |
 | YSS skill 路由已完成 | 是 / 否 |  |
@@ -245,10 +245,12 @@ owner: ai
 | 前置 | `prototype_confirmation`、工程基线、实现仓库和脚手架目标已确认；Router 脚手架合同 draft 已经生命周期批准并持久化为结构化 JSON，生成器通过 `--contract-file` 消费 |
 | 生成器 | `yss-ddd-scaffold-generator` |
 | 模式 | `controlled-generation` |
+| Java / Maven 身份 | `base_package` 与 Maven `group_id` 分开登记；项目版本、父 POM GAV、`yss-components.version` 进入批准合同并原样传给 CLI |
 | 允许生成 | Domain / Application / Infrastructure / Adapter / Bootstrap 目录骨架、POM、配置、Wrapper 和非业务机械模板 |
 | 禁止生成 | 业务规则、状态机、权限、事务、复杂查询、错误映射、业务字段和用户可见行为 |
-| 生成选项 | 关闭 `--with-example`；非空目录 `--force` 默认阻断，覆盖范围、备份、回滚点和批准引用齐全后才能单独审查 |
-| 验证 | 受控验证器实际执行项目根目录 `./mvnw validate`、`./mvnw test`、`./mvnw package`，逐条记录 `exit_code`、`duration_ms`、stdout/stderr 引用和执行时间；打印命令不算证据 |
+| 生成选项 | 关闭 `--with-example`；生成器严格 initialize-only，非空目录、`--force`、旧项目迁移和当前模板升级均为 `unsupported` |
+| Profile | `target-domain-model` / `mybatis-plus` / `mysql` / `spring-boot-2.7-jdk8` / `javax` / `web` / `yss-internal`；其他组合须先通过独立 fixture |
+| 验证 | 使用一键生成验证入口，实际执行项目根目录 `./mvnw validate`、`./mvnw test`、`./mvnw package`；通过后仅为 `empty-scaffold-verified`，golden first slice 通过后才是 `first-slice-verified` |
 | 后置 | `yss-backend-scaffold-parent`、`yss-router` 业务合同重编译、YSS Skill Execution Result |
 
 所有后续生成代码必须绑定当前批准且版本一致的 Slice Implementation Contract、主 YSS skill、依赖闭包、允许写路径、预期证据和 Execution Result。业务行为必须使用 `behavior-tdd`；缺任一条件即阻断，不得以脚手架成功或时间压力豁免。

package/template/docs/templates/review-report-template.md

@@ -87,8 +87,8 @@ rg -n "class (SingleResult|MultiResult|PageResult|Result)<|public static class .
 
 | 检查项 | 结论 | 证据 |
 |---|---|---|
-| `yss-ui` 组件路由已落实：YSS `required` 封装（如 `YTable` / `YTree` / `YssFormily`）未被 AntDV 裸组件或其他重型方案绕过；受控回退有能力缺口记录 | pass / violation / not-applicable |  |
-| `yss-page-module-development` 页面骨架已落实：`index.vue` 只编排，请求与分页不堆在页面根组件 | pass / violation / not-applicable |  |
+| `yss-ui` 组件路由已落实：YSS `required` 封装（如 `YTable` / `YTree` / `YFormily`）未被 AntDV 裸组件或其他重型方案绕过；受控回退有能力缺口记录 | pass / violation / not-applicable |  |
+| `yss-ui-business-page-generation` 页面生成与 `yss-page-module-development` 生命周期编排已落实：`index.vue` 只编排，请求与分页不堆在页面根组件 | pass / violation / not-applicable |  |
 | 切片合同 `required_skills` 中的 Formily / 表格 / 树 / 高度 / 主题 / API 专项 skill 已按影响面引用规则；未命中项有 `not-applicable` 原因 | pass / violation / not-applicable |  |
 | 前端验证使用项目根 `pnpm ...`；实际退出码已记录。只做 type-check 或声称“已对齐”不算通过 | pass / violation / not-applicable |  |
 | 机器检查（`pnpm lint` / `pnpm type-check` 等已存在脚本）已执行，或缺失工具已写 `not-applicable` 及原因 | pass / violation / not-applicable |  |

package/template/docs/user-guide/yss-ui-mcp.md

@@ -0,0 +1,43 @@
+# YSS UI MCP 接入
+
+模板已为支持项目级 MCP 配置的客户端预置 `yss-ui` server：
+
+- Claude Code：`.mcp.json`
+- Antigravity：`.agents/mcp_config.json`
+- Cursor：`.cursor/mcp.json`
+- Gemini CLI：`.gemini/settings.json`
+- Kiro：`.kiro/settings/mcp.json`
+- VS Code：`.vscode/mcp.json`
+
+这些配置统一通过 `npx -y @yss-ui/mcp` 启动，不写用户主目录，也不覆盖个人全局配置。首次加载模板后，重启或刷新对应客户端即可发现 MCP。
+
+## Codex 等全局配置客户端
+
+需要写入用户级配置的客户端不由模板自动修改。以 Codex 为例，由使用者明确执行：
+
+```bash
+npx -y @yss-ui/mcp install codex
+```
+
+其他客户端的安装参数以 `@yss-ui/mcp` 当前 CLI 帮助为准。模板只提供说明，不替用户修改 `~/.codex/config.toml` 等全局文件。
+
+## 使用门禁
+
+生成或审查 YSS UI 页面时：
+
+1. 先调用 `get_codegen_rules` 获取当前代码生成约束。
+2. 不确定组件导出时调用 `list_components`。
+3. 配置组件、Hook 或 Utils 前调用 `get_component_docs`。
+4. 复杂场景调用 `get_demo`；无法确定归属时调用 `search_docs`。
+
+本次模板验证基线为 `@yss-ui/mcp@0.1.8`、YSS UI components `1.5.18`，MCP 对外提供 7 个工具。运行时返回值与项目 lockfile 仍优先于本文快照；MCP 不可用时，按 `AGENTS.md` 读取 `llms-full.txt`，并明确记录降级原因。
+
+## 快速自检
+
+客户端中至少确认以下结果：
+
+- `list_components` 能返回 YSS UI 组件清单。
+- `get_codegen_rules` 能返回当前生成规则。
+- 查询 `YTable` 时，`get_component_docs` 能返回对应文档。
+
+MCP 无法启动时，先确认 Node.js、`npx` 和网络/私有源访问，再直接运行 `npx -y @yss-ui/mcp` 查看启动错误；不要把 Registry 认证内容写入日志或提交到仓库。

package/template/docs/user-guide//347/224/250/346/210/267/346/211/213/345/206/214.md

@@ -536,7 +536,7 @@ Agent 应返回合同版本、修改文件、实际命令、退出码和证据
 | 已确认 | 已由业务方、产品或权威资料确认 | 可以进入后续文档 |
 | 待确认 | 暂时没有答案 | 写负责人和确认时间，不让 Agent 猜 |
 | 非目标 | 本次明确不做 | 用来控制范围 |
-| 外部事实 | 来自法规、第三方 API、竞品或技术资料 | 用 `research` 或 `competitive-intelligence` 核对 |
+| 外部事实 | 来自法规、第三方 API、竞品或技术资料 | 用 `yss-research` 或 `competitive-intelligence` 核对；`research` 仅为兼容旧名 |
 | 猜测 | 还没有人确认的推测 | 保持为待确认 |
 
 ### 处理稳定术语

package/template/scripts/lib/scenario-checks.mjs

@@ -24,7 +24,7 @@ function validateMattContract(data) {
   ensure(includesAll(setup?.preserves, ["lifecycle.status", "gate.status", "ticket.role"]) && setup?.legacy_artifacts_detected?.action === "migration-check" && setup.legacy_artifacts_detected.setup === "forbidden" && setup.legacy_artifacts_detected.write === "paused", "setup 暂停或旧资产迁移暂停契约不完整");
   const grill = data.grill_exit;
   ensure(includesAll(grill?.required, ["frontier_empty", "facts_resolved_or_routed", "decisions_confirmed", "shared_understanding_confirmed", "no_unresolved_runnable_blocker"]) && grill?.user_confirmation_required === true, "grill_exit 缺少 frontier、事实路由、决策、共同理解、用户确认或 runnable blocker 条件");
-  ensure(grill?.facts_resolved_or_routed?.technical_fact === "research" && grill.facts_resolved_or_routed.runnable_question === "handoff-prototype-handoff" && grill.facts_resolved_or_routed.external_decision === "external-input-required", "grill_exit 的事实、runnable 问题或外部决策路由不完整");
+  ensure(grill?.facts_resolved_or_routed?.technical_fact === "yss-research" && grill.facts_resolved_or_routed.runnable_question === "handoff-prototype-handoff" && grill.facts_resolved_or_routed.external_decision === "external-input-required", "grill_exit 的事实、runnable 问题或外部决策路由不完整");
   const git = data.git_authorization;
   for (const action of ["commit", "push"]) {
     const prefix = action === "commit" ? "commit" : "push";
@@ -40,13 +40,13 @@ function validateMattContract(data) {
 function validateInvocationBoundary(data) {
   const boundary = data.matt_invocation_boundary;
   const expectedUserInvoked = ["ask-matt", "grill-me", "grill-with-docs", "handoff", "implement", "improve-codebase-architecture", "loop-me", "setup-matt-pocock-skills", "setup-ts-deep-modules", "teach", "to-questionnaire", "to-spec", "to-tickets", "triage", "wait-what", "wayfinder", "writing-beats", "writing-fragments", "writing-shape"];
-  const expectedModelInvoked = ["code-review", "codebase-design", "diagnosing-bugs", "domain-modeling", "grilling", "migrate-to-shoehorn", "prototype", "research", "resolving-merge-conflicts", "scaffold-exercises", "setup-pre-commit", "tdd", "writing-for-agents"];
-  const expectedLifecycleModelInvoked = ["code-review", "codebase-design", "diagnosing-bugs", "domain-modeling", "grilling", "prototype", "research", "tdd"];
+  const expectedModelInvoked = ["code-review", "codebase-design", "diagnosing-bugs", "domain-modeling", "grilling", "migrate-to-shoehorn", "prototype", "resolving-merge-conflicts", "scaffold-exercises", "setup-pre-commit", "tdd", "writing-for-agents", "yss-research"];
+  const expectedLifecycleModelInvoked = ["code-review", "codebase-design", "diagnosing-bugs", "domain-modeling", "grilling", "prototype", "tdd", "yss-research"];
   ensure(JSON.stringify(boundary?.user_invoked_skills) === JSON.stringify(expectedUserInvoked), "Matt user-invoked skills 清单不完整或已漂移");
   ensure(JSON.stringify(boundary?.lifecycle_managed_user_entries) === JSON.stringify(["setup-matt-pocock-skills", "grill-with-docs", "to-spec", "to-tickets", "implement"]), "生命周期管理的显式用户入口清单不完整");
   ensure(boundary?.lifecycle_may_invoke_user_invoked === false && boundary?.formal_artifact_owner === "explicit-user-entry", "生命周期仍可能自动调用 user-invoked skill 或产出其正式资产");
   ensure(JSON.stringify(boundary?.model_invoked_skills) === JSON.stringify(expectedModelInvoked) && JSON.stringify(boundary?.lifecycle_allowed_model_invoked_skills) === JSON.stringify(expectedLifecycleModelInvoked) && boundary?.continuous_orchestration === "compatibility-prepare-and-validate-only", "Matt invocation inventory 或生命周期 model-invoked 白名单不完整");
-  ensure(JSON.stringify(data.skill_source_contract?.source_revisions_required) === JSON.stringify(["mattpocock/skills"]) && data.skill_source_contract?.adaptation_ref_required_when_effective_diff === true && data.skill_source_contract?.retired_shared_skills?.includes("batch-grill-me"), "上游来源或退役 skill 供应链契约不完整");
+  ensure(JSON.stringify(data.skill_source_contract?.source_revisions_required) === JSON.stringify(["mattpocock/skills", "iloveZzz/yss-ui"]) && data.skill_source_contract?.adaptation_ref_required_when_effective_diff === true && data.skill_source_contract?.retired_shared_skills?.includes("batch-grill-me"), "上游来源或退役 skill 供应链契约不完整");
   validateInvocationMetadata(boundary, (skill) => read(`.agents/skills/${skill}/SKILL.md`));
   const setup = data.setup_readiness;
   ensure(setup?.missing_action === "needs-human" && setup?.requested_skill === "setup-matt-pocock-skills" && setup?.resume_route === "setup-readiness" && setup?.preserves?.includes("lifecycle.status"), "readiness=missing 未形成显式用户 setup 的结构化暂停");
@@ -59,10 +59,14 @@ function validateInvocationBoundary(data) {
   ensure(JSON.stringify(native?.user_confirmation_required_at) === JSON.stringify(["spec-baseline", "prototype-confirmation", "openapi-freeze", "merge-or-release"]), "生命周期人工门禁集合已漂移");
   const routes = data.work_unit_routes;
   ensure(routes?.["work-unit.discovery-requirements"]?.skills?.includes("grilling") && routes?.["work-unit.discovery-requirements"]?.skills?.includes("domain-modeling"), "需求分析工作单元缺少 grilling/domain-modeling");
-  ensure(routes?.["work-unit.discovery-opportunity"]?.route_by?.market_or_competitor_fact === "competitive-intelligence" && routes["work-unit.discovery-opportunity"].route_by.technical_or_standard_fact === "research", "机会调研事实路由不准确");
-  ensure(routes?.["work-unit.slice-implementation"]?.skills?.includes("tdd") && routes?.["work-unit.slice-implementation"]?.skills?.includes("yss-ui"), "原生实现工作单元缺少 TDD 或 UI 路由");
+  ensure(routes?.["work-unit.discovery-opportunity"]?.route_by?.market_or_competitor_fact === "competitive-intelligence" && routes["work-unit.discovery-opportunity"].route_by.technical_or_standard_fact === "yss-research:technical-evidence" && routes["work-unit.discovery-opportunity"].route_by.strategy_fact === "yss-research:strategy-evidence", "机会调研事实路由不准确");
+  const strategyResearch = routes?.["work-unit.domain-strategy-design"]?.research_contract;
+  ensure(strategyResearch?.profile === "strategy-evidence" && strategyResearch.mode_before_gate === "evidence-audited" && strategyResearch.artifact_owner === "yss-research" && strategyResearch.downstream_owner === "yss-stage-decision", "领域战略研究合同缺少 profile、门禁前审计或资产所有权边界");
+  const stageDecisionResearch = routes?.["work-unit.stage-decision"]?.research_contract;
+  ensure(routes?.["work-unit.stage-decision"]?.skills?.includes("yss-research") && stageDecisionResearch?.profile === "strategy-evidence" && stageDecisionResearch.mode_before_gate === "evidence-audited" && stageDecisionResearch.artifact_owner === "yss-research" && stageDecisionResearch.downstream_owner === "yss-stage-decision", "阶段决策工作单元缺少 evidence-audited 战略研究合同");
+  ensure(routes?.["work-unit.slice-implementation"]?.skills?.includes("tdd") && routes?.["work-unit.slice-implementation"]?.skills?.includes("yss-ui") && routes?.["work-unit.slice-implementation"]?.skills?.includes("yss-ui-business-page-generation"), "原生实现工作单元缺少 TDD、UI 或业务页面生成路由");
   const frontendRoute = routes?.["work-unit.slice-implementation"]?.frontend_route;
-  ensure(frontendRoute?.primary_skill === "yss-ui" && frontendRoute?.page_orchestration_skill === "yss-page-module-development", "前端实现路由缺少 yss-ui 主入口或页面编排技能");
+  ensure(frontendRoute?.primary_skill === "yss-ui" && frontendRoute?.page_generation_skill === "yss-ui-business-page-generation" && frontendRoute?.page_orchestration_skill === "yss-page-module-development", "前端实现路由缺少 yss-ui 主入口、业务页面生成或页面编排技能");
   for (const impact of ["api_impact", "formily_impact", "table_impact", "tree_impact", "height_impact", "export_impact", "theme_impact"]) {
     ensure(Array.isArray(frontendRoute?.conditional_skills?.[impact]) && frontendRoute.conditional_skills[impact].length > 0 && typeof frontendRoute.not_applicable_reasons?.[impact] === "string", `前端条件专项路由缺少 ${impact}`);
   }

package/template/scripts/lib/skill-governance.mjs

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { loadSkillRegistry } from "./skill-registry.mjs";
+import { validateYssUiSkillManifest } from "./skill-supply-chain.mjs";
 
 export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 
@@ -27,10 +28,43 @@ export function validateSkillGovernance({ read = (relative) => readFileSync(path
     fail("页面模块 canonical 技能缺少条件化 toolbar-config 规则");
   }
 
+  const yssUiManifest = validateYssUiSkillManifest(JSON.parse(read(".agents/skills/.yss-skills-manifest.json")));
+  const lock = JSON.parse(read("skills-lock.json"));
+  for (const skill of yssUiManifest.skills) {
+    const skillPath = `.agents/skills/${skill.canonical}/SKILL.md`;
+    if (!exists(skillPath)) fail(`yss-ui 前端清单缺少 canonical skill: ${skill.canonical}`);
+    const item = lock.skills?.shared?.[skill.canonical];
+    if (!item || item.source !== yssUiManifest.source || item.sourceRevision !== yssUiManifest.source_revision) {
+      fail(`yss-ui skill 缺少一致的来源锁定: ${skill.canonical}`);
+    }
+    if (item.skillPath !== `${yssUiManifest.source_root}/${skill.upstream}/SKILL.md` || item.upstreamHash !== skill.upstream_hash) {
+      fail(`yss-ui skill 上游路径或 hash 不一致: ${skill.canonical}`);
+    }
+    const content = read(skillPath);
+    for (const match of content.matchAll(/\.\.\/([a-z0-9-]+)\/SKILL\.md/g)) {
+      if (!exists(`.agents/skills/${match[1]}/SKILL.md`)) fail(`${skill.canonical} 引用了不存在的本地 skill: ${match[1]}`);
+    }
+  }
+  const yssUiSkill = read(".agents/skills/yss-ui/SKILL.md");
+  if (!yssUiSkill.includes("`YFormily` 是新代码 canonical name")) fail("yss-ui 必须把 YFormily 声明为新代码 canonical name");
+  if (!yssUiSkill.includes("| 新建或改造完整业务页面 | `yss-ui-business-page-generation` |")) fail("yss-ui 缺少完整业务页面生成路由");
+  const expectedServer = { command: "npx", args: ["-y", "@yss-ui/mcp"] };
+  for (const config of yssUiManifest.mcp.project_configs) {
+    if (!exists(config.path)) fail(`缺少 yss-ui MCP 项目配置: ${config.path}`);
+    const document = JSON.parse(read(config.path));
+    if (JSON.stringify(document?.[config.container]?.[yssUiManifest.mcp.server_name]) !== JSON.stringify(expectedServer)) {
+      fail(`yss-ui MCP 配置不一致: ${config.path}`);
+    }
+  }
+  const mcpGuide = read(yssUiManifest.mcp.global_install_guide);
+  for (const marker of ["npx -y @yss-ui/mcp install codex", "不写用户主目录", "get_codegen_rules", "list_components"]) {
+    if (!mcpGuide.includes(marker)) fail(`YSS UI MCP 指南缺少边界或自检标记: ${marker}`);
+  }
+
   const registry = loadSkillRegistry();
   const canonicalIds = new Set(registry.skills.map((skill) => skill.id));
   const aliases = new Map(registry.skills.flatMap((skill) => skill.aliases.map((alias) => [alias, skill.id])));
-  const legacy = new Set(["api-integration", "page-module-development", "use-table-height", "use-tree-height", "yss-ui-business-page-generation"]);
+  const legacy = new Set(["api-integration", "page-module-development", "use-table-height", "use-tree-height"]);
   for (const alias of legacy) {
     if (exists(`.agents/skills/${alias}`)) fail(`legacy alias 不得存在独立 canonical 目录: ${alias}`);
     if (!aliases.has(alias)) fail(`legacy alias 未登记: ${alias}`);
@@ -65,5 +99,5 @@ export function validateSkillGovernance({ read = (relative) => readFileSync(path
       }
     }
   }
-  return { checked: true, legacy_aliases: legacy.size };
+  return { checked: true, legacy_aliases: legacy.size, yss_ui_skills: yssUiManifest.skills.length };
 }

package/template/scripts/lib/skill-registry.mjs

@@ -58,6 +58,19 @@ function requireStringArray(value, field, { nonEmpty = false } = {}) {
   }
 }
 
+function effectiveInvocationContract(registry, skill) {
+  const contract = registry.invocation_contract;
+  return {
+    ...contract.default,
+    ...contract.layer_defaults[skill.layer],
+    ...(contract.overrides[skill.id] ?? {})
+  };
+}
+
+function sameStringSet(left, right) {
+  return JSON.stringify([...new Set(left)].sort()) === JSON.stringify([...new Set(right)].sort());
+}
+
 function validateInvocationContract(registry, skill) {
   const contract = registry.invocation_contract;
   requireObject(contract, "invocation_contract");
@@ -102,11 +115,7 @@ function validateInvocationContract(registry, skill) {
   const overrideIds = Object.keys(contract.overrides);
   const knownIds = new Set(registry.skills.map((item) => item?.id).filter(Boolean));
   for (const skillId of overrideIds) if (!knownIds.has(skillId)) fail(`invocation_contract.overrides 引用了未登记技能: ${skillId}`);
-  const effective = {
-    ...contract.default,
-    ...contract.layer_defaults[skill.layer],
-    ...(contract.overrides[skill.id] ?? {})
-  };
+  const effective = effectiveInvocationContract(registry, skill);
   effective.trigger_conditions = [...new Set([...(effective.trigger_conditions ?? []), ...skill.impacts.map((impact) => `impact:${impact}`)])];
   if (!INVOCATION_MODES.has(effective.invocation_mode)) fail(`${skill.id}.invocation_mode 无效`);
   requireStringArray(effective.trigger_conditions, `${skill.id}.trigger_conditions`, { nonEmpty: true });
@@ -317,6 +326,23 @@ export function validateSkillRegistry(registry, { lock, routerContract, lifecycl
     }
   }
 
+  const registeredDependency = (name) => ids.has(name)
+    || aliases.has(name)
+    || externalIds.has(name)
+    || platformAliases.has(name)
+    || [...platformIds].some((key) => key.endsWith(`:${name}`));
+  for (const skill of skills) {
+    const effective = effectiveInvocationContract(registry, skill);
+    const required = effective.required_dependencies ?? [];
+    const optional = effective.optional_dependencies ?? [];
+    for (const dependency of [...required, ...optional]) {
+      if (!registeredDependency(dependency)) fail(`${skill.id} 的调用契约依赖引用了未登记技能: ${dependency}`);
+      if (dependency === skill.id) fail(`${skill.id} 的调用契约不得依赖自身`);
+    }
+    const overlap = required.filter((dependency) => optional.includes(dependency));
+    if (overlap.length) fail(`${skill.id} 的必需依赖与可选依赖重复: ${overlap.join(", ")}`);
+  }
+
   if (lock) {
     const shared = Object.keys(lock.skills?.shared ?? {}).sort();
     const registered = [...ids].sort();
@@ -367,6 +393,24 @@ export function validateSkillRegistry(registry, { lock, routerContract, lifecycl
         for (const name of names ?? []) if (!ids.has(name) && !aliases.has(name) && !externalIds.has(name)) fail(`Router 依赖引用了未登记技能: ${name}`);
       }
     }
+    for (const skillId of Object.keys(registry.invocation_contract.overrides)) {
+      const closure = routerContract.dependency_closure?.[skillId];
+      if (!closure) fail(`Router dependency_closure 缺少注册表覆写技能: ${skillId}`);
+      const skill = skills.find((item) => item.id === skillId);
+      const effective = effectiveInvocationContract(registry, skill);
+      const required = effective.required_dependencies ?? [];
+      const optional = effective.optional_dependencies ?? [];
+      const always = closure.always ?? [];
+      const conditional = Object.entries(closure)
+        .filter(([condition]) => condition !== "always")
+        .flatMap(([, names]) => names ?? []);
+      if (!sameStringSet(required, always)) {
+        fail(`${skillId} 的静态必需依赖与 Router always 不一致`);
+      }
+      if (!sameStringSet(optional, conditional)) {
+        fail(`${skillId} 的可选依赖与 Router 条件依赖不一致`);
+      }
+    }
   }
 
   if (lifecycleContract || existsSync(LIFECYCLE_CONTRACT)) {
@@ -392,6 +436,7 @@ export function validateSkillRegistry(registry, { lock, routerContract, lifecycl
       }
       if (route.frontend_route) {
         requireString(route.frontend_route.primary_skill, `${routeId}.frontend_route.primary_skill`);
+        requireString(route.frontend_route.page_generation_skill, `${routeId}.frontend_route.page_generation_skill`);
         requireString(route.frontend_route.page_orchestration_skill, `${routeId}.frontend_route.page_orchestration_skill`);
         const conditional = route.frontend_route.conditional_skills;
         if (!conditional || typeof conditional !== "object" || Array.isArray(conditional)) fail(`${routeId}.frontend_route.conditional_skills 必须是对象`);
@@ -402,7 +447,7 @@ export function validateSkillRegistry(registry, { lock, routerContract, lifecycl
             fail(`${routeId}.frontend_route.not_applicable_reasons.${impact} 必须是字符串`);
           }
         }
-        if (!resolve(route.frontend_route.primary_skill) || !resolve(route.frontend_route.page_orchestration_skill)) {
+        if (!resolve(route.frontend_route.primary_skill) || !resolve(route.frontend_route.page_generation_skill) || !resolve(route.frontend_route.page_orchestration_skill)) {
           fail(`${routeId}.frontend_route 主入口引用了未登记技能`);
         }
       }

package/template/scripts/lib/skill-supply-chain.mjs

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -7,8 +7,9 @@ import { fileURLToPath } from "node:url";
 export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 const SOURCE_ROOT = path.join(ROOT, ".agents/skills");
 const LOCK_PATH = path.join(ROOT, "skills-lock.json");
+const YSS_UI_MANIFEST_PATH = path.join(SOURCE_ROOT, ".yss-skills-manifest.json");
 export const PROJECTION_ROOTS = [".claude/skills", ".codex/skills", ".cursor/skills", ".hermes/skills", ".pi/skills", ".qoder/skills", ".trae/skills"];
-export const OBSOLETE = new Set(["to-" + "prd", "to-" + "issues", "design-an-interface", "qa", "request-refactor-plan", "ubiquitous-language", "edit-article", "obsidian-vault", "writing-great-skills", "code-review-process", "yss-domain-modeling", "yss-dir", "yss-duckdb", "yss-file", "yss-filerunner", "yss-db2mybatis", "yss-mail", "yss-mapper-dynamic", "yss-quality", "yss-sql-condition", "yss-sql-tpl", "yss-valuation", "yss-variable", "yss-openapi", "web-design-engineer", "web-video-presentation", "wireframe-prototype", "wizard", "git-guardrails-claude-code", "claude-handoff", "batch-grill-me", "product-design-prototype", "yss-dictionary", "yss-jdbc", "yss-log", "yss-taskflow", "yss-backend-scaffold-application", "yss-backend-scaffold-domain", "yss-backend-scaffold-infrastructure", "yss-backend-scaffold-web"]);
+export const OBSOLETE = new Set(["to-" + "prd", "to-" + "issues", "design-an-interface", "qa", "request-refactor-plan", "ubiquitous-language", "edit-article", "obsidian-vault", "writing-great-skills", "code-review-process", "yss-domain-modeling", "yss-dir", "yss-duckdb", "yss-file", "yss-filerunner", "yss-db2mybatis", "yss-mail", "yss-mapper-dynamic", "yss-quality", "yss-sql-condition", "yss-sql-tpl", "yss-valuation", "yss-variable", "yss-openapi", "web-design-engineer", "web-video-presentation", "wireframe-prototype", "wizard", "git-guardrails-claude-code", "claude-handoff", "batch-grill-me", "product-design-prototype", "research", "yss-dictionary", "yss-jdbc", "yss-log", "yss-taskflow", "yss-backend-scaffold-application", "yss-backend-scaffold-domain", "yss-backend-scaffold-infrastructure", "yss-backend-scaffold-web"]);
 export function obsoleteCanonicalResidues(names, obsolete = OBSOLETE) {
   return names.filter((name) => obsolete.has(name)).sort();
 }
@@ -33,6 +34,61 @@ export function treeHash(directory) {
   }
   return digest.digest("hex");
 }
+
+/**
+ * 校验并返回 YSS UI 前端 skills 与 MCP 的上游集成合同。
+ *
+ * @param {unknown} manifest 待校验的清单对象
+ * @returns {Record<string, any>} 已校验的清单
+ */
+export function validateYssUiSkillManifest(manifest) {
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) throw new TypeError("yss-ui 清单必须是对象");
+  const requiredStrings = ["source", "source_type", "source_root", "source_category", "source_revision", "adaptation_ref"];
+  for (const field of requiredStrings) {
+    if (typeof manifest[field] !== "string" || !manifest[field].trim()) throw new TypeError(`yss-ui 清单缺少 ${field}`);
+  }
+  if (manifest.schema_version !== 2) throw new TypeError("yss-ui 清单 schema_version 必须为 2");
+  if (!/^[0-9a-f]{40}$/.test(manifest.source_revision)) throw new TypeError("yss-ui source_revision 必须是完整 Git SHA");
+  if (!manifest.package || typeof manifest.package.name !== "string" || typeof manifest.package.version !== "string") {
+    throw new TypeError("yss-ui 清单缺少 package name/version");
+  }
+  if (!Array.isArray(manifest.excluded_categories) || manifest.excluded_categories.some((item) => typeof item !== "string" || !item)) {
+    throw new TypeError("yss-ui 清单缺少有效 excluded_categories");
+  }
+  if (!Array.isArray(manifest.excluded_skills) || manifest.excluded_skills.some((item) => typeof item !== "string" || !item)) {
+    throw new TypeError("yss-ui 清单缺少有效 excluded_skills");
+  }
+  if (!Array.isArray(manifest.skills) || !manifest.skills.length) throw new TypeError("yss-ui 清单缺少 skills");
+  const upstreamNames = new Set();
+  const canonicalNames = new Set();
+  for (const skill of manifest.skills) {
+    if (!skill || typeof skill.upstream !== "string" || typeof skill.canonical !== "string") throw new TypeError("yss-ui skill 缺少 upstream/canonical");
+    if (skill.upstream === "java-backend-commit") throw new TypeError("yss-ui 前端清单不得包含 java-backend-commit");
+    if (manifest.excluded_skills.includes(skill.upstream)) throw new TypeError(`yss-ui 清单包含已排除 skill: ${skill.upstream}`);
+    if (upstreamNames.has(skill.upstream)) throw new TypeError(`upstream 重复: ${skill.upstream}`);
+    if (canonicalNames.has(skill.canonical)) throw new TypeError(`canonical 重复: ${skill.canonical}`);
+    if (!/^[0-9a-f]{64}$/.test(skill.upstream_hash ?? "")) throw new TypeError(`${skill.canonical} 缺少有效 upstream_hash`);
+    upstreamNames.add(skill.upstream);
+    canonicalNames.add(skill.canonical);
+  }
+  const mcp = manifest.mcp;
+  if (!mcp || typeof mcp.package !== "string" || typeof mcp.version !== "string" || typeof mcp.components_version !== "string" || typeof mcp.server_name !== "string") {
+    throw new TypeError("yss-ui 清单缺少 MCP package/version/server 信息");
+  }
+  if (!Array.isArray(mcp.project_configs) || !mcp.project_configs.length) throw new TypeError("yss-ui 清单缺少 MCP project_configs");
+  const configPaths = new Set();
+  for (const config of mcp.project_configs) {
+    if (!config || typeof config.path !== "string" || !["mcpServers", "servers"].includes(config.container)) throw new TypeError("yss-ui MCP project_config 无效");
+    if (configPaths.has(config.path)) throw new TypeError(`yss-ui MCP config path 重复: ${config.path}`);
+    configPaths.add(config.path);
+  }
+  if (typeof mcp.global_install_guide !== "string" || !mcp.global_install_guide) throw new TypeError("yss-ui MCP 缺少 global_install_guide");
+  return manifest;
+}
+
+function loadYssUiSkillManifest() {
+  return validateYssUiSkillManifest(JSON.parse(readFileSync(YSS_UI_MANIFEST_PATH, "utf8")));
+}
 function git(args) { return spawnSync("git", args, { cwd: ROOT, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }); }
 function tracked(relativePath) { return git(["ls-files", "-z", "--", relativePath]).stdout.length > 0; }
 function parseLock() { return existsSync(LOCK_PATH) ? JSON.parse(readFileSync(LOCK_PATH, "utf8")) : null; }
@@ -91,6 +147,7 @@ export function syncSkills({ check = false } = {}) {
     for (const name of OBSOLETE) {
       const target = path.join(projection, name);
       if (check) { if (existsSync(target) || lstatSafe(target)?.isSymbolicLink()) drift.push(`obsolete projection: ${relative(target)}`); }
+      else if (lstatSafe(target)?.isSymbolicLink()) unlinkSync(target);
       else rmSync(target, { recursive: true, force: true });
     }
   }
@@ -140,6 +197,9 @@ function metadata(name, skillPath, directory, previous, canonical = false, sourc
 }
 export function updateSkillLock(arguments_ = process.argv.slice(2)) {
   const oldLock = parseLock(); const previous = priorMetadata(oldLock); const sources = sourceRevisionMap(oldLock, arguments_); const upstreamRoot = option(arguments_, "upstream-root");
+  const yssUiManifest = loadYssUiSkillManifest();
+  sources[yssUiManifest.source] = { ...(sources[yssUiManifest.source] ?? {}), revision: yssUiManifest.source_revision };
+  const yssUiSkills = new Map(yssUiManifest.skills.map((skill) => [skill.canonical, skill]));
   if (upstreamRoot && !existsSync(upstreamRoot)) throw new TypeError(`--upstream-root 不存在: ${upstreamRoot}`);
   const additions = arguments_.filter((arg) => arg.startsWith("--add=")).map((arg) => arg.slice(6));
   const removals = new Set(arguments_.filter((arg) => arg.startsWith("--remove=")).map((arg) => arg.slice(9)));
@@ -152,7 +212,19 @@ export function updateSkillLock(arguments_ = process.argv.slice(2)) {
   if (unlocked.length) throw new TypeError(`发现未登记到 skills-lock.json 的已跟踪共享 skills: ${unlocked.join(", ")}\n确认新增后运行 scripts/update-skill-lock --add=<skill-name>`);
   const targets = [".agents/skills", ...PROJECTION_ROOTS];
   const shared = Object.fromEntries(sharedNames.map((name) => {
-    const item = metadata(name, `.agents/skills/${name}/SKILL.md`, path.join(SOURCE_ROOT, name), previous, true, sources, upstreamRoot); item.targets = targets; return [name, item];
+    const item = metadata(name, `.agents/skills/${name}/SKILL.md`, path.join(SOURCE_ROOT, name), previous, true, sources, upstreamRoot);
+    const yssUiSkill = yssUiSkills.get(name);
+    if (yssUiSkill) {
+      item.source = yssUiManifest.source;
+      item.sourceType = yssUiManifest.source_type;
+      item.skillPath = `${yssUiManifest.source_root}/${yssUiSkill.upstream}/SKILL.md`;
+      item.sourceRevision = yssUiManifest.source_revision;
+      item.upstreamHash = yssUiSkill.upstream_hash;
+      if (item.effectiveHash !== item.upstreamHash) item.adaptationRef = yssUiManifest.adaptation_ref;
+      else delete item.adaptationRef;
+    }
+    item.targets = targets;
+    return [name, item];
   }));
   const platform = {};
   for (const root of PROJECTION_ROOTS) {