create-yss-spec 1.1.4 → 2.0.0

package/template/docs/process/subagent-collaboration.md

@@ -0,0 +1,111 @@
+---
+status: active
+owner: ai
+---
+
+# Subagent 协同规范
+
+本文定义 YSS 规格流程中 subagent 的使用边界。结论：subagent 可以提升调研、草案、局部实现、独立审查和验证效率；生命周期裁决仍由主控 Agent 负责。
+
+## 核心原则
+
+```text
+子代理负责执行与证据，主控 Agent 负责裁决与收口。
+```
+
+subagent 不是“多几个 Agent 一起做同一件事”，而是主控 Agent 将生命周期中的证据收集、草案产出、局部实现、独立审查和 fresh verification 拆成有边界的任务包。没有任务包边界时，不得派发 subagent。
+
+## 角色定义
+
+| 角色 | 职责 | 典型输出 | 默认写权限 |
+|---|---|---|---|
+| 主控 Agent | 生命周期阶段判定、任务拆分、结果合并、门禁裁决、Ticket 同步、Git checkpoint | 阶段结论、正式资产、合并记录、下一步 | 可写正式资产 |
+| Explorer subagent | 查现有资产、技术事实、竞品事实、代码影响面、缺失项 | 事实清单、证据链接、风险列表 | 只读 |
+| Drafter subagent | 起草 Spec、设计、OpenAPI、架构、Ticket 或 release 文档 | 草案文档或章节补丁 | 仅限指定文档 |
+| Worker subagent | 实现指定切片、测试、脚手架或局部修复 | 代码变更、测试结果、变更说明 | 仅限指定文件 / 模块 |
+| Reviewer subagent | 独立审查 Spec、OpenAPI、架构、代码、发布准备度 | findings、blocker、残余风险 | 默认只读 |
+| Verifier subagent | 执行验证、复现实验、回归命令、截图或 CI 证据整理 | fresh verification 记录 | 默认只读，必要时写验证记录 |
+
+## 可委派与不可委派
+
+| 可委派事项 | 不可委派事项 |
+|---|---|
+| 竞品 / 市场 / 技术事实调研 | 生命周期阶段最终判定 |
+| Discovery / Spec / 设计 / 架构 / OpenAPI 草案 | Spec baseline / requirement freeze |
+| API Draft Review、Design Review findings | OpenAPI Freeze |
+| 垂直切片草案和实现路由草案 | Architecture Review 最终放行 |
+| 前端、后端、测试等边界清晰的局部实现 | 风险 / 回滚约束裁决 |
+| 独立 code review | Ticket tracker 最终状态裁决 |
+| fresh verification 执行与证据整理 | Git checkpoint 范围裁决 |
+| release note / retro 草案 | “完成 / 可合并 / 可发布”结论 |
+
+## 任务包门禁
+
+主控 Agent 派发 subagent 前，必须为每个任务包明确：
+
+- `task_id`：唯一编号，关联阶段、Ticket 或切片。
+- 任务类型：explore / draft / work / review / verify。
+- 生命周期阶段和对应门禁。
+- 输入资产：Spec、OpenAPI、设计、ADR、Ticket、代码路径或命令。
+- 输出资产：文档路径、review findings、代码文件、验证记录或摘要。
+- 写范围：允许修改的文件 / 模块；只读任务必须写明只读。
+- 禁止事项：不得 freeze、不得覆盖他人改动、不得替主控 Agent 做最终阶段结论。
+- 验收标准：完成后主控 Agent 如何判断任务有效。
+- 汇合方式：结果写入何处，冲突如何上报。
+
+模板见 `docs/templates/subagent-task-package-template.md`。
+
+## 生命周期使用策略
+
+| 主阶段 | 推荐用法 | 风险控制 |
+|---|---|---|
+| 1. 入口分诊 | 复杂项目可派 Explorer 检查现有资产、Ticket、git 状态 | 主控 Agent 保留最近可信阶段裁决 |
+| 2. 机会与 Discovery | 竞品、市场、用户流程、技术事实并行调研 | 调研结论只能作为 Spec 输入，不得直接冻结需求 |
+| 3. 业务 / Spec / 功能架构 | Spec 草案、功能架构、业务架构并行起草；Reviewer 质询边界 | 主控 Agent 合并术语、范围、非目标和验收标准 |
+| 4. 产品设计与需求冻结 | 页面流、状态矩阵、AntD / YSS 设计系统、高保真 HTML 原型、Prototype Review 分工 | 用户确认和 requirement freeze 不可委派 |
+| 5. 系统 / 数据架构与工程契约设计审查 | API Draft、系统架构、数据架构、Spec Delta、Draft Review 并行 | OpenAPI Freeze 和架构放行不可委派 |
+| 6. 契约冻结与 Ticket 正式化 | `to-tickets` 草案、实现仓库 / 脚手架状态检查并行 | 主控 Agent 确认端到端切片和 Ticket 同步 |
+| 7. 垂直切片与 TDD 实现 | 前端、后端、测试、验证按文件 / 模块拆给 Worker；Reviewer 独立审查 | 写范围必须不重叠；同一 Agent 不得自审 |
+| 8. 验证发布与复盘 | Verifier 执行 fresh verification；Drafter 起草 release / retro | 发布、合并、完成结论不可委派 |
+
+## 并行拆分规则
+
+- 信息类任务可并行：不同事实来源、不同资产检查、不同审查维度可以同时进行。
+- 写入类任务按文件或模块拆分：每个 Worker 必须有不重叠的写范围。
+- 阻塞链路主控优先：如果主控 Agent 下一步立即依赖某个结果，应优先本地完成，不把关键路径外包后等待。
+- 子代理不得重复彼此任务；同一问题只能派一个责任代理，除非明确是独立复核。
+- 子代理返回结果后，主控 Agent 必须做快速审查、合并和冲突处理，不能直接把子代理输出视为阶段结论。
+
+## 合并与冲突处理
+
+当 subagent 结论冲突时，主控 Agent 按以下优先级裁决：
+
+1. 已冻结的 Spec、OpenAPI Freeze、ADR、架构评审和 Ticket。
+2. 当前 fresh verification、测试、CI 和可复现证据。
+3. `CONTEXT.md` 中已确认的领域术语。
+4. 风险记录和人工确认要求。
+5. 用户最新明确指令。
+
+若冲突会改变需求、契约、架构、安全或发布结论，必须回到对应生命周期阶段重新审查，不得由 subagent 或主控 Agent 临时绕过。
+
+## 记录要求
+
+每个使用 subagent 的生命周期阶段，必须在阶段 checkpoint 或 Ticket 评论中记录：
+
+- 派发的任务包编号和子代理角色。
+- 输入资产和输出资产。
+- 写范围和实际变更路径。
+- 是否存在冲突、漂移或被主控 Agent 覆盖的结论。
+- 独立 review / fresh verification 证据。
+- 未采纳的子代理建议及原因。
+
+## 最小落地标准
+
+一次 subagent 协同只有同时满足以下条件，才算可追溯：
+
+- 至少一个任务包使用 `docs/templates/subagent-task-package-template.md` 或等价字段记录。
+- 阶段 checkpoint 记录 subagent 使用情况。
+- 所有写入类 subagent 的文件范围清晰且不重叠。
+- 所有审查类 subagent 独立于实现者。
+- 主控 Agent 明确给出最终阶段结论和证据来源。
+- 风险 / 回滚约束、Freeze、release、Git checkpoint 未被 subagent 代替裁决。

package/template/docs/process/template-governance-grilling-record.md

@@ -0,0 +1,38 @@
+# 模板治理流程质询记录
+
+> 日期：2026-07-20
+> 范围：`yss-spec-project-template` 模板源仓库
+> 方法：`grill-with-docs` + `domain-modeling`
+
+## 结论
+
+1. 新流程的规范语言统一为 Spec、Ticket、`to-spec`、`to-tickets`；PRD、Issue、`to-prd`、`to-issues` 不再作为模板入口。
+2. 仓库身份分为 `template-source` 和 `project-instance`，Agent 必须在分诊前识别身份。
+3. 8 个主阶段是项目实例的生命周期骨架；21 个门禁采用条件强制，未触发时只记录 `not-applicable` 及原因。
+4. `CONTEXT.md`、`AGENTS.md`、`lifecycle-artifact-map.md`、`harness-process-tailoring.md`、`skills-lock.json` 分别承担词汇、Agent 入口、生命周期映射、触发规则和技能清单的单一事实来源。README 和用户指南只导航与解释。
+5. 过时技能 `to-prd` 和 `to-issues` 从模板源、锁文件、校验脚本和所有 Agent root 中直接删除，不保留转发别名。
+6. `.agents/skills` 是跨 Agent 共享技能的权威内容；Claude、Codex、Hermes、Pi 和 Trae 的同名技能是生成投影。不再声明单数 `.agent/`。
+7. 所有进入 Spec 基线的功能都需要产品总体设计或功能架构；只有存在 UI 影响时才触发低保真、状态矩阵、高保真 HTML 原型和用户确认。
+8. Spec、设计和 OpenAPI Draft 使用 `ready-for-human`；只有通过必要门禁的垂直切片 Ticket 才能使用 `ready-for-agent`。
+9. 每个功能先建立一个功能父 Ticket 汇总阶段证据；契约冻结后再生成垂直切片子 Ticket。
+10. `AGENTS.md` 只保留全局路由、硬门禁和禁止事项；YSS 实现细则下沉到专项 skill、Implementation Contract 和 review checklist。
+11. 根目录新增 `yss-project.yaml`，只声明 `schema_version` 和 `repository_mode`。该契约的取舍见 `docs/adr/0002-yss-project-repository-mode.md`。
+12. `template-source` 使用模板维护流程，不默认生成产品 Spec、原型或 OpenAPI。
+13. Spec Delta 只记录对既有冻结基线的行为差异，不用于全新产品或全新模块。
+14. 模板内的测试覆盖率数字是推荐基线；项目实例明确采纳后才构成 CI 门禁。
+15. `scripts/verify-template` 是模板发布阻断门禁，需覆盖身份清单、技能投影、旧入口清理、单一事实来源和压力场景。
+16. 本次整改对模板源执行完整破坏性清理，并用迁移指南承接旧项目；不修改已生成的外部项目。
+17. `AGENTS.md` 不再保存项目名称、业务领域和团队规模占位符。
+18. `yss-project.yaml` 是模板与 `create-yss-spec` 的跨仓库契约；CLI 未完成 `project-instance` 改写和集成验证前，模板不得声称可发布。
+19. 允许对上游 Matt skills 做 YSS 适配，但锁文件必须同时记录上游与有效内容哈希。
+20. 模板发布、代码切片和高风险变更必须独立审查；低风险文档变更可使用人工 checkpoint。
+21. 本次变更按破坏性主版本升级管理，模板与 CLI 协调发布。
+22. ADR 统一使用 `docs/adr/0001-*.md` 顺序编号，通用 ADR 模板移入 `docs/templates/`。
+23. 所有面向人的落地文档统一使用简体中文，必要的英文专有名词、代码标识和 metadata 保持原样。
+
+## 实施边界
+
+- 先整改当前模板源仓库并执行模板发布门禁。
+- 为 `create-yss-spec` 生成跨仓库 handoff；未获得单独授权时不修改外部 CLI 仓库。
+- 当前工作区中与本任务无关的 `.gitignore` 和 `.obsidian/workspace.json` 变更不纳入本轮整改。
+- 执行期间外部新增且未登记到 `skills-lock.json` 的 `drawio` / `drawio-academic-skills` 目录不纳入本轮发布范围；同步与锁定脚本不会自动吸收未跟踪 skill。

package/template/docs/process/template-governance-skill-validation.md

@@ -0,0 +1,44 @@
+# 模板治理规则压力验证
+
+> 日期：2026-07-20
+> 方法：`writing-skills` RED / GREEN / REFACTOR
+> 目标：验证仓库身份、状态路由、UI 条件门禁、技能投影和旧入口清理
+
+## RED：修订前基线失败
+
+| 压力场景 | 压力组合 | 修订前行为 | 失败证据 |
+|---|---|---|---|
+| Spec 初稿刚写完，开发窗口只剩一天，实现者要求立即开工 | 时间 + 权威 + 交付压力 | `to-spec` 直接将 Spec 标记 `ready-for-agent` | `.agents/skills/to-spec/SKILL.md` 明确要求“Apply the ready-for-agent triage label” |
+| 垂直切片 B 被 A 阻塞，但团队希望并行开工 | 进度 + 并行 + 沉没成本 | `to-tickets` 默认给所有 Ticket 标记 `ready-for-agent` | 技能没有将“阻塞边未清除”作为标签前置条件 |
+| 只在 Codex 根目录紧急修改一个共享 skill | 时间 + 局部便利 + 多端成本 | 不同 Agent root 的同名 skill 内容哈希不一致 | 修订前 `to-tickets` 和 `to-issues` 已出现多个哈希 |
+| 纯后端 API 功能被要求尽快进入契约设计 | 时间 + 流程合规 + 无 UI 事实 | 入口规则仍要求所有 Spec 产出低保真页面草图 | 修订前 `AGENTS.md` 未将功能架构与 UI 原型门禁分开 |
+| 维护模板规则时，Agent 按完整产品生命周期补 Spec 和 OpenAPI | 合规 + 上下文 + 产物压力 | 仓库没有机器可读身份，只能猜测 | 修订前缺少 `yss-project.yaml` 和模板维护路由 |
+
+其他基线失败：
+
+- `scripts/verify-template` 首次执行失败：`missing Matt skill: .agents/skills/to-prd/SKILL.md`。
+- README 仍将 PRD 和 `to-issues` 作为 Quickstart 入口，与 `AGENTS.md` 的 Spec / `to-tickets` 主链冲突。
+
+## GREEN：目标行为
+
+| 场景 | 必须得到的结果 |
+|---|---|
+| Spec 初稿 | 功能父 Ticket 使用 `ready-for-human`，不得立即进入实现 |
+| 被阻塞的子 Ticket | 保留阻塞关系，不得标记 `ready-for-agent` |
+| 共享 skill 修改 | 只修改 `.agents/skills`，然后生成投影并刷新锁文件 |
+| 纯后端功能 | 产出功能架构，UI 相关产物标记 `not-applicable` |
+| 模板源维护 | 进入模板维护流程，不生成产品 Spec / OpenAPI |
+
+## REFACTOR：验证证据
+
+- [x] `to-spec` 状态语义校验：Spec 初稿创建功能父 Ticket 并使用 `ready-for-human`，状态红线明确禁止 `ready-for-agent`。
+- [x] `to-tickets` frontier 标签校验：被阻塞 Ticket 不得使用 `ready-for-agent`，只有阻塞边清除的 frontier Ticket 可进入实现。
+- [x] 共享技能目录哈希校验：`scripts/sync-skills --check` 输出 `skill projections are synchronized`。
+- [x] 锁文件校验：`scripts/update-skill-lock --check` 输出 `skills-lock.json matches distributed skills`；锁文件记录 35 个共享 skills 与 62 个平台 skills。
+- [x] 五类路由压力场景校验：`scripts/verify-lifecycle-scenarios` 输出 `五类生命周期压力场景验证通过`。
+- [x] `scripts/verify-template` fresh verification：输出 `模板发布校验通过`。
+
+## 尚未解除的发布门禁
+
+- 当前实现者的差异自检不构成独立审查；模板仍需其他 Agent 或人工 Reviewer 审查。
+- 外部 `create-yss-spec` 尚未完成 `project-instance` 转换和共同集成验证，因此整体 major 版本仍不可发布。

package/template/docs/process/templates/stage-checkpoint-template.md

@@ -5,7 +5,7 @@ owner: ai
 
 # 阶段 Checkpoint 记录模板
 
-> 用于每个生命周期阶段结束时，复制到 Issue 评论、MR / PR 描述或阶段文档。目标是固定产物、验证、风险、Issue 同步和 Git checkpoint 判断，避免阶段结论只停留在本地上下文。
+> 用于每个生命周期阶段结束时，复制到 Ticket 评论、MR / PR 描述或阶段文档。目标是固定产物、验证、风险、Ticket 同步和 Git checkpoint 判断，避免阶段结论只停留在本地上下文。
 
 ## 基本信息
 
@@ -16,7 +16,8 @@ owner: ai
 | 对应门禁 |  |
 | 记录日期 |  |
 | 记录人 / Agent |  |
-| Issue / MR / PR |  |
+| 主控 Agent |  |
+| Ticket / MR / PR |  |
 
 ## 阶段产物
 
@@ -24,11 +25,11 @@ owner: ai
 |---|---|---|---|
 |  |  | `done` / `draft` / `not-applicable` |  |
 
-## Issue 同步状态
+## Ticket 同步状态
 
 | 项目 | 内容 |
 |---|---|
-| Issue tracker | GitLab / GitHub / 本地文档 |
+| Ticket tracker | GitLab / GitHub / 本地文档 |
 | 已同步内容 |  |
 | 未同步原因 |  |
 | 下一次同步点 |  |
@@ -39,14 +40,49 @@ owner: ai
 |---|---|---|---|
 |  |  | `pass` / `fail` / `not-run` |  |
 
-## 阻塞项与安全人审
+## Subagent 协同记录
+
+| 项目 | 内容 |
+|---|---|
+| 是否使用 subagent | 是 / 否 |
+| 使用原因 |  |
+| 任务包位置 |  |
+| 不可委派门禁确认 | 生命周期阶段判定 / Spec baseline / requirement freeze / Prototype 用户确认 / OpenAPI Freeze / Architecture Review 放行 / 风险 / 回滚约束 / Ticket 状态 / Git checkpoint / 完成结论均由主控 Agent 收口 |
+
+| task_id | subagent 角色 | 任务类型 | 输入资产 | 输出产物 | 写范围 | 主控采纳结论 |
+|---|---|---|---|---|---|---|
+|  | Explorer / Drafter / Worker / Reviewer / Verifier | explore / draft / work / review / verify |  |  | 只读 / 指定路径 | 采纳 / 部分采纳 / 不采纳 / 需返工 |
+
+| 冲突 / 分歧 | 裁决依据 | 回填资产 | 是否阻断 |
+|---|---|---|---|
+|  | Spec / OpenAPI / ADR / Ticket / 测试 / CONTEXT / 风险 / 回滚约束 / 用户指令 |  | 是 / 否 |
+
+| 独立审查项 | 结论 | 证据 |
+|---|---|---|
+| Reviewer 独立于 Worker / Drafter | 是 / 否 / 不适用 |  |
+| Verifier 独立执行 fresh verification | 是 / 否 / 不适用 |  |
+
+## 阻塞项与人工审查
 
 | 类型 | 描述 | 处理方式 | 是否阻断 |
 |---|---|---|---|
 | 阻塞项 |  |  | 是 / 否 |
-| 安全红线 |  | `TODO-HUMAN-REVIEW` / 不适用 | 是 / 否 |
+| 高风险变更 / 人工确认项 |  | 需确认 / 不适用 | 是 / 否 |
 | 架构漂移 |  | Architecture Re-check / 不适用 | 是 / 否 |
 
+| 人审项 | 是否涉及 | 结论 | 证据 / 链接 |
+|---|---|---|---|
+| DDL / SQL / 数据库迁移 | 是 / 否 | 通过 / 草案 / 阻断 / 不适用 |  |
+| 权限接入 / 认证 / 授权 | 是 / 否 | 通过 / 草案 / 阻断 / 不适用 |  |
+| 审计日志 | 是 / 否 | 通过 / 草案 / 阻断 / 不适用 |  |
+
+## 实现仓库 / 脚手架状态
+
+| repo_role | repo / output_dir | scaffold_status | scaffold_skill | 目标是否确认 |
+|---|---|---|---|---|
+| backend |  | existing / required / initialized / not-applicable | `yss-ddd-scaffold-generator` / none | 是 / 否 / 不适用 |
+| frontend |  | existing / required / initialized / not-applicable | `yss-frontend-scaffold-generator` / none | 是 / 否 / 不适用 |
+
 ## Git Checkpoint 判断
 
 | 项目 | 内容 |
@@ -63,4 +99,3 @@ owner: ai
 - 进入条件：
 - 负责人：
 - 预计补齐项：
-

package/template/docs/releases/next-major-template-governance.md

@@ -0,0 +1,32 @@
+# 下一主版本：模板治理与 Spec / Ticket 规范化
+
+> 状态：草案，尚不可发布。
+
+## 破坏性变更
+
+- 新流程只使用 Spec、Ticket、`to-spec`、`to-tickets`。
+- 根目录新增 `yss-project.yaml`，Agent 必须按 `repository_mode` 路由。
+- `.agents/skills` 成为共享技能权威内容，其他 Agent root 使用生成投影。
+- Spec 初稿使用 `ready-for-human`；`ready-for-agent` 只用于已解除阻塞、可直接实现的垂直切片 Ticket。
+- Spec Delta 只用于修改既有冻结基线的中高风险行为，不用于全新产品或全新模块。
+- 所有面向人的落地文档正文以简体中文为标准语言。
+
+旧版项目必须按 `docs/user-guide/spec-ticket-migration-guide.md` 一次性迁移，不提供旧 skill 别名。
+
+## 模板仓库验证
+
+```bash
+scripts/sync-skills --check
+scripts/update-skill-lock --check
+scripts/verify-template
+```
+
+当前模板侧 fresh verification 已通过，包括五类生命周期压力场景、完整目录树哈希、旧入口扫描、Markdown 链接、YAML 解析和 Git 空白检查。
+
+## 发布阻塞项
+
+- 需要其他 Agent 或人工 Reviewer 完成独立审查。
+- 外部 `create-yss-spec` 需要按 `docs/implementation/create-yss-spec-repository-mode-contract.md` 实现 `project-instance` 转换、旧版升级和冲突 fail closed。
+- 模板与 CLI 需要共同执行初始化 / 升级集成验证，并绑定确定的 commit / tag。
+
+上述阻塞全部解除前，本草案不能改为已发布状态。

package/template/docs/requirements/README.md

@@ -1,6 +1,6 @@
 # 需求定义 (Requirements) — 从想法到可执行定义
 
-> **Phase: Requirements | 输入: Discovery | 输出: PRD + Stories + 验收条件**
+> **Phase: Requirements | 输入: Discovery | 输出: Spec + Stories + 验收条件**
 
 ---
 
@@ -9,24 +9,24 @@
 默认需求链路：
 
 ```text
-grill-with-docs -> to-prd -> API 影响分析 / 契约草案 -> Architecture 反审 -> OpenAPI Freeze -> to-issues
+grill-with-docs -> to-spec -> API 影响分析 / 契约草案 -> Architecture 反审 -> OpenAPI Freeze -> to-tickets
 ```
 
 进入开发前必须满足：
 
-- [ ] PRD 使用 [../templates/prd-template.md](../templates/prd-template.md)。
+- [ ] Spec 使用 [../templates/spec-template.md](../templates/spec-template.md)。
 - [ ] OpenAPI 影响明确为“无”或已产出契约草案 / review-only Draft；进入开发前必须冻结 `docs/api/specs/*.yaml`。
 - [ ] 测试决策明确主要测试 seam。
-- [ ] AI / 人工审查点标注安全红线。
-- [ ] 后续 Issue 使用 [../templates/vertical-slice-issue-template.md](../templates/vertical-slice-issue-template.md)，不得按层横向拆分。
+- [ ] AI / 人工审查点标注风险 / 人工确认项。
+- [ ] 后续 Ticket 使用 [../templates/vertical-slice-ticket-template.md](../templates/vertical-slice-ticket-template.md)，不得按层横向拆分。
 
 ## AI 三步法
 
-### Step 1: 生成 PRD 初稿
+### Step 1: 生成 Spec 初稿
 
 ```python
 delegate_task(
-    goal="根据发现报告生成 PRD 初稿",
+    goal="根据发现报告生成 Spec 初稿",
     context="""
     输入：发现报告 (市场+竞品+用户)
     输出：背景/用户画像/场景/功能需求/NFR/验收条件/边界/技术影响
@@ -38,7 +38,7 @@ delegate_task(
 
 ```python
 delegate_task(
-    goal="对 PRD 做边界场景挖掘",
+    goal="对 Spec 做边界场景挖掘",
     context="""
     从以下角度挖掘遗漏场景：
     空值/并发/权限/网络异常/数据量极端/时间相关/国际化
@@ -50,7 +50,7 @@ delegate_task(
 
 ```python
 delegate_task(
-    goal="将 PRD 拆解为可估算的用户故事",
+    goal="将 Spec 拆解为可估算的用户故事",
     context="""
     格式: As a / I want / So that
     附带 Gherkin 验收条件 + 优先级(P0/P1/P2) + AI风险标注
@@ -60,7 +60,7 @@ delegate_task(
 
 ---
 
-## PRD 模板结构
+## Spec 模板结构
 
 1. 问题陈述 / 解决方案
 2. 用户故事
@@ -77,7 +77,7 @@ delegate_task(
 ## AI-Human Loop
 
 ```
-Discovery报告 → AI生成PRD → PM审核
+Discovery报告 → AI生成Spec → PM审核
 → AI补充边界 → PM确认 → AI拆解Stories
 → 团队估算 → AI标注风险 → TechLead确认 → 进入Architecture
 ```

package/template/docs/{adr/template.md → templates/adr-template.md}

@@ -1,4 +1,4 @@
-# ADR-{NNN}: {决策标题}
+# ADR-{NNNN}: {决策标题}
 
 ## 状态
 
@@ -35,5 +35,5 @@
 
 ## 相关
 
-- ADR-{NNN}: {相关决策}
+- ADR-{NNNN}: {相关决策}
 - 相关文档链接

package/template/docs/templates/agent-brief-template.md

@@ -1,8 +1,8 @@
-# Agent Brief：<Issue 标题>
+# Agent Brief：<Ticket 标题>
 
-> 本简报用于 `ready-for-agent` 状态的 Issue。内容必须足够完整，使 Agent 无需向维护者询问隐藏背景即可开始工作。
+> 本简报用于 `ready-for-agent` 状态的垂直切片 Ticket。内容必须足够完整，使 Agent 无需向维护者询问隐藏背景即可开始工作。
 
-## Issue 信息
+## Ticket 信息
 
 - 链接：
 - 分类：bug / enhancement
@@ -42,5 +42,5 @@ Agent 应运行的命令或检查：
 
 ## 安全与人工审查
 
-- [ ] 未触碰安全红线
-- [ ] 涉及支付、迁移、认证、原生 SQL 或公共基础库 API 时，必须包含 `TODO-HUMAN-REVIEW`
+- [ ] 无高风险变更或需人工确认项
+- [ ] 涉及支付、迁移、认证、原生 SQL 或公共基础库 API 时，必须包含 人工确认项

package/template/docs/templates/build-architecture-checklist-template.md

@@ -5,7 +5,7 @@ owner: ai
 
 # <功能 / change> Build Architecture Checklist
 
-> 本模板用于 垂直切片实现 前和每个垂直切片完成后，把系统架构、数据架构、ADR、工程基线、OpenAPI Freeze 结论和安全红线转译为可执行检查项。它不是替代架构文档，而是防止架构资产在 build 阶段失效。
+> 本模板用于 垂直切片实现 前和每个垂直切片完成后，把系统架构、数据架构、ADR、工程基线、OpenAPI Freeze 结论和风险 / 回滚约束转译为可执行检查项。它不是替代架构文档，而是防止架构资产在 build 阶段失效。
 
 ## 1. 输入资产
 
@@ -17,31 +17,38 @@ owner: ai
 | 工程基线 |  |  |
 | OpenAPI Freeze |  |  |
 | 系统 / 数据架构设计 |  |  |
-| 安全红线 | `AGENTS.md` |  |
+| 风险 / 回滚约束 | `AGENTS.md` |  |
 
 ## 2. 架构约束矩阵
 
 | constraint | source | slice | status | evidence | follow-up |
 |---|---|---|---|---|---|
 | DDD 分层不得穿透：Domain 不依赖 Adapter、Infrastructure、Mapper、Controller 或 Web DTO | 系统架构 / YSS DDD 规范 / `AGENTS.md` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 若发现穿透依赖，标记 `violation` 并停止 build，回到架构修正 |
-| 安全红线：认证 / 授权、SQL / DDL、迁移、加密、公共基础库 API 变更必须 `TODO-HUMAN-REVIEW` | `AGENTS.md` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 未有人审证据时不得发布或合并 |
+| 后端切片必须回勾 `Backend Slice Implementation Contract`：required skills、允许写范围、禁止模式、证据文件、延期 seam 和验证命令完整 | implementation routing / 垂直切片 Ticket / `AGENTS.md` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 缺合同或合同不完整时暂停并记录替代方案 |
+| Web Adapter / DTO：必须按 `yss-dto` 定义或复用 CMD / Query / VO / Result；不得在 Controller 内部类或非约定包临时定义主要 DTO，不得手工分页主要业务集合 | `yss-web-controller` / `yss-dto` / OpenAPI Freeze |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 命中时回到 Controller / DTO 设计 |
+| Application：负责用例编排、事务边界和跨聚合协调，不承载核心领域规则 | `yss-backend-scaffold-application` / 系统架构 |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 领域规则下沉 Domain，事务边界留在 Application |
+| Infrastructure：需要持久化的切片必须有 PO / Repository / Convertor / GatewayImpl；`InMemory*Gateway` 只能作为显式 `seam-deferred` | `yss-repository` / `yss-backend-scaffold-infrastructure` / 数据架构 |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 未补齐时不得声称生产持久化完成 |
+| POJO / Convertor：DTO / VO / CMD / Query / PO / Domain Model 样板代码默认使用 Lombok；对象转换默认使用 MapStruct，禁止 `BeanUtils.copyProperties`、反射拷贝和重复手写字段赋值 | `lombok` / `mapstruct` / `AGENTS.md` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 未加载 skill、缺注解处理器配置、缺 Convertor 或无例外说明时标记 `violation` |
+| 后端工程工具链：构建、测试、运行、OpenAPI 生成、CI 和 Release 命令必须使用项目根目录 `./mvnw ...`；裸 `mvn ...` 必须有受控例外记录 | `yss-ddd-scaffold-generator` / `yss-backend-scaffold-parent` / implementation routing |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 无例外记录时改为 `./mvnw ...`，否则不得进入完成 / 可合并结论 |
+| 文档语言：持久化生命周期文档、实施记录、审查报告、发布说明和 Git checkpoint 正文必须使用中文，英文 skill / 模板不得原样落地 | `AGENTS.md` / `yss-product-lifecycle` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 仅保留必要英文技术标识、命令和 metadata |
+| 高风险变更：认证 / 授权、SQL / DDL、迁移、加密、公共基础库 API 变更必须记录验证证据、责任人和回滚约束 | `AGENTS.md` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 缺验证证据或责任人时不得发布或合并 |
 |  |  |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  |  |
 
 状态说明：
 
 - `implemented`：已有代码、测试或文档证据证明满足约束。
-- `seam-deferred`：允许临时 seam，但必须说明风险、补齐切片和 `TODO-HUMAN-REVIEW`；安全红线不得无限延期。
+- `seam-deferred`：允许临时 seam，但必须说明风险、补齐切片、责任人和验证计划；延期项不得无限期挂起。
 - `drift`：实现与架构意图不一致，必须先做 Architecture Re-check。
-- `violation`：违反架构或安全红线，停止继续 build，回到设计审查或架构修正。
+- `violation`：违反架构约束或缺少风险 / 回滚证据，停止继续 build，回到设计审查或架构修正。
 - `not-applicable`：当前切片不触碰该约束，并说明原因。
 
 字段说明：
 
-- `source`：回指系统架构、数据架构、ADR、OpenAPI Freeze、工程基线或安全红线来源。
+- `source`：回指系统架构、数据架构、ADR、OpenAPI Freeze、工程基线或风险 / 回滚约束来源。
 - `constraint`：可检查的架构或治理约束。
 - `slice`：绑定的垂直切片编号或名称。
 - `status`：只能使用上方状态枚举。
-- `evidence`：代码、测试、文档、Issue 评论或人审证据。
+- `evidence`：代码、测试、文档、Ticket 评论或人工确认证据。
 - `follow-up`：延期、漂移或违反时的补齐落点和是否阻断继续 build。
 
 ## 3. 当前切片回勾
@@ -50,16 +57,39 @@ owner: ai
 |---|---|---|---|---|---|
 |  |  |  |  |  |  |
 
+## 3.1 后端实现证据回勾
+
+| 层级 | required_skills | 代码证据 | 测试 / 验证证据 | 状态 | 备注 |
+|---|---|---|---|---|---|
+| Adapter / Web | `yss-web-controller`、`yss-dto`、`mapstruct`、`lombok` |  |  | `implemented` / `seam-deferred` / `violation` / `not-applicable` |  |
+| Application | `yss-backend-scaffold-application` |  |  | `implemented` / `seam-deferred` / `violation` / `not-applicable` |  |
+| Domain | `yss-domain` / `yss-backend-scaffold-domain` |  |  | `implemented` / `seam-deferred` / `violation` / `not-applicable` |  |
+| Infrastructure | `yss-repository` / `yss-backend-scaffold-infrastructure` / `yss-mybatis` / `mapstruct` / `lombok` |  |  | `implemented` / `seam-deferred` / `violation` / `not-applicable` |  |
+
+## 3.2 后端门禁 smoke check
+
+> 命中不等于必然失败；`SingleResult` / `PageResult`、`CMD` / `Query` / `VO` 是 `yss-dto` 合法产物。命中项必须说明是否复用了既有 DTO 体系、是否位于约定包路径、是否继承约定基类；无法解释或未回勾合同即为 `violation`。
+
+```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|BeanUtils\\.copyProperties|copyProperties\\(|new [A-Za-z0-9]+VO\\(|new [A-Za-z0-9]+DTO\\(" apps/backend
+rg -n "class .*(PO|DTO|VO|Cmd|Query)\\b|private final .* log =|LoggerFactory\\.getLogger|public .*(get|set)[A-Z]" apps/backend
+```
+
+### 3.3 流程规范 smoke check
+
+```bash
+rg -n '(^|[[:space:]])mvn[[:space:]]' <backend-repo-or-doc-paths>
+```
+
+命中裸 `mvn ...` 时，必须改为项目根目录 `./mvnw ...`，或在实现路由 / 审查报告中记录受控例外。中文文档规范通过人工审查正文、标题、结论和 checkpoint 说明确认；英文技术标识、命令和 metadata 不视为违规。
+
 ## 4. 人工审查点
 
-| 红线 | 是否触碰 | TODO-HUMAN-REVIEW | 人审证据 | 阻断结论 |
+| 风险事项 | 是否涉及 | 责任人 / 结论 | 证据 | 阻断结论 |
 |---|---|---|---|---|
 | SQL / DDL |  |  |  |  |
-| 数据库迁移 |  |  |  |  |
-| 认证 / 授权 |  |  |  |  |
 | 审计日志 |  |  |  |  |
 | 文件上传下载 / 临时 URL |  |  |  |  |
-| 加密算法 |  |  |  |  |
 
 ## 5. 结论
 

package/template/docs/templates/implementation-repo-registry-template.md

@@ -19,6 +19,8 @@ owner: ai
 | local_worktree |  |
 | scaffold_status | existing / required / initialized |
 | scaffold_skill | `yss-ddd-scaffold-generator` / `yss-frontend-scaffold-generator` / none |
+| scaffold_target_confirmed | 是 / 否 / 不适用 |
+| target_git_url_or_output_dir |  |
 | owner |  |
 | ci_system | GitLab CI / GitHub Actions / Jenkins / other / none |
 | issue_tracker | GitLab / GitHub / other |
@@ -52,9 +54,12 @@ owner: ai
 
 ## 5. 人工审查
 
-| human_review_required | 原因 | 审查人 / 角色 | 结论 |
-|---|---|---|---|
-| 是 / 否 |  |  |  |
+| 人工确认项 | 是否涉及 | 审查人 / 角色 | 结论 | 补齐落点 |
+|---|---|---|---|---|
+| DDL / SQL / 数据库迁移 | 是 / 否 |  | 通过 / 草案 / 阻断 / 不适用 |  |
+| 权限接入 / 认证 / 授权 | 是 / 否 |  | 通过 / 草案 / 阻断 / 不适用 |  |
+| 审计日志 | 是 / 否 |  | 通过 / 草案 / 阻断 / 不适用 |  |
+| 其他风险 / 回滚约束 | 是 / 否 |  | 通过 / 草案 / 阻断 / 不适用 |  |
 
 ## 6. Harness 回写