create-yss-spec 3.5.6 → 3.5.8

package/template/.template-spec/plan/templates/competitive-analysis-template.md

@@ -1,20 +1,25 @@
 # [主题] 竞品深度分析报告
 
-> AI 辅助生成，人工审核补充。
-> 建议配套产物：`competitive-matrix-template.md` 用于横向功能矩阵，本模板用于深度分析和 Spec 前置输入。
-> 使用 `work-unit.plan-requirements` 时，请把稳定术语同步沉淀到 `CONTEXT.md`，只有出现难以回滚、非显而易见且存在真实取舍的决策时才新增 ADR。
+> 本文件是研究双文件的附属深度阅读材料，由 `competitive-intelligence` 执行分析、`yss-research` 持有模式和证据包，不能替代 `<slug>-research-brief.md`。
+> 配套 `competitive-matrix-template.md` 用于横向功能矩阵。默认完整矩阵与深度报告同时输出；只选报告时第 5 节包含完整比较表，同时输出时引用同目录矩阵。
+> 结论区分事实、推断、假设和建议并引用统一 Claim / Evidence。候选术语交给 `domain-modeling`，MVP、非目标和优先级交给 Plan / Spec 所有者；本研究不写入 `CONTEXT.md`、Spec、ADR、Ticket 状态或批准。
 
 ## 0. 文档信息
 
 | 项 | 内容 |
 |---|---|
 | 调研主题 | [例如：数据中台数据建模] |
-| 调研日期 | [YYYY-MM-DD] |
+| 调研截至日期 | [YYYY-MM-DD，与 `competitive_analysis.as_of` 一致] |
 | 调研对象 | [竞品 A] / [竞品 B] / [竞品 C] |
 | 调研人 | [姓名 / Agent] |
 | 资料边界 | [公开官网 / 官方文档 / 白皮书 / 访谈 / 试用环境] |
 | 可信度说明 | [哪些信息已验证，哪些信息待验证] |
-| 关联矩阵 | [链接到对应竞品功能矩阵] |
+| Profile / 模式 | [`strategy-evidence` 或 `technical-evidence`] / [`evidence-audited`；探索材料注明未审计] |
+| 输出选择 | [`report` 或 `both`] |
+| 研究简报 / 证据 | [`<slug>-research-brief.md`] / [`<slug>-evidence.yaml`] |
+| 关联矩阵 | [同时输出时链接 `<slug>-competitive-matrix.md`；仅报告时写比较表位于第 5 节] |
+| 版本 / 套餐 / 地区范围 | [以第 5 节工具管理区为准；未确认字段写 `unknown`] |
+| 审核与接收者 | [研究审核人、下游资产所有者和当前审核范围] |
 
 ## 1. 调研背景
 
@@ -56,16 +61,15 @@
 2. [机会点 2]
 3. [机会点 3]
 
-## 3. 竞品矩阵摘要
+## 3. 定位与流程摘要
 
-> 完整矩阵建议放在独立文件中，本节只保留高层摘要。
+> 本节综合定位与流程并引用 Claim；功能支持状态和比较范围以第 5 节工具管理区或其关联矩阵为准，避免另写一份功能事实表。
 
 | 维度 | [竞品 A] | [竞品 B] | [竞品 C] |
 |---|---|---|---|
 | 核心定位 | | | |
 | 目标用户 | | | |
 | 核心流程 | | | |
-| 关键能力 | | | |
 | 差异化亮点 | | | |
 | 公开资料成熟度 | 高 / 中 / 低 | 高 / 中 / 低 | 高 / 中 / 低 |
 
@@ -79,9 +83,7 @@
 
 #### 4.1.2 功能设计
 
-| 模块 | 功能点 | 说明 |
-|---|---|---|
-| [模块] | [功能点] | [功能说明] |
+[引用第 5 节比较结果的能力 ID 和 Claim，解释功能组织、对象与使用条件。不能在区外另行修改支持状态；推断说明依据。]
 
 #### 4.1.3 使用 / 落地流程
 
@@ -109,9 +111,7 @@
 
 #### 4.2.2 功能设计
 
-| 模块 | 功能点 | 说明 |
-|---|---|---|
-| [模块] | [功能点] | [功能说明] |
+[引用第 5 节比较结果的能力 ID 和 Claim，解释功能组织、对象与使用条件。不能在区外另行修改支持状态；推断说明依据。]
 
 #### 4.2.3 使用 / 落地流程
 
@@ -139,9 +139,7 @@
 
 #### 4.3.2 功能设计
 
-| 模块 | 功能点 | 说明 |
-|---|---|---|
-| [模块] | [功能点] | [功能说明] |
+[引用第 5 节比较结果的能力 ID 和 Claim，解释功能组织、对象与使用条件。不能在区外另行修改支持状态；推断说明依据。]
 
 #### 4.3.3 使用 / 落地流程
 
@@ -161,13 +159,15 @@
 - [不足或风险 1]
 - [公开资料不足处]
 
-## 5. 功能拆解
+## 5. 功能比较
 
-| 功能域 | 子功能 | [竞品 A] | [竞品 B] | [竞品 C] | 我们的建议 |
-|---|---|---|---|---|---|
-| [功能域] | [子功能] | ✅ / ⚠️ / ❌ / ❓ | ✅ / ⚠️ / ❌ / ❓ | ✅ / ⚠️ / ❌ / ❓ | P0 / P1 / P2 / 不做 |
+状态口径：✅ 明确支持（`supported`）；⚠️ 部分支持（`partial`，说明限制）；❌ 明确不支持（`absent`，须有适用范围内的已审计依据）；❓ 未知（`unknown`，说明缺口和补证计划）。资料不完整或搜索无结果不能推定部分支持或不支持。
 
-图例：✅ 明确支持；⚠️ 部分支持或资料不完整；❌ 未支持；❓ 公开资料不足。
+以下管理区由 `render-competitive-outputs.mjs` 从 `competitive_analysis` 生成：仅报告时包含完整表；同时输出矩阵时包含同目录矩阵链接和证据摘要。管理区外保留本报告分析正文，不手写第二份比较事实。
+
+<!-- YSS-COMPETITIVE:START -->
+[工具管理区：先填写结构化结果，再运行渲染器；不手填比较事实。]
+<!-- YSS-COMPETITIVE:END -->
 
 ## 6. 流程泳道图
 
@@ -192,19 +192,17 @@ flowchart LR
   U1 --> P1 --> P2 --> O1 --> P3 --> O2 --> U2
 ```
 
-## 7. 能力评分
+## 7. 能力评分（条件适用）
 
-评分说明：1 分弱，5 分强。评分应说明依据，避免只给主观分。
+默认不生成数字排名。只有用户明确要求评分时，先确认量表、能力定义、维度 / 权重和评分依据再填写；否则本节写不适用及原因。未知写“不评分”，不能作为低分或零分，不能按未知项计算综合排名。
 
-| 能力 | [竞品 A] | [竞品 B] | [竞品 C] | 评分依据 |
-|---|---:|---:|---:|---|
-| [能力 1] |  |  |  | [依据] |
-| [能力 2] |  |  |  | [依据] |
-| [能力 3] |  |  |  | [依据] |
+| 能力 ID | 已确认量表 / 权重 | [竞品 A] | [竞品 B] | [竞品 C] | Claim / 评分依据及限制 |
+|---|---|---|---|---|---|
+| [能力 ID] | [量表与确认来源] | [分值或不评分] | [分值或不评分] | [分值或不评分] | [依据与适用范围] |
 
 ## 8. Grilling 问题清单
 
-> 本节用于把竞品分析继续压成 Spec 前的产品边界。明确的问题可进入 Spec；稳定术语进入 `CONTEXT.md`；重大取舍再考虑 ADR。
+> 本节整理供 Plan / Spec 所有者继续澄清的问题。术语、产品边界和重大取舍由各自所有者确认并写入权威资产；竞品研究只回传候选与依据。
 
 1. 首要用户是谁？是否只能先服务一个角色？
 2. 第一高频场景是什么？是新建、改造、迁移、治理，还是消费？
@@ -217,12 +215,14 @@ flowchart LR
 
 ## 9. 机会点
 
-| 机会点 | 用户痛点 | 竞品现状 / 缺口 | 实现难度 | 优先级 |
+| 机会点 | 用户痛点与 Claim | 竞品现状 / 缺口及能力 ID | 实现难度与依据 | 优先级建议与理由 |
 |---|---|---|---|---|
-| [机会点] | [痛点] | [缺口] | 高 / 中 / 低 | P0 / P1 / P2 |
+| [机会点] | [痛点 / Claim] | [现状和已确认缺口，未知不算缺失] | [有依据时填写，否则待技术评估] | [交 Plan 所有者判断的建议] |
 
 ## 10. MVP 建议
 
+> 以下范围和路线是研究建议，引用用户问题、业务约束与竞品 Claim，待 Plan 所有者确认；不构成已批准需求或实现授权。
+
 ### 10.1 MVP 目标
 
 [用一段话说明 MVP 要帮助哪个用户，在什么场景下，完成什么最小闭环。]
@@ -251,11 +251,13 @@ flowchart LR
 
 1. [补充调研 / 用户访谈 / 厂商验证]
 2. [进入 work-unit.plan-requirements 继续澄清的问题]
-3. [生成 Spec]
-4. [判断是否需要 OpenAPI / 垂直切片 issue]
+3. [把已审计结论、候选术语、MVP / 非目标与成功标准建议回交对应所有者]
+4. [由生命周期所有者判断进入 Spec 和后续工程契约 / 垂直切片 Ticket 的条件]
 
 ## 12. 参考资料
 
-| 来源 | 链接 | 类型 | 可信度 | 备注 |
+| Evidence / Claim ID | 来源与可定位链接 | 来源类别 | 来源日期 / 观察日期 | 限制与反向信号 |
 |---|---|---|---|---|
-| [来源名称] | [URL] | 官方文档 / 产品页 / 白皮书 / 访谈 | 高 / 中 / 低 | [备注] |
+| [统一台账 ID] | [URL / 章节 / 记录] | [primary / direct-experience / near-primary 等] | [YYYY-MM-DD] | [抽样、访问、版本、独立性限制或反向来源] |
+
+[引用同目录 evidence 文件中的统一台账，不另建事实台账。来源冲突、访问失败和未知项保留原因、补证动作及接收者；机械校验不能证明来源支持结论，研究审核须核对实质 Claim。]

package/template/.template-spec/plan/templates/competitive-matrix-template.md

@@ -1,28 +1,48 @@
-# 竞品功能矩阵
+# [主题] 竞品功能矩阵
 
-> AI 辅助生成，人工审核补充。状态：✅ 有 | ⚠️ 部分 | ❌ 无 | ❓ 未知
+> 本文件是研究双文件的附属阅读材料。审计模式由 `yss-research` 持有证据，`competitive-intelligence` 执行分析；比较事实来自同目录 evidence 文件的 `competitive_analysis`，分析正文需由研究审核者核验。
+> ✅ 明确支持（`supported`）｜⚠️ 部分支持（`partial`）｜❌ 明确不支持（`absent`）｜❓ 未知（`unknown`）。未查到资料不能证明不支持；未知不能归入部分支持。
+
+## 文档信息
+
+| 项 | 内容 |
+|---|---|
+| 调研主题与读者 | [主题 / 读者] |
+| Profile / 模式 | [`strategy-evidence` 或 `technical-evidence`] / [`quick` 或 `evidence-audited`] |
+| 研究简报 / 证据 | [`<slug>-research-brief.md`] / [`<slug>-evidence.yaml`] |
+| 关联深度报告 | [选定报告时填写同目录链接；仅矩阵时写不适用及原因] |
+| 审核与限制 | [审核人 / 审核范围 / 未覆盖事项；普通探索明确未审计] |
 
 ## 竞品概览
 
-| 竞品 | 类型 | 目标用户 | 核心定位 |
-|------|------|---------|---------|
-| | | | |
+| 竞品 ID / 名称 | 类型 | 目标用户 | 核心定位 | Claim / 来源 |
+|---|---|---|---|---|
+| [稳定 ID / 名称] | [直接 / 间接 / 替代方案] | [用户] | [定位] | [Claim ID / 可定位来源] |
 
 ## 功能矩阵
 
-| 功能模块 | 功能点 | 竞品A | 竞品B | 竞品C | 我们 |
-|---------|--------|-------|-------|-------|------|
-| **模块1** | | | | | |
-| | 功能1 | | | | |
-| | 功能2 | | | | |
-| (按需扩展) | | | | | |
+以下区域由 `render-competitive-outputs.mjs` 根据 `competitive_analysis` 生成，包含截至日期、比较范围、产品 / 版本 / 套餐 / 地区、能力定义、状态表和证据 / 缺口摘要。未确认范围写 `unknown`，完整覆盖每个竞品 × 能力。
+
+<!-- YSS-COMPETITIVE:START -->
+[工具管理区：先填写结构化结果，再运行渲染器；不手填比较事实。]
+<!-- YSS-COMPETITIVE:END -->
 
 ## 差异化亮点
-（每个竞品的独特优势）
 
-## 功能空白区
-| 机会点 | 用户痛点 | 竞品缺失 | 实现难度 | 优先级 |
-|--------|---------|---------|---------|--------|
-| | | | | |
+[按竞品说明优势、适用用户与条件，引用 Claim / 来源。推断写明依据；功能支持状态仅以管理区为准。]
+
+## 功能空白与产品机会
+
+未知不能算作竞品缺失。下表为待 Plan 所有者判断的建议；实现难度只有依据时填写，未评估写待技术评估。
+
+| 机会点 | 用户痛点与依据 | 竞品现状及限制 | 建议与理由 | 待验证问题 |
+|---|---|---|---|---|
+| [机会] | [Claim / 来源] | [关联能力 ID / Claim] | [候选范围或优先级建议] | [补证动作与接收者] |
+
+## 结论与交接
+
+[分别写已支持的事实、推断、反向信号、限制和下一项决定。候选术语回交 `domain-modeling`；产品机会、MVP / 非目标与优先级回交 Plan / Spec 所有者。研究不修改 `CONTEXT.md`、Spec、Ticket 状态或批准记录。]
+
+## 参考资料与缺口
 
-## 结论
+[引用统一证据台账的 Evidence / Claim / Search ID 及可定位来源；保留来源日期、抽样、访问、独立性和版本限制，不另建第二套事实台账。]

package/template/.template-spec/process/document-writing.md

@@ -2,11 +2,11 @@
 
 起草或修订生命周期文档时，先读本规范的共用写法，再按阶段查阅第 3 节；发送进度与会签提示时读取第 4 节。按当前写入范围应用，正文、摘要和结构化信息应保持同一语义。
 
-[Plan、Spec、Ticket 写作对照](../templates/examples/lifecycle-writing-examples.md)提供同一事实输入下的改写样例；示例不构成真实需求或批准。
+[Plan、Spec、Ticket、PR / MR 与复盘写作对照](../templates/examples/lifecycle-writing-examples.md)提供同一事实输入下的改写样例；示例不构成真实需求、执行证据或批准。
 
 ## 1. 适用范围与保留项
 
-适用于研究结论、Plan、Spec、产品设计说明、工程契约的解释正文、Ticket、审查、发布和复盘。聊天中的进度通知按第 4 节处理。
+适用于研究结论、Plan、Spec、产品设计说明、工程契约的解释正文、Ticket、审查、PR / MR 描述、发布和复盘。聊天中的进度通知按第 4 节处理。
 
 本文件是生命周期文档的共用写作规范。生命周期身份、门禁、资产所有权、批准和状态由根 `AGENTS.md` 指定的权威资产决定；标准术语消费根 `CONTEXT.md`。本规范约束表达，不新增阶段、审批或业务规则。
 
@@ -59,6 +59,23 @@
 
 这些指引帮助填写既有模板，不新增必填字段、阶段或门禁。Plan 不提前承诺详细 API 和工程实现；Spec 的例子不代替完整规则；Ticket 不重新设计已冻结行为。
 
+### PR / MR 描述
+
+用户要求起草或修订 PR / MR 描述时，按最终改动组织以下四部分。小改动可以写成四个短段落，复杂改动可用已有 PR / MR 模板；不要求新增模板文件或结构化字段。
+
+1. **问题与 Before / After**：说明谁在什么条件下遇到什么问题，以及当前候选改变了什么可观察行为。已复现的原行为、候选目标与实际验证结果分别表达；未验证的 After 写成待验证目标。背景只保留解释本次改动所需的信息。
+2. **范围与合同**：描述最终修改的范围，引用适用的现行 Spec、Ticket、工程契约或模板维护任务及其版本。交代影响判断所需的边界和依赖；不把未完成的依赖、草案或历史批准写成当前就绪。标题与正文围绕最终改动，不沿用已放弃方案的描述。
+3. **实际验证与限制**：写明已执行命令的工作目录、退出码、对应结果及可定位证据。失败检查保留实际失败现象；未执行或未覆盖的检查说明原因和剩余限制，不能与通过项合并成“全部通过”。验证证据支持到哪里，结论就写到哪里。
+4. **风险与回滚**：按实际影响说明剩余风险、依赖、阻塞及恢复方式。可逆改动引用已知回滚点和可执行恢复步骤；恢复尚未验证时明确说明。数据迁移、外部副作用或其他难以恢复的变化如实说明限制，不凭空承诺可以回滚。
+
+起草或修订描述本身不授予 `git commit`、`git push`、远程创建 PR / MR、合并或发布权限。这些动作继续消费既有授权范围；描述、测试通过或自检结论不替代现行审查、批准和 Fresh Verification。
+
+### 复盘中的改进与沉淀
+
+先根据触发条件、实际影响和执行证据区分事实、已确认机制与待验证假设。检查已经存在但未接入实际执行路径，或本次没有执行时，优先修复接入与执行并引用执行证据。对重复出现、可机械判定的不变量，确认既有检查没有覆盖后，再提出能够检测该情形的最小检查和失败反例；无法机械判定的事项说明人工验证的方法、依据和结果记录位置。
+
+改进动作及关闭状态继续由既有待办 / 工作项持有。复盘引用事实源、Skill、模板或检查的修订去向和实际验证结果；只有计划、建议或尚未执行的验证时保持待处理。单次现象先验证其机制和适用范围，不直接沉淀为通用禁令。
+
 ## 4. 进度与会签提示
 
 ### 将流程编号转成读者能理解的说明
@@ -73,10 +90,12 @@
 
 状态阅读可用 `scripts/lifecycle-status --root <项目> --checkpoint <ref> --format text`；默认 JSON 继续供工具读取。该查询及其中文展示均不授予执行或批准权限。
 
-仅在用户询问状态、阶段切换或出现阻塞时，简短展示四项信息：**当前阶段、当前阻塞、谁处理、下一动作**。可以用一句话或四行表达，不要求表格。普通问题直接回答；其他进度更新只说明本轮有意义的变化，状态未变时不重复整套说明。
+生命周期主控每轮返回或暂停，以及用户询问状态、恢复、阶段切换或出现阻塞时，简短说明：**当前阶段与本轮结果、下一阶段或单元及进入条件、问题与阻塞、谁处理及如何解除、下一动作**。依具体内容用连贯短段落或列表，不强制表格或固定行数；输出检查以当前编排合同的 `user_progress_report` 为准。普通问题直接回答；其他进度更新只说明本轮有意义的变化，状态未变时不重复整套说明。
 
 状态读取已有 checkpoint 和适用验证结果，不建立或要求用户填写另一套状态文件。未核验的阶段或阻塞情况写“待核验”；只有当前适用证据支持时才能写“无阻塞”。证据过期应明确指出过期输入及恢复动作，不能沿用历史通过结论。责任人按已有登记填写，缺失写“未登记”，不自行指派；下一动作说明如何补齐登记或核验。
 
+下一单元仍属当前阶段时说明剩余工作；拟进入的下一阶段附进入条件，不把目标写成已获准流转。阻塞逐项说明影响、来源、责任方、处理动作、解除证据和恢复检查；未决项与建议按实际影响表达。只读查询的未发现不等于已核验无阻塞，缺少下一路由不等于完成。模板源展示维护步骤和验证目标，阶段、批准和完成结论仍由原权威合同裁决。
+
 默认只展示当前需要处理的事项，证据路径按需展开。查看状态本身不改文件，也不触发全套验证；推进阶段时仍执行原有适用校验。已授权且 Agent 可以完成的动作继续执行，避免把操作转交用户。
 
 请求决定时展示当前版本、推荐方案及理由、实质选项和取舍、风险、批准范围与后续动作，遵守既有用户决定协议。可以突出当前最重要的问题，但所有影响决定的阻塞和选项都应可见。一次回复需要多个相互独立的决定时，分别说明各自影响。

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

@@ -10,7 +10,11 @@
 
 普通功能采用一个推进负责人和一个独立审查者，按主要风险选择专业能力；仅在能力缺口、专业结论冲突或项目外部制度要求时增加审查者。角色表的 `countersigners` 是候选能力，不是全员签字名单。无依赖的审查可并行；同一候选的相邻检查可一次审查并逐项记录，聚合验收引用已有结论。
 
-人工暂停由决定变化触发：业务范围、关键规则、验收标准、契约承诺、授权边界、风险接受、已采纳质量标准或对外承诺发生实质变化时，展示差异后重新决定。API、数据和跨仓影响仍触发适用专业检查，但技术载体本身不要求重复人工批准。授权清单明确覆盖的范围按生命周期用户决定协议延续；未知变化先补影响分析，不默认沿用。
+人工暂停由决定变化触发：业务范围、关键规则、验收标准、契约承诺、授权边界、风险接受、已采纳质量标准或对外承诺发生实质变化时，展示差异后重新决定。API、数据和跨仓影响仍触发适用专业检查，但技术载体本身不要求重复人工批准。授权清单明确覆盖的范围按生命周期用户决定协议延续；未知变化先调查并补影响分析，确认需要新的真实决定后才询问，不默认沿用或以全轴复审兜底。
+
+专业能力和只读补充技能读取角色表的 `review_capabilities` 与检查策略，由主控编译正式任务的 `review_context` 和 `skill_source.review_skills`，不复制能力定义。专业审查未返回时，主控自主派发或核对现有任务后等待，同时继续无依赖工作；验证失败或结果不可验收时修复、补证据或重新路由。仅缺真实决定、新授权或无法自主取得的必要输入时，完成可审阅资产后向指定负责人询问。给出完成结论本身不形成新暂停。
+
+首轮按实际影响覆盖全部适用检查。修复后先比较旧候选与当前候选，列明受影响结论、行为及直接 / 传递依赖，再定向复审并重新绑定当前候选、依据和实际验证。未受影响项只在可读取比较依据证明其条件与依赖未变时复用；摘要变化、UI 影响或 `new_impacts` 不自动扩展为全部审查轴，未知影响先调查并阻断依赖事项。
 
 排版、措辞和派生内容调整也必须更新当前摘要、差异说明和验证证据；独立审查证明决定依据未变后可延续，不通过忽略字节差异或修改原回复实现复用。普通实现细化补受影响测试和审查。项目外部制度未确认时不能使用自动延续；已登记的客户、公司和审计强制审批按原要求执行。
 

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

@@ -46,7 +46,7 @@ apps/
 - 后端：已登记项目根的 `./mvnw` 校验 / 测试；若工程已配置 Checkstyle、P3C 或 Spotless，审查时实际执行。
 - `git-submodule` 必须递归检出；空 gitlink 不得当作「没有工程」。
 - 模板源 `.cursor/environment.json` 只安装模板校验依赖（`jsonschema`、模板 `pnpm`），**不是**实现仓审查运行时。`project-instance` 与实现仓库的 Cloud / CI 环境自行包含 JDK、Maven Wrapper 和 `pnpm`。
-- 审查任务包只写证据路径；专项 skill 只读，不得写实现。审查 finding 按 `review_standards_route.finding_disposition` 分流：`violation` 交实现者修复后全轴复审；`drift` / `new_impacts` 回 实现合同编译器，不在审查会话中改代码。
+- 审查任务包只写证据路径；专项 skill 只读，不得写实现。审查 finding 按 `review_standards_route.finding_disposition` 分流：`violation` 交实现者修复后按差异、受影响结论及依赖定向复审；`drift` / `new_impacts` 回 实现合同编译器，不在审查会话中改代码。
 
 ## 1.3 `repository_scope: git-submodule`
 
@@ -74,11 +74,29 @@ apps/
 
 采用后端交付驱动前端的专职项目，按 [前后端交付与联合接收](frontend-backend-delivery.md) 执行输入校验。该条件同时进入合同编译、任务派发、生命周期实施/恢复和正式前端证据检查；原通用研发 profile 保留兼容，不能以兼容入口替专职项目跳过接收。
 
-| 影响面 | 必须绑定的记录 | 本变更结论 |
-|---|---|---|
-| 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 变化 |
+| 影响面 | 必须绑定的记录 |
+|---|---|
+| Harness-only | change、文档路径、压力场景、fresh verification、checkpoint |
+| release-only | release note、发布顺序、观察信号、rollback |
+| backend-only | backend repo、分支、MR / PR、CI、API 影响 |
+| frontend-only | frontend repo、分支、lint / type-check / build |
+| contract-only | OpenAPI Draft / Freeze、消费者确认 |
 
+## 3. 跨仓库责任
+
+- 模板仓库负责 `yss-project.yaml`、流程事实源、迁移指南、技能投影、模板校验脚本和快照可发布状态。
+- CLI 仓库负责 `attach`、`sync`、受管 manifest、快照 commit、metadata、迁移计划、备份 / 回滚、端到端测试和用户说明。
+- CLI 只写研发管理资产；不得创建或覆盖前后端运行时代码，不删除目标 `.git`，也不创建、覆盖或删除 `.gitmodules` 与 gitlink。
+- 模板 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/.template-spec/process/research-completion.md

@@ -12,6 +12,8 @@ node scripts/verify-maintenance-research <slug>-research-brief.md <slug>-evidenc
 
 命令实际调用研究包校验器，保留 stdout/stderr、退出码、起止时间及简报、台账、校验器、日志的 SHA-256；返回 `binding: {ref, digest}`。不会覆盖旧目录。失败记录保留，不能用于完成。
 
+包含 `competitive_analysis` 的新研究包还在 `inputs.competitive` 中绑定选定的矩阵、报告，以及竞品 Schema、渲染器、比较校验模块、两份模板与 JSON Schema 执行器的 `{ref, digest}`。这些引用同时写入结果的 `evidence_refs`。产物仅允许同目录相对文件名；越界或符号链接逃逸直接拒绝。接收端重新核验当前字节并重跑校验，任何绑定变化都使旧记录失效。没有扩展的旧包和历史记录保留原合同，不改写旧字节。
+
 Workflow Execution Result 在原字段之外携带 `research_verification: {ref, digest}`。`evidence_refs` 包含验证记录、简报、台账和 Context 不适用说明。`context_reconciliation.status` 为 `not-applicable` 且必须给出原因；执行阻断、drift、violation、new_impacts 和 stale_candidates 必须为空。
 
 接收端重读绑定字节，并实际重跑当前研究校验器。通过后可以 `next_route: null` 独立结束。结构校验不证明来源中的事实，也不代替主控对重要结论的来源审计；研究报告保留反证、来源缺口和结论边界。

package/template/.template-spec/process/runtime-storage.md

@@ -0,0 +1,78 @@
+# 运行记录与证据留存
+
+运行工具把普通执行记录保存到仓库外的 SQLite 和日志目录。checkpoint、合同、批准、用户原始决定、迁移回执及恢复事务继续使用现有文件作为权威。查询索引和历史通过记录只能帮助定位证据；阶段流转、实现和交付仍执行当前合同要求的 Fresh Verification。
+
+## 存储位置与运行方式
+
+受影响工具要求 Node `>=22.13 <27`，使用内置 `node:sqlite`，不安装原生驱动。低于最低版本或达到 27 时，在创建目标目录、数据库或日志前拒绝执行；`off` 模式也遵守工具的 Node 基线。
+
+默认目录为 `~/.yss-harness/runtime/<workspace-id>/`，其中 `workspace-id` 是项目根目录真实路径的 SHA-256。不同 worktree 分开保存。`YSS_RUNTIME_HOME` 可指定仓外绝对目录，CI 优先使用 `RUNNER_TEMP`。目录本身及符号链接解析后的目标均不得进入项目或已登记子仓。
+
+支持运行存储的执行入口接受 `--runtime-store sqlite|off`。试点使用显式模式；验证及分发闭合后，新版本默认使用 `sqlite`。`off` 回到原文件执行路径，用于受控回退。已有实例通过升级计划接入，不自动迁移业务文件。
+
+运行由创建它的存储会话登记终止；其它连接不能通过 `finish` 接管运行或覆写报告。进程中断后保留待恢复状态，历史状态不能据此转成当前验证通过。
+
+| 内容 | 保存方式与用途 |
+|---|---|
+| 运行摘要、命令结果、事件 | SQLite 保存输入摘要、实际退出码、耗时和终止原因 |
+| checkpoint 查询索引 | 绑定源文件路径和当前摘要；源文件变化后索引过期，不能改变门禁结果 |
+| stdout / stderr | 执行时流式写日志文件，正文不逐段进入数据库 |
+| 重复运行输入清单 | 以原字节 SHA-256 去重并压缩，数据库登记对象引用 |
+| 正式验证材料 | 独立文件包，保留原报告与 `run:` 格式，并登记永久保护 |
+
+数据库文件名为 `runtime.sqlite`。SQLite 使用短事务、`journal_mode=DELETE`、`synchronous=FULL` 和 5 秒锁等待。事务资产中的完整输入、恢复备份仍保留原字节，不替换为运行对象引用。Fresh Verification 的源码扫描范围保持不变；如果以后消费仓外对象作为输入，必须显式绑定对象摘要。
+
+模板 runner 在同一短事务中保存一次实际命令结果、日志索引和对应完成事件；复用执行仍单独登记各查询位置的事件，通过 command_id 引用首个实际命令，避免在事件中重复保存命令及日志路径。文件摘要与序列化在事务前完成，事务失败回滚全部登记，命令及已有日志不重跑或删除。首次登记失败后的复用事件保留脱敏命令和日志路径，不能引用不存在的命令记录。
+
+命令结果保留原有 runner 状态，并追加 actual_exit_code、actual_exit_signal 和 actual_exit_code_observed。超时、取消的包装状态不替代子进程实际退出观察；未执行或启动失败的实际退出码为 null，信号终止保留实际信号。普通退出 130 仍按实际失败处理，不能仅凭数字判为取消。
+
+## 执行与证据
+
+运行登记完成后执行命令，保存实际结果并形成报告。命令执行成功和运行存储成功分别记录；数据库故障不得改写实际命令退出码，也不得重跑已经执行的命令。已有日志继续保留，报告给出存储异常。无法形成完整验证报告时，不能宣布验证通过。
+
+模板验证未指定 `--report-dir` 时保存普通运行记录；显式报告目录自动保护。发布验证保护内部完整验证报告。只读分诊继续保存独立运行包并保护整个包，`run:` 仍解析到真实文件。`project-ci check` 的 stdout JSON 和原退出码保持兼容，可选择登记运行。
+
+导出包带相对路径和摘要清单，能够在没有原数据库的环境核验。新阅读入口消费该清单；旧报告字段和历史已批准材料继续兼容，不重新序列化历史材料。
+
+## 管理入口
+
+统一使用 `scripts/runtime-store`。精确参数可通过 `scripts/runtime-store --help` 查询；查询和验证的 `--plan` 不创建数据库或运行文件。
+
+| 命令 | 行为 |
+|---|---|
+| `inspect` | 查询运行、存储量、保护原因和过期候选 |
+| `inventory` | 只读盘点存量机器文件，报告分类、大小、重复内容和归档候选 |
+| `export` | 导出指定运行的报告、日志、输入和摘要清单，登记永久保护 |
+| `plan-gc` | 生成可审阅的清理计划，不删除文件 |
+| `apply-gc` | 按计划重验引用、占用与输入摘要后清理 |
+| `backup` | 创建一致性数据库快照及恢复所需文件 |
+| `restore` | 从备份恢复，拒绝覆盖不同内容的目标 |
+
+常用操作如下；输出、计划与备份目录均选择仓外绝对路径：
+
+```bash
+scripts/runtime-store inspect --root <项目根> --json
+scripts/runtime-store inventory --root <项目根> --json
+scripts/runtime-store export --root <项目根> --run <运行ID> --output <新的仓外目录>
+scripts/runtime-store inspect --source <导出包目录>
+scripts/runtime-store plan-gc --root <项目根> > <仓外计划.json>
+scripts/runtime-store apply-gc --root <项目根> --plan <仓外计划.json>
+scripts/runtime-store backup --root <项目根> --output <新的仓外备份目录>
+scripts/runtime-store restore --root <项目根> --source <仓外备份目录>
+```
+
+数据库版本由迁移记录管理，升级前备份；未知版本和不符合初始化条件的已有数据库拒绝写入。备份等待运行占用解除后创建独立一致性快照，并保存相关文件摘要；恢复核对所属工作区和摘要，已有不同内容不覆盖。派生索引可以从仍保留的权威文件重建，未导出的运行事件依赖备份恢复。
+
+备份保存运行存储目录及一致性数据库快照。登记在其它仓外目录的正式报告列为 `external_dependencies`，保留其路径和摘要；恢复结果的 `formal_evidence_complete` 表示这些外部材料是否仍完整。需要脱离原环境携带正式证据时，应先使用 `export` 生成独立包，再通过 `inspect --source` 校验并解析相对日志路径。备份不会搬迁或覆盖原正式报告。
+
+## 留存与显式清理
+
+普通成功运行从结束时间起保留 7 天；失败、超时和取消运行保留 30 天。只有显式执行 `apply-gc` 才删除过期日志。清理后保留精简摘要及“日志已过期”标记，查询者不能将其作为完整证据。
+
+清理须同时满足：运行已结束且过期、没有保护记录或正式引用、没有进程占用、引用扫描完整。未知分类、未解析动态引用、待恢复运行和运行中记录均保留。计划生成后输入发生变化时，执行拒绝该计划。共享输入对象只有在全部引用都具备清理资格时才删除。正式导出材料不适用 7 / 30 天留存期。
+
+文件占用探测不可用或结果不完整时，清理资格保持不确定并保留文件。macOS / Linux 使用 `lsof`，Windows 使用独占文件探测。清理中断记录 `gc-pending`；恢复清理由重新执行 `plan-gc` 生成计划，再显式执行 `apply-gc`，重新检查引用、保护、占用和剩余原字节。普通启动不会自动继续删除。
+
+执行清理时应保持正式引用和日志读写的静止窗口；需要作为正式材料使用的运行先执行 `export` 登记保护。SQLite 事务能协调本存储的登记、保护与对象引用，任意外部文件写者和日志读取进程不共享该锁，因此删前复核不能提供跨进程文件系统的原子快照。无法建立静止窗口时只运行 `plan-gc`，保留候选。
+
+历史合同、批准、checkpoint、回执和维护证据只参与 `inventory`。盘点列出的归档候选不授予删除或迁移权限；历史整理需要独立的范围授权及当前验证。

package/template/.template-spec/process/schemas/approval-context.schema.json

@@ -0,0 +1,67 @@
+{
+  "type": "object",
+  "required": [
+    "subject_ref",
+    "approval_scope",
+    "basis",
+    "drafter_principal_ref"
+  ],
+  "properties": {
+    "subject_ref": {
+      "type": "string",
+      "minLength": 1
+    },
+    "subject_digest": {
+      "type": "string",
+      "pattern": "^(sha256:)?[a-f0-9]{64}$"
+    },
+    "approval_scope": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "basis": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "ref",
+          "digest"
+        ],
+        "properties": {
+          "ref": {
+            "type": "string",
+            "minLength": 1
+          },
+          "digest": {
+            "type": "string",
+            "pattern": "^(sha256:)?[a-f0-9]{64}$"
+          },
+          "version": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "drafter_principal_ref": {
+      "type": "string",
+      "minLength": 1
+    },
+    "review_package": {
+      "type": "boolean"
+    },
+    "review_context": {
+      "type": "object"
+    }
+  },
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Consumer-owned current approval context",
+  "additionalProperties": false
+}