create-yss-spec 1.1.4 → 2.0.0

package/template/docs/discovery/templates/discovery-template.md

@@ -7,8 +7,8 @@ owner: ai
 
 # <功能名称> Discovery 收敛文档
 
-> 适用场景：机会探索、竞品分析或用户材料已经有初步输入，需要收敛为 PRD 上游事实。
-> 本文回答“为谁、为什么、第一版做什么、不做什么、如何判断成功、产品能力往哪里建设、后续可能影响哪些设计资产”，不替代 PRD、业务架构、功能架构、OpenAPI 或系统 / 数据架构。
+> 适用场景：机会探索、竞品分析或用户材料已经有初步输入，需要收敛为 Spec 上游事实。
+> 本文回答“为谁、为什么、第一版做什么、不做什么、如何判断成功、产品能力往哪里建设、后续可能影响哪些设计资产”，不替代 Spec、业务架构、功能架构、OpenAPI 或系统 / 数据架构。
 
 ## 1. 输入材料
 
@@ -46,7 +46,7 @@ owner: ai
 
 ## 6. 产品功能指引 / 能力候选
 
-> 本节用于给 PRD 和功能架构输入方向，不冻结最终功能架构或技术系统方案。
+> 本节用于给 Spec 和功能架构输入方向，不冻结最终功能架构或技术系统方案。
 
 | 能力候选 | 用户价值 | 优先级假设 | 是否进入 MVP | 证据 / 依据 | 下游影响 |
 |----------|----------|------------|---------------|-------------|----------|
@@ -54,7 +54,7 @@ owner: ai
 
 ## 7. 下游影响清单
 
-> 只记录影响信号和待验证假设；具体方案在 PRD、产品设计、API、系统 / 数据架构和设计审查阶段收敛。
+> 只记录影响信号和待验证假设；具体方案在 Spec、产品设计、API、系统 / 数据架构和设计审查阶段收敛。
 
 | 影响域 | 是否可能影响 | 说明 | 需要进入的后续门禁 |
 |--------|--------------|------|--------------------|
@@ -64,7 +64,7 @@ owner: ai
 | 权限 / 审计 | 是 / 否 / 待定 |  | 系统架构 / 安全审查 |
 | 外部系统 / 集成 | 是 / 否 / 待定 |  | 系统架构 / ADR |
 | 发布 / 回滚 / 运维 | 是 / 否 / 待定 |  | 系统架构 / Release Review |
-| 安全红线 | 是 / 否 / 待定 |  | `TODO-HUMAN-REVIEW` |
+| 高风险变更 / 人工确认项 | 是 / 否 / 待定 |  | 人工确认项 |
 
 ## 8. 成功标准
 
@@ -76,12 +76,12 @@ owner: ai
 
 | 风险 / 问题 | 影响 | 处理方式 | 截止点 |
 |-------------|------|----------|--------|
-|  |  |  | PRD 前 |
+|  |  |  | Spec 前 |
 
 ## 10. 完成标准
 
 - [ ] 目标用户、痛点、为什么现在做已经明确。
-- [ ] MVP 和非目标范围可直接输入 PRD。
+- [ ] MVP 和非目标范围可直接输入 Spec。
 - [ ] 产品功能指引已经形成能力候选和优先级假设，但未替代正式功能架构。
 - [ ] 下游 UI、API、数据、权限、架构、安全影响信号已列出。
 - [ ] 成功标准可验收。
@@ -91,5 +91,5 @@ owner: ai
 ## 11. 下一步门禁
 
 - 结论：Approved / Blocked
-- 下一步：业务架构 / PRD / 继续 Discovery
+- 下一步：业务架构 / Spec / 继续 Discovery
 - 阻断项：

package/template/docs/implementation/create-yss-spec-repository-mode-contract.md

@@ -0,0 +1,59 @@
+# `create-yss-spec` 仓库身份与迁移契约
+
+本文定义模板仓库与外部 `create-yss-spec` CLI 仓库之间的跨仓库发布契约。模板治理父 Ticket 为 [#24](https://github.com/iloveZzz/yss-spec-project-template/issues/24)，CLI 交接子 Ticket 为 [#26](https://github.com/iloveZzz/yss-spec-project-template/issues/26)。
+
+## 契约目标
+
+- 模板源仓库保留 `repository_mode: template-source`。
+- CLI 创建的产品仓库必须写入 `repository_mode: project-instance`，不得原样保留模板源身份。
+- 清单只包含 `schema_version` 与 `repository_mode`；项目名称、团队规模、Tracker 和实现仓库信息不得写入清单。
+- CLI 初始化与升级后的落地文档正文以简体中文为标准语言。
+
+## 初始化转换
+
+CLI 从模板内容生成目标仓库时，必须在写入目标目录后、执行模板验证前完成以下转换：
+
+1. 将根目录 `yss-project.yaml` 的 `repository_mode` 从 `template-source` 改为 `project-instance`。
+2. 保持 `schema_version: 1`，拒绝未知 schema 版本或未知模式。
+3. 保持 `.agents/skills` 为共享技能权威内容，并保留其他 Agent root 的生成投影与平台专属技能。
+4. 执行目标仓库的 `scripts/sync-skills --check`、`scripts/update-skill-lock --check` 和 `scripts/verify-template`。
+
+## 旧版升级转换
+
+升级已有仓库时必须执行 `docs/user-guide/spec-ticket-migration-guide.md` 中的路径迁移，删除过时 skill 目录且不创建兼容别名。若目标路径已存在或旧、新资产内容冲突，CLI 必须停止并输出冲突清单，不得静默覆盖用户内容。
+
+## 外部仓库验收测试
+
+CLI 仓库至少补充以下集成场景：
+
+1. 从当前模板初始化空目录，断言输出清单为 `project-instance` 且只含两个字段。
+2. 断言初始化输出不存在过时 skill、旧模板路径和单数 Agent skill root。
+3. 断言共享 skill 投影及 `skills-lock.json` 完整目录树哈希校验通过。
+4. 用旧版 fixture 执行升级，断言 Spec / Ticket 新路径生效；存在内容冲突时 fail closed。
+5. 在初始化后的仓库运行 `scripts/verify-template`，断言五类压力场景、Markdown 链接和 YAML 解析全部通过。
+
+## 发布顺序
+
+1. 模板仓库完成 fresh verification 与独立审查，形成待发布 commit / tag，但暂不声明整体可发布。
+2. CLI 仓库按本契约实现身份转换与升级测试，并绑定模板的确定 commit / tag。
+3. 两个仓库共同执行初始化和升级集成测试。
+4. 先发布模板兼容版本或确定模板引用，再发布 CLI major 版本；最后同步父 Ticket、迁移说明和发布记录。
+
+任一仓库未通过共同集成验证时，只能声明“本仓库实现完成，跨仓库发布受阻”，不得声明整体可发布。
+
+## 当前责任边界
+
+- 本仓库负责：清单 schema、流程事实源、迁移指南、skills 投影与锁定、模板验证脚本。
+- `create-yss-spec` 仓库负责：初始化转换、升级转换、冲突处理、CLI 集成测试、CLI major 发布。
+- 模板实现 PR：[#30](https://github.com/iloveZzz/yss-spec-project-template/pull/30)，修正 Ticket 目录、空 skill 锁登记和无 Git 初始化时的模板校验。
+- CLI 实现 PR：[`create-yss-spec` #10](https://github.com/iloveZzz/create-yss-spec/pull/10)，实现身份转换、旧版迁移、fail closed、skill 投影复制和 `2.0.0` 版本准备。
+- 共同验证：`YSS_SPEC_TEMPLATE_REF=codex/ticket-directory-contract npm test`，20/20 通过；生成实例执行 `scripts/verify-template` 通过；`npm pack --dry-run` 通过。
+- 下一责任人：模板与 CLI 独立 reviewer；合并后由发布负责人绑定确定 commit / tag 重跑验证并确认 npm `2.0.0` 发布。
+- 建议 skills：`cross-repo-implementation-routing`、`tdd`、`code-review`。
+
+## 当前阻断条件
+
+- 模板 PR #30 尚未独立 review 与合并。
+- CLI PR #10 尚未独立 review 与合并。
+- 当前共同测试绑定开发分支；合并后必须改绑确定 commit / tag 再执行 fresh verification。
+- npm `2.0.0` 尚未获得发布确认，本轮不执行 npm 发布。

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

@@ -3,7 +3,7 @@
 > 来源：<https://github.com/mattpocock/skills/tree/main/skills/engineering>
 > 项目内置快照：`272f99b22574f50e4266791c86b9302682970e23`
 
-本文说明本模板如何使用 Matt Pocock `skills/engineering` 作为默认轻量研发流程。它不是代码库依赖，而是 Agent 可读取和执行的操作规程，用来把模糊需求逐步转化为 PRD、OpenAPI 契约、垂直切片 Issue、TDD 实现、审查和验证证据。
+本文说明本模板如何使用 Matt Pocock `skills/engineering` 作为默认轻量研发流程。它不是代码库依赖，而是 Agent 可读取和执行的操作规程，用来把模糊需求逐步转化为 Spec、OpenAPI 契约、垂直切片 Ticket、TDD 实现、审查和验证证据。
 
 ## 1. 总体定位
 
@@ -11,11 +11,11 @@ Matt Pocock Engineering Skills 是一组小而可组合的工程工作流。本
 
 | 本模板层级 | 默认能力 | 说明 |
 |---|---|---|
-| 需求与任务 | `competitive-intelligence`、`research`、`grill-with-docs`、`prototype`、`to-prd`、`to-issues` | 收集竞品 / 市场 / 技术事实、澄清需求、用一次性原型回答设计问题、沉淀 PRD、拆端到端垂直切片 |
+| 需求与任务 | `competitive-intelligence`、`research`、`grill-with-docs`、`prototype`、`to-spec`、`to-tickets`、`wayfinder` | 收集竞品 / 市场 / 技术事实、澄清需求、用一次性原型回答设计问题、沉淀 Spec、拆端到端垂直切片 Ticket；大范围不清晰时用 Wayfinder 建图 |
 | 契约层 | OpenAPI 3.1 Draft / Freeze、OpenSpec-style Spec Delta | 前后端契约、行为差异、验收场景和契约测试输入 |
 | 方法论层 | `implement`、`tdd`、`diagnosing-bugs`、`code-review` | 实现、红绿重构、Bug 诊断和独立审查 |
 | 架构与领域 | `domain-modeling`、`codebase-design`、`improve-codebase-architecture` | 领域语言、深模块设计、架构治理 |
-| 协作层 | `triage`、`handoff` / 等价交接记录、Issue tracker、Git checkpoint | 分诊、跨线程 / 跨仓库交接、同步状态、记录验证证据 |
+| 协作层 | `triage`、`handoff` / 等价交接记录、Ticket tracker、Git checkpoint | 分诊、跨线程 / 跨仓库交接、同步状态、记录验证证据 |
 
 ## 2. 标准执行流程
 
@@ -23,12 +23,12 @@ Matt Pocock Engineering Skills 是一组小而可组合的工程工作流。本
 
 | 项 | 内容 |
 |---|---|
-| 触发语 | “做一个功能”、“把这个想法落成需求”、“生成 PRD/Issue”、“可以开始实现” |
-| 使用 skills | `competitive-intelligence`（需要竞品 / 市场事实时）、`research`（需要技术 / 标准 / API 一手资料时）、`grill-with-docs`、`prototype`（需要一次性验证时）、`domain-modeling`、`to-prd`、`to-issues`、`implement`、`tdd`、`code-review` |
+| 触发语 | “做一个功能”、“把这个想法落成需求”、“生成 Spec/Ticket”、“可以开始实现” |
+| 使用 skills | `competitive-intelligence`（需要竞品 / 市场事实时）、`research`（需要技术 / 标准 / API 一手资料时）、`grill-with-docs`、`prototype`（需要一次性验证时）、`domain-modeling`、`to-spec`、`to-tickets`、`wayfinder`、`implement`、`tdd`、`code-review` |
 | 输入 | 业务想法、发现报告、用户故事草案、干系人讨论记录 |
-| 输出 | PRD、OpenAPI 3.1 Spec、垂直切片 Issue、实现与测试 |
+| 输出 | 产品 Spec、OpenAPI 3.1 契约、垂直切片 Ticket、实现与测试 |
 | 落点 | `docs/requirements/`、`docs/api/specs/`、GitLab / GitHub Issues、`CONTEXT.md`、`docs/adr/` |
-| 人工确认点 | PRD 范围、OpenAPI 契约、Issue 粒度、安全红线、最终 Review |
+| 人工确认点 | Spec 范围、OpenAPI 契约、Ticket 粒度、风险 / 回滚约束、最终 Review |
 
 执行顺序：
 
@@ -38,13 +38,13 @@ competitive-intelligence (when market / competitor facts are needed)
   -> grill-with-docs
   -> prototype (when a design question needs runnable feedback)
   -> domain-modeling
-  -> to-prd
+  -> to-spec
   -> OpenAPI 3.1 Draft
   -> OpenSpec-style Spec Delta (medium/high-risk behavior changes)
   -> Engineering Baseline / YSS DDD review
   -> Architecture / Data Design Review
   -> OpenAPI 3.1 Freeze
-  -> to-issues
+  -> to-tickets
   -> handoff / implementation routing (when crossing contexts or repos)
   -> implement with tdd
   -> code-review / fresh verification
@@ -52,15 +52,15 @@ competitive-intelligence (when market / competitor facts are needed)
 
 门禁：
 
-- PRD 进入开发前必须明确用户故事、验收条件、OpenAPI 影响和测试决策。
-- 技术 / 标准 / 第三方 API 事实影响 PRD、OpenAPI、架构或验收时，必须有 `research` 或等价一手资料记录，并在下游资产中引用。
-- 一次性 `prototype` 只回答设计问题；结论必须回填到 PRD、设计、ADR 或 Issue，原型代码不得作为生产实现或 YSS 高保真 HTML 原型交付。
+- Spec 进入开发前必须明确用户故事、验收条件、OpenAPI 影响和测试决策。
+- 技术 / 标准 / 第三方 API 事实影响 Spec、OpenAPI、架构或验收时，必须有 `research` 或等价一手资料记录，并在下游资产中引用。
+- 一次性 `prototype` 只回答设计问题；结论必须回填到 Spec、设计、ADR 或 Ticket，原型代码不得作为生产实现或 YSS 高保真 HTML 原型交付。
 - 任何 API 变更必须先在 `docs/api/specs/*.yaml` 形成 Draft，经工程基线、系统 / 数据架构和设计审查后 Freeze，再进入实现。
 - API、权限、状态机、数据模型、跨端、新模块或高风险行为变化，应在 Design Review / OpenAPI Freeze 前补 OpenSpec-style Spec Delta；它只描述行为差异、验收场景和测试映射，不恢复 OpenSpec 工具链。
-- OpenAPI Freeze 后进入 `to-issues` 或等价垂直切片拆分；Issue 必须可以独立 demo 或验证。
+- OpenAPI Freeze 后进入 `to-tickets` 或等价垂直切片拆分；Ticket 必须可以独立 demo 或验证。
 - 后端新服务或新模块必须先确认 YSS DDD 工程基线；从零创建服务时优先使用 `yss-ddd-scaffold-generator`。
-- `to-issues` 只能产出可独立验证的垂直切片，不允许只按 Adapter / Application / Domain / Infrastructure 横向拆分。
-- 涉及安全红线时，Issue 必须标注 `ready-for-human` 或 `TODO-HUMAN-REVIEW`。
+- `to-tickets` 只能产出可独立验证的垂直切片，不允许只按 Adapter / Application / Domain / Infrastructure 横向拆分。
+- 存在需要人工确认的风险时，Ticket 必须记录范围、责任人和结论或待补齐事项。
 - 跨线程、跨仓库、上下文接近上限或原型分支回流时，必须留下 `handoff` 或等价交接记录。
 
 ### 2.2 Bug 修复流程
@@ -71,8 +71,8 @@ competitive-intelligence (when market / competitor facts are needed)
 | 使用 skills | `diagnosing-bugs`、`tdd`、必要时 `domain-modeling` |
 | 输入 | 报错信息、复现步骤、日志、失败测试、性能指标 |
 | 输出 | 可复现反馈命令、最小复现、假设列表、回归测试、修复说明 |
-| 落点 | 测试文件、Issue/PR 评论、审查报告、必要时 ADR |
-| 人工确认点 | 无法复现、缺少环境、触碰安全红线、需要生产插桩 |
+| 落点 | 测试文件、Ticket/PR 评论、审查报告、必要时 ADR |
+| 人工确认点 | 无法复现、缺少环境、存在高风险变更、需要生产插桩 |
 
 门禁：
 
@@ -88,7 +88,7 @@ competitive-intelligence (when market / competitor facts are needed)
 | 使用 skills | `improve-codebase-architecture`、`codebase-design`、`domain-modeling`、必要时 `grill-with-docs` |
 | 输入 | 代码结构、测试痛点、维护痛点、ADR、领域词汇表 |
 | 输出 | 架构深度报告、deepening candidate、接口/seam 设计、ADR |
-| 落点 | `docs/architecture/`、`docs/adr/`、`CONTEXT.md`、后续 Issue |
+| 落点 | `docs/architecture/`、`docs/adr/`、`CONTEXT.md`、后续 Ticket |
 | 人工确认点 | 是否采纳候选重构、是否重开已有 ADR、是否投入 Sprint |
 
 门禁：
@@ -97,13 +97,13 @@ competitive-intelligence (when market / competitor facts are needed)
 - 只有难以回滚、非显而易见、存在真实取舍的决策才写 ADR。
 - 与既有 ADR 冲突时必须显式指出，并说明为什么值得重新讨论。
 
-### 2.4 Issue 分诊流程
+### 2.4 Ticket 分诊流程
 
 | 项 | 内容 |
 |---|---|
 | 触发语 | “看下 issue”、“分诊这些需求”、“哪些可以给 Agent 做”、“把 #42 准备好” |
 | 使用 skills | `triage`、必要时 `grill-with-docs`、`domain-modeling`、`diagnosing-bugs` |
-| 输入 | GitLab / GitHub Issue、评论、标签、复现步骤、需求背景 |
+| 输入 | GitLab / GitHub Ticket、评论、标签、复现步骤、需求背景 |
 | 输出 | 分类标签、状态标签、triage notes、agent brief、关闭说明 |
 | 落点 | GitLab / GitHub Issues、`.out-of-scope/`、`CONTEXT.md`、`docs/adr/` |
 | 人工确认点 | 状态跳转异常、信息不足、拒绝请求、必须人工实现 |
@@ -122,7 +122,7 @@ competitive-intelligence (when market / competitor facts are needed)
 
 | Skill | 用途 | 产物 |
 |---|---|---|
-| `setup-matt-pocock-skills` | 为仓库配置 issue tracker、triage label、领域文档布局 | `docs/agents/issue-tracker.md`、`docs/agents/triage-labels.md`、`docs/agents/domain.md`，并在 `AGENTS.md` 增加 Agent skills 区块 |
+| `setup-matt-pocock-skills` | 为仓库配置 Ticket tracker、triage label、领域文档布局 | `docs/agents/issue-tracker.md`、`docs/agents/triage-labels.md`、`docs/agents/domain.md`，并在 `AGENTS.md` 增加 Agent skills 区块 |
 
 本仓库已完成项目内置安装。后续升级应按固定快照同步，并在 Git diff 中检查技能目录变化。
 
@@ -131,13 +131,13 @@ competitive-intelligence (when market / competitor facts are needed)
 | Skill | 触发场景 | 核心动作 | 推荐落点 |
 |---|---|---|---|
 | `ask-matt` | 不确定该走哪个流程 | 路由到合适 skill | 作为入口说明 |
-| `competitive-intelligence` | 需要竞品、替代方案、定价、定位、用户口碑或市场事实 | 基于公开来源形成竞品情报、证据表、竞品矩阵和 PRD 输入 | `docs/discovery/reports/` |
+| `competitive-intelligence` | 需要竞品、替代方案、定价、定位、用户口碑或市场事实 | 基于公开来源形成竞品情报、证据表、竞品矩阵和 Spec 输入 | `docs/discovery/reports/` |
 | `research` | 需要技术事实、标准、第三方 API、框架行为或官方文档依据 | 基于一手来源形成可引用调研记录 | `docs/discovery/reports/` 或 `docs/research/` |
 | `grill-with-docs` | 想法还不清晰，需要追问 | 结合领域建模持续追问，沉淀 glossary / ADR | `CONTEXT.md`、`docs/adr/` |
-| `prototype` | 状态机、复杂规则或 UI 方向需要可运行反馈 | 生成一次性逻辑 / UI 原型并沉淀结论 | PRD、设计、ADR 或 Issue 的结论章节 |
-| `to-prd` | 已有对话，需要整理成 PRD | 不再访谈，直接合成 PRD 并发布到 issue tracker | `docs/requirements/` 或 Issue |
-| `to-issues` | PRD / 计划需要拆任务 | 拆成可独立领取的垂直切片 Issue | Issue tracker |
-| `implement` | 按 PRD 或 Issue 实现 | 业务行为默认按 TDD 推进；生成代码、配置或一次性原型说明例外和验证方式；最后 independent review + fresh verification + commit | 当前代码分支 |
+| `prototype` | 状态机、复杂规则或 UI 方向需要可运行反馈 | 生成一次性逻辑 / UI 原型并沉淀结论 | Spec、设计、ADR 或 Ticket 的结论章节 |
+| `to-spec` | 已有对话，需要整理成 Spec | 不再访谈，直接合成 Spec 并发布到 Ticket tracker | `docs/requirements/` 或 Ticket |
+| `to-tickets` | Spec / 计划需要拆任务 | 拆成可独立领取的垂直切片 Ticket | Ticket tracker |
+| `implement` | 按 Spec 或 Ticket 实现 | 业务行为默认按 TDD 推进；生成代码、配置或一次性原型说明例外和验证方式；最后 independent review + fresh verification + commit | 当前代码分支 |
 
 ### 3.3 编码与验证
 
@@ -168,32 +168,32 @@ competitive-intelligence (when market / competitor facts are needed)
 
 | Engineering Skills 产物 | 本模板建议位置 |
 |---|---|
-| PRD | `docs/requirements/`，必要时同步到 Issue |
+| Spec | `docs/requirements/`，必要时同步到 Ticket |
 | OpenAPI 契约 | `docs/api/specs/` |
 | ADR | `docs/adr/` |
 | 架构方案 | `docs/architecture/` |
 | 测试策略 | `docs/testing/` |
 | Sprint / Standup / Retro | `docs/process/` |
-| Issue tracker 配置 | `docs/agents/` |
+| Ticket tracker 配置 | `docs/agents/` |
 | 领域词汇表 | 根目录 `CONTEXT.md` |
 | 技术 / 标准 / API 调研 | `docs/discovery/reports/` 或 `docs/research/` |
-| 一次性原型结论 | PRD、设计、ADR 或垂直切片 Issue |
-| 跨线程 / 跨仓库交接 | Issue / MR / PR 评论或 `docs/implementation/` |
+| 一次性原型结论 | Spec、设计、ADR 或垂直切片 Ticket |
+| 跨线程 / 跨仓库交接 | Ticket / MR / PR 评论或 `docs/implementation/` |
 
 ## 5. 门禁与验收规则
 
-### 5.1 PRD Ready
+### 5.1 Spec Ready
 
 - [ ] 问题陈述与解决方案明确。
 - [ ] 用户故事覆盖主要用户路径。
 - [ ] 验收标准可验证。
 - [ ] OpenAPI 影响明确为“无”或列出 Draft spec 文件；进入开发前必须 Freeze。
 - [ ] 测试决策明确测试 seam。
-- [ ] AI / 人工审查点标注安全红线和人工确认点。
+- [ ] AI / 人工审查点标注风险 / 回滚约束和人工确认点。
 
-### 5.2 Issue Ready
+### 5.2 Ticket Ready
 
-- [ ] Issue 是一个端到端垂直切片。
+- [ ] Ticket 是一个端到端垂直切片。
 - [ ] 完成后可独立 demo 或验证。
 - [ ] Blocked by 清楚。
 - [ ] 测试命令和 fresh verification 方式清楚。
@@ -204,7 +204,7 @@ competitive-intelligence (when market / competitor facts are needed)
 - [ ] `yss-router` 已选择最小 YSS skill 集合。
 - [ ] Build Architecture Checklist 已绑定当前切片。
 - [ ] TDD 适用性已明确；若例外，说明验证方式。
-- [ ] 安全红线和人审点已标注。
+- [ ] 风险与人审点已标注。
 - [ ] 实现仓库、分支、测试命令和回滚点清楚。
 - [ ] 跨线程 / 跨仓库 / 原型回流场景已有 `handoff` 或等价交接记录。
 - [ ] 如发生 merge / rebase 冲突，已有冲突处理取舍和重新验证证据。

package/template/docs/process/harness-automation-candidates.md

@@ -6,41 +6,38 @@
 
 - 可自动检查：输入、规则和失败条件明确，机器可以稳定判断。
 - 可半自动生成 checklist：机器能收集证据和生成问题，但放行需要人或 Agent 判断。
-- 必须人工审查：涉及安全红线、业务取舍、不可逆变更或责任确认。
+- 需要人工审查：涉及业务取舍、不可逆变更或责任确认。
 
 ## 可自动检查
 
 | 编号 | 门禁 | 触发阶段 | 输入 | 输出 | 失败处理 | 人工接管点 |
 |---|---|---|---|---|---|---|
-| HAC-001 | active Issue change 完整性 | 6. 契约冻结与 Issue | `docs/requirements/issues/**`、`垂直切片 Issue 状态` | 缺失文件清单 | 阻止进入正式垂直切片 | change 命名或匹配关系不明确 |
+| HAC-001 | 功能父 Ticket 完整性 | 6. 契约冻结与 Ticket | `docs/requirements/tickets/**`、`垂直切片 Ticket 状态` | 缺失文件清单 | 阻止进入正式垂直切片 | change 命名或匹配关系不明确 |
 | HAC-002 | API 影响记录 / OpenAPI Draft / Freeze 文件存在性 | 5 / 6. API 相关阶段 | API 影响记录、`docs/api/specs/*.yaml`、Freeze 记录 | API 资产状态 | 要求补齐影响记录、契约草案、Draft / Freeze 或无 API 影响记录 | API 影响范围有争议 |
 | HAC-003 | Build Architecture Checklist 字段完整性 | 7. 垂直切片与 TDD 实现 | checklist 文档 | 缺失字段和未回勾项 | 阻止 build-ready 结论 | 架构约束是否适用需判断 |
-| HAC-004 | fresh verification 记录存在性 | 8. 验证发布与复盘 | verification 文档、Issue 评论、测试输出 | 验证证据摘要 | 阻止“完成 / 可合并 / 可发布”结论 | 验证范围是否足够需判断 |
-| HAC-005 | 阶段 checkpoint 字段完整性 | 每个主阶段结束 | checkpoint 记录 | 缺失字段清单 | 要求补齐后再推进 | Issue tracker 不可用或权限不足 |
+| HAC-004 | fresh verification 记录存在性 | 8. 验证发布与复盘 | verification 文档、Ticket 评论、测试输出 | 验证证据摘要 | 阻止“完成 / 可合并 / 可发布”结论 | 验证范围是否足够需判断 |
+| HAC-005 | 阶段 checkpoint 字段完整性 | 每个主阶段结束 | checkpoint 记录 | 缺失字段清单 | 要求补齐后再推进 | Ticket tracker 不可用或权限不足 |
 
 ## 可半自动生成 checklist
 
 | 编号 | 门禁 | 触发阶段 | 输入 | 输出 | 失败处理 | 人工接管点 |
 |---|---|---|---|---|---|---|
-| HAC-101 | PRD Review 缺口 | 3. 业务 / PRD / 功能架构 | PRD、Discovery、CONTEXT | 用户、痛点、MVP、非目标、验收缺口 | 返回 PRD 补齐 | 业务优先级和非目标取舍 |
+| HAC-101 | Spec Review 缺口 | 3. 业务 / Spec / 功能架构 | Spec、Discovery、CONTEXT | 用户、痛点、MVP、非目标、验收缺口 | 返回 Spec 补齐 | 业务优先级和非目标取舍 |
 | HAC-102 | Prototype Review 缺口 | 4. 产品设计与需求冻结 | 页面清单、状态矩阵、原型说明 | UI / 状态 / 权限 / API 反推缺口 | 返回产品设计 | 交互体验和视觉取舍 |
 | HAC-103 | Architecture Review 缺口 | 5. 系统 / 数据架构与工程契约设计审查 | 系统架构、数据架构、ADR、OpenAPI | 架构约束和风险清单 | 返回设计审查 | 服务边界、NFR、数据约束取舍 |
-| HAC-104 | 垂直切片拆分质量 | 7. 垂直切片与 TDD 实现 | Issue、tasks、实施计划 | 横向拆层风险、切片过大风险 | 返回计划修正 | MVP 范围和拆分优先级 |
+| HAC-104 | 垂直切片拆分质量 | 7. 垂直切片与 TDD 实现 | Ticket、tasks、实施计划 | 横向拆层风险、切片过大风险 | 返回计划修正 | MVP 范围和拆分优先级 |
 | HAC-105 | Skill 沉淀候选 | 8. 验证发布与复盘 | 复盘、重复动作、模板变更 | 模板 / 脚本 / Skill 候选 | 进入治理 backlog | 是否值得产品化 |
 
 ## 必须人工审查
 
 | 编号 | 门禁 | 触发阶段 | 输入 | 输出 | 失败处理 | 人工接管点 |
 |---|---|---|---|---|---|---|
-| HAC-201 | 支付相关逻辑 | 任意阶段 | PRD、设计、代码草案 | `TODO-HUMAN-REVIEW` | Agent 只生成草案 | 产品 / 安全 / 研发负责人确认 |
-| HAC-202 | 数据库迁移 / DDL | 6 / 8. 架构与实现 | 数据架构、迁移模板 | 人审结论 | 不得自动执行迁移 | DBA / 架构负责人确认 |
-| HAC-203 | 认证 / 授权中间件 | 6 / 8. 架构与实现 | 权限模型、代码草案 | 人审结论 | fail-closed | 安全负责人确认 |
-| HAC-204 | 加密算法实现 | 任意阶段 | 需求或代码请求 | 禁止生成结论 | 停止实现 | 安全负责人确认替代方案 |
-| HAC-205 | SQL 原生查询 | 6 / 8. 架构与实现 | 查询草案、数据架构 | 人审结论 | Agent 只生成草案 | DBA / 安全负责人确认 |
-| HAC-206 | 公共基础库 API 变更 | 6 / 8. 架构与实现 | API 设计、影响面 | 人审结论 | Agent 只生成草案 | 架构负责人确认 |
+| HAC-202 | 数据库迁移 / DDL | 6 / 8. 架构与实现 | 数据架构、迁移模板 | 人工确认结论 | 迁移执行按发布流程确认 | DBA / 架构负责人确认 |
+| HAC-204 | 加密算法实现 | 任意阶段 | 需求或代码请求 | 替代方案、验证证据和责任人 | 暂停并记录替代方案 | 安全负责人确认替代方案 |
+| HAC-206 | 公共基础库 API 变更 | 6 / 8. 架构与实现 | API 设计、影响面 | 人工确认结论 | 记录验证和责任人 | 架构负责人确认 |
 
 ## 自动化 backlog 排序建议
 
 1. 先做存在性和字段完整性检查：HAC-001、HAC-003、HAC-004、HAC-005。
 2. 再做 checklist 生成：HAC-101 到 HAC-105。
-3. 安全红线只做识别和提醒，不做自动放行。
+3. 自动化只做识别和提醒，不替代必要的责任确认。

package/template/docs/process/harness-executive-blueprint.md

@@ -13,12 +13,12 @@ AI 不能只作为一次性辅助工具使用。Harness 工程的目标，是把
 ```text
 机会 / 问题收集
 → 需求澄清
-→ PRD -> 产品总体设计 -> 原型校准
+→ Spec -> 产品总体设计 -> 原型校准
 → SDD 研发规范基线
 → DDD 领域建模
 → 架构设计
-→ 垂直切片 Issue
-→ 垂直 Issue 详细设计
+→ 垂直切片 Ticket
+→ 垂直切片详细设计
 → TDD 并行开发
 → 测试验证
 → Code Review
@@ -31,26 +31,26 @@ AI 不能只作为一次性辅助工具使用。Harness 工程的目标，是把
 ## 哪些门禁不能跳
 
 - API 变化必须先有 API 影响记录和契约草案 / review-only OpenAPI Draft，并在实现或生成客户端前完成 Freeze 或记录无 API 影响。
-- 进入 PRD 初稿 / 需求基线流程后，必须先有产品总体设计 / 功能架构，才能进入页面 / 原型 / 交互设计、OpenAPI Draft、PRD 校准、需求冻结或实现；不进入 PRD 生命周期的小改动才可记录不适用原因。
-- 正式垂直切片前必须有 active Issue change 和完整 change 资产。
-- 架构、数据、ADR、工程基线和安全红线必须进入 Build Architecture Checklist。
-- 支付、迁移、认证授权、加密、SQL、公共基础库 API 等安全红线必须人工审查。
+- 进入 Spec 初稿 / 需求基线流程后，必须先有产品总体设计 / 功能架构，才能进入页面 / 原型 / 交互设计、OpenAPI Draft、Spec 校准、需求冻结或实现；不进入 Spec 生命周期的小改动才可记录不适用原因。
+- 正式垂直切片前必须有 功能父 Ticket 和完整 change 资产。
+- 架构、数据、ADR、工程基线和风险、回滚约束和验证证据必须进入 Build Architecture Checklist。
+- 支付、迁移、认证授权、加密、SQL、公共基础库 API 等高风险事项必须记录验证证据、责任人和回滚约束。
 - 完成、可合并或可发布结论必须有 fresh verification。
-- 每个阶段结束必须记录 Issue 同步状态和 Git checkpoint 判断。
+- 每个阶段结束必须记录 Ticket 同步状态和 Git checkpoint 判断。
 
 ## 试点怎么跑
 
 先选择一个真实、低风险、边界清晰的业务模块，按半自动闭环推进：
 
 ```text
-PRD
+Spec
 → 产品总体设计 / 功能架构
 → 页面 / 原型 / 交互设计与 prototype-review（有 UI 时）
 → product-design:index 路由 Product Design focused skill 产出 Ant Design v6 高保真 HTML 原型（有 UI 时）
 → antd CLI 校验证据与用户确认记录（有 UI 时）
 → API 影响分析 / 契约草案
 → review-only OpenAPI Draft（如需要）
-→ Issue Change
+→ 功能父 Ticket 更新 / 契约冻结
 → 垂直切片
 → TDD
 → Review
@@ -62,7 +62,7 @@ PRD
 
 ## 成功指标
 
-- PRD Ready 一次通过率提升。
+- Spec Ready 一次通过率提升。
 - 阶段产物一次通过率提升。
 - 规范偏离次数下降。
 - ready-for-agent 到可验证 PR 的周期缩短。

package/template/docs/process/harness-optimization-backlog.md

@@ -1,6 +1,6 @@
 # Harness 工程优化调整待办
 
-本文档记录基于《产品全生命周期 AI 研发工程化体系》PPT 与当前项目流程对比后，需要优化调整的待办事项。目标不是削弱现有治理能力，而是在保留 Issue、YSS、门禁、追踪和验证优势的前提下，补齐轻量表达、流程裁剪、试点推进和自动化落地能力。
+本文档记录基于《产品全生命周期 AI 研发工程化体系》PPT 与当前项目流程对比后，需要优化调整的待办事项。目标不是削弱现有治理能力，而是在保留 Ticket、YSS、门禁、追踪和验证优势的前提下，补齐轻量表达、流程裁剪、试点推进和自动化落地能力。
 
 ## 优化目标
 
@@ -17,7 +17,7 @@
 | HOB-001 | 已落地 | 建立“13 个工作单元 → 9 阶段 / 21 门禁”映射表 | 当前项目执行规则完整但对外表达重；PPT 蓝图易懂但缺少执行约束。 | `docs/process/harness-work-unit-map.md` | 每个 PPT 工作单元都能映射到项目阶段、门禁、产物、Skill、是否可裁剪和是否可自动化。 |
 | HOB-002 | 已落地 | 定义三档流程裁剪策略 | 小改动、中等变更和新模块现在都容易被理解成同一套重流程。 | `docs/process/harness-process-tailoring.md`；`docs/process/lifecycle-artifact-map.md` 引用 | 明确“小改动 / 中等变更 / 新模块或高风险变更”的入口判断、最小产物、验证要求和升级条件。 |
 | HOB-003 | 已落地 | 制定 Harness 试点模块选择标准 | 没有试点边界时，流程优化容易停留在抽象讨论。 | `docs/process/harness-pilot-selection.md` | 标准包含低风险、边界清晰、真实业务价值、可验证 API / UI / 数据影响、适合垂直切片等条件。 |
-| HOB-004 | 已落地 | 明确阶段结束 Git checkpoint 与 Issue 同步最小模板 | 当前要求存在，但执行时容易靠 Agent 临场组织语言。 | `docs/process/templates/stage-checkpoint-template.md` | 每个阶段都能按固定字段记录产物、验证、阻塞、安全人审、排除的脏文件和下一步。 |
+| HOB-004 | 已落地 | 明确阶段结束 Git checkpoint 与 Ticket 同步最小模板 | 当前要求存在，但执行时容易靠 Agent 临场组织语言。 | `docs/process/templates/stage-checkpoint-template.md` | 每个阶段都能按固定字段记录产物、验证、阻塞、人工审查、排除的脏文件和下一步。 |
 
 ## P1：试点前补齐
 
@@ -25,18 +25,18 @@
 |---|---|---|---|---|---|
 | HOB-005 | 已落地 | 梳理可自动化门禁清单 | 现在门禁多，但哪些能机器检查、哪些必须人工判断还不够清楚。 | `docs/process/harness-automation-candidates.md` | 门禁按“可自动检查 / 可半自动生成 checklist / 必须人工审查”分类，并标注触发阶段。 |
 | HOB-006 | 已落地 | 设计 Build Architecture Checklist 生成与回勾模板 | 架构约束进入实现阶段的成本偏高，容易变成手写负担。 | `docs/templates/build-architecture-checklist-template.md` | 模板包含 source、constraint、slice、status、evidence、follow-up，并给出示例。 |
-| HOB-007 | 已落地 | 建立 Skill 沉淀规则 | 当前 skill 很多，但缺少“何时新增 / 合并 / 脚本化”的判断标准。 | `docs/process/skill-governance.md` | 明确重复 3 次以上动作的处理路径：模板、脚本、Skill、Issue 节点或无需沉淀。 |
+| HOB-007 | 已落地 | 建立 Skill 沉淀规则 | 当前 skill 很多，但缺少“何时新增 / 合并 / 脚本化”的判断标准。 | `docs/process/skill-governance.md` | 明确重复 3 次以上动作的处理路径：模板、脚本、Skill、Ticket 节点或无需沉淀。 |
 | HOB-008 | 已落地 | 形成对外汇报版 Harness 蓝图 | 当前 `AGENTS.md` 适合 Agent 执行，不适合业务方和管理者快速理解。 | `docs/process/harness-executive-blueprint.md` | 能用 5 分钟讲清楚：为什么做、怎么分阶段、哪些门禁不能跳、试点怎么跑。 |
-| HOB-009 | 已落地 | 定义“最近可信阶段”判定表 | 项目已有原则，但缺少可查表，执行时容易争议。 | `docs/process/harness-process-tailoring.md` | 输入不同变更类型后，能定位从 PRD、设计、OpenAPI、架构、Issue 或实现哪个阶段开始补齐。 |
+| HOB-009 | 已落地 | 定义“最近可信阶段”判定表 | 项目已有原则，但缺少可查表，执行时容易争议。 | `docs/process/harness-process-tailoring.md` | 输入不同变更类型后，能定位从 Spec、设计、OpenAPI、架构、Ticket 或实现哪个阶段开始补齐。 |
 
 ## P2：试点后演进
 
 | 编号 | 状态 | 待办 | 问题空间 | 交付物 | 验收标准 |
 |---|---|---|---|---|---|
-| HOB-010 | 已落地 | 建立试点复盘指标 | 没有指标时，很难判断 Harness 是否真正降风险、提效率。 | `docs/process/harness-pilot-retro-metrics.md` | 至少跟踪 PRD Ready 一次通过率、阶段产物一次通过率、规范偏离次数、ready-for-agent 到可验证 PR 周期、回归缺陷数、模板 / Skill 更新次数。 |
+| HOB-010 | 已落地 | 建立试点复盘指标 | 没有指标时，很难判断 Harness 是否真正降风险、提效率。 | `docs/process/harness-pilot-retro-metrics.md` | 至少跟踪 Spec Ready 一次通过率、阶段产物一次通过率、规范偏离次数、ready-for-agent 到可验证 PR 周期、回归缺陷数、模板 / Skill 更新次数。 |
 | HOB-011 | 已并入 | 沉淀门禁自动化脚本 backlog | 自动化不能一次做完，需要按收益排序。 | `docs/process/harness-automation-candidates.md` | 每项脚本记录触发阶段、输入、输出、失败处理和人工接管点。 |
 | HOB-012 | 试点后执行 | 试点后更新 AGENTS / CONTEXT / ADR | 试点结论如果不回流，流程会停留在一次性经验。 | `docs/process/harness-pilot-retro-metrics.md` 中的治理回流检查 | 只把稳定语言写入 CONTEXT；只有难回滚、非显而易见且有真实取舍的决策写 ADR。 |
-| HOB-013 | 已落地 | 评估是否需要 Harness 状态模型 | 当前阶段状态主要散落在文档、Issue 和 Issue 中，后续自动化可能需要统一状态模型。 | `docs/process/harness-state-model-evaluation.md` | 明确状态来源、状态流转、谁有权推进、失败回退和人工审查状态。 |
+| HOB-013 | 已落地 | 评估是否需要 Harness 状态模型 | 当前阶段状态主要散落在文档、Ticket 和 tracker 评论中，后续自动化可能需要统一状态模型。 | `docs/process/harness-state-model-evaluation.md` | 明确状态来源、状态流转、谁有权推进、失败回退和人工审查状态。 |
 
 ## 推荐执行顺序
 

package/template/docs/process/harness-pilot-retro-metrics.md

@@ -6,13 +6,13 @@
 
 | 指标 | 定义 | 数据来源 | 目标方向 |
 |---|---|---|---|
-| PRD Ready 一次通过率 | PRD 首次评审即可进入下一阶段的比例 | PRD Review 记录、Issue 评论 | 提升 |
+| Spec Ready 一次通过率 | Spec 首次评审即可进入下一阶段的比例 | Spec Review 记录、Ticket 评论 | 提升 |
 | 阶段产物一次通过率 | 阶段产物首次 checkpoint 无阻断项的比例 | 阶段 checkpoint、门禁记录 | 提升 |
-| 规范偏离次数 | 违反流程、模板、YSS、Issue 或安全红线的次数 | Review、Architecture Re-check、Issue | 降低 |
-| ready-for-agent 到可验证 PR 周期 | 从进入 Agent 可执行状态到出现可验证 PR / MR 的耗时 | Issue 状态、Git 记录、验证记录 | 缩短 |
-| 回归缺陷数 | 试点上线或合并后发现的回归问题 | 缺陷 Issue、Release Review | 降低 |
+| 规范偏离次数 | 违反流程、模板、YSS、Ticket 或风险 / 回滚约束的次数 | Review、Architecture Re-check、Ticket | 降低 |
+| ready-for-agent 到可验证 PR 周期 | 从进入 Agent 可执行状态到出现可验证 PR / MR 的耗时 | Ticket 状态、Git 记录、验证记录 | 缩短 |
+| 回归缺陷数 | 试点上线或合并后发现的回归问题 | 缺陷 Ticket、Release Review | 降低 |
 | 模板 / Skill 更新次数 | 复盘后新增、修改、合并或废弃的模板 / Skill 数量 | 复盘记录、Git diff | 稳定沉淀 |
-| 人审阻断命中次数 | 安全红线或不可逆变更触发人工审查的次数 | `TODO-HUMAN-REVIEW`、Review 记录 | 可解释，不追求为零 |
+| 人审阻断命中次数 | 不可逆变更或责任确认触发人工审查的次数 | 人工确认项、Review 记录 | 可解释，不追求为零 |
 | 自动化候选新增数 | 复盘中新识别的可自动 / 半自动检查项 | `harness-automation-candidates.md` | 持续收敛 |
 
 ## 复盘记录模板
@@ -24,14 +24,14 @@
 | 试点模块 |  |
 | 时间范围 |  |
 | 参与角色 |  |
-| 关联 Issue / MR / PR |  |
-| 使用的 Issue change |  |
+| 关联 Ticket / MR / PR |  |
+| 使用的 Ticket |  |
 
 ### 指标结果
 
 | 指标 | 目标 | 实际 | 结论 |
 |---|---|---|---|
-| PRD Ready 一次通过率 |  |  |  |
+| Spec Ready 一次通过率 |  |  |  |
 | 阶段产物一次通过率 |  |  |  |
 | 规范偏离次数 |  |  |  |
 | ready-for-agent 到可验证 PR 周期 |  |  |  |

package/template/docs/process/harness-pilot-selection.md

@@ -8,7 +8,7 @@
 |---|---|---|
 | 业务价值 | 真实业务需求，能被产品、研发和测试共同验收 | 避免试点变成纯流程演示 |
 | 风险等级 | 低到中等风险，不涉及支付、加密、核心认证授权或不可逆迁移 | 降低首次试点的人审和回滚压力 |
-| 边界清晰 | 功能边界、用户角色、输入输出和非目标范围容易定义 | 便于验证 PRD、OpenAPI 和垂直切片 |
+| 边界清晰 | 功能边界、用户角色、输入输出和非目标范围容易定义 | 便于验证 Spec、OpenAPI 和垂直切片 |
 | API / UI / 数据影响 | 至少触碰一个可验证接口或页面，最好有轻量数据读写 | 能检验契约、前后端协作和测试闭环 |
 | 切片可拆 | 可以拆成 1 到 3 个端到端垂直切片 | 避免横向拆层或范围过大 |
 | 验证可得 | 有明确验收标准、测试命令或人工验收路径 | 便于 fresh verification |
@@ -26,22 +26,22 @@
 
 | 检查项 | 要求 |
 |---|---|
-| 试点目标 | 说明要验证哪些 Harness 能力，例如裁剪、OpenAPI、Issue、Build Checklist、fresh verification |
+| 试点目标 | 说明要验证哪些 Harness 能力，例如裁剪、OpenAPI、Ticket、Build Checklist、fresh verification |
 | 业务范围 | 明确用户、痛点、MVP、非目标和成功标准 |
-| 现有资产 | 列出已有 PRD、设计、OpenAPI、架构、Issue、垂直切片 Issue 或代码入口 |
+| 现有资产 | 列出已有 Spec、设计、OpenAPI、架构、Ticket、垂直切片 Ticket 或代码入口 |
 | 影响面 | 标注 UI、API、数据、权限、安全、部署和回滚影响 |
 | 垂直切片 | 拆成可独立验证的 1 到 3 个端到端切片 |
 | 验证方式 | 明确测试命令、契约检查、人工验收或截图证据 |
-| 人审点 | 标注 `TODO-HUMAN-REVIEW` 和责任人 |
-| Git / Issue | 明确 Issue tracker、里程碑、分支策略和 checkpoint 节奏 |
+| 人审点 | 标注 人工确认项和责任人 |
+| Git / Ticket | 明确 Ticket tracker、里程碑、分支策略和 checkpoint 节奏 |
 
 ## 推荐试点闭环
 
 ```text
-PRD
+Spec
 → API 影响分析 / 契约草案
 → review-only OpenAPI Draft（如需要）
-→ Issue Change
+→ 功能父 Ticket 更新 / 契约冻结
 → 垂直切片
 → TDD
 → Review
@@ -49,4 +49,4 @@ PRD
 → Retro
 ```
 
-试点过程中只补必要文档。若发现流程负担高于收益，优先调整模板和自动化候选，而不是删除安全红线、契约冻结或 fresh verification。
+试点过程中只补必要文档。若发现流程负担高于收益，优先调整模板和自动化候选，而不是删除风险 / 回滚约束、契约冻结或 fresh verification。