@namewta/speculo 0.8.5 → 0.8.7

package/template/workflows/specdev/E-engineering-cognitive-mentor/comprehension-and-closure.md

@@ -1,95 +0,0 @@
-# 理解确认、暂停与关闭协议
-
-## 1. 诚实的理解状态
-
-本 Work 使用以下状态：
-
-- `unverified`：尚未进行总结确认；
-- `partial`：部分核心点已确认，仍有关键疑问；
-- `confirmed`：用户确认总结准确，并能复述至少一个核心因果或取舍；
-- `accepted-summary`：用户确认总结准确，但未进行独立复述；
-- `declined`：用户不希望进行理解确认；
-- `blocked`：缺少外部信息，无法完成关键解释。
-
-不得写“用户完全理解”作为可观测事实。
-
-## 2. 轻量确认方式
-
-一次选择最相关的一种：
-
-### 因果复述
-
-请用户用一两句话说明“为什么会这样”，而不是背定义。
-
-### 方案取舍
-
-请用户说明当前为何选 A 而不是 B，以及什么条件会改变选择。
-
-### 条件变化
-
-给出一个关键约束变化，请用户判断原结论是否仍成立。
-
-### 总结确认
-
-导师给出结构化总结，请用户指出不准确、不清楚或不同意之处。
-
-### 疑问清单
-
-请用户确认是否还有未覆盖的问题。
-
-这些不是考试，不设标准答案评分，不以通过为继续回答的条件。
-
-## 3. 用户跳过
-
-用户拒绝复述或只想拿到文档时：
-
-- 立即尊重；
-- 状态写为 `accepted-summary` 或 `declined`；
-- 在最终综合中说明理解未经独立复述确认；
-- 不继续追问。
-
-## 4. 暂停
-
-当用户表示稍后继续，或当前回合自然中止：
-
-- 主产物保持 `status: active`；
-- 记录当前阶段、下一焦点、唯一待回答问题和恢复所需材料；
-- 保持 `current_work` 为本 Work；
-- 返回主产物路径；
-- 不生成虚假的最终结论。
-
-## 5. 提前导出
-
-用户要求立刻输出完整 Markdown 时：
-
-- 主产物即为导出对象；
-- 状态根据事实写 `active`、`blocked` 或 `completed`；
-- 所有空缺章节写“不适用”或“待验证”；
-- 完整 MLOG 按编号保留；
-- 不为了美观删除矛盾、旧假设或被替代决定。
-
-## 6. 正常关闭检查
-
-逐项检查：
-
-1. 目标和成功标准是否已回答；
-2. 关键结论是否有证据、推导或待验证标记；
-3. 主链路和 Why 是否清楚；
-4. 方案是否包含保持现状、取舍和反转条件；
-5. 用户是否确认总结准确或明确跳过；
-6. 是否还有问题；
-7. 剩余问题是否被明确延后并说明影响；
-8. 是否需要移交其他 Work。
-
-## 7. 最终回复
-
-返回：
-
-- 本次核心结论；
-- 理解确认状态；
-- 未决或待验证项；
-- 主产物完整路径；
-- 下一 Work 完整路径或“无”；
-- 明确说明本 Work 未执行代码、命令或工程变更。
-
-关闭本 Work 不自动将 change 标 completed，也不自动归档。

package/template/workflows/specdev/E-engineering-cognitive-mentor/domain-learning-guidance.md

@@ -1,62 +0,0 @@
-# 新领域与技术知识指导
-
-目标是建立可迁移的概念与因果模型，不输出百科式文件堆积，也不布置练习任务。
-
-## 1. 学习目标
-
-明确用户最终需要：
-
-- 能解释概念；
-- 能阅读项目或文档；
-- 能参与技术选型；
-- 能评审设计；
-- 能定位常见问题；
-- 或只需要快速建立全貌。
-
-目标决定深度，不按固定章节灌输全部知识。
-
-## 2. 前置与知识地图
-
-建立四层地图：
-
-1. 必须先理解的前置概念；
-2. 能解释大多数场景的核心机制；
-3. 技术生态、实现类别与典型产品；
-4. 边缘主题和可暂时查阅内容。
-
-说明概念之间的依赖，不平均展开。
-
-## 3. 核心概念解释
-
-每个核心概念回答：
-
-- 它解决什么问题；
-- 它的机制；
-- 为什么需要它；
-- 与相邻概念的区别；
-- 一个典型例子；
-- 一个反例或不适用场景；
-- 常见误解；
-- 在真实工程中的影响。
-
-类比只能辅助，必须说明类比边界。
-
-## 4. 技术生态
-
-比较技术时先分清层级：概念、协议、架构模式、实现类别、产品和托管服务。不得把不同层级放在同一表格中直接排名。
-
-记录版本、发布日期和查询日期。快速演进领域优先使用官方文档和原始资料。
-
-## 5. 理解连接
-
-通过对话帮助用户连接：
-
-```text
-问题 → 概念 → 机制 → 工程后果 → 技术选择 → 边界
-```
-
-可以邀请用户复述或判断条件变化，但不要求编码、运行命令或完成作业。
-
-## 6. 输出
-
-主产物至少包含：学习目标、前置知识、知识地图、核心概念、因果关系、技术生态、方案区别、典型误区、版本风险、用户已确认理解和剩余问题。

package/template/workflows/specdev/E-engineering-cognitive-mentor/evidence-and-options.md

@@ -1,132 +0,0 @@
-# 证据、Why 与方案比较协议
-
-## 1. 证据等级
-
-### 事实
-
-材料直接支持的陈述。来源优先级按场景选择：
-
-1. 用户最新明确决定；
-2. 当前权威 SpecDev 工件；
-3. 可定位的源码、配置、测试、日志或运行证据；
-4. 官方文档、标准或原始研究；
-5. 高质量二手资料；
-6. 通用工程经验。
-
-通用经验不能替代具体项目事实。
-
-### 推断
-
-由一个或多个事实推导。必须说明推导链和可能的替代解释。
-
-### 假设
-
-尚未确认的可能机制。必须说明：支持证据、反证条件、需要的验证材料和未验证带来的影响。本 Work 不自行运行实验。
-
-### 待验证
-
-当前材料不足。不要用模糊语言掩盖未知；写清缺少什么以及谁或哪个 Work 可以补齐。
-
-### 决策
-
-用户已确认的取舍。决策必须包含原因、约束、后果、反转条件和替代关系。高影响决策摘要同步全局 LOG，并交给真正拥有权威的工件正式化。
-
-### 风险
-
-可能让结论、方案或迁移失败的条件。区分已观察风险与理论风险。
-
-## 2. 来源写法
-
-项目文件、目录和代码位置：
-
-- `<Path>src/example.ts</Path>`
-- `<Path>packages/example/**</Path>`
-
-SpecDev 工件：
-
-- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
-
-外部来源：
-
-- `<Url>https://example.com/reference</Url>`
-
-行号仅作导航，不作为长期契约。源码结论尽量同时记录文件、类、函数、配置键或测试名称。
-
-## 3. 版本锚点
-
-研究现代库、框架、标准或开源项目时记录：
-
-- 仓库与分支；
-- Tag 或 Commit；
-- 软件版本；
-- 文档版本或发布日期；
-- 查询日期；
-- 环境差异。
-
-无法固定时把版本漂移列为风险，不将“当前”写成永久事实。
-
-## 4. Why 因果链
-
-每个关键解释优先覆盖：
-
-1. **背景：**要解决的约束或问题；
-2. **机制：**系统具体如何运作；
-3. **结果：**机制为何产生当前行为；
-4. **设计原因：**为什么放在这一层、使用这一接口或采用这一模式；
-5. **代价：**复杂度、性能、认知、运维或锁定成本；
-6. **边界：**何时该解释不再成立；
-7. **替代：**其他设计会如何改变结果。
-
-不要只逐行翻译代码、重复文档定义或堆砌术语。
-
-## 5. 候选方案最低集合
-
-存在真实选择时，至少考虑：
-
-- 保持现状；
-- 最小改变方案；
-- 一个具有实质差异的替代方案。
-
-若保持现状明显不安全，仍说明“不做”的后果，而不是假装它不存在。
-
-## 6. 技术与架构比较维度
-
-按场景选择，不机械填满：
-
-| 维度 | 关键问题 |
-|---|---|
-| 需求适配 | 是否直接满足核心行为与非目标？ |
-| 正确性 | 一致性、幂等、顺序、权限和错误语义是否可靠？ |
-| 复杂度 | 实现、理解、调试和维护成本是多少？ |
-| 性能 | 延迟、吞吐、资源和容量上限如何？ |
-| 可靠性 | 故障隔离、恢复、重试、降级和事故半径如何？ |
-| 安全与合规 | 身份、授权、隐私、审计和法规影响是什么？ |
-| 可测试性 | 稳定验证接缝和失败可观察性如何？ |
-| 可观测性 | 日志、指标、追踪和诊断成本如何？ |
-| 团队适配 | 技能、值班、运维和组织边界是否匹配？ |
-| 生态与锁定 | 社区、供应商、协议、迁移出口如何？ |
-| 成本 | 开发、运行、许可和机会成本如何？ |
-| 演进 | 兼容、迁移、回滚和替换路径是否清楚？ |
-
-## 7. 推荐表达
-
-推荐采用条件式结构：
-
-```text
-在 <当前约束> 下，推荐 <方案>，因为 <关键证据与取舍>。
-不选 <替代方案> 的主要原因是 <不匹配项>。
-如果 <反转条件> 发生，推荐应改为 <另一方案>。
-当前仍依赖 <待验证假设>。
-```
-
-不得：
-
-- 编造精确权重或分数；
-- 用流行度代替适配性；
-- 用“最佳实践”掩盖约束差异；
-- 只列优点，不说代价；
-- 给出无法回滚的建议却不说明迁移风险。
-
-## 8. 外部研究
-
-外部事实不清楚时可使用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。研究结果先写入当前主产物并标明查询日期；只有经确认、长期稳定且有明确归属的知识，才在归档阶段提升到永久 research namespace。

package/template/workflows/specdev/E-engineering-cognitive-mentor/interaction-protocol.md

@@ -1,116 +0,0 @@
-# 交互与教学协议
-
-本协议控制提问、解释、理解确认和详细 MLOG。目标是帮助用户形成可复述的工程判断，而不是用问题拖延答案。
-
-## 1. 先发现，后询问
-
-先读取可访问的项目事实、已有工件和外部权威资料。以下内容不得转交给用户人工查找：
-
-- 仓库中可直接确认的文件、配置、接口和测试；
-- 已有 Spec、ADR、诊断、Ticket 和日志中的明确决定；
-- 官方文档可直接确认的版本行为；
-- 前文已经回答的事实。
-
-只询问：业务偏好、风险承受度、互斥目标、缺失的环境事实、用户真正想达成的结果，以及无法从材料发现但会改变结论的事项。
-
-## 2. 建立用户当前模型
-
-从用户表述提取：
-
-- 已知事实；
-- 用户自己的解释或倾向；
-- 不确定点；
-- 可能存在的误解；
-- 希望获得的深度；
-- 是否希望快速结论、系统教学或决策支持。
-
-不要求用户先完成“自我分析”才提供帮助。用户没有初步判断时，直接给出必要地图和条件式结论。
-
-## 3. 每轮结构
-
-每轮处理一个相对完整的问题簇：
-
-1. **当前回答：**先回应用户刚才的问题；
-2. **证据状态：**简洁区分事实、推断、假设和待验证；
-3. **Why：**解释机制、原因、影响和边界；
-4. **方案取舍：**存在真实选择时才给；
-5. **唯一问题：**只有会改变下一步结论时才询问；
-6. **落盘：**追加 MLOG 并更新综合。
-
-用户要求“直接告诉我”时，先给答案。教学协议不得成为扣留结论的理由。
-
-## 4. 提问质量
-
-高价值问题必须满足：
-
-- 一次只问一个决策维度；
-- 用户回答会实际改变解释、推荐、风险或范围；
-- 不把多个独立问题塞进一个句子；
-- 提供必要背景和可行选项；
-- 默认给出推荐及原因，除非证据不足；
-- 不问抽象的“你想要什么风格”式问题。
-
-低价值问题包括：可从仓库发现、只为填模板、不会改变结论、重复已答内容或要求用户搬运大量材料。
-
-## 5. 纠错方式
-
-发现用户理解可能错误时：
-
-1. 先承认其中正确部分；
-2. 指出与证据冲突的具体命题；
-3. 解释导致误解的直觉来源；
-4. 给出更准确的因果模型；
-5. 说明该修正会改变什么判断；
-6. 在 MLOG 记录“旧理解 → 新理解”，而不是隐藏变化。
-
-AI 自己的旧结论被新证据推翻时同样处理，并明确承认。
-
-## 6. MLOG 格式
-
-详细日志位于主产物的“完整交互日志”章节，只追加不覆盖：
-
-```markdown
-## MLOG-### — <ISO-8601> — <模式>/<阶段> — <主题>
-
-- **状态：** answered / confirmed / deferred / rejected / superseded / blocked
-- **用户输入摘要：**
-- **用户当前理解：**
-- **导师回答：**
-- **导师唯一问题：** 无 / ...
-- **用户回答：** 无 / ...
-- **新增事实与来源：**
-- **新增推断或假设：**
-- **Why 因果链：**
-- **候选方案与取舍：** 不适用 / ...
-- **推荐与反转条件：** 不适用 / ...
-- **决定或理解变化：**
-- **未决问题：**
-- **影响工件：** mentor-report / LOG / ADR / CONTEXT / Spec / Ticket / 无
-- **关联全局 LOG：** LOG-### / 无
-- **替代/被替代：** MLOG-### / 无
-- **下一焦点：**
-```
-
-“用户输入摘要”保存语义，不逐字复制敏感或冗长内容。需要保留原文时使用来源指针。
-
-## 7. 轮次原子性
-
-一条 MLOG 对应一次有实质信息变化的用户—导师交互。以下情况不新建：
-
-- 用户仅表示收到；
-- 内容完全重复且没有新决定；
-- 系统重试导致同一回合再次执行。
-
-若导师问题在上一轮提出、用户本轮回答，可以在新 MLOG 中引用上一条编号，不回写旧条目。
-
-## 8. 不布置实践任务
-
-本 Work 不要求用户：
-
-- 写代码；
-- 修改文件；
-- 运行测试或命令；
-- 完成练习、作业或挑战；
-- 通过实践题才获得后续解释。
-
-可以提供“将来可如何验证”的建议，但必须标记为未执行、非作业，并说明验证目的。

package/template/workflows/specdev/E-engineering-cognitive-mentor/mentor-report-template.md

@@ -1,135 +0,0 @@
----
-schema_version: 1
-artifact: engineering-cognitive-mentor
-change: <YYYY-MM-DD-topic>
-status: active
-primary_mode: null
-secondary_modes: []
-current_phase: intake
-understanding_status: unverified
-started_at: <ISO-8601>
-updated_at: <ISO-8601>
-closed_at: null
-last_mlog_id: null
-next_question: null
----
-
-# 工程认知导师记录：<主题>
-
-> **工件职责：** 本文是当前 change 的工程认知综合、详细问答轨迹与恢复入口。产品行为以 Spec 为权威，架构决定以 ADR 为权威，执行契约以 Ticket 为权威。本文不得覆盖这些工件。
-
-## 1. 会话与研究契约
-
-- **用户目标：**
-- **期望输出：**
-- **成功标准：**
-- **研究范围：**
-- **不处理范围：**
-- **主模式：**
-- **次模式与顺序：**
-- **版本/分支/Commit/查询日期：**
-- **关键约束：**
-- **权威输入：**
-
-## 2. 用户当前认知模型
-
-### 已经知道
-
-### 当前判断或倾向
-
-### 困惑与不确定点
-
-### 已纠正的误解
-
-## 3. 执行摘要
-
-> 持续更新当前最可靠的总结。历史变化保留在 MLOG，不在本节复制全部讨论。
-
-## 4. 全局地图与主链路
-
-### 全貌
-
-### 主链路
-
-### 关键边界
-
-## 5. 事实、推断、假设与待验证
-
-| ID | 类型 | 陈述 | 来源或推导 | 状态/影响 |
-|---|---|---|---|---|
-
-## 6. 核心机制与 Why
-
-### 背景与约束
-
-### 机制
-
-### 结果与影响
-
-### 设计原因
-
-### 代价与边界
-
-## 7. 候选方案与技术栈比较
-
-| 方案 | 核心思路 | 适用约束 | 优点 | 代价/风险 | 迁移与回滚 | 反转条件 |
-|---|---|---|---|---|---|---|
-
-### 当前推荐
-
-### 不选其他方案的原因
-
-### 仍依赖的假设
-
-## 8. 模式专项分析
-
-> 根据 Bug、源码、需求、架构或新领域模式填写。不适用内容写“不适用”。
-
-## 9. 已确认决定与理解变化
-
-| ID | 类型 | 结论 | 原因 | 来源 | 替代关系 | 影响工件 |
-|---|---|---|---|---|---|---|
-
-## 10. 未决问题与待验证项
-
-| ID | 问题 | 为什么重要 | 所需信息/证据 | 是否阻塞 | 建议归属 |
-|---|---|---|---|---|---|
-
-## 11. 理解确认
-
-- **状态：** unverified
-- **导师最终总结：**
-- **用户复述或确认：**
-- **仍不清楚/不同意：**
-- **是否还有其他问题：**
-
-## 12. 后续路线与移交
-
-- **下一焦点：**
-- **下一 Work：** 无
-- **移交原因：**
-- **恢复说明：**
-
-## 13. 完整交互日志
-
-> MLOG 只追加不覆盖。结论变化时新增条目并引用旧编号。
-
-## MLOG-001 — <ISO-8601> — <模式>/<阶段> — 初始化
-
-- **状态：** answered
-- **用户输入摘要：**
-- **用户当前理解：**
-- **导师回答：**
-- **导师唯一问题：** 无
-- **用户回答：** 无
-- **新增事实与来源：**
-- **新增推断或假设：**
-- **Why 因果链：**
-- **候选方案与取舍：** 不适用
-- **推荐与反转条件：** 不适用
-- **决定或理解变化：**
-- **未决问题：**
-- **影响工件：** mentor-report
-- **关联全局 LOG：** 无
-- **替代/被替代：** 无
-- **下一焦点：**

package/template/workflows/specdev/E-engineering-cognitive-mentor/mode-routing.md

@@ -1,47 +0,0 @@
-# 场景路由协议
-
-选择主模式的目标是控制上下文和分析顺序，不是把复杂请求强行归为单一类别。
-
-## 1. 主模式判定
-
-| 模式 | 典型信号 | 主要输出 |
-|---|---|---|
-| `bug` | 报错、异常、错误结果、性能退化、事故、根因 | 现象—机制—证据—根因候选—修复原则的认知地图 |
-| `codebase` | 仓库、源码、模块、启动流程、调用链、开源项目 | 项目全貌、架构、入口、核心链路、关键代码与阅读地图 |
-| `requirements` | 需求、业务流程、技术方案、技术选型、可行性 | 问题定义、约束、候选方案、推荐与反转条件 |
-| `architecture` | 系统边界、架构设计、高可用、扩展性、一致性、评审 | 驱动因素、结构与数据流、质量属性、故障模型和架构取舍 |
-| `domain-learning` | 陌生概念、新技术、新行业、原理学习、技术地图 | 知识地图、核心机制、术语关系、技术生态与常见误区 |
-
-## 2. 混合模式
-
-混合请求先识别“当前阻止用户继续判断的主要未知”。按依赖顺序处理，例如：
-
-- Bug + 源码：先建立最短故障链，再补相关模块结构；
-- 需求 + 架构：先明确业务目标与质量属性，再比较架构；
-- 新领域 + 技术选型：先建立概念和约束，再做产品或技术比较；
-- 源码 + 二次开发方案：先理解现有扩展点，再讨论方案；
-- 架构 + Bug：若事故正在发生，先解释故障机制；若是长期治理，先明确架构压力。
-
-在主产物记录：
-
-- `primary_mode`；
-- `secondary_modes`；
-- `mode_order`；
-- 每个模式的进入条件与退出条件。
-
-## 3. 不应由本 Work 独立承担的情况
-
-- 必须运行实验、测试或插桩才能继续定位：移交 `<Path>{roots.workflows}/specdev/D-diagnose-bugs/D-diagnose-bugs.md</Path>`；
-- 调查面过大、需多 Agent 或并行领取未知项：移交 `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>`；
-- 需要正式锁定产品行为和验收：移交 `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`；
-- 需要正式架构候选接受与 ADR 同步：移交 `<Path>{roots.workflows}/specdev/R-review-architecture/R-review-architecture.md</Path>` 或 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`；
-- 用户要求实施、修复或提交：本 Work 先完成解释与边界说明，再按治理路线移交，不自行执行。
-
-## 4. 路由变更
-
-新证据改变主问题时可以切换模式，但必须：
-
-1. 在 MLOG 记录旧模式为何不足；
-2. 标记旧结论仍有效、被限制或被替代的部分；
-3. 更新 frontmatter 的模式与阶段；
-4. 不重复加载无关专项协议。