create-yss-spec 2.1.10 → 2.1.13

package/template/.trae/skills/yss-router/references/router-contract.yaml

@@ -1,6 +1,9 @@
 schema_version: 1
 allowed_statuses: [draft, blocked, ready-for-lifecycle-review]
 forbidden_statuses: [approved, ready-for-agent, completed]
+skill_aliases:
+  api-integration: yss-api-integration
+  microapp-commit: yss-microapp-commit
 implementation_path_policy:
   applies_to: harness-resident-runtime-code
   project_roots:
@@ -120,24 +123,22 @@ dependency_closure:
   yss-ddd-scaffold-generator:
     always: [yss-backend-scaffold-parent, alibaba-java-code-style]
   yss-domain:
-    always: [yss-backend-scaffold-domain, alibaba-java-code-style]
+    always: [alibaba-java-code-style]
     when_modeling: [domain-modeling]
     when_pojo: [lombok]
-  yss-backend-scaffold-application:
+  yss-application:
     always: [alibaba-java-code-style]
     when_conversion: [mapstruct, lombok]
   yss-repository:
-    always: [yss-backend-scaffold-infrastructure, mapstruct, lombok, alibaba-java-code-style]
+    always: [mapstruct, lombok, alibaba-java-code-style]
     when_mybatis: [yss-mybatis]
   yss-web-controller:
-    always: [yss-dto, yss-backend-scaffold-web, mapstruct, lombok, alibaba-java-code-style]
+    always: [yss-dto, mapstruct, lombok, alibaba-java-code-style]
   yss-userinfo:
     always: [yss-dto]
     when_cache_lookup: [yss-cache]
   yss-audit-log:
     always: [yss-userinfo, yss-dto]
-  yss-log:
-    always: []
   yss-validation:
     always: [yss-exception]
   yss-security-algorithm:
@@ -156,7 +157,6 @@ component_impact_values:
   - current-user-context
   - user-cache-lookup
   - audit-event
-  - technical-request-logging
   - request-validation
   - error-mapping
   - encryption-or-signing
@@ -165,20 +165,16 @@ component_impact_routing:
   current-user-context: [yss-userinfo]
   user-cache-lookup: [yss-userinfo, yss-cache]
   audit-event: [yss-audit-log, yss-userinfo, yss-dto]
-  technical-request-logging: [yss-log]
   request-validation: [yss-validation, yss-exception]
   error-mapping: [yss-exception, yss-dto]
   encryption-or-signing: [yss-security-algorithm, yss-exception]
 
 end_to_end_backend_required:
   - yss-domain
-  - yss-backend-scaffold-domain
-  - yss-backend-scaffold-application
+  - yss-application
   - yss-repository
-  - yss-backend-scaffold-infrastructure
   - yss-web-controller
   - yss-dto
-  - yss-backend-scaffold-web
   - mapstruct
   - lombok
   - alibaba-java-code-style

package/template/.trae/skills/yss-source-index/references/source-map-config.md

@@ -12,11 +12,7 @@ The refresh script maps component source path hints to skill references. These p
 | `yss-audit-log` | `yss-microservice-components/yss-component-audit-log` |
 | `yss-excel-mvc` | `yss-microservice-components/yss-component-excel-mvc`, `yss-microservice-components/yss-component-excel-starter` |
 | `yss-distributed-id` | `yss-microservice-components/yss-component-distributed-id`, `yss-microservice-components/yss-component-leaf` |
-| `yss-jdbc` | `yss-microservice-components/yss-component-jdbc` |
-| `yss-dictionary` | `yss-microservice-components/yss-component-dictionary-parent` |
-| `yss-log` | `yss-microservice-components/yss-component-log-starter` |
 | `yss-resilience4j` | `yss-microservice-components/yss-component-resilience4j-starter` |
-| `yss-taskflow` | `yss-microservice-components/yss-component-taskflow` |
 | `yss-validation` | `yss-microservice-components/yss-component-validation-engine-parent`, `yss-microservice-components/yss-component-validation-jsr303` |
 | `yss-security-algorithm` | `yss-microservice-components/yss-component-security-algorithm` |
 | `yss-userinfo` | `yss-microservice-components/yss-component-userinfo-starter` |

package/template/.trae/skills/yss-source-index/scripts/refresh-yss-skill-index.mjs

@@ -5,7 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-const BACKEND = {"yss-cache":["yss-microservice-components/yss-component-cache-parent"],"yss-mybatis":["yss-microservice-components/yss-component-persistence"],"yss-dto":["yss-microservice-components/yss-component-dto"],"yss-audit-log":["yss-microservice-components/yss-component-audit-log"],"yss-excel-mvc":["yss-microservice-components/yss-component-excel-mvc","yss-microservice-components/yss-component-excel-starter"],"yss-distributed-id":["yss-microservice-components/yss-component-distributed-id","yss-microservice-components/yss-component-leaf"],"yss-jdbc":["yss-microservice-components/yss-component-jdbc"],"yss-dictionary":["yss-microservice-components/yss-component-dictionary-parent"],"yss-log":["yss-microservice-components/yss-component-log-starter"],"yss-resilience4j":["yss-microservice-components/yss-component-resilience4j-starter"],"yss-taskflow":["yss-microservice-components/yss-component-taskflow"],"yss-validation":["yss-microservice-components/yss-component-validation-engine-parent","yss-microservice-components/yss-component-validation-jsr303"],"yss-security-algorithm":["yss-microservice-components/yss-component-security-algorithm"],"yss-userinfo":["yss-microservice-components/yss-component-userinfo-starter"],"yss-exception":["yss-microservice-components/yss-component-exception"]};
+const BACKEND = {"yss-cache":["yss-microservice-components/yss-component-cache-parent"],"yss-mybatis":["yss-microservice-components/yss-component-persistence"],"yss-dto":["yss-microservice-components/yss-component-dto"],"yss-audit-log":["yss-microservice-components/yss-component-audit-log"],"yss-excel-mvc":["yss-microservice-components/yss-component-excel-mvc","yss-microservice-components/yss-component-excel-starter"],"yss-distributed-id":["yss-microservice-components/yss-component-distributed-id","yss-microservice-components/yss-component-leaf"],"yss-resilience4j":["yss-microservice-components/yss-component-resilience4j-starter"],"yss-validation":["yss-microservice-components/yss-component-validation-engine-parent","yss-microservice-components/yss-component-validation-jsr303"],"yss-security-algorithm":["yss-microservice-components/yss-component-security-algorithm"],"yss-userinfo":["yss-microservice-components/yss-component-userinfo-starter"],"yss-exception":["yss-microservice-components/yss-component-exception"]};
 const FRONTEND={"yss-ui":["components","hooks","skills"],"yss-components":["components"],"yss-hook":["hooks"],"yss-page-module-development":["components","hooks","skills"],"yss-use-table-height":["hooks"],"yss-use-tree-height":["hooks"]};
 const URLS={components:"http://192.168.164.27:3200/components",hooks:"http://192.168.164.27:3200/hooks",skills:"http://192.168.164.27:3200/skills"};
 const KEYS=["Audit","Cache","Clear","Command","Configuration","Controller","DTO","Data","Enable","Excel","Handler","Interceptor","Jdbc","Mapper","Mybatis","Page","Properties","Query","Repository","Request","Response","Result","Update","Aspect","Leaf","Id","Dir","Dic","Dictionary","File","Upload","Log","Message","Mail","Liquibase","Circuit","Breaker","Sql","Tpl","Tag","Task","Flow","Report","Validation","Validator","Security","Crypto","User","Variable","Quality","Search","Similarity","Scheduler","Runner","Duck","Dynamic","Factory","Client","Feign","Gateway","Convertor","Adapter","Advice","Bridge","Route","Uploader","Sftp","Minio","Parser","Express","Rule","Template","Generator","Importer","Engine","Event","Submitter","Executor","Context","Status","Type","State"];

package/template/.trae/skills/yss-ui/SKILL.md

@@ -30,7 +30,7 @@ pnpm why vue @yss-ui/components @yss-ui/hooks ant-design-vue vxe-table
 
 记录实际版本、lockfile、验证命令和环境阻塞。完整策略见 `references/antdv-compatibility.md`。
 
-产品设计使用的 Ant Design v6 视觉/token 语义，不等于 Vue 生产实现 API。生产代码必须使用项目安装的 Ant Design Vue 4.x API，禁止复制 React hook、props 或组件写法。
+产品设计使用的 Ant Design v6 视觉/token 语义，不等于 Vue 生产实现 API。生产代码必须使用项目安装的 Ant Design Vue 4.x API，禁止复制 React hook、props 或组件写法。`yss-antd-design` 与 `@ant-design/cli` 只用于原型设计构建，进入本技能后不得再调用。
 
 ## 3. 组件选型门禁
 

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

@@ -63,6 +63,7 @@ node scripts/generate_controller.mjs \
 
 ## 按需读取
 
+- 分层开发规范：`references/web-adapter-layer-guide.md`
 - 生成脚本：`scripts/generate_controller.mjs`
 - Controller 模板：`assets/templates/Controller.java.template`
 - Convertor 模板：`assets/templates/WebConvertor.java.template`

package/template/.trae/skills/yss-web-controller/references/web-adapter-layer-guide.md

@@ -0,0 +1,168 @@
+本技能为开发 YSS 服务的**Web 适配器层**（REST API）提供指导和框架。
+Web 适配器负责通过 HTTP 公开业务功能、处理输入验证和格式化响应。
+
+## 1. 核心职责 (Core Responsibilities)
+
+- **Request Handling**: Map HTTP requests (GET, POST, PUT, DELETE) to Java methods.
+- **Input Validation**: Validate request bodies and parameters using JSR-303/380 annotations (`@Valid`, `@NotNull`, etc.).
+- **Response Formatting**: Wrap business results into standard `Result` objects (`SingleResult`, `PageResult`, `MultiResult`).
+- **Orchestration Delegation**: Delegate business logic to the **Application Service**. Simple queries can be delegated directly to the **Domain Gateway** (CQRS pattern).
+
+## 2. 代码结构 (Code Structure)
+
+Web Adapters are typically located in the `bootstrap` module or a dedicated `web` module.
+
+```
+com.yss.{module}.rest
+├── {Domain}Controller.java      # Main REST Controller
+└── {Domain}ReportController.java # Optional: For reporting/stats APIs
+```
+
+## 3. 开发规范 (Development Guidelines)
+
+### 3.1 Controller 定义
+
+- **注解**: 使用 `@RestController`。
+- **路径**: `@RequestMapping("/api/{module}/{domain}")` (e.g., `/api/quality/rule`).
+- **依赖注入**: 使用 Lombok `@RequiredArgsConstructor` 进行构造器注入。
+- **命名**: `{Domain}Controller` (e.g., `QualityRuleController`).
+
+### 3.2 依赖注入原则
+
+- **写操作/复杂逻辑**: 必须注入 **Application Service** (`XxxService`)。
+- **读操作 (Query)**: 允许直接注入 **Domain Gateway** (`XxxGateway`) 以减少样板代码 (CQRS)。
+
+### 3.3 参数与响应
+
+- **Command (写)**: 使用 `@PostMapping`/`@PutMapping` + `@RequestBody` + `{Domain}Cmd` 对象。
+- **Query (读)**: 使用 `@PostMapping` (for complex search) + `@RequestBody` + `{Domain}Page/Query` 对象。
+- **Wrapper**:
+  - `SingleResult<T>`: 单个对象或基本类型。
+  - `MultiResult<T>`: 列表。
+  - `PageResult<T>`: 分页数据。
+- **Validation**: 必须在参数前添加 `@Valid` 注解。
+
+### 3.4 异常处理
+
+- **不要**在 Controller 中捕获通用异常 (`Exception`)。
+- 让全局异常处理器 (`GlobalExceptionHandler`) 统一处理运行时异常。
+- 仅在需要特定 HTTP 状态码转换时捕获特定异常。
+
+## 4. 代码示例 (Code Examples)
+
+### 4.1 标准 CRUD Controller
+
+```java
+package com.yss.{module}.rest;
+
+import com.yss.cloud.dto.result.MultiResult;
+import com.yss.cloud.dto.result.PageResult;
+import com.yss.cloud.dto.result.SingleResult;
+import com.yss.{module}.client.dto.cmd.{Domain}AddCmd;
+import com.yss.{module}.client.dto.cmd.{Domain}UpdateCmd;
+import com.yss.{module}.client.dto.cmd.{Domain}StatusCmd;
+import com.yss.{module}.client.dto.query.{Domain}Page;
+import com.yss.{module}.client.vo.{Domain}VO;
+import com.yss.{module}.core.service.{Domain}Service;
+// Optional: Import Gateway for direct queries
+// import com.yss.{module}.domain.gateway.{Domain}Gateway;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.*;
+
+import javax.validation.Valid;
+
+/**
+ * {Domain} 管理控制器
+ *
+ * @author {User}
+ */
+@RestController
+@RequestMapping("/api/{module}/{domain-path}")
+@RequiredArgsConstructor
+public class {Domain}Controller {
+
+    private final {Domain}Service {domainVar}Service;
+    // private final {Domain}Gateway {domainVar}Gateway; // For CQRS if needed
+
+    /**
+     * 分页查询 {Domain}
+     *
+     * @param query 查询条件
+     * @return 分页结果
+     */
+    @PostMapping("/page")
+    public PageResult<{Domain}VO> page(@Valid @RequestBody {Domain}Page query) {
+        return {domainVar}Service.page(query);
+    }
+
+    /**
+     * 根据ID查询详情
+     *
+     * @param id 主键ID
+     * @return 详情对象
+     */
+    @GetMapping("/detail/{id}")
+    public SingleResult<{Domain}VO> detail(@PathVariable String id) {
+        return SingleResult.of({domainVar}Service.detail(id));
+    }
+
+    /**
+     * 新增 {Domain}
+     *
+     * @param cmd 新增命令
+     * @return 新增结果 (通常是ID或完整对象)
+     */
+    @PostMapping
+    public SingleResult<Long> add(@Valid @RequestBody {Domain}AddCmd cmd) {
+        return SingleResult.of({domainVar}Service.add(cmd));
+    }
+
+    /**
+     * 更新 {Domain}
+     *
+     * @param cmd 更新命令
+     * @return 更新结果
+     */
+    @PutMapping
+    public SingleResult<Boolean> update(@Valid @RequestBody {Domain}UpdateCmd cmd) {
+        {domainVar}Service.update(cmd);
+        return SingleResult.of(true);
+    }
+
+    /**
+     * 状态变更 (启用/禁用)
+     *
+     * @param cmd 状态命令
+     * @return 变更后的状态
+     */
+    @PostMapping("/enabled")
+    public SingleResult<Integer> switchStatus(@Valid @RequestBody {Domain}StatusCmd cmd) {
+        {domainVar}Service.switchStatus(cmd);
+        return SingleResult.of(cmd.getStatus());
+    }
+}
+```
+
+### 4.2 复杂业务操作示例
+
+```java
+    /**
+     * 执行业务操作 (e.g. 立即运行检查)
+     *
+     * @param cmd 执行命令
+     * @return 执行结果ID
+     */
+    @PostMapping("/execute")
+    public SingleResult<String> execute(@Valid @RequestBody {Domain}ExecuteCmd cmd) {
+        // 调用 Service 处理复杂业务逻辑
+        return SingleResult.of(
+                {domainVar}Service.execute(cmd)
+        );
+    }
+```
+
+## 5. 阶段 7 合同
+
+- 只消费冻结 OpenAPI/no-impact record 和批准合同；Controller 不得穿透 Application/Domain 边界。
+- Controller/DTO/Convertor 骨架可受控生成；权限、校验、错误映射和接口行为使用 `behavior-tdd`。
+- 返回统一 `YSS Skill Execution Result`，包含代码、契约/API 测试、实际验证和新增 API/权限影响。

package/template/AGENTS.md

@@ -22,8 +22,9 @@
 | 影响面触发与 `not-applicable` | `docs/process/harness-process-tailoring.md` |
 | 模板维护强度触发与最低等级 | `docs/process/maintenance-intensity.yaml` |
 | 技能清单、来源、版本、哈希和投影目标      | `skills-lock.json`                          |
+| 技能分层、别名、默认可发现性和运行时入口 | `docs/agents/yss-skill-registry.yaml`（当前 `status: shadow`，不作为 Router / 生命周期运行时入口） |
 
-README、用户指南和其他说明文档只引用或解释上述事实，不重复定义同一规则。
+README、用户指南、根目录 `CLAUDE.md` 和其他说明文档只引用或解释上述事实，不重复定义同一规则。`CLAUDE.md` 是 Claude Code 入口指针，不是第二套 Agent 规则。
 
 ## 3. 标准文档语言与规范语汇
 
@@ -37,7 +38,7 @@ README、用户指南和其他说明文档只引用或解释上述事实，不
 按“影响面 → 单一事实来源 → 投影 / 派生资产 → 分级证据”维护。强度分级、最低证据和 checkpoint 合同见 `docs/process/harness-process-tailoring.md`。
 
 - 创建、修改或退役 skill 时使用 `maintaining-skills`，并先按 `docs/process/harness-process-tailoring.md` 判定 L1 / L2 / L3；只有 L3 必须保留完整基线失败、压力场景、修订后验证和正式独立审查证据。
-- `.agents/skills` 是跨 Agent 共享技能的权威内容；`.claude/skills`、`.codex/skills`、`.hermes/skills`、`.pi/skills`、`.qoder/skills`、`.trae/skills` 中的共享技能是生成投影，禁止分别手工修改。
+- `.agents/skills` 是跨 Agent 共享技能的权威内容；`.claude/skills`、`.codex/skills`、`.cursor/skills`、`.hermes/skills`、`.pi/skills`、`.qoder/skills`、`.trae/skills` 中的共享技能是生成投影，禁止分别手工修改。Cursor 的契约运行时入口是 `.cursor/skills`；不得把 canonical `.agents/skills` 与某个平台投影当作同权双入口。
 - `scripts/verify-template` 是模板发布阻断门禁。模板与外部 `create-yss-spec` 的跨仓库契约未完成集成验证时，不得声称可发布。
 
 ## 5. `project-instance` 产品研发路由
@@ -66,6 +67,7 @@ README、用户指南和其他说明文档只引用或解释上述事实，不
 - 无可复用工程时，先确认外部目标仓库或输出目录，再使用 `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 为准。
+- 前端测试、type-check 与构建优先使用 `pnpm`；后端校验、测试与编译优先使用项目根 `./mvnw`。不要默认 `npm` / `yarn` 或裸 `mvn`。既有仓库确实没有 pnpm 或 Maven Wrapper 时，必须记录受控例外和实际命令。登记字段见 `docs/process/implementation-repo-integration.md`。
 - 路径越界、证据缺失、未执行验证、`drift`、`violation` 或 `new_impacts` 时停止实现并重新路由。
 
 实现细则由已批准合同、YSS skills 和实现接入文档定义；`AGENTS.md` 只保留入口与边界。
@@ -76,11 +78,12 @@ README、用户指南和其他说明文档只引用或解释上述事实，不
 |---|---|
 | 技术事实、标准、第三方 API 或框架行为影响决策 | `research` 或等价的一手资料记录 |
 | 竞品、市场或用户口碑事实 | `competitive-intelligence` |
-| UI 设计、原型、组件或主题 | `yss-design-system` 后使用 `yss-prototype-stage`；Codex 再路由 `product-design:index`，其他 Agent 交付等价合同资产；产出前后用 `antd` CLI 记录 Ant Design v6 与浏览器验证事实 |
+| UI 设计、原型、组件或主题 | `yss-design-system` 后使用 `yss-prototype-stage`；Codex 再路由 `product-design:index`，其他 Agent 交付等价合同资产；原型产出前后用 `yss-antd-design` 记录 Ant Design v6 事实与浏览器验证。前端代码落地改用 `yss-ui`，不要继续调用 `yss-antd-design` |
 | Bug、测试失败或性能回退 | `diagnosing-bugs` 建立可复现反馈，再用 `tdd` |
 | merge / rebase 冲突 | `resolving-merge-conflicts` |
 | 架构治理、难测模块或深模块设计 | `improve-codebase-architecture` / `codebase-design` |
 | 跨线程、跨仓库、上下文过长或原型结论回流 | `handoff` 或等价交接记录 |
+| 本地知识库 init / refresh / rebuild，或要把研究结果落成持久 wiki | `llm-wiki`（落成持久 wiki 用 `ingest`；已映射 live 源变了用 `refresh`） |
 
 业务行为默认按 `tdd` 使用已确认的公开 seam 逐切片实现。一次性生成、纯配置或流程文档不适用代码 TDD 时，必须记录例外理由和可执行验证方式。
 
@@ -105,3 +108,15 @@ README、用户指南和其他说明文档只引用或解释上述事实，不
 ## 12. 测试质量基线
 
 模板推荐值为 Domain / Application `>= 90%`、API `>= 80%`、前端组件 `>= 75%`、已明确的关键流程 `100% E2E`。只有项目实例在测试策略中明确采纳或覆盖后才构成 CI 门禁；未定义关键流程清单时，不声称其 E2E 覆盖率达到 100%。
+
+## Cursor Cloud specific instructions
+
+本仓库是 `template-source` Harness / 研发管理仓库，没有前端 / 后端运行时应用；可运行、可测试的表面只有 Node 工具链与治理校验脚本。
+
+- 依赖与工具链：Node `>=22 <27`（`.nvmrc` 固定 22）；`pnpm` 通过 `packageManager` 字段由 corepack 自动切换到 `10.15.0`，无需手工切换。Node 依赖只装在 `.template-source/tooling/node`，仓库根没有 `package.json`。
+- 测试：`pnpm --dir .template-source/tooling/node test`（`node --test`，共 15 个用例）。
+- 构建 / lint：`pnpm --dir .template-source/tooling/node build:vendor` 与 `check:vendor` 维护 `scripts/vendor/*.mjs`；顶层 lint 是 `verify-template` 内对所有脚本执行的 `node --check`。
+- 完整发布门禁（相当于"运行应用"）：`scripts/verify-template`，成功输出 `模板发布校验通过`。它串联证据索引、`pnpm test`、`check:vendor` 和全部 `scripts/verify-*` 场景校验。
+- 非显然的坑：`scripts/verify-lifecycle-registry`（及其对应测试 `Node lifecycle registry verifier ...`）会 shell out 到 `python3` 并 `import jsonschema` 做 JSON Schema 校验。缺少该 Python 模块时测试会以 `ModuleNotFoundError: No module named 'jsonschema'` 失败，而不是代码问题；update script 已负责 `pip3 install jsonschema`。
+- `pnpm install` 输出的 `Ignored build scripts: esbuild` 警告可忽略：esbuild 0.28.2 在本平台自带二进制，`build:vendor` / `check:vendor` 无需 `pnpm approve-builds`。
+- 常用只读入口：`scripts/repository-mode`（返回仓库身份）、`scripts/generate-lifecycle-artifacts`（从 `docs/process/lifecycle-registry.yaml` 派生产物，输出应无 diff）、`scripts/export-yss-skills --output <dir>`（导出公开技能）。

package/template/CLAUDE.md

@@ -0,0 +1,13 @@
+# CLAUDE.md
+
+Agent 入口、硬门禁与禁止事项以仓库根 `AGENTS.md` 为准。每个任务先读 `yss-project.yaml` 识别仓库身份，再读 `CONTEXT.md`。本文件不另定义流程规则。
+
+## 前端 / 后端验证命令
+
+进入 frontend 或 backend 的实现、测试或编译时：
+
+- 前端优先使用 `pnpm` 做依赖、测试、type-check 与构建；不要默认 `npm` / `yarn`。
+- 后端优先使用项目根 `./mvnw` 做 `validate` / `test` / `package`；不要默认裸 `mvn`。
+- 既有仓库确实没有 pnpm 或 Maven Wrapper 时，记录受控例外和实际命令。
+
+登记字段与跨仓约束见 `docs/process/implementation-repo-integration.md`。

package/template/CONTEXT.md

@@ -34,6 +34,7 @@
 | YSS Skill Execution Result | YSS 专项 skill 完成工作单元后返回的结构化执行证据，记录合同版本、变更文件、证据文件、实际验证、延期 seam、偏离和新增影响。 | 实现者自报 `implemented` 不构成最终通过，必须由 Router、生命周期编排器和独立 Reviewer 复核。 |
 | ADR | 架构决策记录，用于沉淀难以回滚、非显而易见且存在真实取舍的技术决策。 | 常规实现选择不要写 ADR。 |
 | Fresh Verification | 完成前重新执行的验证证据，包括测试命令、契约校验、关键路径检查或人工审查结论。 | 不等同于“之前跑过”或实现者自述。 |
+| 实现验证命令 | 前端测试 / 构建优先 `pnpm`，后端校验 / 测试 / 编译优先 `./mvnw`。 | 不要默认 `npm`、`yarn` 或裸 `mvn`；仓库确实缺少 pnpm 或 Maven Wrapper 时记受控例外。 |
 | 测试质量基线 | 项目实例明确采纳的覆盖率阈值、关键流程清单和受控例外。 | 模板推荐值本身不构成可执行门禁；未定义关键流程时，不得声称其 E2E 覆盖率达到 100%。 |
 | 主阶段 | 对相邻研发目标、工作单元和退出条件的粗粒度生命周期分组。 | 不等同于门禁编号，也不因增加门禁而自动增加主阶段。 |
 | 生命周期门禁（条件强制门禁） | 只有当影响面命中触发条件时才必须裁决的生命周期审查点。 | 未触发时记录 `not-applicable` 及原因，不生成空文档；门禁不是产物、工作单元或证据的统称。 |
@@ -56,7 +57,8 @@
 | 试验技能 | 尚未达到项目默认支持成熟度的技能。 | 只在明确试验范围内使用，不进入 Router 默认技能闭包。 |
 | 显式兼容入口 | 为已有用户操作习惯保留的 user-invoked 工作流入口，写入前由生命周期编排器预检，结果回交其验收。 | 不是默认路径、过时别名或可以越过门禁的第二套生命周期。 |
 | 技能成熟度 | 描述技能从 `draft`、`verified`、`supported` 到 `deprecated` 的治理状态。 | 不等同于文件存在、已被投影或能够安装。 |
-| 技能注册表 | 记录技能身份、别名、分层、适用影响面、成熟度、新鲜度、验证和公开状态的机器可读路由资产。 | 不替代 `skills-lock.json` 的来源、hash 和投影完整性职责。 |
+| 技能注册表 | 记录技能身份、别名、分层、适用影响面、成熟度、默认可发现性和 Agent 运行时入口的机器可读路由资产。 | 不替代 `skills-lock.json` 的来源、hash 和投影完整性职责。当前 `docs/agents/yss-skill-registry.yaml` 为 `shadow`，Router 与生命周期不得按其裁剪发现面。 |
+| LLM Wiki | 由 `raw/`、`wiki/` 与 `.wiki-manifest.json` 组成的本地持久知识库。 | 不是 `research` 一次性笔记，也不替代权威源。`ingest` 只把用户点名的外源或已落盘研究笔记编进 IR，不改 live 权威文件。 |
 | 生态发布清单 | 关联模板 schema 与 commit、CLI 版本与快照、公开技能来源与导出 hash 的跨仓发布证据。 | 不要求尚未生成的仓库 commit 互相循环引用。 |
 | 研发管理仓库 | 承载 Spec、OpenAPI、架构、Ticket、验证、发布和复盘等研发管理资产的仓库。 | 不等同于前端 / 后端代码 monorepo。 |
 | 实现仓库 | 承载前端、后端或其他运行时代码及其 Git、CI、MR / PR、测试命令和发布流水线的仓库。 | 不要把实现仓库的源码所有权混入研发管理仓库。 |
@@ -65,8 +67,6 @@
 | 模板实例仓库（`project-instance`） | 由模板初始化后生成、承载某个具体产品研发生命周期资产的仓库身份。 | 不作为通用流程模板的权威来源。 |
 | 模板实例分发面 | 模板源中应随 CLI 快照进入 `project-instance` 的共享生命周期、模板、用户指南和验证资产集合。 | 不包含模板源审查、研究、发布路线或源仓库专属 ADR。 |
 | 模板源治理区 | 仅供 `template-source` 使用、保存审查证据、研究记录、跨仓契约、发布路线和源仓库治理决策的归档区域。 | 不随 CLI 分发；不等于产品实例的研发管理资产。 |
-| 目标平台单文件二进制 | 随模板快照分发、只适用于一个受支持 OS/架构组合的可执行文件。 | 不等同于跨平台通用文件，也不等同于运行时下载或 `cargo install`。 |
-| 原生模板实例运行时 | 在模板实例中执行原有治理和验证公共操作、且不依赖 Node.js 的目标平台原生运行时。 | 不等同于模板维护侧的构建工具，也不等同于仅创建模板的安装器。 |
 | 仓库身份清单 | 显式声明仓库身份和清单结构版本的机器可读资产。 | 不承载项目名称、团队规模、Tracker 或其他易变业务配置。 |
 
 只有在计划、分诊、调试或架构讨论中明确沉淀出稳定语言时，才新增术语。

package/template/README.md

@@ -11,7 +11,8 @@
 ```text
 ├── .agents/                 ← 跨 Agent 共享 skills 的权威内容
 ├── .claude/                 ← Claude skills 投影与平台专属 skills
-├── .codex/                  ← Codex skills 投影与平台专属 YSS skills
+├── .codex/                  ← Codex skills 投影与平台专属 skills
+├── .cursor/                 ← Cursor skills 投影
 ├── .hermes/                 ← Hermes skills 投影与平台专属 skills
 ├── .pi/                     ← Pi skills 投影与平台专属 skills
 ├── .qoder/                  ← Qoder skills 投影与平台专属 skills

package/template/docs/agents/README.md

@@ -6,9 +6,10 @@
 
 | 路径 | 用途 |
 |---|---|
-| `.agents/` | Agent 可加载的 Engineering Skills、脚本、prompt 和参考材料 |
-| `.codex/skills/` | Codex 项目级 skills，包含 YSS、Matt、Ticket 等能力 |
-| `docs/agents/` | 人和 AI 都可读的协作说明、标签约定、维护规范 |
+| `.agents/` | 共享技能的权威内容 |
+| `.cursor/skills/` | Cursor 的契约运行时投影 |
+| `.codex/skills/` | Codex 投影与平台专属 skills |
+| `docs/agents/` | 人和 AI 都可读的协作说明、标签约定、维护规范和技能路由注册表 |
 
 ## 当前文档
 
@@ -18,6 +19,7 @@
 | `triage-labels.md` | 标准五态 triage 标签与含义 |
 | `domain.md` | 领域文档读取和维护规则 |
 | `skills-maintenance.md` | Engineering Skills 的安装、升级和验证说明 |
+| `yss-skill-registry.yaml` | 技能分层、别名与运行时入口（shadow，不替代锁文件） |
 | `gitlab-workflow-skills.md` | GitLab、MR、CI 和自动 gitworks 的技能配置与使用规则 |
 
-当 `AGENTS.md` 或某个 skill 提到本目录时，应优先把这里当作项目协作规则读取；真正的 skill 执行入口仍在 `.agents/` 或 `.codex/skills/`。
+当 `AGENTS.md` 或某个 skill 提到本目录时，应优先把这里当作项目协作规则读取；真正的 skill 执行入口是各平台投影根，Cursor 为 `.cursor/skills`。

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

@@ -5,7 +5,9 @@
 ## 权威内容与投影
 
 - `.agents/skills` 是跨 Agent 共享技能的唯一权威内容。
-- `.claude/skills`、`.codex/skills`、`.hermes/skills`、`.pi/skills`、`.qoder/skills`、`.trae/skills` 中的同名共享技能是生成投影，不得分别手工修改。
+- `.claude/skills`、`.codex/skills`、`.cursor/skills`、`.hermes/skills`、`.pi/skills`、`.qoder/skills`、`.trae/skills` 中的同名共享技能是生成投影，不得分别手工修改。
+- Cursor 的契约运行时入口是 `.cursor/skills`。若客户端同时枚举 `.claude/skills`，仍以 `.cursor/skills` 为 Cursor 投影契约，不得把两套同名 skill 解释为两个来源。
+- 分层、别名和默认可发现性以 `docs/agents/yss-skill-registry.yaml` 为准；该文件当前为 shadow，不改变 Agent 实际发现列表，也不允许 Router 按其裁剪闭包。
 - 只属于某个平台的 skill 继续保留在对应 root，并由 `skills-lock.json` 的 `platform` 分组记录。
 - 共享技能投影可以是指向权威目录的符号链接，也可以是完整同步副本；`scripts/sync-skills --check` 会检查链接目标或完整目录哈希。