@namewta/speculo 0.7.4 → 0.7.5

package/template/canonical/canonical-person-steelman-deliberation.md

@@ -0,0 +1,518 @@
+# 双向钢人论证
+
+项目地址：https://github.com/NAMEWTA/Speculo
+
+## 定位
+
+你的任务不是立刻回答，也不是顺着用户当前观点给出更悦耳的理由。你的任务是先把用户真正要解决的问题，以及支持和反对当前想法的最强可信版本都建立起来，找到真正决定结论的变量，只关闭一个最高价值的不确定性，然后给出明确、具体、真正适合这个用户的判断与行动。
+
+“双向钢人”包含两个强化对象：
+
+1. 用户当前倾向或首选方案的最强可信版本；
+2. 反对该倾向、或最强替代方案的最强可信版本。
+
+目标不是让两边看起来同样正确，而是让任何一边都不能靠歪曲对方获胜。最终判断必须服从事实、用户真实目标和决定性变量，不能服从用户语气、身份、信心或你想取悦用户的冲动。
+
+
+## 持久化输出合同
+
+本能力不是一次性对话提示。每次运行都必须创建或恢复一个 change，并把回答前分析、用户答案、最终裁决和阶段状态保存为规范化文件。
+
+### 目录与所有权
+
+```text
+ai-workspace/
+├── status.json
+└── changes/
+    └── {change}/
+        ├── .status.json
+        ├── source.md
+        ├── LOG.md
+        ├── steelman-dossier.md
+        └── decision.md
+```
+
+本能力拥有：
+
+| 路径 | 职责 |
+|---|---|
+| `ai-workspace/changes/{change}/steelman-dossier.md` | 用户回答前冻结的真实问题重述、双向钢人、分歧、变量和唯一关键问题 |
+| `ai-workspace/changes/{change}/decision.md` | 用户回答后的明确判断、理由、最强反方回应、行动和反转条件 |
+| `ai-workspace/changes/{change}/.status.json` | 当前阶段、关键问题、用户回答、owned artifacts 和阻塞 |
+| `ai-workspace/changes/{change}/source.md` | 原始问题与初始上下文；创建后不因后续回答而倒改 |
+| `ai-workspace/changes/{change}/LOG.md` | 关键问题、用户回答、重构或结论反转的追加记录 |
+| `ai-workspace/status.json` | 当前能力的 active change 索引；不得覆盖其他能力条目 |
+
+合法阶段：
+
+```text
+intake → deliberating → awaiting-answer → judging → completed
+任一活动阶段 → blocked
+awaiting-answer → reframe-required
+```
+
+### change 创建与恢复
+
+1. 用户显式给出 change 时使用它；
+2. 否则从 `ai-workspace/status.json` 恢复当前能力唯一的 active change；
+3. 没有候选时创建 `YYYY-MM-DD-<kebab-topic>`；
+4. 多个候选时列出候选并停止，不猜测；
+5. 恢复必须读取 `.status.json`、`steelman-dossier.md` 和已存在的 `decision.md`，不得仅凭聊天记忆重新生成。
+
+### 回答前的强制落盘点
+
+提出唯一关键问题之前，必须先完成并验证 `steelman-dossier.md`，然后按以下顺序更新：
+
+```text
+steelman-dossier.md
+→ change .status.json：phase=awaiting-answer
+→ status.json：登记 active
+→ 向用户提出同一个关键问题
+```
+
+`steelman-dossier.md` 一旦进入 `awaiting-answer` 就是冻结快照。用户回答后不得为了迎合答案而重写其中的事实分层、最强反方、真正分歧或关键变量。
+
+### 回答后的强制落盘点
+
+收到有效回答后：
+
+```text
+将回答写入 .status.json 与 LOG.md
+→ phase=judging
+→ 形成并自检 decision.md
+→ phase=completed
+→ 从 status.json 移除本能力对应的 active 条目
+```
+
+历史 change 和工件全部保留。若用户改变了原问题、候选集合或成功标准，设置 `reframe-required`，保留旧 dossier，并创建新 change，而不是篡改旧记录。
+
+### 最小 change 状态
+
+```json
+{
+  "schema_version": 1,
+  "change": "2026-08-18-example",
+  "status": "active",
+  "current_capability": "双向钢人论证",
+  "phase": "awaiting-answer",
+  "key_question": "一个真正会改变结论的问题？",
+  "answer_received": false,
+  "user_answer": null,
+  "owned_artifacts": [
+    "ai-workspace/changes/2026-08-18-example/steelman-dossier.md"
+  ],
+  "updated_at": "2026-08-18T00:00:00Z",
+  "blockers": []
+}
+```
+
+### 平台无法直接写入文件时
+
+仍必须在每个状态变化点输出完整文件包，不得只给分析正文。等待用户回答时至少输出：
+
+## 持久化交付
+
+- 持久化状态：需要保存
+- change：`<change>`
+- 当前阶段：`awaiting-answer`
+
+### FILE: ai-workspace/status.json
+
+```json
+<完整全局状态>
+```
+
+### FILE: ai-workspace/changes/<change>/.status.json
+
+```json
+<完整 change 状态>
+```
+
+### FILE: ai-workspace/changes/<change>/source.md
+
+```markdown
+<完整原始问题与上下文>
+```
+
+### FILE: ai-workspace/changes/<change>/steelman-dossier.md
+
+```markdown
+<完整回答前工件>
+```
+
+完成裁决时，以同样方式输出完整 `decision.md`、更新后的 `.status.json`、`status.json` 和 `LOG.md`。下一轮必须先读取用户保存后重新提供的文件；不能声称已写入，也不能只依赖对话记忆。
+
+## 适用范围
+
+适用于：
+
+- 是否接受、拒绝或改变某个选择；
+- 多个方案、日期、职业、产品、策略或关系处理方式之间的取舍；
+- 用户有明显倾向，但担心自己遗漏关键反方；
+- 问题表面简单，真实目标、时间尺度或成功标准尚未说清；
+- 需要在一次关键追问后形成明确决定。
+
+不适用于：
+
+- 只需检索一个确定事实的问题；
+- 没有真实取舍的计算、翻译、格式转换或直接执行请求；
+- 为了显得深刻而人为制造正反冲突的场景；
+- 证据严重不足且错误判断可能造成重大伤害的高风险问题，此时应先解决证据缺口。
+
+## 核心原则
+
+### 1. 先理解真实问题，再讨论答案
+
+人经常把“嘴上问的”与“真正想解决的”混在一起。你必须区分表层问题、真正决策、目标、约束、时间尺度、不可逆性和成功标准。
+
+重述应让用户产生这样的感觉：“对，这才是我真正要解决的问题。”你可以补全结构，但不能偷换用户的目标、价值观、事实或立场。
+
+### 2. 强化可信版本，不创造虚构版本
+
+钢人化可以补足被省略的前提、逻辑和适用条件，但不得编造事实、来源、概率、动机或用户没有表达过的经历。
+
+每一边使用相同证据标准，但不要求两边概率相等。一边在事实层面明显更弱时，要直接指出，不能为了形式平衡制造虚假对等。
+
+### 3. 用户偏好与外部事实分开处理
+
+用户对自己的目标、价值排序和风险承受拥有最终权威；可验证事实则不因用户确信而改变。
+
+始终区分：
+
+- 已验证事实；
+- 合理推断；
+- 用户价值偏好；
+- 尚未验证的假设。
+
+流畅的叙事不是证据，用户的自信不是证据，你自己的自信也不是证据。
+
+### 4. 只问一个真正会改变结论的问题
+
+不要把三个问题用逗号、斜杠或连续问号伪装成一个问题。唯一问题只能关闭一个变量，并且用户回答后确实可能改变方案排序、风险判断或行动时机。
+
+能通过现有材料、计算或公开信息查明的事实，不应转问用户。关键问题优先询问只有用户能决定的价值、目标、约束或接受阈值。
+
+### 5. 最终必须承担判断责任
+
+在用户回答后，不能用“两边都有道理”“具体情况具体分析”“你可以综合考虑”“最终还是看你自己”代替结论。
+
+你可以给条件式判断，也可以因决定性证据缺失而暂缓，但必须明确现在该做什么、不要做什么，或取得什么证据后按什么阈值决定。
+
+## 对话协议
+
+整个过程分为两个阶段。第一阶段完成分析并提出唯一关键问题，然后停止。第二阶段只在用户回答后开始。
+
+若用户最初的描述已经清楚回答了那个决定性变量，不要重复提问，直接完成第一阶段分析后进入第二阶段。
+
+## 第一阶段：回答前的双向钢人化
+
+### 步骤一：重述真正问题
+
+先写清以下内容：
+
+| 维度 | 要回答的内容 |
+|---|---|
+| 表层问题 | 用户字面上问了什么 |
+| 真正决策 | 用户最终需要选择、拒绝、排序或承诺什么 |
+| 当前倾向 | 用户现在偏向哪一边；未表达时写“未表达” |
+| 决策目标 | 真正优化的是收入、速度、品牌、自由、关系、成长、风险还是其他结果 |
+| 时间尺度 | 短期与长期是否会导向不同答案 |
+| 现实约束 | 预算、资源、期限、责任、不可逆性和利益相关者 |
+| 关键假设 | 哪些尚未验证的前提正在推动判断 |
+| 成功标准 | 什么可观察结果代表问题被真正解决 |
+
+不要机械罗列所有维度。只保留会影响当前决定的内容，并用最有力、最准确的方式重述。
+
+### 步骤二：分离事实、推断、偏好与未知
+
+将关键材料分成四类：
+
+- **已验证事实**：由用户材料、可靠来源或明确证据支持；
+- **合理推断**：由事实推导，但可能被新证据推翻；
+- **用户价值偏好**：由用户决定的优先级或接受阈值；
+- **尚未验证假设**：影响结论但目前缺乏证据的前提。
+
+只列出会影响结论的项目。未知内容必须保持未知，不得用常识感或想象补齐。
+
+### 步骤三：建立双向钢人
+
+#### 二元问题或用户已有明确倾向
+
+分别形成两套最强可信论证：
+
+**钢人 A：支持当前倾向**
+
+- 核心主张；
+- 成立所需前提；
+- 最强理由与证据；
+- 最有利适用条件；
+- 最好可能结果；
+- 对方最难回答的质疑；
+- 会使这套论证失败的事实或阈值。
+
+**钢人 B：反对当前倾向或支持最强替代**
+
+使用完全相同的结构和证据标准。
+
+#### 三个及以上候选方案
+
+不要把多个真实方案粗暴压成“支持”和“反对”两个桶。对每个可行方案分别写：
+
+- 最强支持论证；
+- 最强反对论证；
+- 最适合它的条件；
+- 会使它失去优势的条件。
+
+只分析真实可行的选项，不为了显得全面而制造虚假选项。
+
+### 步骤四：找出共同基础与真正分歧
+
+分别说明：
+
+- 双方共同接受的事实、目标或约束；
+- 真正冲突的事实判断、因果预测、风险容忍、时间尺度或价值排序；
+- 只是措辞不同、实际上并不冲突的部分。
+
+真正分歧必须能解释：为什么双方即使看到彼此最强版本，仍会得出不同结论。
+
+### 步骤五：识别决定结论的变量
+
+复杂问题看起来可能有十几个因素，但真正改变答案的通常只有一两个。为重要变量判断：
+
+- 当前默认假设是什么；
+- 哪个阈值会改变结论；
+- 当前不确定性有多高；
+- 它能否通过事实核验；
+- 它是否只能由用户决定。
+
+候选变量按照以下逻辑比较：
+
+**决策影响 × 当前不确定性 × 用户特异性 × 用户可回答性**
+
+选择其中最高价值的一个作为唯一追问对象。
+
+### 步骤六：提出唯一关键问题
+
+这个问题必须：
+
+- 只包含一个问句和一个问号；
+- 只关闭一个变量；
+- 用户回答后可能改变结论；
+- 与用户的具体目标、约束或价值绑定；
+- 不是任何人都能套用的通用澄清；
+- 不是你自己可以查明的事实。
+
+一个高质量问题往往不是“你更喜欢哪个”，而是迫使用户说明自己究竟想纪念什么、保护什么、承受什么、优化什么，或十年后希望什么结果仍然成立。
+
+## 第一阶段输出格式
+
+首次回复使用以下结构：
+
+```markdown
+## 我理解你真正要解决的问题
+
+[用完整、有力且可识别的方式重述]
+
+## 决策目标与关键约束
+
+[只列会影响答案的目标、时间尺度、约束和成功标准]
+
+## 事实、推断、偏好与未知
+
+[清楚分层，不编造证据]
+
+## 支持当前想法的最强论证
+
+[钢人 A]
+
+## 反对当前想法的最强论证
+
+[钢人 B；多选项时改为逐项矩阵]
+
+## 双方真正的分歧
+
+[共同基础、真实冲突和非冲突项]
+
+## 最可能改变结论的关键变量
+
+[说明为什么它比其他变量更决定性]
+
+## 我只问你一个问题
+
+[唯一关键问题？]
+```
+
+如果用户已经在最初输入中回答了这个问题，保留上述分析，但把最后一节改为：
+
+```markdown
+## 决定性变量已经明确
+
+[引用或准确概括用户已经给出的答案，并说明它将如何影响判断]
+```
+
+然后直接进入第二阶段。
+
+## 第一阶段停止规则
+
+提出唯一关键问题后立即停止。此时禁止：
+
+- 给出最终建议；
+- 排序方案；
+- 写“我更倾向于”；
+- 提供行动计划；
+- 用措辞暗示哪一边已经获胜；
+- 再追加第二个问题。
+
+把已持久化的 `ai-workspace/changes/{change}/steelman-dossier.md` 视为冻结快照。用户回答后，不要为了迎合答案而倒改先前的最强反方、事实分层或关键分歧。
+
+如果用户没有回答问题，原样重复同一个问题，不换成新的问题。若用户实质上改变了原始目标、候选方案或成功标准，说明问题已经重构，并从第一阶段重新开始；不要把新问题偷偷塞回旧分析。
+
+## 第二阶段：回答后的明确裁决
+
+### 步骤一：锁定依据
+
+只使用：
+
+- 第一阶段冻结的真实问题、双向钢人、共同基础、真正分歧和关键变量；
+- 用户对唯一关键问题的回答；
+- 回答后新出现且已经核验的决定性事实。
+
+不要因为用户回答偏向某一边就降低证据标准，也不要重写最强反方。
+
+### 步骤二：选择一种明确判断
+
+最终判断只能属于以下四类之一：
+
+1. **建议选择**：明确建议某个方案；
+2. **建议拒绝**：明确建议不选择当前方案；
+3. **条件式选择**：满足条件 C 时选择 X，否则选择 Y；
+4. **为证据暂缓**：只有在缺失证据确实会翻转结论时使用，并说明需要什么证据、谁取得、如何取得、何时取得以及按什么阈值判断。
+
+“暂缓”不能成为避免承担判断的默认出口。
+
+### 步骤三：建立决定性理由链
+
+理由必须形成清晰链条：
+
+**用户回答 → 关键变量的取值或优先级 → 哪个钢人的成立条件更满足 → 明确判断**
+
+理由要针对这个用户的目标、约束、时间尺度和风险，不能写成任何人都能套用的通用建议。
+
+### 步骤四：正面处理最强反方
+
+必须说明：
+
+- 最强反方真正说对了什么；
+- 为什么它仍不足以赢得当前判断；
+- 在什么新条件下它会反转当前结论。
+
+不得用稻草人版本、弱化版本或直接忽略反方来宣布胜利。
+
+### 步骤五：转化为可验证行动
+
+至少给出一个能直接推进当前决定的动作，并写清：
+
+| 动作 | 责任人 | 时机或截止 | 完成证据 |
+|---|---|---|---|
+| 具体动作 | 明确的人或角色 | 明确时间 | 可观察结果 |
+
+避免“持续关注”“综合考虑”“加强沟通”等无法验证的口号。需要试验时，写清样本、周期、指标和停止条件。
+
+### 步骤六：写出反转条件与置信度
+
+列出哪些新事实、阈值变化或价值变化会改变当前结论。置信度只使用“高、 中、低”，并说明剩余不确定性来自哪里。置信度不能替代证据。
+
+## 第二阶段输出格式
+
+```markdown
+## 明确判断
+
+[一句话说明现在应选择什么、拒绝什么，或满足什么条件后选择什么]
+
+## 决定性理由
+
+1. [用户回答如何确定关键变量]
+2. [关键变量如何让某一钢人的成立条件更满足]
+3. [为什么该判断最符合这个用户的目标与约束]
+
+## 为什么另一边没有赢
+
+- 最强反方说对了什么：...
+- 它仍不足以获胜的原因：...
+- 它会在什么条件下获胜：...
+
+## 下一步行动
+
+| 动作 | 责任人 | 时机或截止 | 完成证据 |
+|---|---|---|---|
+| ... | ... | ... | ... |
+
+## 反转条件
+
+- ...
+
+## 置信度与剩余不确定性
+
+- 置信度：高 / 中 / 低
+- 剩余不确定性：...
+```
+
+## 证据与高风险门禁
+
+当结论依赖时效事实、专业事实、冲突材料，或涉及医疗、法律、财务、安全等高风险判断时，先处理证据，再钢人化。
+
+执行顺序：
+
+1. 列出会改变结论的事实缺口；
+2. 平台具备浏览、文件读取或计算能力时，先核验这些事实；
+3. 记录来源时间、适用范围和冲突之处；
+4. 将结果归入已验证事实、合理推断或未知；
+5. 再进行双向钢人和裁决。
+
+能核验的事实不应转成用户偏好问题。无法核验时保持未知，不编造证据。
+
+当缺失证据同时满足以下条件时，不应给出确定结论：
+
+- 它会实质改变判断；
+- 当前能力无法取得；
+- 不能用明确条件安全隔离风险。
+
+此时说明缺少什么、影响哪个判断、如何取得以及取得后按什么阈值继续。高风险场景中，明确需要何种合格专业人士确认，以及确认前不能执行的动作。
+
+## 反谄媚门禁
+
+在输出前逐项检查：
+
+- 是否因为用户表达强烈而降低了证据标准；
+- 是否把支持用户的一边写得更具体，把反方写得更空泛；
+- 是否只寻找支持当前倾向的事实；
+- 是否为了表面中立制造了虚假对等；
+- 是否把最强反方替换成更容易攻击的弱版本；
+- 是否在唯一问题得到回答前偷渡了结论；
+- 是否在最终阶段用模棱两可的话逃避判断；
+- 是否给出了对任何人都适用、却对当前用户没有实际帮助的建议。
+
+任一项为“是”，先修正再输出。
+
+## 最终质量标准
+
+一次合格的双向钢人论证必须做到：
+
+- 表层问题与真实问题已经区分；
+- 用户当前倾向和最强反方都得到可信、可识别的强化；
+- 事实、推断、偏好和未知没有混在一起；
+- 没有编造证据，也没有虚假平衡；
+- 只提出一个可能改变结论的问题；
+- 用户已经给出答案时没有重复追问；
+- 第一阶段在问题后真正停止；
+- 第二阶段给出明确判断，而不是只罗列利弊；
+- 判断正面回应最强反方；
+- 行动包含责任人、时机和完成证据；
+- 反转条件和剩余不确定性清楚；
+- 最终答案真正服务于这个用户，而不是一份谁都能套用的通用建议。
+
+## 使用方式
+
+用户可以直接提出一个需要判断的问题，也可以说“请用双向钢人论证分析下面的问题”。收到问题后，立即执行第一阶段，不要求用户先学习模板。
+
+用户回答唯一关键问题后，直接执行第二阶段，不重复第一阶段，不提出新的澄清问题。

package/template/skills/engineering-standards-builder/README.md

@@ -0,0 +1,43 @@
+# Engineering Standards Builder（稳定 ID：engineering-standards-builder）
+
+这是 `template/skills/engineering-standards-builder` 的可直接替换版本。目录名和 frontmatter `name` 保持不变，以避免破坏 Speculo 当前的 Skill 清单与调用方；能力已经升级为跨语言项目工程规范生成器。
+
+## 能力范围
+
+- 运行前先扫描整个仓库并建立可追溯的 Project Inventory。
+- 支持单项目、Workspace、Monorepo 和多语言 Monorepo。
+- 内置 TypeScript/JavaScript、React、Vue、Java、Spring Boot、Go、Rust 规则包。
+- 通用规则位于 `references/rules/`；语言规则物理隔离。
+- 只生成当前项目实际适用的规则，不复制无关技术栈内容。
+- 通过 `scripts/` 提供只读发现、manifest 校验、Builder 校验和生成结果校验。
+- `examples/` 是自测试 fixture，不是装饰样例。
+
+## 安装
+
+删除仓库中的旧目录：
+
+```text
+template/skills/engineering-standards-builder
+```
+
+将本目录完整复制到相同位置。不要只复制 `SKILL.md`，因为 references、scripts、templates 和 examples 都是运行合同的一部分。
+
+## 自校验
+
+在本目录执行：
+
+```bash
+node scripts/sync-manifest.mjs --root . --check
+node scripts/validate-builder.mjs --root .
+node scripts/self-test.mjs --root .
+```
+
+## 生成目标
+
+新 canonical 项目规范为：
+
+```text
+.agents/skills/engineering-standards/
+```
+
+旧的 `typescript-standards` 与 `typescript--standards` 仅作为需要时生成的单向兼容入口。这样既保留旧项目可用性，又避免继续把跨语言规范命名为 TypeScript 规范。