create-yss-spec 1.1.4 → 2.0.0

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

@@ -7,34 +7,36 @@ owner: ai
 
 # <功能名称>实现路由记录
 
-> 适用场景：PRD、OpenAPI Freeze / 无 API 影响记录、Design Review 和垂直切片 Issue 已就绪后，进入实现前。
-> 本文记录契约状态、Issue 状态、YSS skill 最小集合、测试策略和回滚点，不替代垂直切片 Issue 或实施计划。
+> 适用场景：Spec、OpenAPI Freeze / 无 API 影响记录、Design Review 和垂直切片 Ticket 已就绪后，进入实现前。
+> 本文记录契约状态、Ticket 状态、YSS skill 最小集合、测试策略和回滚点，不替代垂直切片 Ticket 或实施计划。
 
 ## 1. 输入材料
 
 | 资产 | 路径 / 链接 | 状态 | 备注 |
 |------|-------------|------|------|
-| 垂直切片 Issue |  |  |  |
+| 垂直切片 Ticket |  |  |  |
 | OpenAPI Freeze / 无 API 影响记录 |  |  |  |
 | OpenSpec-style Spec Delta（条件必需） |  |  | 仅 API、权限、状态机、数据模型、跨端、新模块或高风险变更需要 |
 | Design Review |  |  |  |
 | 实现仓库 / 实现位置 |  |  |  |
 | 前后端工程存在性判定 |  |  | 记录 frontend / backend 是否已存在且可复用 |
-| `垂直切片 Issue 状态` |  |  | ready / blocked / in-progress |
+| `垂直切片 Ticket 状态` |  |  | ready / blocked / in-progress |
 
 ## 2. 实现前门禁
 
 | 检查项 | 结果 | 备注 |
 |--------|------|------|
-| PRD 验收标准已可追溯 | 是 / 否 |  |
+| Spec 验收标准已可追溯 | 是 / 否 |  |
 | OpenAPI Freeze 或无 API 影响记录已完成 | 是 / 否 |  |
 | Spec Delta 已补齐或明确不需要 | 是 / 否 / 不适用 |  |
 | Design Review 阻断项已关闭 | 是 / 否 / 不适用 |  |
-| 垂直切片 Issue 已拆到端到端可验收 | 是 / 否 |  |
+| 垂直切片 Ticket 已拆到端到端可验收 | 是 / 否 |  |
 | 实现仓库 / 实现位置已登记 | 是 / 否 |  |
-| 受影响 frontend 工程已存在可复用，或已完成初始化决策 | 是 / 否 / 不适用 |  |
-| 受影响 backend 工程已存在可复用，或已完成初始化决策 | 是 / 否 / 不适用 |  |
+| 受影响 frontend 工程已存在可复用，或已登记 `scaffold_status=required` 并确认外部脚手架目标 | 是 / 否 / 不适用 |  |
+| 受影响 backend 工程已存在可复用，或已登记 `scaffold_status=required` 并确认外部脚手架目标 | 是 / 否 / 不适用 |  |
 | 缺失工程时已路由到对应脚手架 skill | 是 / 否 / 不适用 | `yss-ddd-scaffold-generator` / `yss-frontend-scaffold-generator` |
+| 后端构建 / 测试 / OpenAPI / CI 命令均使用项目根目录 `./mvnw ...`，或已记录受控例外 | 是 / 否 / 不适用 | 裸 `mvn ...` 默认为规范偏离 |
+| 持久化文档正文和章节标题已转换为中文，仅保留必要英文技术标识 / metadata | 是 / 否 | 英文 skill / 模板不得原样落地为交付文档 |
 | YSS skill 路由已完成 | 是 / 否 |  |
 | fresh verification 方式已明确 | 是 / 否 |  |
 
@@ -47,6 +49,43 @@ owner: ai
 | API / 契约 |  |  | 是 / 否 |
 | 测试 / 验证 |  |  | 是 / 否 |
 
+### 3.1 Backend Slice Implementation Contract
+
+> 任一后端切片写业务代码前必须填写本合同；没有后端影响时标记 `not-applicable` 并说明原因。合同缺少必填项时，结论必须为 `Blocked`，不得进入实现。
+
+| 项 | 内容 |
+|---|---|
+| slice_id |  |
+| affected_layers | Adapter / Application / Domain / Infrastructure / Bootstrap / not-applicable |
+| required_skills | `yss-domain` / `yss-backend-scaffold-application` / `yss-repository` / `yss-mybatis` / `yss-backend-scaffold-infrastructure` / `yss-web-controller` / `yss-dto` / `mapstruct` / `lombok` / `alibaba-java-code-style` / other |
+| allowed_write_paths |  |
+| forbidden_patterns | 私自新建 / 混用 Result 包装；Controller 内部类或非约定包临时定义主要 DTO / VO；DTO 未按 `yss-dto` 继承 `CommandDTO` / `QueryDTO` / `PageQuery`；Controller 手工分页；Controller 穿透 Repository；InMemory Gateway 作为正式持久化；`BeanUtils.copyProperties` / 反射拷贝 / 重复手写 mapping；成片手写 POJO getter/setter/constructor/builder/logger；其他： |
+| expected_evidence_files |  |
+| seam_deferred |  |
+| 人工确认项 |  |
+| verification_commands | 后端命令必须使用 `./mvnw ...`；如使用裸 `mvn ...`，必须在备注中记录受控例外原因 |
+
+| 层级 | 必需 skill | 预期文件 / 证据 | 状态 |
+|---|---|---|---|
+| Adapter / Web | `yss-web-controller`、`yss-dto`、`yss-backend-scaffold-web`、`mapstruct`、`lombok` | Controller、CMD / Query / VO、WebConvertor、统一响应包装、Lombok 注解和 MapStruct 转换证据 | pending / implemented / seam-deferred / violation / not-applicable |
+| Application | `yss-backend-scaffold-application` | AppService / UseCase、事务边界、跨聚合协调、异常处理 | pending / implemented / seam-deferred / violation / not-applicable |
+| Domain | `yss-domain-modeling`、`yss-domain`、`yss-backend-scaffold-domain` | Entity / ValueObject / DomainService / Gateway interface / 状态方法 | pending / implemented / seam-deferred / violation / not-applicable |
+| Infrastructure | `yss-repository`、`yss-mybatis`、`yss-backend-scaffold-infrastructure`、`mapstruct`、`lombok` | PO、Repository、Convertor、GatewayImpl、Mapper / XML / 查询策略、Lombok 注解和 MapStruct 转换证据 | pending / implemented / seam-deferred / violation / not-applicable |
+| Java 规范 | `alibaba-java-code-style` | 命名、异常、日志、ORM、Maven、单测和安全项审查记录 | pending / implemented / seam-deferred / violation / not-applicable |
+
+### 3.2 后端门禁压力场景
+
+| 场景 | 期望处理 |
+|---|---|
+| Agent 试图在 Controller 中新增内部 `CreateXCommand`、`XVO` 或私自新建 `PageResult` | 标记 `violation`；回到 `yss-web-controller` / `yss-dto` 补独立 DTO / VO / WebConvertor、复用既有响应包装或记录受控例外 |
+| Agent 试图用 `InMemory*Gateway` 完成需要持久化的切片 | 仅允许 `seam-deferred`；必须写补齐切片、风险、人工确认项，不得作为正式持久化实现 |
+| Agent 试图跳过 Repository / PO / Convertor，直接在 Application 中过滤集合 | 若切片需要持久化或查询策略，标记 `violation`；回到 `yss-repository` / `yss-mybatis` |
+| Agent 试图用 `BeanUtils.copyProperties`、反射拷贝或大段手写字段赋值完成对象转换 | 标记 `violation`；回到 `mapstruct` / `yss-repository` / `yss-web-controller` 补 MapStruct Convertor，或记录受控例外、测试和 review 证据 |
+| Agent 试图成片手写 POJO getter/setter、constructor、builder 或 logger | 标记 `violation`；回到 `lombok` 补注解，或记录受控例外、测试和 review 证据 |
+| Agent 只写“符合 YSS”但没有列出 skill 证据和文件证据 | 标记 `violation`；不得进入 code review / 完成结论 |
+| Agent 在后端 README、CI、Ticket、Review 或验证记录中使用 `mvn clean test` 等裸 Maven 命令 | 标记规范偏离；改为项目根目录 `./mvnw ...`，或记录既有仓库无法使用 wrapper 的受控例外 |
+| Agent 将英文 skill 模板标题 / checklist 原样复制为持久化交付文档 | 标记规范偏离；正文、标题、审查结论、实施说明和 checkpoint 说明必须改为中文 |
+
 ## 4. 外部实现仓库
 
 | repo_role | git_url | default_branch | working_branch | MR / PR | CI | test_command | build_command | 状态 |
@@ -59,10 +98,18 @@ owner: ai
 
 ## 4.1 脚手架初始化判定
 
-| 受影响端 | 是否已有可用工程 | 处理结论 | 使用 skill | 输出位置 / 仓库 | 备注 |
-|---|---|---|---|---|---|
-| backend | 是 / 否 / 不适用 | 复用现有 / 初始化 / 阻塞 | `yss-ddd-scaffold-generator` / none |  |  |
-| frontend | 是 / 否 / 不适用 | 复用现有 / 初始化 / 阻塞 | `yss-frontend-scaffold-generator` / none |  |  |
+| 受影响端 | 是否已有可用工程 | scaffold_status | 目标是否确认 | 处理结论 | 使用 skill | 输出位置 / 仓库 | 备注 |
+|---|---|---|---|---|---|---|---|
+| backend | 是 / 否 / 不适用 | existing / required / initialized / not-applicable | 是 / 否 / 不适用 | 复用现有 / 初始化 / 阻塞 | `yss-ddd-scaffold-generator` / none |  |  |
+| frontend | 是 / 否 / 不适用 | existing / required / initialized / not-applicable | 是 / 否 / 不适用 | 复用现有 / 初始化 / 阻塞 | `yss-frontend-scaffold-generator` / none |  |  |
+
+## 4.2 人工确认结论
+
+| 人工确认项 | 是否涉及 | 结论 | 证据 / 链接 | 补齐落点 |
+|---|---|---|---|---|
+| DDL / SQL / 数据库迁移 | 是 / 否 | 通过 / 草案 / 阻断 / 不适用 |  |  |
+| 权限接入 / 认证 / 授权 | 是 / 否 | 通过 / 草案 / 阻断 / 不适用 |  |  |
+| 审计日志 | 是 / 否 | 通过 / 草案 / 阻断 / 不适用 |  |  |
 
 ## 5. TDD 与验证策略
 
@@ -73,22 +120,41 @@ owner: ai
 | 前端组件 |  |  |
 | E2E / 关键路径 |  |  |
 
-## 6. 回滚点与风险
+## 6. Subagent 执行计划
+
+| task_id | subagent 角色 | 责任范围 | 允许修改文件 / 模块 | 禁止事项 | 输出回填位置 |
+|---|---|---|---|---|---|
+|  | Explorer / Drafter / Worker / Reviewer / Verifier | frontend / backend / test / review / verify / docs |  | 不得 Freeze / 不得安全放行 / 不得覆盖他人改动 |  |
+
+| 并行风险 | 缓解措施 | 合并负责人 | 状态 |
+|---|---|---|---|
+| 写范围冲突 | 按文件 / 模块拆分，不重叠写入 | 主控 Agent | open / mitigated / blocked |
+| 实现者自审 | Reviewer 必须独立于 Worker / Drafter | 主控 Agent | open / mitigated / blocked |
+| 验证不足 | Verifier 执行 fresh verification 并记录命令 | 主控 Agent | open / mitigated / blocked |
+
+| 子代理输出 | 主控采纳结论 | 未采纳原因 | 回填资产 |
+|---|---|---|---|
+|  | 采纳 / 部分采纳 / 不采纳 / 需返工 |  |  |
+
+## 7. 回滚点与风险
 
 | 风险 | 回滚点 | 观察信号 | 负责人 |
 |------|--------|----------|--------|
 |  |  |  |  |
 
-## 7. 完成标准
+## 8. 完成标准
 
-- [ ] 垂直切片 Issue 完整，且状态允许进入实现。
-- [ ] YSS skills 已最小化选择，没有绕过 Issue、OpenAPI Freeze / 无 API 影响记录或必要的 Spec Delta。
+- [ ] 垂直切片 Ticket 完整，且状态允许进入实现。
+- [ ] YSS skills 已最小化选择，没有绕过 Ticket、OpenAPI Freeze / 无 API 影响记录或必要的 Spec Delta。
+- [ ] 后端切片如适用，已填写 `Backend Slice Implementation Contract`，并且 required skills、禁止模式、证据文件、延期 seam 和验证命令完整。
 - [ ] 受影响外部实现仓库已登记，并绑定分支、MR / PR、CI 和验证命令。
-- [ ] 受影响 frontend / backend 工程存在性已判定；缺失工程已完成脚手架初始化或明确阻塞原因。
+- [ ] 受影响 frontend / backend 工程存在性已判定；0-1 缺失工程已登记 `scaffold_status=required`、确认外部脚手架目标并路由对应脚手架 skill。
+- [ ] DDL / SQL / 数据库迁移、权限接入和审计日志的人工确认结论已记录；未通过时记录阻塞原因、责任人和补齐计划。
+- [ ] 若使用 subagent，已记录任务包、写范围、独立 review、verification 命令和主控采纳结论。
 - [ ] 每个切片包含测试命令、验证方式和回滚点。
-- [ ] 触碰安全红线的项已标记 `TODO-HUMAN-REVIEW`。
+- [ ] 需要人工确认的事项已记录范围、责任人和结论。
 
-## 8. 下一步门禁
+## 9. 下一步门禁
 
 - 结论：Approved / Blocked
 - 下一步：TDD 实现 / 回到 系统 / 数据架构设计 / 回到垂直切片

package/template/docs/templates/requirement-freeze-template.md

@@ -7,14 +7,14 @@ owner: ai
 
 # <功能名称>需求冻结记录
 
-> 适用场景：PRD 初稿经过产品总体设计 / 功能架构、产品设计 / 原型评审后，需要冻结可进入 API 影响分析 / 契约草案和工程设计的范围。
-> 本文记录最终范围、回填项、非目标和开放问题，不替代 PRD。
+> 适用场景：Spec 初稿经过产品总体设计 / 功能架构、产品设计 / 原型评审后，需要冻结可进入 API 影响分析 / 契约草案和工程设计的范围。
+> 本文记录最终范围、回填项、非目标和开放问题，不替代 Spec。
 
 ## 1. 输入材料
 
 | 资产 | 路径 / 链接 | 状态 | 备注 |
 |------|-------------|------|------|
-| PRD 初稿 |  |  |  |
+| Spec 初稿 |  |  |  |
 | 产品总体设计 / 功能架构 |  |  | 必需 |
 | 产品设计 / 交互说明 |  |  |  |
 | 高保真 HTML 原型 | `docs/design/prototypes/<feature>/index.html` |  | 有 UI 时必需；Ant Design v6 |
@@ -27,7 +27,7 @@ owner: ai
 |------|------------------|--------|---------------------|
 |  | 是 / 否 | P0 / P1 / P2 |  |
 
-## 3. PRD 回填完成情况
+## 3. Spec 回填完成情况
 
 | 回填项 | 来源 | 处理结果 | 是否阻断 |
 |--------|------|----------|----------|
@@ -47,17 +47,17 @@ owner: ai
 | 工程基线 | 有 / 无 | 工程基线审查 / 跳过 |
 | 系统架构 | 有 / 无 | 系统概要设计 / 跳过 |
 | 数据架构 | 有 / 无 | 数据架构 / 跳过 |
-| 安全红线 | 有 / 无 | `TODO-HUMAN-REVIEW` / 跳过 |
+| 高风险变更 / 人工确认项 | 有 / 无 | 需确认 / 不适用 |
 
 ## 6. 完成标准
 
-- [ ] PRD 已吸收产品总体设计 / 功能架构、产品设计、低保真原型评审和高保真 HTML 原型暴露的阻断项。
+- [ ] Spec 已吸收产品总体设计 / 功能架构、产品设计、低保真原型评审和高保真 HTML 原型暴露的阻断项。
 - [ ] 本轮做什么、不做什么、延后什么已经明确。
-- [ ] OpenAPI、工程基线、系统架构、数据架构、安全红线影响已有明确结论。
+- [ ] OpenAPI、工程基线、系统架构、数据架构、风险影响已有明确结论。
 - [ ] 可进入 API 影响分析 / 契约草案 / 工程基线，或阻断项已列出。
 
 ## 7. 下一步门禁
 
 - 结论：Approved / Blocked
-- 下一步：API 影响分析 / 契约草案 / 工程基线 / 回到 PRD 或产品设计
+- 下一步：API 影响分析 / 契约草案 / 工程基线 / 回到 Spec 或产品设计
 - 阻断项：

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

@@ -9,8 +9,58 @@ owner: ai
 
 ## 结论
 
+Approved / Changes requested / Blocked
+
 ## 发现
 
+| 严重级别 | 文件 / 位置 | 问题 | 建议 |
+|---|---|---|---|
+|  |  |  |  |
+
 ## 必须修复项
 
+- [ ]
+
+## YSS 后端门禁审查
+
+> 涉及后端切片时必填；不涉及时写 `not-applicable`。任何 `violation` 都阻断完成 / 可合并结论。
+
+| 检查项 | 结论 | 证据 |
+|---|---|---|
+| 已存在 `Backend Slice Implementation Contract`，且 required skills / allowed paths / forbidden patterns / evidence / seam / verification 完整 | pass / violation / not-applicable |  |
+| `yss-domain` / `yss-backend-scaffold-domain` 已按影响面落实，Domain 不依赖 Adapter、Infrastructure、Mapper、Controller 或 Web DTO | pass / violation / not-applicable |  |
+| `yss-backend-scaffold-application` 已按影响面落实，Application 只做用例编排、事务边界和跨聚合协调 | pass / violation / not-applicable |  |
+| `yss-repository` / `yss-backend-scaffold-infrastructure` 已按影响面落实，需要持久化的切片有 PO / Repository / Convertor / GatewayImpl | pass / seam-deferred / violation / not-applicable |  |
+| `yss-web-controller` / `yss-dto` 已按影响面落实，CMD / Query / VO / Result 按既有 DTO 体系定义或复用，Controller 不用内部类或非约定包临时承载主要 DTO / VO、不手工分页主要业务集合、不穿透 Repository | pass / violation / not-applicable |  |
+| `mapstruct` 已按影响面落实，PO / Domain Model / DTO / VO / CMD / Query 转换使用 MapStruct Convertor / Mapper，未使用 `BeanUtils.copyProperties`、反射拷贝或重复手写字段赋值；例外已记录测试和补齐落点 | pass / violation / not-applicable |  |
+| `lombok` 已按影响面落实，POJO 样板代码使用 Lombok，未成片手写 getter/setter、constructor、builder、logger；实体 / POJO 未触发 `@Data` 等反模式或已说明例外 | pass / violation / not-applicable |  |
+| `alibaba-java-code-style` 已纳入审查，命名、异常、日志、ORM/MyBatis、Maven、MapStruct / Lombok 注解处理器配置、安全项无 blocker | pass / violation / not-applicable |  |
+| 后端构建 / 测试 / OpenAPI / CI / Release 命令使用项目根目录 `./mvnw ...`；裸 `mvn ...` 已改正或有受控例外记录 | pass / violation / not-applicable |  |
+| 持久化文档正文、章节标题、审查结论和实施说明使用中文；英文模板内容未原样落地 | pass / violation / not-applicable |  |
+| `Build Architecture Checklist` 已回勾，延期项、漂移项、违反项有明确处理结论 | pass / violation / not-applicable |  |
+
+### 后端 smoke check
+
+```bash
+rg -n "class (SingleResult|MultiResult|PageResult|Result)<|public static class .*(Command|Cmd|Query|VO)|subList\\(|InMemory.*Gateway|implements .*Gateway|extends .*Repository|@TableName|Mappers\\.getMapper" apps/backend
+```
+
+命中说明：`SingleResult` / `PageResult`、`CMD` / `Query` / `VO` 命中不等于失败；需要说明其是否来自 `yss-dto` / 项目既有体系、是否位于约定包路径、是否继承约定基类。
+
+| 命中 | 解释 | 结论 |
+|---|---|---|
+|  |  | expected / seam-deferred / violation |
+
+## 压力场景验证
+
+| 压力场景 | 预期 | 本次结论 |
+|---|---|---|
+| Agent 尝试用 Controller 内部类承载主要 CMD / VO 或私自新建 Result 包装 | 应被标记为 `violation`，回到 `yss-web-controller` / `yss-dto` 复用 / 定义约定 DTO |  |
+| Agent 尝试用 `BeanUtils.copyProperties`、反射拷贝或大段手写字段赋值完成 POJO 转换 | 应被标记为 `violation`，回到 `mapstruct` 补 Convertor / Mapper，或补受控例外、测试和 review 证据 |  |
+| Agent 尝试成片手写 getter/setter、constructor、builder 或 logger | 应被标记为 `violation`，回到 `lombok` 补注解，或补受控例外、测试和 review 证据 |  |
+| Agent 尝试用 `InMemory*Gateway` 完成正式持久化 | 只能 `seam-deferred`，必须有补齐切片和风险说明 |  |
+| Agent 只写“符合 YSS”但没有 skill / 文件 / 测试证据 | 应被标记为 `violation` |  |
+| Agent 在后端验证、CI、README 或发布说明中写裸 `mvn ...` | 应改为项目根目录 `./mvnw ...`，否则标记为 `violation` |  |
+| Agent 将英文 skill / 模板的标题和说明原样输出为项目持久化文档 | 应改为中文正文和中文章节标题，否则标记为 `violation` |  |
+
 ## 签字确认

package/template/docs/templates/spec-delta-template.md

@@ -1,16 +1,16 @@
 # <功能名称> Spec Delta
 
-> 适用场景：API、权限、状态机、数据模型、跨端协作、新模块或高风险变更需要在 PRD、OpenAPI Draft、Design Review 和垂直切片之间明确行为差异时使用。  
+> 适用场景：修改既有冻结 Spec 基线时，API、权限、状态机、数据模型、跨端协作或其他高风险行为需要在 Spec、OpenAPI Draft、Design Review 和垂直切片之间明确差异。全新产品或全新模块不使用本模板。
 > 本模板只借鉴 OpenSpec 的行为差异表达方式，不引入 OpenSpec CLI、旧式变更目录、变更状态文件或额外状态机。
 
 ## 1. 变更摘要
 
 | 项 | 内容 |
 |---|---|
-| 需求 / PRD |  |
+| 需求 / Spec |  |
 | 相关 OpenAPI Draft / Freeze |  |
 | 相关架构 / 设计审查 |  |
-| 相关 Issue / 切片 |  |
+| 相关 Ticket / 切片 |  |
 | 变更类型 | 新增 / 修改 / 移除 / 高风险修正 |
 | 是否阻塞实现 | 是 / 否 |
 
@@ -39,7 +39,7 @@
 | 数据模型 / Repository / 查询索引 | 是 / 否 |  |
 | 外部系统 / 跨端协作 | 是 / 否 |  |
 | 发布 / 回滚 / 运维 | 是 / 否 |  |
-| 安全红线 / 人审点 | 是 / 否 |  |
+| 风险 / 人审点 | 是 / 否 |  |
 
 ## 4. 验收场景
 
@@ -64,6 +64,6 @@
 ## 7. 结论
 
 - 是否允许进入 OpenAPI Freeze / no API impact 记录：
-- 是否允许进入 `to-issues`：
+- 是否允许进入 `to-tickets`：
 - 必须带入垂直切片的约束：
 - Git checkpoint 状态：

package/template/docs/templates/{prd-template.md → spec-template.md}

@@ -1,11 +1,15 @@
 ---
 pipeline: <feature-id>
 stage: open
-status: draft
+status: ready-for-human
 owner: ai
 ---
 
-# 产品需求文档：<功能名称>
+# 产品研发规格：<功能名称>
+
+## 功能父 Ticket
+
+<GitHub / GitLab Ticket 链接或本地待发布 Ticket 路径>
 
 ## 问题陈述
 
@@ -41,6 +45,15 @@ owner: ai
 那么 <可观察结果>
 ```
 
+## 产品总体设计 / 功能架构
+
+- 功能域与模块边界：
+- MVP / 非目标：
+- UI 影响：是 / 否
+- 产品总体设计：`docs/design/<feature>-product-overview-design.md`
+
+> 只有存在 UI 影响时，才强制低保真页面草图、状态矩阵、高保真 HTML 原型和用户确认；否则记录 `not-applicable` 及原因。
+
 ## OpenAPI 影响
 
 - [ ] 无
@@ -65,7 +78,7 @@ owner: ai
 | 是否新增或改变限界上下文 / 模块边界 |  | 需要在产品总体设计中完成 Strategic DDD Check |
 | 是否改变上下文间协作关系 |  | 说明上游 / 下游 / 防腐层 / 共享内核关系 |
 | 是否新增或改变聚合、不变量、状态机 |  | 需要在系统概要设计 / 数据架构中完成 Tactical DDD Check |
-| 是否影响 API、权限、数据、审计或安全红线 |  | 进入对应契约、架构或人工审查门禁 |
+| 是否影响 API、权限、数据、审计或风险 / 回滚约束 |  | 进入对应契约、架构或人工审查门禁 |
 
 ## 测试决策
 
@@ -81,12 +94,9 @@ owner: ai
 
 | 范围 | Agent 权限 | 是否需要人工审查 | 备注 |
 |---|---|---|---|
-| 支付逻辑 | 仅生成草案 | 是 | |
-| 数据库迁移 | 仅生成模板 | 是 | |
-| 认证 / 授权 | 仅生成草案 | 是 | |
-| 加密算法 | 禁止生成 | 是 | |
-| 原生 SQL | 仅生成草案 | 是 | |
-| 公共基础库 API | 仅生成草案 | 是 | |
+| 支付逻辑 | 记录验证证据 | 是 | |
+| 原生 SQL | 记录验证证据 | 是 | |
+| 公共基础库 API | 记录验证证据 | 是 | |
 
 ## 非目标范围
 

package/template/docs/templates/subagent-task-package-template.md

@@ -0,0 +1,93 @@
+---
+status: template
+owner: ai
+---
+
+# Subagent Task Package：<task_id>
+
+> 用于主控 Agent 派发 subagent 前固定输入、输出、写范围和验收标准。没有任务包边界时，不得派发 subagent。
+
+## 1. 基本信息
+
+| 字段 | 内容 |
+|---|---|
+| task_id |  |
+| Feature / Change |  |
+| 生命周期阶段 |  |
+| 对应门禁 |  |
+| Ticket / MR / PR |  |
+| 主控 Agent |  |
+| subagent 角色 | Explorer / Drafter / Worker / Reviewer / Verifier |
+| 任务类型 | explore / draft / work / review / verify |
+
+## 2. 输入资产
+
+| 输入 | 路径 / 链接 | 用途 |
+|---|---|---|
+| Spec / Discovery |  |  |
+| Product / Interaction Design |  |  |
+| OpenAPI Draft / Freeze |  |  |
+| Architecture / ADR / CONTEXT |  |  |
+| Ticket / Slice / Checklist |  |  |
+| 代码 / 命令 / 其他 |  |  |
+
+## 3. 输出要求
+
+| 输出 | 路径 / 链接 | 完成标准 |
+|---|---|---|
+|  |  |  |
+
+## 4. 写范围
+
+| 范围 | 允许 / 禁止 | 说明 |
+|---|---|---|
+| 允许修改的文件 / 模块 |  |  |
+| 只读路径 |  |  |
+| 明确禁止修改 |  |  |
+
+## 5. 禁止事项
+
+- [ ] 不得执行 Spec baseline / requirement freeze。
+- [ ] 不得执行 OpenAPI Freeze。
+- [ ] 不得给出 Architecture Review 最终放行结论。
+- [ ] 不得替代风险 / 回滚约束人工确认。
+- [ ] 不得替代 Git checkpoint 范围裁决。
+- [ ] 不得宣布“完成 / 可合并 / 可发布”。
+- [ ] 不得 revert 或覆盖其他 Agent / 用户的改动。
+
+## 6. 验收标准
+
+- [ ] 输出与输入资产逐项对应。
+- [ ] 结论区分事实、推断和建议。
+- [ ] 写入类任务只修改授权范围。
+- [ ] 审查类任务列出 blocker / non-blocker / residual risk。
+- [ ] 验证类任务记录命令、时间、结果和残余风险。
+- [ ] 需要人工确认的事项记录范围、责任人和结论。
+
+## 7. 汇合方式
+
+| 项目 | 内容 |
+|---|---|
+| 结果回填位置 |  |
+| 冲突上报方式 |  |
+| 主控 Agent 合并动作 | 采纳 / 部分采纳 / 不采纳 / 需返工 |
+| 未采纳原因 |  |
+
+## 8. 子代理最终回复格式
+
+```markdown
+### 结果摘要
+- <完成了什么>
+
+### 证据
+- <文件 / 命令 / 链接>
+
+### 变更路径
+- <如无写入，填“无，只读任务”>
+
+### 风险与阻塞
+- <blocker / residual risk / 人工确认项>
+
+### 需要主控 Agent 裁决
+- <Freeze / 安全 / 范围 / 发布等事项>
+```

package/template/docs/templates/verification-record-template.md

@@ -14,12 +14,12 @@ owner: ai
 
 | 范围 | 说明 | 是否覆盖 |
 |------|------|----------|
-| PRD 验收标准 |  | 是 / 否 |
+| Spec 验收标准 |  | 是 / 否 |
 | OpenAPI / 契约 |  | 是 / 否 / 不适用 |
 | 后端行为 |  | 是 / 否 / 不适用 |
 | 前端组件 / 页面 |  | 是 / 否 / 不适用 |
 | E2E 关键路径 |  | 是 / 否 / 不适用 |
-| 安全红线 |  | 是 / 否 / 不适用 |
+| 风险 / 回滚约束 |  | 是 / 否 / 不适用 |
 
 ## 2. 命令与结果
 

package/template/docs/templates/vertical-slice-ticket-template.md

@@ -0,0 +1,88 @@
+# 垂直切片 Ticket：<标题>
+
+## 父级
+
+<Spec / 功能父 Ticket 链接>
+
+## 要构建什么
+
+描述本 Ticket 要交付的窄而完整的端到端行为。它必须贯穿所有受影响层，是可独立验证的垂直切片，不能只是某一层的横向任务。
+
+## 覆盖的用户故事
+
+- <用户故事 ID 或文本>
+
+## OpenAPI 影响
+
+- [ ] 无
+- [ ] 基于冻结 OpenAPI：`docs/api/specs/<feature>.yaml`
+
+受影响端点：
+
+| 方法 | 路径 | 变更 |
+|---|---|---|
+| | | |
+
+## 验收标准
+
+- [ ] 标准 1
+- [ ] 标准 2
+- [ ] 标准 3
+
+## 测试 Seam
+
+- 主要公共接口：
+- 必需测试：
+  - [ ] 行为 / 领域测试
+  - [ ] API / 契约测试
+  - [ ] UI / 组件测试
+  - [ ] E2E 测试
+
+## YSS 技能与后端实现合同
+
+> 涉及后端时必须填写；不涉及时写明 `not-applicable`。不得只写“符合 YSS”。
+
+| 影响面 | 必需 skill | 需要 / 不需要的理由 | 预期证据 |
+|---|---|---|---|
+| Domain / 领域行为 | `yss-domain` / `yss-backend-scaffold-domain` |  |  |
+| Application / 用例编排 | `yss-backend-scaffold-application` |  |  |
+| Infrastructure / Repository | `yss-repository` / `yss-mybatis` / `yss-backend-scaffold-infrastructure` |  |  |
+| Web Adapter / DTO | `yss-web-controller` / `yss-dto` / `yss-backend-scaffold-web` |  |  |
+| POJO / 对象转换 | `lombok` / `mapstruct` |  |  |
+| Java 规范 | `alibaba-java-code-style` |  |  |
+
+### 后端阻断规则
+
+- [ ] 未填写 `Backend Slice Implementation Contract` 时不得写后端业务代码。
+- [ ] `CMD` / `Query` / `VO` / `SingleResult` / `MultiResult` / `PageResult` 按 `yss-dto` 定义或复用；不私自新建 / 混用响应包装。
+- [ ] Controller 不用内部类或非约定包临时承载主要 DTO / VO；写操作参数继承 `CommandDTO`，读操作参数继承 `QueryDTO` 或 `PageQuery`，分页查询优先继承 `PageQuery`。
+- [ ] Controller 不手工分页主要业务集合，不穿透 Repository / Mapper / PO。
+- [ ] Application 只做用例编排、事务边界和跨聚合协调，核心领域规则放入 Domain。
+- [ ] 需要持久化的切片必须补 PO / Repository / Convertor / GatewayImpl；临时 `InMemory*Gateway` 必须标记 `seam-deferred`。
+- [ ] POJO 样板代码默认使用 Lombok；成片手写 getter/setter、constructor、builder、logger 必须说明例外原因、测试证据和 review 结论。
+- [ ] MapStruct / Convertor 强制优先；`BeanUtils.copyProperties`、反射式通用拷贝或重复手写 mapping 必须说明例外原因、测试证据和 review 结论。
+
+## 阻塞关系
+
+- 无，可立即开始
+
+## 状态
+
+`ready-for-agent`
+
+> 仅当阻塞关系为“无”且必要门禁已通过时填写 `ready-for-agent`；否则写明被哪个 Ticket 阻塞。
+
+## AI / 人工审查点
+
+- [ ] 无高风险变更或需人工确认项
+- [ ] 原生 SQL：记录验证证据
+- [ ] 公共基础库 API：记录验证证据
+
+## 完成定义
+
+- [ ] 如有需要，已基于冻结 OpenAPI Spec 拆分切片
+- [ ] 实现完成
+- [ ] 已新增测试且测试通过
+- [ ] 已移除调试 / 原型代码
+- [ ] 已回勾 `Backend Slice Implementation Contract` 和 `Build Architecture Checklist`
+- [ ] 如领域或架构决策变化，已更新 `CONTEXT.md` / ADR

package/template/docs/user-guide/README.md

@@ -9,7 +9,7 @@
 ## 推荐流程
 
 1. 在 `docs/discovery/` 记录机会探索、市场、竞品和用户洞察。
-2. 在 `docs/requirements/` 维护 PRD、用户故事和验收标准。
+2. 在 `docs/requirements/` 维护 Spec、用户故事和验收标准。
 3. 在 `docs/design/` 维护页面、原型、用户流和交互状态。
 4. 在 `docs/api/` 维护 OpenAPI 3.1 契约。
 5. 在 `docs/architecture/` 和 `docs/adr/` 记录业务架构、功能架构、系统总体架构、数据架构和架构决策。
@@ -18,7 +18,7 @@
 
 ## 继续阅读
 
-- [create-yss-spec 使用手册](./create-yss-spec-cli-guide.md)
+- [create-yss-spec 外部 CLI 实践指南](./create-yss-spec-cli-guide.md)
 - [产品全生命周期使用手册](./product-lifecycle-workflow.md)
 - [全生命周期最佳实践](./lifecycle-best-practices.md)
 - [产品研发全生命周期最佳实践](./product-rd-lifecycle-best-practices.md)