create-yss-spec 2.1.11 → 2.1.14

package/template/wiki/raw/CONTEXT.md

@@ -1,46 +1,80 @@
 # 领域上下文
 
-本文档是项目的领域词汇表，只记录业务语言和协作概念，不记录实现细节、计划草稿或架构说明。
-
-## 术语表
-
-| 术语 | 含义 | 避免 / 备注 |
-|---|---|---|
-| Agent | 执行特定工作流步骤的 AI 协作者。 | 不要与人工审查者混用。 |
-| Agent 入口规则 | Agent 启动任务时必须先遵守的全局路由、硬门禁和禁止事项。 | 不作为 YSS 后端、前端或其他专项编码规范的完整手册。 |
-| 标准文档语言 | 面向业务、产品、架构、实施、审查、发布和复盘的持久化文档所使用的默认语言。 | 统一使用简体中文；英文专有名词、代码标识、API 路径、schema、文件名和协议 metadata 保持原样。 |
-| Matt Engineering Skills | 来自 `mattpocock/skills` 的轻量工程流程技能集合。 | 用于澄清、Spec、Ticket、实现、TDD、诊断、审查和架构治理，不替代 YSS 专项规范。 |
-| YSS skills | 本项目内置的 YSS 工程规范技能。 | 用于 DDD、UI、OpenAPI、Repository、Controller、DTO、组件和编码规范。 |
-| 技能投影 | 从权威共享技能生成、供特定 Agent root 加载的同步副本。 | 投影不是独立维护的技能源，不应在各 Agent root 中分别修改。 |
-| Spec | 记录用户问题、解决方案、用户故事、关键决策、验收标准和测试 seam 的产品研发规格。 | 新资产统一使用 Spec；旧规格称谓只在迁移记录中保留。 |
-| Spec Delta | 记录相对于既有冻结 Spec 基线的 `ADDED / MODIFIED / REMOVED` 行为、验收场景和测试映射。 | 不用于全新产品或全新模块，也不替代完整 Spec、OpenAPI 或架构资产。 |
-| Ticket | 在追踪平台上承载功能生命周期或可实现工作单元的通用追踪对象。 | GitHub Issues / GitLab Issues 是具体平台对象名称；领域资产统一称为 Ticket。 |
-| 功能父 Ticket | 汇总一个功能从 Spec 到契约冻结的阶段状态、资产链接、审查结论和阻塞项的 Ticket。 | 不作为 Agent 直接实现的垂直切片。 |
-| 垂直切片 Ticket | 契约冻结后生成的可独立验证实现单元，记录范围、阻塞关系、验收标准和验证证据。 | 只有通过必要门禁并具备直接实现条件时才能标记 `ready-for-agent`。 |
-| `ready-for-human` | 表示 Spec、设计、契约草案或其他资产仍需人工审查或确认的流程状态。 | 此状态不表示可以直接进入实现。 |
-| `ready-for-agent` | 表示垂直切片已通过必要门禁并具备直接实现条件的流程状态。 | 不得用于 Spec 初稿、原型、OpenAPI Draft 或其他未冻结资产。 |
-| OpenAPI Draft | review-only 的 OpenAPI 3.1 契约草案。 | Freeze 前不得作为前后端稳定实现契约。 |
-| OpenAPI Freeze | 已通过评审、可作为前后端实现和契约测试输入的 OpenAPI 3.1 契约。 | Freeze 后变更必须回到 API 影响分析和设计审查。 |
-| UI 影响 | 会改变用户可见页面、导航、交互流程、状态呈现或权限体验的功能影响。 | 纯后端、API、批处理或数据变更不自动构成 UI 影响。 |
-| 产品设计影响 | UI 变化触及主流程、导航、权限体验、异常 / 恢复状态、状态流转或 API 反推，需要页面流、状态矩阵和原型校准。 | 文案、token、颜色、间距和无行为变化的孤立视觉修复属于 UI 影响，但不自动构成产品设计影响。 |
-| 高保真 HTML 原型 | 低保真原型评审通过后，用于在浏览器中审查真实视觉密度、交互状态和页面流的产品设计资产。 | 不等同于生产前端实现，也不替代 OpenAPI、Spec 校准或垂直切片。 |
-| 垂直切片（Vertical Slice） | 贯穿所有受影响层、可独立验证的窄功能路径。 | 优先使用垂直切片，避免只按层拆分的横向任务。 |
-| Slice Implementation Contract | 阶段 7 进入实现前，由 `yss-router` 根据冻结资产和垂直切片编译、再由生命周期编排器批准的实现合同，包含 Common、Frontend、Backend、Contract 和 Cross-repo 子合同。 | Router 只能生成草案，不能自行批准、设置 `ready-for-agent` 或宣布完成；Backend 子合同仍保留额外强约束。 |
-| YSS Skill Execution Result | YSS 专项 skill 完成工作单元后返回的结构化执行证据，记录合同版本、变更文件、证据文件、实际验证、延期 seam、偏离和新增影响。 | 实现者自报 `implemented` 不构成最终通过，必须由 Router、生命周期编排器和独立 Reviewer 复核。 |
-| ADR | 架构决策记录，用于沉淀难以回滚、非显而易见且存在真实取舍的技术决策。 | 常规实现选择不要写 ADR。 |
-| Fresh Verification | 完成前重新执行的验证证据，包括测试命令、契约校验、关键路径检查或人工审查结论。 | 不等同于“之前跑过”或实现者自述。 |
-| 测试质量基线 | 项目实例明确采纳的覆盖率阈值、关键流程清单和受控例外。 | 模板推荐值本身不构成可执行门禁；未定义关键流程时，不得声称其 E2E 覆盖率达到 100%。 |
-| 条件强制门禁 | 只有当影响面命中触发条件时才必须完成的生命周期审查点。 | 未触发时记录 `not-applicable` 及原因，不生成空文档；不要理解为所有任务默认执行全部门禁。 |
-| 单一事实来源（Single Source of Truth） | 对某一类流程事实拥有唯一定义权的权威资产。 | 其他资产只引用或解释，不重复定义同一规则。 |
-| 流程模板资产 | 可被不同项目复用的文档模板、技能说明、校验脚本、流程规范和目录占位文件。 | 不包含某个具体产品的 Spec、设计、OpenAPI 或 Ticket。 |
-| 模板维护流程 | 用于评估影响、修改权威资产、同步投影、执行压力验证并审查模板演进的工作流。 | 面向模板源仓库，不默认生成具体产品的 Spec、原型、OpenAPI 或垂直切片 Ticket。 |
-| 模板发布门禁 | 模板源发布前必须通过的结构、技能同步、流程语义和压力场景验证集合。 | 不等同于只检查文件存在、Markdown 链接或 YAML 语法。 |
-| Harness 工程 | 串联研发生命周期阶段、门禁、产物、Agent/Skill 编排和追踪证据的工程化治理载体。 | 不等同于单个 CI 流水线或零散提示词集合。 |
-| 研发管理仓库 | 承载 Spec、OpenAPI、架构、Ticket、验证、发布和复盘等研发管理资产的仓库。 | 不等同于前端 / 后端代码 monorepo。 |
-| 实现仓库 | 承载前端、后端或其他运行时代码及其 Git、CI、MR / PR、测试命令和发布流水线的仓库。 | 不要把实现仓库的源码所有权混入研发管理仓库。 |
-| 跨仓库契约变更 | 需要两个或多个独立仓库协同实现、验证和按顺序发布的共享契约变化。 | 任一参与仓库未完成契约对齐和集成验证时，不得单独声称整体可发布。 |
-| 模板源仓库（`template-source`） | 承载 `yss-spec-project-template` 权威模板资产及其演进规则的仓库身份。 | 只管理可复用模板，不承载某个具体产品的研发生命周期资产。 |
-| 模板实例仓库（`project-instance`） | 由模板初始化后生成、承载某个具体产品研发生命周期资产的仓库身份。 | 不作为通用流程模板的权威来源。 |
-| 仓库身份清单 | 显式声明仓库身份和清单结构版本的机器可读资产。 | 不承载项目名称、团队规模、Tracker 或其他易变业务配置。 |
+本文档是项目的领域词汇表，只记录稳定业务语言和协作概念，不记录实现细节、计划草稿或架构说明。
+
+`英文标识` 是 PascalCase 词干，不是英语释义。`## 业务术语` 必须填写该列；`## 流程术语` 填 `—`。代码类型名、字段名和契约 property 由该词干变形：类名 = 词干 + YSS 工程后缀；字段与 JSON property 为 camelCase；数据库列为 snake_case；枚举常量为 UPPER_SNAKE。工程后缀以 YSS skill 和当前工程惯例为准，不作为领域词写入本表。JSON 与 Java 字段不一致时，以 DTO wire shape / OpenAPI 为准，不在本表另开列。改中文术语或英文标识都是统一语言变更，必须先回写本表。`避免 / 备注` 同时记录禁用中文和禁用英文别名。
 
 只有在计划、分诊、调试或架构讨论中明确沉淀出稳定语言时，才新增术语。
+
+## 流程术语
+
+模板源与生命周期协作概念放在本节。`英文标识` 填 `—`，不回溯补译。
+
+| 术语 | 含义 | 英文标识 | 避免 / 备注 |
+|---|---|---|---|
+| Agent | 执行特定工作流步骤的 AI 协作者。 | — | 不要与人工审查者混用。 |
+| Agent 入口规则 | Agent 启动任务时必须先遵守的全局路由、硬门禁和禁止事项。 | — | 不作为 YSS 后端、前端或其他专项编码规范的完整手册。 |
+| 标准文档语言 | 面向业务、产品、架构、实施、审查、发布和复盘的持久化文档所使用的默认语言。 | — | 统一使用简体中文；英文专有名词、代码标识、API 路径、schema、文件名和协议 metadata 保持原样。 |
+| Matt Engineering Skills | 来自 `mattpocock/skills` 的轻量工程流程技能集合。 | — | 用于澄清、Spec、Ticket、实现、TDD、诊断、审查和架构治理，不替代 YSS 专项规范。 |
+| 上游技能基线 | 从外部技能源锁定的可追溯 revision 及其未经项目适配的原始内容。 | — | 不等同于项目当前实际生效的 skill；上游更新不得直接覆盖 YSS 适配。 |
+| YSS 技能适配 | 在上游技能基线之上，为 YSS 仓库身份、门禁、状态、授权和专项规范保留的可追溯差异。 | — | 必须同时保留上游内容哈希、有效内容哈希和适配依据，不作无记录的直接 fork。 |
+| YSS skills | 本项目内置的 YSS 工程规范技能。 | — | 用于 DDD、UI、OpenAPI、Repository、Controller、DTO、组件和编码规范。 |
+| 技能投影 | 从权威共享技能生成、供特定 Agent root 加载的同步副本。 | — | 投影不是独立维护的技能源，不应在各 Agent root 中分别修改。 |
+| Spec | 记录用户问题、解决方案、用户故事、关键决策、验收标准和测试 seam 的产品研发规格。 | — | 新资产统一使用 Spec；旧规格称谓只在迁移记录中保留。 |
+| Spec Delta | 记录相对于既有冻结 Spec 基线的 `ADDED / MODIFIED / REMOVED` 行为、验收场景和测试映射。 | — | 不用于全新产品或全新模块，也不替代完整 Spec、OpenAPI 或架构资产。 |
+| Ticket | 在追踪平台上承载功能生命周期或可实现工作单元的通用追踪对象。 | — | GitHub Issues / GitLab Issues 是具体平台对象名称；领域资产统一称为 Ticket。 |
+| 功能父 Ticket | 汇总一个功能从 Spec 到契约冻结的阶段状态、资产链接、审查结论和阻塞项的 Ticket。 | — | 不作为 Agent 直接实现的垂直切片。 |
+| 垂直切片 Ticket | 契约冻结后生成的可独立验证实现单元，记录范围、阻塞关系、验收标准和验证证据。 | — | 只有通过必要门禁并具备直接实现条件时才能标记 `ready-for-agent`。 |
+| `ready-for-human` | 表示 Spec、设计、契约草案或其他资产仍需人工审查或确认的流程状态。 | — | 此状态不表示可以直接进入实现。 |
+| `ready-for-agent` | 表示垂直切片已通过必要门禁并具备直接实现条件的流程状态。 | — | 不得用于 Spec 初稿、原型、OpenAPI Draft 或其他未冻结资产。 |
+| OpenAPI Draft | review-only 的 OpenAPI 3.1 契约草案。 | — | Freeze 前不得作为前后端稳定实现契约。 |
+| OpenAPI Freeze | 已通过评审、可作为前后端实现和契约测试输入的 OpenAPI 3.1 契约。 | — | Freeze 后变更必须回到 API 影响分析和设计审查。 |
+| YSS 响应包装 | 对外 API 使用 `Result` 基础字段及 `SingleResult`、`MultiResult`、`PageResult` 表达单对象、非分页列表和分页查询结果的统一返回结构。 | — | Java 泛型记法是语义简称；公开 schema 必须落成具体 endpoint wire shape。 |
+| DTO wire shape | DTO 在 HTTP/JSON 边界实际暴露的字段、类型、可空性和方向性；与 Java 字段、getter 或内部协作字段区分。 | — | 以目标 mapper / contract evidence 为准，不从 getter、Lombok 或 `@JsonIgnore` 机械推断。 |
+| UI 影响 | 会改变用户可见页面、导航、交互流程、状态呈现或权限体验的功能影响。 | — | 纯后端、API、批处理或数据变更不自动构成 UI 影响。 |
+| 产品设计影响 | UI 变化触及主流程、导航、权限体验、异常 / 恢复状态、状态流转或 API 反推，需要页面流、状态矩阵和原型校准。 | — | 文案、token、颜色、间距和无行为变化的孤立视觉修复属于 UI 影响，但不自动构成产品设计影响。 |
+| 高保真 HTML 原型 | 低保真原型评审通过后，用于在浏览器中审查真实视觉密度、交互状态和页面流的产品设计资产。 | — | 不等同于生产前端实现，也不替代 OpenAPI、Spec 校准或垂直切片。 |
+| Visual Baseline Contract | 为生产前端还原冻结页面、视口、交互状态、参考图像和允许差异的可验收合同。 | — | 不是仅有一张原型截图或绝对像素匹配；每个基线必须可定位到同一视口和同一状态复验。 |
+| 垂直切片（Vertical Slice） | 贯穿所有受影响层、可独立验证的窄功能路径。 | — | 优先使用垂直切片，避免只按层拆分的横向任务。 |
+| Slice Implementation Contract | 阶段 7 进入实现前，由 `yss-router` 根据冻结资产和垂直切片编译、再由生命周期编排器批准的实现合同，包含 Common、Frontend、Backend、Contract 和 Cross-repo 子合同。 | — | Router 只能生成草案，不能自行批准、设置 `ready-for-agent` 或宣布完成；Backend 子合同仍保留额外强约束。 |
+| YSS Skill Execution Result | YSS 专项 skill 完成工作单元后返回的结构化执行证据，记录合同版本、变更文件、证据文件、实际验证、延期 seam、偏离和新增影响。 | — | 实现者自报 `implemented` 不构成最终通过，必须由 Router、生命周期编排器和独立 Reviewer 复核。 |
+| ADR | 架构决策记录，用于沉淀难以回滚、非显而易见且存在真实取舍的技术决策。 | — | 常规实现选择不要写 ADR。 |
+| Fresh Verification | 完成前重新执行的验证证据，包括测试命令、契约校验、关键路径检查或人工审查结论。 | — | 不等同于“之前跑过”或实现者自述。 |
+| 实现验证命令 | 前端测试 / 构建优先 `pnpm`，后端校验 / 测试 / 编译优先 `./mvnw`。 | — | 不要默认 `npm`、`yarn` 或裸 `mvn`；仓库确实缺少 pnpm 或 Maven Wrapper 时记受控例外。 |
+| 测试质量基线 | 项目实例明确采纳的覆盖率阈值、关键流程清单和受控例外。 | — | 模板推荐值本身不构成可执行门禁；未定义关键流程时，不得声称其 E2E 覆盖率达到 100%。 |
+| 主阶段 | 对相邻研发目标、工作单元和退出条件的粗粒度生命周期分组。 | — | 不等同于门禁编号，也不因增加门禁而自动增加主阶段。 |
+| 生命周期门禁（条件强制门禁） | 只有当影响面命中触发条件时才必须裁决的生命周期审查点。 | — | 未触发时记录 `not-applicable` 及原因，不生成空文档；门禁不是产物、工作单元或证据的统称。 |
+| 生命周期产物 | 生命周期工作单元形成并持久化、可被审查和引用的业务或工程结果。 | — | 文件存在不代表产物已经批准或仍然新鲜。 |
+| 工作单元 | 具有明确输入、输出、允许动作和完成条件的一次有界执行。 | — | 不等同于主阶段或门禁；一个主阶段可以包含多个工作单元。 |
+| 执行证据 | 用于证明工作单元结果、门禁裁决或完成结论的可读取引用和实际验证记录。 | — | 口头声明、计划执行的命令或无法解析的引用不构成执行证据。 |
+| 单一事实来源（Single Source of Truth） | 对某一类流程事实拥有唯一定义权的权威资产。 | — | 其他资产只引用或解释，不重复定义同一规则。 |
+| 流程模板资产 | 可被不同项目复用的文档模板、技能说明、校验脚本、流程规范和目录占位文件。 | — | 不包含某个具体产品的 Spec、设计、OpenAPI 或 Ticket。 |
+| 模板维护流程 | 用于评估影响、修改权威资产、同步投影、执行压力验证并审查模板演进的工作流。 | — | 面向模板源仓库，不默认生成具体产品的 Spec、原型、OpenAPI 或垂直切片 Ticket。 |
+| 模板发布门禁 | 模板源发布前必须通过的结构、技能同步、流程语义和压力场景验证集合。 | — | 不等同于只检查文件存在、Markdown 链接或 YAML 语法。 |
+| Harness 工程 | 串联研发生命周期阶段、门禁、产物、Agent/Skill 编排和追踪证据的工程化治理载体。 | — | 不等同于单个 CI 流水线或零散提示词集合。 |
+| YSS 研发操作系统 | 由生命周期控制、通用工作流、YSS 专项技能、证据反馈和技能供应链共同构成的可版本化研发治理体系。 | — | 不等同于单个主控 skill、某个 Agent 客户端或运行时代码平台。 |
+| 生命周期注册表 | 结构化定义主阶段、门禁、产物、工作单元、证据及其稳定标识和关系的机器可读权威资产。 | — | Markdown 地图、数量说明和验证 fixture 是其派生产物，不应分别维护同一结构事实。 |
+| 生命周期编排器 | 持有阶段、影响面、产物状态、门禁裁决、工作单元路由和恢复条件的研发流程控制平面。 | — | 不替代专项技能执行业务实现，也不以文件存在或执行者自述宣布完成。 |
+| 前端实现还原验证 | 证明生产前端相对冻结 Spec、交互说明、状态矩阵和高保真原型不存在未解释差异的独立验证。 | — | 不是绝对像素复刻、普通 type-check 或原型评审；UI 影响切片需覆盖关键视觉、状态、交互和工程证据。 |
+| 生命周期稳定 ID | 以对象类型命名空间和英文标识唯一指向一个生命周期对象的兼容身份。 | — | 中文名称、展示顺序和数量可以变化；已发布 ID 不得复用来表达另一种语义。 |
+| 派生产物 | 根据生命周期注册表确定性生成的结构表、数量、索引、依赖图或测试 fixture。 | — | 不承载需要人工解释的原理、取舍或实践建议，禁止脱离注册表分别维护。 |
+| 核心技能（Core Skill） | 默认可发现、负责生命周期控制或通用研发入口的稳定技能。 | — | 不包含只在特定技术影响下才需要的专项实现规则。 |
+| 专项技能（Specialist Skill） | 由 Router 根据影响面和实现合同按需选择的前端、后端、OpenAPI 或组件技能。 | — | 不作为所有任务的平级默认入口。 |
+| 试验技能 | 尚未达到项目默认支持成熟度的技能。 | — | 只在明确试验范围内使用，不进入 Router 默认技能闭包。 |
+| 显式兼容入口 | 为已有用户操作习惯保留的 user-invoked 工作流入口，写入前由生命周期编排器预检，结果回交其验收。 | — | 不是默认路径、过时别名或可以越过门禁的第二套生命周期。 |
+| 技能成熟度 | 描述技能从 `draft`、`verified`、`supported` 到 `deprecated` 的治理状态。 | — | 不等同于文件存在、已被投影或能够安装。 |
+| 技能注册表 | 记录技能身份、别名、分层、适用影响面、成熟度、默认可发现性和 Agent 运行时入口的机器可读路由资产。 | — | 不替代 `skills-lock.json` 的来源、hash 和投影完整性职责。当前 `docs/agents/yss-skill-registry.yaml` 为 `shadow`，Router 与生命周期不得按其裁剪发现面。 |
+| LLM Wiki | 由 `raw/`、`wiki/` 与 `.wiki-manifest.json` 组成的本地持久知识库。 | — | 不是 `research` 一次性笔记，也不替代权威源。`ingest` 只把用户点名的外源或已落盘研究笔记编进 IR，不改 live 权威文件。 |
+| 生态发布清单 | 关联模板 schema 与 commit、CLI 版本与快照、公开技能来源与导出 hash 的跨仓发布证据。 | — | 不要求尚未生成的仓库 commit 互相循环引用。 |
+| 研发管理仓库 | 承载 Spec、OpenAPI、架构、Ticket、验证、发布和复盘等研发管理资产的仓库。 | — | 不等同于前端 / 后端代码 monorepo。 |
+| 实现仓库 | 承载前端、后端或其他运行时代码及其 Git、CI、MR / PR、测试命令和发布流水线的仓库。 | — | 不要把实现仓库的源码所有权混入研发管理仓库。 |
+| 跨仓库契约变更 | 需要两个或多个独立仓库协同实现、验证和按顺序发布的共享契约变化。 | — | 任一参与仓库未完成契约对齐和集成验证时，不得单独声称整体可发布。 |
+| 模板源仓库（`template-source`） | 承载 `yss-spec-project-template` 权威模板资产及其演进规则的仓库身份。 | — | 只管理可复用模板，不承载某个具体产品的研发生命周期资产。 |
+| 模板实例仓库（`project-instance`） | 由模板初始化后生成、承载某个具体产品研发生命周期资产的仓库身份。 | — | 不作为通用流程模板的权威来源。 |
+| 模板实例分发面 | 模板源中应随 CLI 快照进入 `project-instance` 的共享生命周期、模板、用户指南和验证资产集合。 | — | 不包含模板源审查、研究、发布路线或源仓库专属 ADR。 |
+| 模板源治理区 | 仅供 `template-source` 使用、保存审查证据、研究记录、跨仓契约、发布路线和源仓库治理决策的归档区域。 | — | 不随 CLI 分发；不等于产品实例的研发管理资产。 |
+| 仓库身份清单 | 显式声明仓库身份和清单结构版本的机器可读资产。 | — | 不承载项目名称、团队规模、Tracker 或其他易变业务配置。 |
+
+## 业务术语
+
+`project-instance` 在本节新增产品对象。每一行必须有 PascalCase `英文标识`；缺该列视为统一语言未冻结。模板源不放虚构业务行。

package/template/wiki/raw/README.md

@@ -11,7 +11,8 @@
 ```text
 ├── .agents/                 ← 跨 Agent 共享 skills 的权威内容
 ├── .claude/                 ← Claude skills 投影与平台专属 skills
-├── .codex/                  ← Codex skills 投影与平台专属 YSS skills
+├── .codex/                  ← Codex skills 投影与平台专属 skills
+├── .cursor/                 ← Cursor skills 投影
 ├── .hermes/                 ← Hermes skills 投影与平台专属 skills
 ├── .pi/                     ← Pi skills 投影与平台专属 skills
 ├── .qoder/                  ← Qoder skills 投影与平台专属 skills
@@ -105,6 +106,7 @@ scripts/verify-template
 | [docs/user-guide/图示生成器使用指南.md](./docs/user-guide/图示生成器使用指南.md) | Excalidraw 可视化辅助 skill 使用手册 |
 | [docs/process/PDCA-SCRUM.md](./docs/process/PDCA-SCRUM.md) | PDCA × Scrum × AI |
 | [docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md](./docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md) | Matt Pocock Engineering Skills 集成与使用 |
+| [docs/process/lifecycle-registry.yaml](./docs/process/lifecycle-registry.yaml) | 生命周期结构事实源：主阶段、门禁、产物、工作单元、证据与稳定 ID |
 | [docs/process/harness-process-tailoring.md](./docs/process/harness-process-tailoring.md) | 小改动 / 中等变更 / 新模块的流程裁剪指南 |
 | [docs/process/harness-executive-blueprint.md](./docs/process/harness-executive-blueprint.md) | 面向业务方和管理者的 Harness 一页式蓝图 |
 | [docs/process/implementation-repo-integration.md](./docs/process/implementation-repo-integration.md) | 外部前端 / 后端实现仓库接入与跨仓库切片绑定 |
@@ -120,6 +122,7 @@ scripts/verify-template
 | 模板 | 用途 |
 |------|------|
 | [docs/templates/spec-template.md](./docs/templates/spec-template.md) | Spec，包含 OpenAPI 影响、测试决策、AI / 人工审查点 |
+| [docs/templates/local-parent-ticket-template.md](./docs/templates/local-parent-ticket-template.md) | Local Markdown 功能父 Ticket 与生命周期索引 |
 | [docs/templates/vertical-slice-ticket-template.md](./docs/templates/vertical-slice-ticket-template.md) | 垂直切片 Ticket |
 | [docs/templates/agent-brief-template.md](./docs/templates/agent-brief-template.md) | `triage` 产出的 Agent Brief |
 | [docs/templates/implementation-repo-registry-template.md](./docs/templates/implementation-repo-registry-template.md) | 外部实现仓库登记 |

package/template/wiki/raw/create-yss-spec-repository-mode-contract.md

@@ -0,0 +1,95 @@
+# `create-yss-spec` 接管与模板同步跨仓库契约
+
+本文定义模板源仓库与外部 `create-yss-spec` CLI 仓库之间的身份、资产边界、迁移、同步、验证和发布契约。
+
+## 契约目标
+
+- 模板源仓库保留 `repository_mode: template-source`。
+- CLI 创建或接管的产品仓库写入 `repository_mode: project-instance`。
+- CLI 只管理 manifest 声明的研发管理资产，不接管前后端运行时代码、业务目录、用户文件或 `.git`。
+- 通过模板快照和 40 位 `templateCommit` 使每次初始化、升级和回滚可追踪。
+- 新模板快照的实例门禁以 Node `>=22 <27` 运行；不得执行 `npm install`、`pnpm install` 或维护侧 vendor 构建。`scripts/vendor/` 必须随快照分发且可离线使用。
+
+## 生命周期接口
+
+### 空目录初始化
+
+初始化必须把模板身份转换为 `schema_version: 1`、`repository_mode: project-instance`，并执行目标仓库的：
+
+```bash
+scripts/sync-skills --check
+scripts/update-skill-lock --check
+scripts/verify-template
+```
+
+### 已有项目 `attach`
+
+```bash
+npx create-yss-spec@latest attach \
+  --target-dir . \
+  --project-name "项目名称" \
+  --business-domain "业务领域" \
+  --dry-run
+npx create-yss-spec@latest attach \
+  --target-dir . \
+  --project-name "项目名称" \
+  --business-domain "业务领域" \
+  --apply [--force]
+```
+
+`attach` 必须显式选择 dry-run 或 apply，已有 `.yss-template.json` 时拒绝并提示 `sync`。计划按 `missing`、`matched`、`conflict`、`unsafe` 分类；force 只能覆盖受管 conflict，不能绕过 unsafe 或迁移冲突。合法 `template-source` 可转换为 `project-instance`，合法 `project-instance` 保留并校验，非法身份在写入前阻断。
+
+### 持续同步 `sync`
+
+`sync` 只使用 CLI 包内置的模板快照。“最新”指用户执行 `npx create-yss-spec@latest` 所携带的最新已发布快照，不在运行时直接拉取模板仓库。普通同步新增缺失文件、更新 baseline 未被本地修改的文件、报告冲突和模板删除；`sync --force` 先备份再覆盖受管冲突，模板删除默认只报告。
+
+完成后必须重新执行三个模板门禁；任一门禁失败时回滚文件变更并保持旧 metadata 版本。
+
+模板把共享运行脚本从 Ruby 迁移到 Node 时，CLI 同步继续将模板删除按 `remove-report` 报告；不得静默删除既有实例的 `.rb` 文件。对新快照，CLI 必须验证公开入口、Node 版本失败信息、离线门禁和回滚均符合本契约。
+
+## metadata v2
+
+`.yss-template.json` 至少包含：
+
+```json
+{
+  "metadataSchemaVersion": 2,
+  "templateName": "create-yss-spec",
+  "cliVersion": "2.1.4",
+  "templateSource": "github:iloveZzz/yss-spec-project-template",
+  "templateCommit": "<40-char-commit>",
+  "managedFilesManifestVersion": "<manifest-hash>",
+  "managedFiles": {}
+}
+```
+
+`managedFiles` 是每个受管文件的 baseline。CLI apply 前把将被覆盖的文件保存到目标目录外的临时备份目录；验证成功后默认保留，失败按操作日志回滚，metadata 不更新。
+
+## 固定迁移规则
+
+CLI 必须遵循 [Spec / Ticket 迁移指南](../../docs/user-guide/规格与任务迁移指南.md) 的固定映射：旧 Spec / Ticket skill 和模板入口迁移为当前名称，旧规格文件、根 `.scratch/<feature>/` 迁移到当前路径；无法推断功能归属的扁平 Ticket 标记为 `unsafe` 并阻断。新旧目标内容不一致时标记 `conflict`，不得静默覆盖。
+
+## 跨仓库验收
+
+| 场景 | 必须验证 |
+|---|---|
+| 空目录初始化 | `project-instance`、metadata v2、固定 commit、六类 projection 和模板门禁 |
+| 任意已有项目 attach dry-run | 不写文件、不删除 `.git`，运行时代码和无关文件不变 |
+| attach apply | 缺失资产新增；matched 纳入 baseline；conflict 需 force；unsafe 不可 force 绕过 |
+| 旧资产迁移 | 规格 / Ticket 路径和根 scratch 安全迁移；目标冲突与扁平 Ticket fail closed |
+| sync | 新增、更新、冲突、迁移和删除报告完整；force 只作用于受管文件 |
+| post-sync | 三个门禁全部 fresh 通过；失败时文件和 metadata 回滚 |
+| Node 运行时迁移 | Node 22 / 24 下 init、attach dry-run/apply、sync 都无需安装依赖；缺失或不兼容 Node 必须 fail closed 且回滚 |
+| 遗留 Ruby | 新快照无活动 Ruby 脚本；既有实例遗留 `.rb` 仅 `remove-report`，不静默删除 |
+| 发布包 | 固定 commit 下 `npm test` 和 `npm pack --dry-run` 通过，包内含 `template.snapshot.json` |
+
+本变更只涉及模板治理和外部 CLI，不涉及 frontend、backend、OpenAPI 或运行时工程；这些范围为 `not-applicable`。
+
+## 发布顺序与阻断条件
+
+1. 模板恢复 `docs/process/*`、正式处理 `.qoder` 投影并通过 fresh verification，形成确定 commit。
+2. CLI 绑定该 commit，完成 attach / sync 跨仓库测试和独立 review。
+3. 运行固定 commit 的 `npm test`、`npm pack --dry-run`，确认包内快照和实例门禁通过。
+4. 发布 CLI `2.1.4`，并回写版本、验证证据、备份恢复路径和回滚点。
+
+模板引用仍为浮动 ref、任一共同验证失败、独立 review 未完成或打包失败时，只能声明“本仓库实现完成，跨仓库发布受阻”，不得声明整体可发布。本轮不执行 npm publish。

package/template/wiki/raw/harness-process-tailoring.md

@@ -0,0 +1,64 @@
+# Harness 流程裁剪与影响面判定
+
+本文件规定如何根据变更规模和风险选择最近可信阶段。裁剪只减少未触发的门禁，不得跳过已经命中的条件强制门禁。
+
+安全 / 权限不单独分诊。需求或冻结资产没有明确改变相关行为时不登记、不解释 `not-applicable`、不增加门禁；明确改变时只按实际 UI、API、Backend、Data、High-risk 影响复用普通流程。SQL / DDL / 迁移、上传 / 下载等技术载体继续由其数据或 API 影响决定路线，不自动升级为安全专项。
+
+## 1. 判定顺序
+
+1. 先读取 `yss-project.yaml`，非法、缺失或不支持的身份直接进入迁移检查。
+2. 判断是否为模板源维护、项目实例小改动、中等变更或全新产品 / 模块。
+3. 判断 UI、API、数据、后端、前端、跨仓库和高风险影响。
+4. 从最近可信阶段恢复；不要因为当前目录存在某类文件就猜测阶段已通过。
+
+## 2. 裁剪矩阵
+
+| 类型 | 默认入口 | 必需工作 | 可记录为 `not-applicable` |
+|---|---|---|---|
+| 模板源维护 | 影响面分析 | 修改单一事实来源、按验证与审查强度分级执行证据、必要的技能投影同步、fresh verification / review | 产品 Spec、产品设计、OpenAPI、运行时代码 |
+| 小改动 | 入口分诊 | 影响面、主 tracker 同步、fresh verification | Spec、架构、原型、切片（没有触发条件时） |
+| 中等变更 | 最近可信的 Spec / 架构阶段 | Spec、功能架构、必要工程审查、父 Ticket 和切片 | 未命中的 UI、数据或 API 门禁 |
+| 全新产品 / 模块 | Discovery | Discovery、Spec、产品总体设计、功能架构、必要设计 / 契约审查、父 Ticket 和切片 | 未命中的 UI、数据或 API 门禁 |
+| 高风险变更 | 既有冻结基线 | Spec Delta、架构 / 数据 / 工程审查、契约复核、切片和回滚设计 | 与风险证据无关的门禁 |
+
+任何裁剪都必须写明原因和证据，不生成空文档。对跨仓库变更，Harness 记录必须绑定实现仓库、分支、CI、验证命令、发布顺序和回滚点；没有前端、后端或 OpenAPI 影响时显式记录 `not-applicable`。
+
+## 3. 执行与证据
+
+同一独立执行者可以在一个连续工作单元内完成相邻的实现动作，但不能替代独立审查者。阶段证据在集中 checkpoint 回写，至少包含：范围、变更文件、受影响仓库、验证命令及结果、阻塞项、人工审查点、Ticket 状态和下一步。
+
+## 4. 模板维护验证与审查强度分级
+
+本节只适用于 `template-source` 的模板、流程规则和共享 skill 维护，不降低 `project-instance` 的 Spec、OpenAPI Freeze、垂直切片或高风险工程门禁。强度由错误逃逸损失和是否改变 Agent 行为决定，不由文件所在目录单独决定。
+
+| 强度 | 权威触发项 | 最低验证证据 | Review |
+|---|---|---|---|
+| L1 | `maintenance-intensity.yaml` 的 `levels.L1.triggers` | 至少一项与变更直接相关的实际检查 | `self-check` 或显式 `human-checkpoint` |
+| L2 | `maintenance-intensity.yaml` 的 `levels.L2.triggers`，或该策略的 `default_level` | 修改前可失败的最小反例，以及本轮 fresh verification | 一名非实施者执行 `focused-independent` 聚焦审查；结论可内联 checkpoint |
+| L3 | `maintenance-intensity.yaml` 的 `levels.L3.triggers` | 完整 RED、GREEN、REFACTOR、压力场景与本轮 fresh verification | 冻结候选后执行 `formal-independent` 正式独立审查；需要时使用完整 `code-review` |
+
+判定规则：
+
+1. 等级只由 `maintenance-intensity.yaml` 计算；未给出 trigger 时使用该策略的 `default_level`，未知 trigger 必须更新策略后才可验证。
+2. 实施者可先分级，不要求 L1/L2 预批准；发现新影响时立即更新 `escalation`、重新分级并补齐证据。
+3. 发布、合并或阶段完成时按整体候选重新判定；不得把共同改变整体语义的修改拆成多个 L1/L2 规避 L3。
+4. RED 用于证明行为差异。L1 不人为构造失败；L2 可使用已有失败、最小 fixture 或现有测试修改前失败；只有行为无法确定性表达时才运行聚焦压力场景。L3 使用 `maintaining-skills` 并执行本节定义的完整 RED、GREEN、REFACTOR 和压力场景要求。
+5. 模板发布候选固定按 L3 聚合验证，但不追溯补造每个既有 L1/L2 修改的独立 RED。
+
+每个模板维护 checkpoint 使用以下轻量合同；L1/L2 可直接写入主 Ticket 或集中 checkpoint，不要求新增独立文档：
+
+```yaml
+schema_version: 1
+intensity: L1 | L2 | L3
+classification_reason: <分级理由>
+triggers: [<可观察触发项>]
+changed_assets: [<路径或资产引用>]
+verification_evidence:
+  - kind: relevant-check | counterexample | red | green | refactor | pressure-scenario | fresh-verification | focused-independent-review | formal-independent-review
+    command: <本轮实际命令或可读取证据引用>
+    result: pass
+review_mode: self-check | human-checkpoint | focused-independent | formal-independent # L2/L3 还必须在 verification_evidence 中给出对应 review 证据引用
+escalation: none | <升级原因和原等级>
+```
+
+使用 `scripts/verify-maintenance-checkpoint <file>` 或通过 stdin 传入 YAML / JSON 做只读校验。触发项 ID 与最低等级只由 `docs/process/maintenance-intensity.yaml` 维护；校验器消费该策略。未知触发项必须先更新该权威策略和场景，不能静默接受。

package/template/wiki/raw/implementation-repo-integration.md

@@ -0,0 +1,62 @@
+# 实现仓库接入与跨仓库切片绑定
+
+本文件是 Harness 仓库连接外部实现仓库的事实源。当前 `yss-spec-project-template` 与 `create-yss-spec` 的模板接管 / 同步变更属于 Harness-only 加 release-only 影响，不创建前端、后端或运行时代码目录。
+
+## 1. 接入清单
+
+每个受影响实现仓库必须登记：仓库地址、分支、代码所有者、CI 入口、测试 / 构建命令、允许写路径、回滚点和 MR / PR。没有登记记录时，先完成 onboarding，不能用本仓库目录代替实现仓库。
+
+## 1.1 Harness 内实现项目路径策略
+
+当前 Harness 明确承载运行时代码时，统一使用以下多项目布局：
+
+```text
+apps/
+├── backend/<backend-project>/
+└── frontend/<frontend-project>/
+```
+
+- `apps/backend/` 和 `apps/frontend/` 是项目容器，不是可生成的工程项目根；后端、前端项目必须分别位于 `apps/backend/<project>/`、`apps/frontend/<project>/`，多个项目按 `<project>` 目录并列。
+- `app/backend/`、`app/frontend/` 及其所有子路径均禁止作为工程生成目标；单复数差异不能被视为等价路径。
+- `allowed_write_paths`、`expected_evidence_files` 和生成器输出位置必须能回指具体项目目录；直接放开 `apps/backend/` 或 `apps/frontend/` 属于路径策略违规。
+- 外部实现仓库不要求采用 Harness 的 `apps/` 布局，但仍必须登记该仓库内的实际项目根路径；跨仓库切片的写路径不得用本 Harness 的占位路径冒充真实路径。
+
+每个 Harness 内项目至少登记 `project_type`、`project_name`、`project_root` 和 `repository_scope`。同一 Git monorepo 下的多个项目可以共用一条仓库登记，但必须逐项目列出根路径和独立验证命令；不同 Git 仓库必须分别登记。
+
+## 1.2 前端 / 后端验证命令
+
+登记和执行测试、编译时按工程类型选择命令，不要把模板源的 Node 工具链命令套到产品运行时工程。
+
+- **frontend**：依赖安装、测试、type-check 与构建优先使用 `pnpm`（例如 `pnpm test`、`pnpm type-check`、`pnpm build`）。不要默认 `npm` 或 `yarn`。
+- **backend**：校验、测试与编译优先使用项目根 `./mvnw`（例如 `./mvnw validate`、`./mvnw test`、`./mvnw package`）。不要默认裸 `mvn`。
+- Ticket、Slice Implementation Contract、CI 和 Review 证据必须写下实际执行的上述命令。既有仓库缺少 `pnpm` 或 Maven Wrapper 时，先记录受控例外、替代命令和责任人，再执行。
+- 本模板源仓库没有产品 frontend / backend 运行时；其 Node 校验仍按 `AGENTS.md` 的 Cursor Cloud 说明使用 `pnpm --dir .template-source/tooling/node`。
+
+## 2. 影响面路由
+
+| 影响面 | 必须绑定的记录 | 本变更结论 |
+|---|---|---|
+| Harness-only | change、文档路径、压力场景、fresh verification、checkpoint | required：模板仓库、CLI 仓库 |
+| release-only | release note、发布顺序、观察信号、rollback | required：模板 commit → CLI 包 |
+| backend-only | backend repo、分支、MR / PR、CI、API 影响 | `not-applicable`：无后端运行时代码 |
+| frontend-only | frontend repo、分支、lint / type-check / build | `not-applicable`：无前端运行时代码 |
+| contract-only | OpenAPI Draft / Freeze、消费者确认 | `not-applicable`：无 OpenAPI 变化 |
+
+## 3. 本变更的跨仓库合同
+
+- 模板仓库负责 `yss-project.yaml`、流程事实源、迁移指南、技能投影、模板校验脚本和快照可发布状态。
+- CLI 仓库负责 `attach`、`sync`、受管 manifest、快照 commit、metadata、迁移计划、备份 / 回滚、端到端测试和用户说明。
+- CLI 只写研发管理资产；不得创建或覆盖前后端运行时代码，不删除目标 `.git`。
+- 模板 commit 必须是 40 位不可变提交；开发测试可通过 `YSS_SPEC_TEMPLATE_REF` 覆盖，正式发布不得跟随浮动 `main`。
+
+## 4. Fresh verification 与 checkpoint
+
+模板仓库至少执行：
+
+```bash
+scripts/sync-skills --check
+scripts/update-skill-lock --check
+scripts/verify-template
+```
+
+CLI 仓库至少执行固定 commit 的 `YSS_SPEC_TEMPLATE_REF=<pinned-commit> npm test`、`npm pack --dry-run`，并在解包后的 CLI 上验证 init、attach、sync、迁移冲突和回滚。共同发布前记录两个仓库的 commit、模板快照 hash、测试结果、独立审查结论和 rollback 路径。

package/template/wiki/raw/issue-tracker.md

@@ -0,0 +1,135 @@
+---
+tracker:
+  platform: local-markdown
+  root: docs/.scratch
+  legacy_roots:
+    - .scratch
+    - docs/requirements/tickets
+  remote_mirror: false
+---
+
+# Ticket 追踪平台：Local Markdown / GitHub / GitLab
+
+> 本文是项目 Ticket tracker 的单一事实来源。当前模板默认使用 `local-markdown`；GitHub / GitLab 只有在项目明确选择时才作为主 tracker。Git remote 是代码托管信息，不会自动覆盖显式 tracker 配置。
+
+## 当前项目配置
+
+| 字段 | 值 |
+|---|---|
+| `platform` | `local-markdown` |
+| `root` | `docs/.scratch/` |
+| `feature_layout` | 完整功能包 |
+| `remote_mirror` | 可选，默认关闭 |
+| `legacy_roots` | `.scratch/`、`docs/requirements/tickets/`（只读迁移来源） |
+
+上方 front matter 是机器可读的持久化配置；表格用于人和 Agent 阅读。初始化或迁移到 GitHub / GitLab 时，必须同时更新两处，并保留迁移记录。
+
+## 平台选择规则
+
+按以下优先级确定 Ticket tracker：
+
+1. 已写入本文件的项目配置优先；本模板默认配置为 `local-markdown`。
+2. 初始化或迁移时用户明确选择 GitHub / GitLab，则更新本文件后使用所选平台。
+3. Git remote 只用于代码托管、分支、PR / MR 和 CI；不能单独把 Ticket tracker 改成远程平台。
+4. 多个持久化配置声明不同平台时返回 `conflict`，暂停并要求迁移，不覆盖任何配置。
+5. 选定 GitHub / GitLab 但凭据或平台暂不可用时，先在 `docs/.scratch/<feature>/` 生成“待发布平台”草案；`parent-ticket.md` 保留目标平台、标记 `publication: pending` 和 `pending_publication_to`；不得自动改投另一远程平台。
+
+## Local Markdown 主 tracker
+
+Local 主 tracker 的完整功能包结构如下：
+
+```text
+docs/.scratch/<feature>/
+├── map.md
+├── discovery/
+├── spec.md
+├── spec-delta/
+├── parent-ticket.md
+├── design/
+├── api/
+├── architecture/
+├── gates/
+├── verification/
+└── issues/01-<slug>.md
+```
+
+- `parent-ticket.md` 汇总 Spec、设计、契约、门禁、阻塞边和阶段证据。
+- `issues/01-<slug>.md` 等文件是垂直切片或 Wayfinder 子 Ticket；不得把多个 Ticket 合并成一个文件。
+- 每个 Ticket 在顶部附近使用 `Status:` 记录 Matt 五态之一：`needs-triage`、`needs-info`、`ready-for-agent`、`ready-for-human`、`wontfix`。
+- 评论和对话追加在 `## Comments` 下；状态变化必须保留原因、证据引用和下一步。
+- Wayfinder 的临时子问题可以沿用 Matt 的 `Status: claimed/resolved` 工作状态；它不是交付 Ticket 的五态角色，进入正式切片前必须转换为上述五态之一。
+- Local 主 tracker 不要求远程 Ticket 存在；`ready-for-agent` 仍必须满足生命周期门禁、阻塞边关闭、实现上下文和 Slice Implementation Contract 要求。
+- YSS active 调用 `to-tickets` 时，新建垂直切片的初始 `Status:` 固定为 `ready-for-human`；只有生命周期编排器核验完整就绪公式后才能改为 `ready-for-agent`。
+- GitHub / GitLab 可以作为显式开启的镜像，在功能包中记录 URL、编号和最近同步时间；镜像失败不改变 Local 主 tracker 的权威性。
+- 根目录 `.scratch/` 与 `docs/requirements/tickets/` 是旧路径，只允许用于只读迁移检查；不再作为新 Ticket 或阶段证据的写入目录。
+- 仅发现旧路径资产时，readiness 不得进入 `ready`，必须保留 `migration_ref` 并先完成迁移；新旧路径同时存在时返回 `conflict`，不得静默覆盖或合并。
+
+## 生命周期状态同步
+
+Spec、生命周期和交付任务状态必须同步到当前主 tracker：
+
+- `local-markdown`：写入 `docs/.scratch/<feature>/`，本地文件即 Ticket 和阶段证据的权威载体。
+- `github`：使用 GitHub Issues，并在本地功能包记录 URL / 编号和最近同步时间；平台不可用时保留 `tracker: github`、`publication: pending`、`pending_publication_to: github`。
+- `gitlab`：使用 GitLab Issues，并在本地功能包记录 URL / IID 和最近同步时间；平台不可用时保留 `tracker: gitlab`、`publication: pending`、`pending_publication_to: gitlab`。
+
+所有平台都保留相同的父 Ticket、垂直切片、阻塞关系、验收标准、测试 seam、人工审查点和 `ready-for-agent` 语义。平台差异只影响存储和操作方式，不改变生命周期阶段或门禁。
+
+Git checkpoint 必须说明主 tracker、同步状态、验证命令、剩余风险和下一步。Local 主 tracker 的“已同步”表示本地功能包已更新；远程镜像只有明确启用时才需要同步。
+
+## GitLab Issues
+
+当平台为 GitLab 时，优先使用 `glab` 或项目快捷入口 `scripts/gitworks`。
+
+常用命令：
+
+- Create an issue: `glab issue create --title "..." --description "..."`
+- Read an issue: `glab issue view <iid> --comments`
+- List issues: `glab issue list --state opened`
+- Comment on an issue: `glab issue note <iid> --message "..."`
+- Apply labels: `glab issue update <iid> --label "ready-for-agent"`
+- Close an issue: `glab issue close <iid>`
+
+GitLab 相关配置和 MR / CI 工作流见 `docs/agents/gitlab-workflow-skills.md`。
+
+## GitHub Issues
+
+当平台为 GitHub 时，使用 `gh` CLI。
+
+常用命令：
+
+- Create an issue: `gh issue create --title "..." --body "..."`
+- Read an issue: `gh issue view <number> --comments`
+- List issues: `gh issue list --state open --json number,title,body,labels,comments`
+- Comment on an issue: `gh issue comment <number> --body "..."`
+- Apply or remove labels: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- Close an issue: `gh issue close <number> --comment "..."`
+
+## Local Markdown 操作
+
+- 创建或发布 Ticket：创建 `docs/.scratch/<feature>/`，按上述结构写入 `parent-ticket.md`、`spec.md` 或 `issues/NN-<slug>.md`。
+- 读取 Ticket：优先读取用户提供的 `docs/.scratch/<feature>/` 或具体 Ticket 路径；如果引用旧路径，进入迁移检查，不把旧路径当作新写入目标。
+- 更新状态：修改文件顶部的 `Status:`，并在 `## Comments` 追加原因和证据。
+- Wayfinder map：使用 `docs/.scratch/<feature>/map.md`，子 Ticket 放在 `issues/`。
+
+## Triage Surface
+
+Ticket 是默认 triage surface。MR / PR 是否纳入 triage 取决于当前平台和用户请求：
+
+- GitLab 项目：可按需读取 GitLab Issues、Merge Requests 和 Pipeline 状态。
+- GitHub 项目：可按需读取 GitHub Issues、Pull Requests 和 Actions 状态。
+- 用户只要求 issue triage 时，不主动扩展到 MR / PR。
+
+## Publishing
+
+当 skill 说 “publish to the issue tracker” 时：
+
+1. 读取本文件的 `platform` 配置。
+2. `local-markdown` 直接在 `docs/.scratch/<feature>/` 创建或更新 Ticket。
+3. `github` / `gitlab` 在对应平台创建或更新 Ticket，并在本地功能包记录 URL / 编号和最近同步时间。
+4. 选定远程平台不可用时，在 `docs/.scratch/<feature>/` 创建并标注“待发布平台”的草案；在 `parent-ticket.md` 写入 `publication: pending` 和 `pending_publication_to`，恢复后优先补同步。
+
+当 skill 说 “fetch the relevant ticket” 时：
+
+- Local Markdown：读取引用的 `docs/.scratch/<feature>/...` 文件；旧路径引用必须先经过迁移检查。
+- GitLab：使用 `glab issue view <iid> --comments`。
+- GitHub：使用 `gh issue view <number> --comments`。