create-yss-spec 1.0.0

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

@@ -0,0 +1,65 @@
+# Harness 工程一页蓝图
+
+本文面向业务方、管理者和项目干系人，用于快速说明 Harness 工程为什么做、怎么跑、哪些门禁不能跳，以及如何从试点开始。
+
+## 为什么做
+
+AI 不能只作为一次性辅助工具使用。Harness 工程的目标，是把 AI 放进可治理的软件研发流水线，让需求、设计、契约、实现、审查、发布和复盘都有可追踪产物、质量门禁和验证证据。
+
+## 怎么分阶段
+
+对外可以用 13 个工作单元理解全链路：
+
+```text
+机会 / 问题收集
+→ 需求澄清
+→ PRD + 原型并行
+→ SDD 研发规范基线
+→ DDD 领域建模
+→ 架构设计
+→ 垂直切片 Issue
+→ 垂直 Issue 详细设计
+→ TDD 并行开发
+→ 测试验证
+→ Code Review
+→ 发布部署
+→ 反馈复盘
+```
+
+对内执行时，13 个工作单元映射到本仓库 8 个主阶段和 21 个门禁。权威执行索引仍是 `docs/process/lifecycle-artifact-map.md`。
+
+## 哪些门禁不能跳
+
+- API 变化必须先有 API 影响记录和契约草案 / review-only OpenAPI Draft，并在实现或生成客户端前完成 Freeze 或记录无 API 影响。
+- 正式垂直切片前必须有 active Issue change 和完整 change 资产。
+- 架构、数据、ADR、工程基线和安全红线必须进入 Build Architecture Checklist。
+- 支付、迁移、认证授权、加密、SQL、公共基础库 API 等安全红线必须人工审查。
+- 完成、可合并或可发布结论必须有 fresh verification。
+- 每个阶段结束必须记录 Issue 同步状态和 Git checkpoint 判断。
+
+## 试点怎么跑
+
+先选择一个真实、低风险、边界清晰的业务模块，按半自动闭环推进：
+
+```text
+PRD
+→ API 影响分析 / 契约草案
+→ review-only OpenAPI Draft（如需要）
+→ Issue Change
+→ 垂直切片
+→ TDD
+→ Review
+→ Release
+→ Retro
+```
+
+试点不追求一开始全自动。优先验证流程能否降低风险、减少返工、稳定沉淀模板和 Skill。
+
+## 成功指标
+
+- PRD Ready 一次通过率提升。
+- 阶段产物一次通过率提升。
+- 规范偏离次数下降。
+- ready-for-agent 到可验证 PR 的周期缩短。
+- 回归缺陷数下降。
+- 模板、脚本和 Skill 能从复盘中持续更新。

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

@@ -0,0 +1,53 @@
+# Harness 工程优化调整待办
+
+本文档记录基于《产品全生命周期 AI 研发工程化体系》PPT 与当前项目流程对比后，需要优化调整的待办事项。目标不是削弱现有治理能力，而是在保留 Issue、YSS、门禁、追踪和验证优势的前提下，补齐轻量表达、流程裁剪、试点推进和自动化落地能力。
+
+## 优化目标
+
+- 让 Harness 工程有一版容易对外说明的轻量蓝图。
+- 让不同规模任务可以按风险裁剪流程，而不是默认套完整链路。
+- 让高频门禁、同步和检查动作逐步自动化，降低流程执行成本。
+- 让 Skill、模板和脚本沉淀有明确触发标准。
+- 让试点模块可以端到端验证完整闭环。
+
+## P0：必须先做
+
+| 编号 | 状态 | 待办 | 问题空间 | 交付物 | 验收标准 |
+|---|---|---|---|---|---|
+| 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` | 每个阶段都能按固定字段记录产物、验证、阻塞、安全人审、排除的脏文件和下一步。 |
+
+## P1：试点前补齐
+
+| 编号 | 状态 | 待办 | 问题空间 | 交付物 | 验收标准 |
+|---|---|---|---|---|---|
+| 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-008 | 已落地 | 形成对外汇报版 Harness 蓝图 | 当前 `AGENTS.md` 适合 Agent 执行，不适合业务方和管理者快速理解。 | `docs/process/harness-executive-blueprint.md` | 能用 5 分钟讲清楚：为什么做、怎么分阶段、哪些门禁不能跳、试点怎么跑。 |
+| HOB-009 | 已落地 | 定义“最近可信阶段”判定表 | 项目已有原则，但缺少可查表，执行时容易争议。 | `docs/process/harness-process-tailoring.md` | 输入不同变更类型后，能定位从 PRD、设计、OpenAPI、架构、Issue 或实现哪个阶段开始补齐。 |
+
+## P2：试点后演进
+
+| 编号 | 状态 | 待办 | 问题空间 | 交付物 | 验收标准 |
+|---|---|---|---|---|---|
+| HOB-010 | 已落地 | 建立试点复盘指标 | 没有指标时，很难判断 Harness 是否真正降风险、提效率。 | `docs/process/harness-pilot-retro-metrics.md` | 至少跟踪 PRD 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` | 明确状态来源、状态流转、谁有权推进、失败回退和人工审查状态。 |
+
+## 推荐执行顺序
+
+1. 先完成 HOB-001、HOB-002、HOB-003，形成“讲得清、裁得动、试得起来”的基础。
+2. 再完成 HOB-004、HOB-005、HOB-006，把试点前的门禁成本压下来。
+3. 选择一个真实低风险模块跑试点，试点中只补必要文档，不追求全自动。
+4. 试点结束后执行 HOB-010、HOB-011、HOB-012，把经验回流到模板、Skill 和流程规则。
+
+## 暂不做
+
+- 不把当前 9 阶段 / 21 门禁替换成 PPT 的 13 个工作单元；13 个工作单元只作为轻量表达层。
+- 不一开始建设全自动流水线；先跑通半自动闭环。
+- 不为每个普通流程选择都写 ADR；只有满足难回滚、非显而易见、有真实取舍时才写。
+- 不把所有检查都做成 Skill；低频、一次性或高度依赖人工判断的动作保留为模板或 checklist。

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

@@ -0,0 +1,64 @@
+# Harness 试点复盘指标
+
+本文用于 Harness 试点结束后的复盘。它覆盖 HOB-010，并把 HOB-012 的 AGENTS / CONTEXT / ADR 回流动作作为复盘检查项处理。
+
+## 指标定义
+
+| 指标 | 定义 | 数据来源 | 目标方向 |
+|---|---|---|---|
+| PRD Ready 一次通过率 | PRD 首次评审即可进入下一阶段的比例 | PRD Review 记录、Issue 评论 | 提升 |
+| 阶段产物一次通过率 | 阶段产物首次 checkpoint 无阻断项的比例 | 阶段 checkpoint、门禁记录 | 提升 |
+| 规范偏离次数 | 违反流程、模板、YSS、Issue 或安全红线的次数 | Review、Architecture Re-check、Issue | 降低 |
+| ready-for-agent 到可验证 PR 周期 | 从进入 Agent 可执行状态到出现可验证 PR / MR 的耗时 | Issue 状态、Git 记录、验证记录 | 缩短 |
+| 回归缺陷数 | 试点上线或合并后发现的回归问题 | 缺陷 Issue、Release Review | 降低 |
+| 模板 / Skill 更新次数 | 复盘后新增、修改、合并或废弃的模板 / Skill 数量 | 复盘记录、Git diff | 稳定沉淀 |
+| 人审阻断命中次数 | 安全红线或不可逆变更触发人工审查的次数 | `TODO-HUMAN-REVIEW`、Review 记录 | 可解释，不追求为零 |
+| 自动化候选新增数 | 复盘中新识别的可自动 / 半自动检查项 | `harness-automation-candidates.md` | 持续收敛 |
+
+## 复盘记录模板
+
+### 基本信息
+
+| 字段 | 内容 |
+|---|---|
+| 试点模块 |  |
+| 时间范围 |  |
+| 参与角色 |  |
+| 关联 Issue / MR / PR |  |
+| 使用的 Issue change |  |
+
+### 指标结果
+
+| 指标 | 目标 | 实际 | 结论 |
+|---|---|---|---|
+| PRD Ready 一次通过率 |  |  |  |
+| 阶段产物一次通过率 |  |  |  |
+| 规范偏离次数 |  |  |  |
+| ready-for-agent 到可验证 PR 周期 |  |  |  |
+| 回归缺陷数 |  |  |  |
+| 模板 / Skill 更新次数 |  |  |  |
+
+### 复盘问题
+
+| 问题 | 证据 | 原因 | 处理动作 | 负责人 |
+|---|---|---|---|---|
+|  |  |  |  |  |
+
+### 治理回流检查
+
+| 回流项 | 是否需要 | 动作 |
+|---|---|---|
+| 更新 `AGENTS.md` | 是 / 否 | 仅当硬性入口规则稳定变化时执行 |
+| 更新 `CONTEXT.md` | 是 / 否 | 只写稳定领域语言，不写实现细节 |
+| 新增 / 更新 ADR | 是 / 否 | 仅当决策难回滚、非显而易见且存在真实取舍 |
+| 更新模板 | 是 / 否 | 记录模板路径和变化原因 |
+| 更新 Skill | 是 / 否 | 按 `docs/process/skill-governance.md` 评估 |
+| 更新自动化候选 | 是 / 否 | 写入 `docs/process/harness-automation-candidates.md` |
+
+### 结论
+
+- 是否继续扩大试点：
+- 必须先修正的问题：
+- 可进入自动化 backlog 的动作：
+- 需要人工决策的事项：
+

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

@@ -0,0 +1,52 @@
+# Harness 试点模块选择标准
+
+本文用于选择第一个 Harness 工程试点模块。试点目标是跑通半自动治理闭环，而不是一开始追求全自动流水线。
+
+## 选择标准
+
+| 维度 | 推荐条件 | 原因 |
+|---|---|---|
+| 业务价值 | 真实业务需求，能被产品、研发和测试共同验收 | 避免试点变成纯流程演示 |
+| 风险等级 | 低到中等风险，不涉及支付、加密、核心认证授权或不可逆迁移 | 降低首次试点的人审和回滚压力 |
+| 边界清晰 | 功能边界、用户角色、输入输出和非目标范围容易定义 | 便于验证 PRD、OpenAPI 和垂直切片 |
+| API / UI / 数据影响 | 至少触碰一个可验证接口或页面，最好有轻量数据读写 | 能检验契约、前后端协作和测试闭环 |
+| 切片可拆 | 可以拆成 1 到 3 个端到端垂直切片 | 避免横向拆层或范围过大 |
+| 验证可得 | 有明确验收标准、测试命令或人工验收路径 | 便于 fresh verification |
+| 回滚简单 | 可以通过配置、开关、接口兼容或小范围发布回滚 | 便于 Release Review |
+
+## 排除标准
+
+- 首次试点不选择支付、核心权限、加密算法、数据库迁移、公共基础库 API 变更。
+- 不选择边界仍在探索的新产品机会；这类任务先进入 Discovery。
+- 不选择只有文案或样式的小改动；它不足以验证端到端 Harness。
+- 不选择依赖多个外部团队同步上线的跨系统大变更。
+- 不选择无法提供测试命令或人工验收路径的隐性治理任务。
+
+## 试点准备清单
+
+| 检查项 | 要求 |
+|---|---|
+| 试点目标 | 说明要验证哪些 Harness 能力，例如裁剪、OpenAPI、Issue、Build Checklist、fresh verification |
+| 业务范围 | 明确用户、痛点、MVP、非目标和成功标准 |
+| 现有资产 | 列出已有 PRD、设计、OpenAPI、架构、Issue、垂直切片 Issue 或代码入口 |
+| 影响面 | 标注 UI、API、数据、权限、安全、部署和回滚影响 |
+| 垂直切片 | 拆成可独立验证的 1 到 3 个端到端切片 |
+| 验证方式 | 明确测试命令、契约检查、人工验收或截图证据 |
+| 人审点 | 标注 `TODO-HUMAN-REVIEW` 和责任人 |
+| Git / Issue | 明确 Issue tracker、里程碑、分支策略和 checkpoint 节奏 |
+
+## 推荐试点闭环
+
+```text
+PRD
+→ API 影响分析 / 契约草案
+→ review-only OpenAPI Draft（如需要）
+→ Issue Change
+→ 垂直切片
+→ TDD
+→ Review
+→ Release
+→ Retro
+```
+
+试点过程中只补必要文档。若发现流程负担高于收益，优先调整模板和自动化候选，而不是删除安全红线、契约冻结或 fresh verification。

package/template/docs/process/harness-process-tailoring.md

@@ -0,0 +1,49 @@
+# Harness 流程裁剪指南
+
+本文定义 Harness 工程在不同任务规模下的最小流程、最近可信阶段和升级条件。它补充 `docs/process/lifecycle-artifact-map.md`，不替代其中的 8 个主阶段和 21 个门禁。
+
+本仓库默认使用 Matt Pocock Engineering Skills 承接需求澄清、PRD、Issue 拆分、实现、TDD、诊断、审查和架构治理。OpenAPI 3.1 继续作为前后端契约资产；OpenSpec-style Spec Delta 只作为中高风险变更的轻量行为差异记录，不再引入额外变更状态机。
+
+## 三档流程
+
+| 档位 | 适用场景 | 最小入口 | 最小产物 | 最小验证 | 典型退出标准 |
+|---|---|---|---|---|---|
+| 小改动 | 文案、局部样式、配置微调、无 API / 数据 / 权限影响的低风险修正 | 影响面评估 | issue 备注或简短实施说明 | 相关页面 / 命令 / 文档检查 | 变更范围清楚、验证新鲜、无安全红线 |
+| 中等变更 | 已有功能迭代、已有页面 / API 的局部扩展、非核心流程调整 | 最近可信阶段 | 受影响 PRD / 设计 / OpenAPI / 架构 / Issue 的增量更新；必要时 Spec Delta | 受影响切片测试、契约检查、review | 下游门禁补齐，未受影响资产不重跑 |
+| 新模块 / 高风险变更 | 新产品、新业务域、新模块、跨端协作、服务边界、数据模型、权限、安全或发布回滚变化 | 入口分诊 | Discovery、PRD、设计、OpenAPI、Spec Delta、架构、垂直切片 Issue | TDD、契约验证、独立审查、fresh verification | 完整生命周期关键门禁都有证据 |
+
+## 最近可信阶段判定表
+
+| 当前输入 / 变更事实 | 最近可信阶段 | 需要补齐的下游 |
+|---|---|---|
+| 只有模糊想法、业务机会或竞品输入 | 2. 机会与 Discovery | Discovery、`grill-with-docs`、PRD、业务 / 功能架构 |
+| 已有清晰 PRD，但用户、痛点、MVP 或非目标不稳 | 3. 业务 / PRD / 功能架构 | PRD Review、功能架构、必要的产品设计 |
+| 有 UI 变更但缺页面流、状态矩阵或原型评审 | 4. 产品设计与需求冻结 | 交互说明、状态矩阵、Prototype Review、PRD 回填 |
+| API 路径、schema、错误结构、分页或权限发生变化 | 5. 系统 / 数据架构与工程契约设计审查 | API 影响记录、契约草案 / OpenAPI Draft Review、必要时 Spec Delta、系统 / 数据架构反审、Freeze、`to-issues` |
+| 服务边界、集成、部署、性能、可靠性或运维变化 | 5. 系统 / 数据架构与工程契约设计审查 | 系统架构、Design Review、必要时 Spec Delta、Build Architecture Checklist |
+| 持久化、元数据、版本、血缘、搜索、索引或迁移变化 | 5. 系统 / 数据架构与工程契约设计审查 | 数据架构、必要时 Spec Delta、人审点、Repository / MyBatis 前置审查 |
+| OpenAPI 已冻结但还没有垂直切片 Issue | 6. 契约冻结与 Issue formalization | `to-issues`、实施计划、Build Architecture Checklist |
+| 已有垂直切片 Issue，但实现准备不完整 | 7. 垂直切片与 TDD 实现 | 实施计划、YSS skill routing、测试命令、回滚点 |
+| 只有代码修复或测试失败 | 7. 垂直切片与 TDD 实现 | 可复现命令、失败测试、最小修复、fresh verification |
+| 准备发布或宣称完成 | 8. 验证发布与复盘 | fresh verification、发布说明、回滚方案、复盘入口 |
+
+## 升级条件
+
+任一条件命中时，不得按小改动处理，必须升级到对应最近可信阶段：
+
+- API 契约、OpenAPI schema、错误结构、分页、权限或版本发生变化。
+- 认证、授权、支付、加密、SQL 原生查询、数据库迁移、公共基础库 API 等安全红线被触碰。
+- 数据模型、Repository / Gateway、持久化边界、审计日志、文件上传下载、临时 URL、版本快照、血缘或查询索引变化。
+- 服务边界、外部系统集成、部署、回滚、可观测性、性能、可靠性或运维约束变化。
+- UI 变更影响用户主流程、权限状态、异常状态、页面导航或 OpenAPI 反推清单。
+- 实现与既有架构、CONTEXT 术语、ADR、PRD 或垂直切片 Issue 出现漂移。
+- 无法给出 fresh verification 证据。
+
+## 裁剪原则
+
+- 裁剪的是不相关阶段和产物，不裁剪证据链。
+- 中等变更只补受影响阶段及其下游，不回到机会探索。
+- 小改动必须保留影响面评估、验证证据和 Git checkpoint 判断。
+- 小改动默认不创建 Spec Delta；只有扩散到 API、权限、状态机、数据模型、跨端或安全红线时才升级补齐。
+- 安全红线只能进入人工审查或草案状态，不能因任务小而跳过。
+- OpenAPI Freeze 后直接进入 `to-issues` 或等价垂直切片拆分；不要求额外变更状态文件。

package/template/docs/process/harness-work-unit-map.md

@@ -0,0 +1,33 @@
+# Harness 13 个工作单元映射表
+
+本文把《产品全生命周期 AI 研发工程化体系》PPT 中的 13 个可治理工作单元，映射到本仓库现行的 8 个主阶段和 21 个门禁 / 职责点。13 个工作单元只作为轻量表达层；执行、审查和追踪仍以 `docs/process/lifecycle-artifact-map.md` 为权威来源。
+
+## 使用方式
+
+- 对外沟通时使用 13 个工作单元讲清楚端到端链路。
+- 对内执行时按映射表回到 8 个主阶段、21 个门禁、模板和 Skill。
+- 小改动、中等变更和新模块是否裁剪，以 `docs/process/harness-process-tailoring.md` 为准。
+
+## 映射表
+
+| PPT 工作单元 | 对应主阶段 | 对应门禁 / 职责点 | 关键产物 | 推荐 Skill / 能力 | 可裁剪 | 自动化潜力 |
+|---|---|---|---|---|---|---|
+| 0. 机会 / 问题收集 | 1. 入口分诊；2. 机会与 Discovery | 0. 入口分诊；1. 机会探索 | 分诊结论、Discovery 收敛、MVP 边界 | `yss-product-lifecycle`、`competitive-intelligence`、Discovery 模板 | 小改动可跳过；新产品 / 新模块必需 | 半自动生成分诊清单、竞品情报简报和 Discovery 模板 |
+| 1. 需求澄清 | 3. 业务 / PRD / 功能架构 | 3. 需求澄清 | 澄清记录、用户 / 痛点 / 验收标准 | `grill-with-docs`、`to-prd` | 小文案 / 单点 bug 可轻量化 | 半自动生成澄清问题和缺口清单 |
+| 2. PRD + 原型并行 | 3. 业务 / PRD / 功能架构；4. 产品设计与需求冻结 | 4. 需求基线 / 功能架构；5. 页面 / 原型 / 交互设计；6. 原型评审；7. PRD 校准 / 需求冻结 | PRD、页面清单、状态矩阵、原型评审、需求冻结 | `yss-design-system`、`product-design-prototype`、`prototype-review` | 无 UI 可省略原型；中等变更只补受影响页面 | 半自动检查 PRD 字段、状态矩阵和原型评审项 |
+| 3. SDD 研发规范基线 | 5. 系统 / 数据架构与工程契约设计审查；6. 契约冻结与 Issue | 8. API 影响分析 / 契约草案；9. 工程基线；13. 契约冻结；14. Issue formalization | API 影响记录、契约草案 / OpenAPI Draft / Freeze、Spec Delta、工程基线、垂直切片 Issue、实施路由、验证证据 | `to-issues`、`yss-router` | 无 API / 无工程边界变化时记录无影响结论；低风险小改动跳过 Spec Delta | 自动检查 OpenAPI Freeze / no API impact / Spec Delta / vertical slice Issue / implementation routing |
+| 4. DDD 领域建模 | 3. 业务 / PRD / 功能架构；5. 系统 / 数据架构与工程契约设计审查 | 2. 业务架构；10. 系统总体架构；11. 数据架构 | CONTEXT 术语、业务能力、领域边界、聚合 / 状态规则 | `domain-modeling`、`yss-domain-modeling`、`yss-domain` | 小改动只校验是否影响既有术语或边界 | 半自动检查术语回填和领域边界审查项 |
+| 5. 架构设计 | 5. 系统 / 数据架构与工程契约设计审查 | 8. API 影响分析 / 契约草案；9. 工程基线；10. 系统总体架构；11. 数据架构；12. 设计审查 | API 影响记录、工程基线、系统概要设计、数据架构、ADR 候选、架构评审 | `codebase-design`、`improve-codebase-architecture`、YSS 架构模板 | 不触碰 API、工程边界、服务边界、数据、NFR、部署时可轻量记录无影响 | 半自动生成 Architecture Review checklist |
+| 6. 垂直切片 Issue | 7. 垂直切片与 TDD 实现 | 15. 实施计划 | 垂直切片 Issue、实现路由、Build Architecture Checklist | `to-issues`、`yss-router`、`implement` | 小改动可用单一 Issue / 实施备注替代 | 半自动检查切片是否端到端而非横向拆层 |
+| 7. 垂直 Issue 详细设计 | 7. 垂直切片与 TDD 实现 | 15. 实施计划 | 切片设计、接口字段映射、回滚点、架构约束绑定 | 实现计划模板、Build Architecture Checklist 模板 | 低风险小改动可合并到实施说明 | 半自动生成字段映射和架构约束回勾表 |
+| 8. TDD 并行开发 | 7. 垂直切片与 TDD 实现 | 16. 开发实现 | 失败测试、最小实现、重构记录 | `tdd`、YSS 实现专项 Skill | 文档-only 变更可说明 TDD 例外 | 自动执行测试命令并收集 fresh verification |
+| 9. 测试验证 | 7. 垂直切片与 TDD 实现；8. 验证发布与复盘 | 16. 开发实现；19. 验证发布 | 测试报告、验收映射、fresh verification | fresh verification 记录、验证模板 | 不可裁剪为“未验证”；只能裁剪验证范围 | 自动跑命令、汇总覆盖率和验收映射 |
+| 10. Code Review | 7. 垂直切片与 TDD 实现 | 17. 独立审查；18. 清理简化 | Review Report、MR / PR 评论、清理项 | `code-review`、`code-review-process` | 合并 / 发布前不可跳过；小改动可轻量 review | 半自动生成 review checklist，人工确认风险 |
+| 11. 发布部署 | 8. 验证发布与复盘 | 19. 验证发布 | 发布说明、实施记录、回滚方案、观察窗口 | Release 模板、实施记录模板 | 未发布的文档 / 草案可记录不适用 | 半自动生成发布检查和回滚清单 |
+| 12. 反馈复盘 | 8. 验证发布与复盘 | 20. 复盘沉淀 | 复盘、模板 / Skill 更新、CONTEXT / ADR 回流 | `writing-skills`、复盘模板、Skill 治理规则 | 小改动可阶段性合并复盘 | 半自动生成指标和待沉淀动作清单 |
+
+## 不变规则
+
+- 13 个工作单元不能替代 OpenAPI Freeze、Issue formalization、Build Architecture Checklist、安全红线和 fresh verification。
+- 裁剪只能减少不相关产物，不能裁剪关键追踪关系和验证证据。
+- 触碰安全红线时必须进入人工审查，不能被自动化门禁放行。

package/template/docs/process/implementation-repo-integration.md

@@ -0,0 +1,100 @@
+# 实现仓库接入流程
+
+本文定义研发管理仓库与外部实现仓库的集成方式。当前仓库默认作为研发管理仓库，承载 PRD、OpenAPI、Issue、架构、垂直切片、验证、发布和复盘；前端、后端和其他运行时代码默认保留在独立实现仓库中。
+
+## 职责边界
+
+| 仓库类型 | 职责 | 不负责 |
+|---|---|---|
+| 研发管理仓库 | 规格、契约、架构、切片、Issue 同步、验证记录、发布说明和复盘 | 长期拥有前端 / 后端源码、替代实现仓库 CI |
+| 实现仓库 | 前端 / 后端代码、分支、MR / PR、CI、测试命令、构建和发布流水线 | 定义跨仓库产品规格和生命周期门禁 |
+
+## 接入路径
+
+| 场景 | 推荐路径 | 关键产物 |
+|---|---|---|
+| 已有后端工程 | `implementation-repo-onboarding` 只读扫描，记录工程基线、测试命令和偏离项 | 实现仓库登记、工程基线审查、验证命令 |
+| 已有前端工程 | `implementation-repo-onboarding` 只读扫描，检查技术栈、OpenAPI client、设计 token 和页面规范 | 实现仓库登记、前端基线审查、验证命令 |
+| 0-1 后端工程 | 先在 Harness change 中记录实现仓库决策，再使用 `yss-ddd-scaffold-generator` 生成外部后端工程 | 后端 Git 仓库、YSS DDD 基线、Harness 登记 |
+| 0-1 前端工程 | 先记录实现仓库决策，再按 `yss-frontend-scaffold-generator` 使用 YSS 前端模板生成外部工程 | 前端 Git 仓库、前端模板基线、Harness 登记 |
+| 跨仓库垂直切片 | 使用 `cross-repo-implementation-routing` 绑定 Harness change、后端 MR、前端 MR 和验证证据 | 跨仓库切片记录、fresh verification |
+
+## 实现前工程存在性判定
+
+进入业务实现前，必须先判断当前需求受影响的 frontend / backend 运行时代码工程是否已经存在且可复用。该判定必须写入实施计划、实现路由记录或切片 issue，至少回答：
+
+- 当前切片是否影响 frontend、backend，或两者都影响。
+- 对应实现仓库 / 本地工程是否已经存在。
+- 已有工程是否满足当前 OpenAPI、设计系统、YSS DDD 或工程基线要求。
+- 若不存在或不可复用，是否需要初始化 0-1 脚手架，以及初始化到哪个目标仓库或输出目录。
+
+判定结论的路由规则：
+
+- 后端受影响且不存在可用工程：先记录实现仓库决策，再路由 `yss-ddd-scaffold-generator`。
+- 前端受影响且不存在可用工程：先记录实现仓库决策，再路由 `yss-frontend-scaffold-generator`。
+- 前后端均受影响且均不存在可用工程：先分别完成前后端初始化，再进入垂直切片业务实现。
+- 工程已存在但与当前目录约定或技术基线冲突：先停在 engineering baseline / implementation routing，补齐偏离说明和处理决策。
+
+## 实现仓库登记
+
+每个参与实现的仓库都必须有登记记录。推荐使用 `docs/templates/implementation-repo-registry-template.md`，至少记录：
+
+- repo role：backend / frontend / fullstack / other。
+- Git URL、默认分支、本地 worktree 或远端 MR / PR 链接。
+- CI 系统、测试命令、构建命令。
+- OpenAPI 接入方式、设计 token 接入方式。
+- 已知偏离项、人审要求和补齐计划。
+
+登记记录可以放在当前 change 的 `design.md`、build entry review、实施计划或 `docs/implementation/` 下的实现记录中，但必须能被垂直切片和阶段 checkpoint 引用。
+
+若当前切片需要新建 0-1 工程，登记记录还必须额外说明：
+
+- `scaffold_status`：existing / required / initialized。
+- `scaffold_skill`：`yss-ddd-scaffold-generator` / `yss-frontend-scaffold-generator` / none。
+- 初始化理由、目标输出目录或目标仓库，以及是否已经通过基线检查。
+
+## 跨仓库切片规则
+
+每个跨前后端切片必须绑定以下信息：
+
+- Harness change：Issue change ID、垂直切片 ID、OpenAPI Freeze 记录。
+- Backend：repo、branch、MR / PR、测试命令、验证结果。
+- Frontend：repo、branch、MR / PR、测试命令、验证结果。
+- Contract：OpenAPI spec 路径、生成类型或 API client 版本、契约验证命令。
+- Release：发布说明、回滚点、观察信号。
+
+推荐使用 `docs/templates/cross-repo-slice-template.md` 记录。没有前端或后端影响时，对应仓库字段必须标记 `not-applicable` 并说明原因。
+
+## 0-1 后端工程
+
+从零创建后端服务时，继续使用 `yss-ddd-scaffold-generator` 生成 YSS DDD 多模块骨架。生成前必须先记录：
+
+- 目标 Git 仓库或本地输出目录。
+- 项目名、基础包名、数据库类型、是否带示例代码。
+- 是否初始化 Git、是否创建远端仓库、默认分支和 CI 策略。
+- 与当前 Harness change 的绑定关系。
+
+生成后必须使用 `yss-backend-scaffold-parent` 做工程基线检查，不得把脚手架 sample 代码当作业务实现交付。
+
+## 0-1 前端工程
+
+从零创建前端工程时，目标模板固定为：
+
+```text
+http://192.168.167.142:8081/Data-Middleground-Develop-Area/product-code/ai-frontend/yss-design/yss-frontend-template.git#template
+```
+
+模板基线：Vue 3、TypeScript、Vite、Qiankun、pnpm、Ant Design Vue、`@yss-ui/components`、`@yss-ui/hooks`、Orval。
+
+生成前必须记录：app name、microapp name、base route、OpenAPI source、目标 Git 仓库或本地输出目录、是否初始化 Git。初始化 Git、推送远端或创建仓库必须得到用户明确授权。
+
+## 阶段回流
+
+阶段结束时，按 `docs/process/templates/stage-checkpoint-template.md` 回写：
+
+- Harness 资产完成情况。
+- 各实现仓库 MR / PR 和 CI 状态。
+- 测试命令和 fresh verification。
+- 安全人审点、阻塞项和下一步。
+
+不得只在实现仓库 MR / PR 中保留结论；Harness 仓库必须保留可追溯的规格和验证证据。

package/template/docs/process/lifecycle-artifact-map.md

@@ -0,0 +1,112 @@
+---
+status: active
+owner: ai
+---
+
+# 产品研发生命周期产物映射表
+
+本文是本仓库产品研发流程的权威索引。日常执行使用 8 个主阶段；21 个门禁 / 职责点用于审查、路由和补齐缺失资产。小需求、Bug、局部样式或配置调整不重跑完整流程，只从最早受影响资产开始补齐下游门禁。
+
+本仓库的默认流程已迁移为 Matt Pocock Engineering Skills + YSS + OpenAPI：用 Matt skills 做需求澄清、PRD、Issue 拆分、实现、TDD、诊断、审查和架构治理；用 YSS skills 做业务工程规范；用 OpenAPI 3.1 做前后端契约。中高风险变更可用 OpenSpec-style Spec Delta 补充行为差异、验收场景和测试映射，但不恢复 OpenSpec CLI 或额外变更状态机。
+
+补充执行资产：
+
+- 13 个对外工作单元与本表的映射见 `docs/process/harness-work-unit-map.md`。
+- 小改动 / 中等变更 / 新模块的流程裁剪和最近可信阶段判定见 `docs/process/harness-process-tailoring.md`。
+- 外部前端 / 后端实现仓库的接入和跨仓库切片绑定见 `docs/process/implementation-repo-integration.md`。
+- 阶段结束的 Issue 同步与 Git checkpoint 记录可使用 `docs/process/templates/stage-checkpoint-template.md`。
+
+## 8 个主阶段
+
+| 主阶段 | 目标 | 必须产物 | 条件产物 | 下一门禁 |
+|---|---|---|---|---|
+| 1. 入口分诊 | 判断任务类型、风险等级、最近可信阶段和最小技能集 | 分诊结论或 issue 备注 | `yss-product-lifecycle` 路由结果、Git checkpoint 判断 | 是否需要 Discovery / PRD / API / 架构 / Issue |
+| 2. 机会与 Discovery | 收敛用户、痛点、为什么现在做、MVP、非目标、成功标准、产品功能指引和下游影响信号 | `docs/discovery/<feature>-discovery.md` 或等价说明 | `competitive-intelligence` 竞品情报、竞品矩阵、机会说明、产品功能指引、下游影响清单、市场分析、用户痛点文档 | 是否足以进入业务架构和 PRD |
+| 3. 业务 / PRD / 功能架构 | 明确产品边界、用户旅程、功能域、模块边界、优先级和验收标准 | `docs/requirements/<feature>-prd.md` | `grill-with-docs` 澄清记录、业务架构、功能架构、CONTEXT 术语回填 | PRD Review / 产品设计准备度 |
+| 4. 产品设计与需求冻结 | 对 UI、页面流、状态矩阵、异常路径和 PRD 回填做闭环 | 有 UI 时：交互说明和原型评审结论；无 UI 时：需求冻结记录 | 状态矩阵、页面地图、原型链接 | PRD 校准 / 工程契约与架构设计准备度 |
+| 5. 系统 / 数据架构与工程契约设计审查 | 合并 API 影响分析、契约草案、工程基线、系统架构、数据架构和 Design Review；Draft 仅用于评审，Freeze 前不得作为实现或生成客户端契约 | 系统概要设计或等价架构记录；Design Review 结论；有 API 时：API 影响记录和契约草案 / review-only OpenAPI Draft；有后端结构影响时：工程基线审查 | OpenAPI Draft Review、OpenSpec-style Spec Delta、工程基线审查、无 API 影响记录、数据架构、ADR、架构图 | OpenAPI Freeze 准备度 |
+| 6. 契约冻结与 Issue formalization | 冻结契约并把交付范围转成可执行 Issue，并明确受影响前后端工程是否已存在 | OpenAPI Freeze 记录或无 API 影响记录；垂直切片 Issue 入口 | `to-issues` 输出、实施路由记录、实现仓库 / 脚手架判定、Issue tracker 同步 | 垂直切片准备度 |
+| 7. 垂直切片与 TDD 实现 | 将冻结范围拆成端到端切片并按 TDD 实现 | 垂直切片 Issue、实施计划、Build Architecture Checklist、测试 / 验证记录 | YSS skill routing、前后端脚手架初始化记录、`implement` / `tdd` 证据、`code-review` 报告、清理简化记录、Architecture Re-check | Fresh verification / Release Review |
+| 8. 验证发布与复盘 | 保留发布、实施、验证和经验沉淀证据 | fresh verification、发布说明、复盘记录 | 实施记录、用户手册、AGENTS / CONTEXT / ADR 更新 | 下一轮规划 |
+
+## 21 个门禁 / 职责点映射
+
+| 原职责点 | 归属主阶段 | 产物要求 | 是否必需 |
+|---|---|---|---|
+| 0. 入口分诊 | 1. 入口分诊 | 分诊结论、最小技能集、最近可信阶段 | 必需 |
+| 1. 机会探索 | 2. 机会与 Discovery | 机会输入、MVP 边界、非目标范围 | 新产品 / 新模块必需 |
+| 2. 业务架构 | 3. 业务 / PRD / 功能架构 | 业务架构或 PRD 中等价章节 | 新产品 / 新业务域必需 |
+| 3. 需求澄清 | 3. 业务 / PRD / 功能架构 | `grill-with-docs` 结论或等价澄清记录 | 新功能 / 较大改动必需 |
+| 4. 需求基线 / 功能架构 | 3. 业务 / PRD / 功能架构 | PRD、功能域、模块边界、验收标准 | 新功能 / 较大改动必需 |
+| 5. 页面 / 原型 / 交互设计 | 4. 产品设计与需求冻结 | 交互说明、页面清单、状态矩阵 | 有 UI 时必需 |
+| 6. 原型评审 | 4. 产品设计与需求冻结 | Prototype Review 结论 | 有 UI 时必需 |
+| 7. PRD 校准 / 需求冻结 | 4. 产品设计与需求冻结 | 需求冻结记录或校准后的 PRD | 必需；无 UI 可轻量化 |
+| 8. API 影响分析 / 契约草案 | 5. 系统 / 数据架构与工程契约设计审查 | API 影响记录、契约草案 / OpenAPI Draft 或无 API 影响记录；Draft 在 Freeze 前仅可评审；中高风险变更补 OpenSpec-style Spec Delta | 有 API 影响时必需；Spec Delta 条件必需 |
+| 9. 工程基线 | 5. 系统 / 数据架构与工程契约设计审查 | 工程基线 / YSS DDD Review | 新服务 / 新模块 / 后端结构变化时必需 |
+| 10. 系统总体架构 / 方案设计 | 5. 系统 / 数据架构与工程契约设计审查 | 系统概要设计、ADR 候选 | 服务边界、集成、NFR、运维变化时必需 |
+| 11. 数据架构 / 元模型设计 | 5. 系统 / 数据架构与工程契约设计审查 | 数据架构 | 持久化、元数据、版本、血缘、查询 / 搜索变化时必需 |
+| 12. 设计审查 | 5. 系统 / 数据架构与工程契约设计审查 | Design Review 结论 | 进入 Freeze 前必需 |
+| 13. 契约冻结 | 6. 契约冻结与 Issue formalization | OpenAPI Freeze 记录或无 API 影响记录 | 有 API 影响时必需；无 API 时记录结论 |
+| 14. Issue formalization | 6. 契约冻结与 Issue formalization | 垂直切片 Issue、`to-issues` 输出或等价任务记录，并记录受影响前后端工程存在性判定与脚手架初始化决策 | 正式垂直切片前必需 |
+| 15. 实施计划 | 7. 垂直切片与 TDD 实现 | 垂直切片 Issue、实施计划、Build Architecture Checklist、回滚点，以及缺失前后端工程时的脚手架初始化记录 | 正式开发前必需 |
+| 16. 开发实现 | 7. 垂直切片与 TDD 实现 | TDD 证据、代码实现、契约对齐、架构约束回勾 | 代码变更时必需 |
+| 17. 独立审查 | 7. 垂直切片与 TDD 实现 | Review Report、`code-review` 结论或 MR / PR 评论 | 合并 / 发布前必需 |
+| 18. 清理简化 | 7. 垂直切片与 TDD 实现 | 清理项记录或 review 建议 | 有复用 / 可读性 / 性能问题时执行 |
+| 19. 验证发布 | 8. 验证发布与复盘 | fresh verification、发布说明、实施 / 回滚说明 | 发布 / 可合并结论前必需 |
+| 20. 复盘沉淀 | 8. 验证发布与复盘 | 复盘、CONTEXT / AGENTS / ADR 更新 | 发布后或阶段性复盘时必需 |
+
+## 模板索引
+
+| 产物 | 推荐路径 | 模板 |
+|---|---|---|
+| Discovery 收敛 | `docs/discovery/<feature>-discovery.md` | `docs/discovery/templates/discovery-template.md` |
+| 竞品情报简报 | `docs/discovery/reports/<feature>-competitive-intelligence.md` | `competitive-intelligence` 输出格式 |
+| 竞品矩阵 | `docs/discovery/reports/<feature>-competitive-matrix.md` | `docs/discovery/templates/competitive-matrix-template.md` |
+| PRD | `docs/requirements/<feature>-prd.md` | `docs/templates/prd-template.md` |
+| 业务架构 | `docs/architecture/<feature>-business-architecture.md` | `docs/architecture/templates/business-architecture-template.md` |
+| 功能架构 | `docs/architecture/<feature>-functional-architecture.md` | `docs/architecture/templates/functional-architecture-template.md` |
+| 产品总体设计 | `docs/design/<feature>-product-overview-design.md` | `docs/design/templates/product-overview-design-template.md` |
+| 交互说明 | `docs/design/<feature>-interaction-spec.md` | `docs/design/templates/interaction-spec-template.md` |
+| 状态矩阵 | `docs/design/<feature>-state-matrix.md` | `docs/design/templates/state-matrix-template.md` |
+| 原型评审 | `docs/design/<feature>-prototype-review.md` | `docs/design/templates/prototype-review-checklist.md` |
+| 需求冻结 | `docs/requirements/<feature>-requirement-freeze.md` | `docs/templates/requirement-freeze-template.md` |
+| API 影响分析 / 契约草案 / OpenAPI Draft | API 影响记录、issue note 或 `docs/api/specs/<feature>.yaml` | `docs/templates/openapi-spec-template.yaml` |
+| OpenSpec-style Spec Delta | `docs/specs/<feature>-spec-delta.md` | `docs/templates/spec-delta-template.md` |
+| OpenAPI Draft Review | `docs/api/<feature>-openapi-draft-review.md` | `docs/api/templates/openapi-draft-review-checklist.md` |
+| 工程基线审查 | `docs/architecture/<feature>-engineering-baseline-review.md` | `docs/architecture/templates/engineering-baseline-review-template.md` |
+| 系统概要设计 | `docs/architecture/<feature>-system-overview-design.md` | `docs/architecture/templates/system-overview-design-template.md` |
+| 数据架构 | `docs/architecture/<feature>-data-architecture.md` | `docs/architecture/templates/data-architecture-template.md` |
+| 架构 / 设计审查 | `docs/architecture/<feature>-architecture-review.md` | `docs/architecture/templates/architecture-review-checklist.md` |
+| OpenAPI Freeze | `docs/api/<feature>-openapi-freeze.md` | `docs/api/templates/openapi-freeze-record-template.md` |
+| 垂直切片 Issue | GitLab / GitHub Issues 或 `docs/requirements/issues/<feature>-slice.md` | `docs/templates/vertical-slice-issue-template.md` |
+| 实现路由 | `docs/requirements/issues/<feature>-implementation-routing.md` | `docs/templates/implementation-routing-template.md` |
+| 实现仓库登记 | 实施计划 / Issue / `docs/implementation/<feature>-repo-registry.md` | `docs/templates/implementation-repo-registry-template.md` |
+| 跨仓库切片记录 | 垂直切片 Issue / `docs/implementation/<feature>-cross-repo-slice.md` | `docs/templates/cross-repo-slice-template.md` |
+| Build Architecture Checklist | `docs/implementation/<feature>-build-architecture-checklist.md` 或实施计划 / Issue | `docs/templates/build-architecture-checklist-template.md` |
+| 审查报告 | MR / PR 评论或 `docs/requirements/issues/<feature>-review.md` | `docs/templates/review-report-template.md` |
+| Fresh verification | issue / MR / release note 或 `docs/testing/<feature>-verification.md` | `docs/templates/verification-record-template.md` |
+| 发布说明 | `docs/releases/<version>-<feature>.md` | `docs/templates/release-note-template.md` |
+| 实施记录 | `docs/implementation/<feature>-rollout.md` | `docs/templates/implementation-plan-template.md` |
+| 用户手册 | `docs/user-guide/<feature>.md` | `docs/user-guide/templates/user-guide-template.md` |
+| 复盘 | `docs/process/sprint-retros/<date>-<topic>.md` | `docs/templates/retro-report-template.md` |
+| Harness 工作单元映射 | `docs/process/harness-work-unit-map.md` | 直接维护 |
+| Harness 流程裁剪 | `docs/process/harness-process-tailoring.md` | 直接维护 |
+| 阶段 checkpoint | Issue / MR / PR 评论或阶段文档 | `docs/process/templates/stage-checkpoint-template.md` |
+
+## 执行规则
+
+- 每次开始前先判断任务类型和最近可信阶段；不要把小文案、局部样式、单点 Bug 套进完整新功能流程。
+- 判断流程裁剪时先引用 `docs/process/harness-process-tailoring.md`；该指南只能减少不相关产物，不能裁剪关键追踪关系、安全人审或 fresh verification。
+- Discovery 可以通过 `competitive-intelligence` 形成竞品情报、竞品矩阵、机会说明、产品功能指引和下游影响清单，但这些只是 PRD、功能架构、产品设计、API 和架构阶段的输入，不冻结后续设计。
+- API 相关阶段必须区分“契约草案 / OpenAPI Draft”和“OpenAPI Freeze”：Draft 仅可用于评审和架构反审，Freeze 前不得作为前后端实现或生成客户端的稳定契约。
+- OpenSpec-style Spec Delta 只用于表达行为差异、验收场景和测试映射；它不替代 PRD、OpenAPI、Design Review 或垂直切片 Issue，也不要求创建额外变更目录。
+- API、权限、状态机、数据模型、跨端、新模块或高风险变更应在 Design Review / OpenAPI Freeze 前补充 Spec Delta；小文案、局部样式、配置微调和低风险 Bug 默认跳过。
+- OpenAPI Freeze 后直接进入 `to-issues` 或等价垂直切片拆分，不再要求额外变更目录或状态文件。
+- 进入实现前，必须先判断当前切片受影响的 frontend / backend 运行时代码工程是否已经存在且可复用；若不存在、不可复用或目录约定缺失，必须先记录原因并路由 `yss-ddd-scaffold-generator` 或 `yss-frontend-scaffold-generator` 初始化，再进入业务实现。
+- 进入垂直切片实现前，必须将系统架构、数据架构、ADR、工程基线、OpenAPI Freeze 结论和安全红线转译成 `Build Architecture Checklist`。
+- 每个垂直切片完成时必须回勾 `Build Architecture Checklist`，用 `implemented`、`seam-deferred`、`drift`、`violation` 或 `not-applicable` 标记状态，并提供证据或补齐落点。`drift` 触发 Architecture Re-check；`violation` 阻断继续 build。
+- Repository / Gateway / 持久化、权限 / 授权、审计、SQL / DDL / 迁移、文件上传下载、版本快照 / 元数据 / 血缘 / 查询索引、部署 / 回滚 / 运维约束，必须在 checklist 中逐项绑定切片和人审要求。
+- 每个主阶段结束都要做 issue tracker 同步：按用户明确选择或当前仓库主远端路由到 GitLab / GitHub，更新对应 PRD、垂直切片 Issue、里程碑或评论，记录阶段状态、完成范围、验证证据、阻塞项、下一步和安全人审点。
+- 每个主阶段结束都要做 Git checkpoint 判断：列出变更产物、Issue 同步状态、排除无关脏文件，并说明提交 / 推送 / 暂缓原因。
+- 触碰安全红线时，模板中必须标记 `TODO-HUMAN-REVIEW`，Agent 只能生成草案。
+- 任何“完成 / 可合并 / 可发布”结论必须有 fresh verification 证据。

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

@@ -0,0 +1,50 @@
+# Skill 沉淀治理规则
+
+本文定义何时把重复动作沉淀为模板、脚本或 Skill。目标是让 Skill 成为可复用能力单元，而不是零散提示词集合。
+
+本仓库默认使用 Matt Pocock Engineering Skills 承接通用工程流程，使用 YSS skills 承接领域工程规范。新增技能前必须先确认是否已有 Matt / YSS skill、模板或脚本覆盖。
+
+## 沉淀触发条件
+
+同一类人工提示、文档结构、检查动作或执行步骤重复出现 3 次以上时，必须进入沉淀评估。评估不等于一定创建 Skill。
+
+## 决策路径
+
+| 场景 | 推荐沉淀方式 | 判断标准 |
+|---|---|---|
+| 只是固定字段和格式 | 模板 | 输入输出简单，不需要复杂判断 |
+| 需要稳定检查但不需要生成大量内容 | checklist | 人仍然负责放行判断 |
+| 规则明确、可机器判断 | 脚本 | 有确定输入、输出和失败条件 |
+| 需要一组可复用步骤、上下文规则和产物规范 | Skill | 多次复用，且普通模板无法约束执行质量 |
+| 属于需求澄清、PRD、Issue、TDD、诊断、审查或架构治理 | 优先复用 Matt skill | 与 `grill-with-docs`、`to-prd`、`to-issues`、`implement`、`tdd`、`diagnosing-bugs`、`code-review`、`codebase-design` 等职责重合 |
+| 属于 YSS DDD、UI、OpenAPI、Repository、Controller、DTO 或组件规范 | 优先复用 YSS skill | 与现有 YSS 专项规范强相关 |
+| 低频、一次性或高度依赖人工判断 | 不沉淀为 Skill | 记录在复盘或 checklist 即可 |
+
+## Skill 候选评估表
+
+| 字段 | 说明 |
+|---|---|
+| 候选名称 | 使用动词或明确能力名 |
+| 触发场景 | 什么时候必须使用 |
+| 输入 | 需要哪些文档、代码、Issue 或上下文 |
+| 输出 | 生成什么产物或判断 |
+| 质量门禁 | 如何判断执行合格 |
+| 是否已有模板 / 脚本 | 避免重复建设 |
+| 是否已有 Matt / YSS skill | 避免重复建设 |
+| 不适用场景 | 明确不要使用的情况 |
+
+## 不封装 Skill 的情况
+
+- 只出现 1 到 2 次，尚未证明复用价值。
+- 动作结果高度依赖个人经验或业务拍板。
+- 只需要复制一个模板即可完成。
+- 已经有现成 Skill、脚本或生命周期门禁覆盖。
+- 会绕过安全红线、人审或 fresh verification。
+
+## 治理回流
+
+- 试点复盘时记录新增、修改、合并或废弃 Skill 的候选。
+- 只有稳定语言写入 `CONTEXT.md`。
+- 只有难回滚、非显而易见且有真实取舍的治理决策写入 ADR。
+- Skill 更新后必须同步相关模板、触发规则和用户指南。
+- Matt skills 升级必须记录来源提交、变更摘要和验证结果。