@namewta/speculo 0.4.0 → 0.6.0

package/template/workflows/specdev/common/rules/codebase-design.md

@@ -0,0 +1,148 @@
+# 代码仓设计
+
+设计**深层模块**：通过一个小接口承载大量行为，放置在干净的缝合点处，可通过该接口进行测试。在任何设计或重构代码的地方使用这些语言和原则。目标是为调用者提供杠杆效应，为维护者提供局部性，为所有人提供可测试性。
+
+使用 `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` 和 `<Path>{roots.state}/specdev/context/</Path>` 的词汇谈论领域；使用本规则的词汇谈论架构。
+
+## 术语表
+
+严格使用以下术语 — 不要用 "component"、"service"、"API" 或 "boundary" 替代。一致的语言才是重点。
+
+**Module（模块）** — 任何具有接口和实现的东西。有意识地与规模无关：函数、类、包或跨层切片。_避免使用_：unit、component、service。
+
+**Interface（接口）** — 调用者正确使用模块所需了解的一切：类型签名，还包括不变量、顺序约束、错误模式、必需配置和性能特征。_避免使用_：API、signature（太窄 — 它们仅指类型层面的表面）。
+
+**Implementation（实现）** — 模块内部的内容，它的代码体。区别于 **Adapter（适配器）**：一个东西可以是一个小适配器加一个大实现（Postgres 仓库），也可以是一个大适配器加一个小实现（内存假实现）。当讨论缝合点时用 "adapter"；否则用 "implementation"。
+
+**Depth（深度）** — 接口处的杠杆效应：调用者（或测试）每学习一个单位的接口可以驱动的行为量。当大量行为隐藏在小接口后面时，模块是**深层的**；当接口几乎和实现一样复杂时，模块是**浅层的**。
+
+**Seam（缝合点）** _(Michael Feathers)_ — 一个可以在不编辑该位置的情况下改变行为的地方；模块接口所在的*位置*。缝合点放在哪里本身就是一个设计决策，与缝合点后面放什么不同。_避免使用_：boundary（与 DDD 的有界上下文重载）。
+
+**Adapter（适配器）** — 在缝合点处满足接口的具体事物。描述的是*角色*（它填充哪个槽位），而非实质（内部是什么）。
+
+**Leverage（杠杆效应）** — 调用者从深度中获得的好处：每学习一个单位的接口获得更多的能力。一个实现为 N 个调用点和 M 个测试带来回报。
+
+**Locality（局部性）** — 维护者从深度中获得的好处：变更、bug、知识和验证集中在一个地方，而非分散在调用者之间。一次修复，处处生效。
+
+## 深层 vs 浅层
+
+**深层模块** = 小接口 + 大量实现：
+
+```text
+┌─────────────────────┐
+│   小接口             │  ← 少量方法，简单参数
+├─────────────────────┤
+│                     │
+│  深层实现            │  ← 隐藏的复杂逻辑
+│                     │
+└─────────────────────┘
+```
+
+**浅层模块** = 大接口 + 少量实现（应避免）：
+
+```text
+┌─────────────────────────────────┐
+│       大接口                     │  ← 大量方法，复杂参数
+├─────────────────────────────────┤
+│  薄实现                          │  ← 仅仅是透传
+└─────────────────────────────────┘
+```
+
+设计接口时，问自己：
+
+- 我能减少方法数量吗？
+- 我能简化参数吗？
+- 我能隐藏更多内部的复杂性吗？
+
+## 原则
+
+- **深度是接口的属性，而非实现的属性。** 一个深层模块内部可以由小型、可模拟、可替换的部分组成 — 只是它们不属于接口的一部分。一个模块可以拥有**内部缝合点**（对其实现私有，用于其自身测试）以及位于其接口处的**外部缝合点**。
+- **删除测试。** 想象删除这个模块。如果复杂性消失，它就是个透传层。如果复杂性在 N 个调用者中重新出现，它就在发挥价值。
+- **接口就是测试表面。** 调用者和测试穿过同一个缝合点。如果你想测试接口_之外_的内容，模块可能形状不对。
+- **一个适配器意味着假设的缝合点。两个适配器意味着真实的缝合点。** 除非有东西确实在缝合点两侧变化，否则不要引入缝合点。
+
+## 为可测试性而设计
+
+良好的接口使测试变得自然：
+
+1. **接收依赖，不要创建依赖。**
+
+   ```typescript
+   // 可测试
+   function processOrder(order, paymentGateway) {}
+
+   // 难以测试
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **返回结果，不要产生副作用。**
+
+   ```typescript
+   // 可测试
+   function calculateDiscount(cart): Discount {}
+
+   // 难以测试
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **小表面积。** 更少的方法 = 更少的测试需求。更少的参数 = 更简单的测试设置。
+
+## 关系
+
+- 一个 **Module** 恰好有一个 **Interface**（它向调用者和测试呈现的表面）。
+- **Depth** 是一个 **Module** 的属性，对照其 **Interface** 来度量。
+- 一个 **Seam** 是一个 **Module** 的 **Interface** 所在的位置。
+- 一个 **Adapter** 位于 **Seam** 处，满足 **Interface**。
+- **Depth** 为调用者产生 **Leverage**，为维护者产生 **Locality**。
+
+## 已拒绝的框架
+
+- **深度作为实现行数与接口行数之比** (Ousterhout)：奖励填充实现。我们使用深度即杠杆效应来替代。
+- **"Interface" 作为 TypeScript 的 `interface` 关键字或类的公开方法**：太窄 — 此处的接口包括调用者必须了解的每个事实。
+- **"Boundary"**：与 DDD 的有界上下文重载。说 **seam** 或 **interface**。
+
+## 深化
+
+如何在给定依赖关系的情况下，安全地深化一组浅模块。假定你已掌握上面的词汇 — **module**（模块）、**interface**（接口）、**seam**（接缝）、**adapter**（适配器）。
+
+### 依赖类别
+
+在评估一个深化候选时，对其依赖进行分类。类别决定了深化后的模块如何通过其缝合点进行测试。
+
+#### 1. 进程内
+
+纯计算、内存状态、无 I/O。始终可深化 — 合并模块并通过新接口直接测试。不需要适配器。
+
+#### 2. 本地可替换
+
+具有本地测试替代品的依赖（PGLite 替代 Postgres、内存文件系统）。如果存在替代品则可深化。深化后的模块在测试套件中使用运行的替代品进行测试。接缝是内部的；在模块的外部接口处不需要端口。
+
+#### 3. 远程但自有（端口与适配器）
+
+跨网络边界的自有服务（微服务、内部 API）。在接缝处定义一个 **port**（端口，即接口）。深模块拥有逻辑；传输层作为 **adapter**（适配器）注入。测试使用内存适配器。生产环境使用 HTTP/gRPC/队列适配器。
+
+建议形式：*"在接缝处定义一个端口，为生产环境实现 HTTP 适配器，为测试实现内存适配器，这样逻辑就驻留在一个深模块中，即使它跨网络部署。"*
+
+#### 4. 真正的外部依赖（Mock）
+
+你无法控制的第三方服务（Stripe、Twilio 等）。深化后的模块将外部依赖作为注入端口；测试提供一个 mock 适配器。
+
+### 接缝纪律
+
+- **一个适配器意味着假设性接缝。两个适配器意味着真正的接缝。** 除非至少有两个适配器是合理的（通常是生产 + 测试），否则不要引入端口。单一适配器的接缝只是间接层。
+- **内部接缝 vs 外部接缝。** 一个深模块可以既有内部接缝（对其实现私有，供其自身的测试使用），也有其接口处的外部接缝。不要仅仅因为测试使用了内部接缝就通过接口暴露它们。
+
+### 测试策略：替换，而非叠加
+
+- 一旦深化后模块接口的测试存在，旧有浅模块上的单元测试就变成了废料 — 删除它们。
+- 在深化后模块的接口处编写新测试。**接口就是测试表面**。
+- 测试通过接口断言可观察的结果，而非内部状态。
+- 测试应经受住内部重构 — 它们描述的是行为，而非实现。如果测试在实现改变时必须更改，那它就是在测试接口之后的东西。
+
+## SpecDev 应用边界
+
+扫描前先划定范围并遵循 YAGNI。用户指定 module、子系统或痛点时直接采用；否则从足够长的 Git 历史识别反复变化的热点，只有热点不明确时才扩大范围。实现中的局部设计遵守 Ticket/Spec；需要改变公共契约、数据、安全、兼容、范围、迁移或验收时返回拥有该决定的上游工件。

package/template/workflows/specdev/common/schemas/design-tree.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:specdev:design-tree:v1",
+  "title": "SpecDev Grilling Design Tree",
+  "type": "object",
+  "required": ["schema_version", "artifact", "change", "status", "round", "nodes"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "artifact": { "const": "design-tree" },
+    "change": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["active", "consensus", "blocked"] },
+    "round": { "type": "integer", "minimum": 0 },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "question", "depends_on", "recommendation", "status", "round", "answer", "log_ref"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^D-[0-9]{3,}$" },
+          "title": { "type": "string", "minLength": 1 },
+          "question": { "type": "string", "minLength": 1 },
+          "depends_on": { "type": "array", "items": { "type": "string", "pattern": "^D-[0-9]{3,}$" } },
+          "recommendation": { "type": "string", "minLength": 1 },
+          "status": { "enum": ["open", "answered", "deferred", "rejected"] },
+          "round": { "type": ["integer", "null"], "minimum": 1 },
+          "answer": { "type": ["string", "null"] },
+          "log_ref": { "type": ["string", "null"], "pattern": "^LOG-[0-9]{3,}$" }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}
+

package/template/workflows/specdev/common/schemas/wayfinder-ticket.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:specdev:wayfinder-ticket:v1",
+  "title": "SpecDev Wayfinder Ticket Frontmatter",
+  "type": "object",
+  "required": ["artifact", "id", "name", "parent_map", "label", "status", "blocked_by", "resolution"],
+  "properties": {
+    "artifact": { "const": "wayfinder-ticket" },
+    "id": { "type": "string", "pattern": "^INV-[0-9]{2,}$" },
+    "name": { "type": "string", "minLength": 1 },
+    "parent_map": { "type": "string", "minLength": 1 },
+    "label": { "enum": ["wayfinder:research", "wayfinder:prototype", "wayfinder:grilling", "wayfinder:task"] },
+    "status": { "enum": ["open", "closed"] },
+    "blocked_by": { "type": "array", "items": { "type": "string", "pattern": "^INV-[0-9]{2,}$" } },
+    "resolution": { "enum": [null, "answered", "out-of-scope", "superseded", "cancelled"] }
+  },
+  "additionalProperties": false
+}
+

package/template/workflows/specdev/common/skills/subagent-delivery/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: subagent-delivery
+description: 交付合同：为 Goal Plan 生成可恢复的 direct、原生或外部网页 Agent 派单，并在 Implement 阶段核对基线、候选交付、修正和 Lead 验收。
+---
+
+# SpecDev Subagent Delivery
+
+本 Skill 管理一次 **Agent 交付合同**：规划时把 Ticket 压缩成可独立投递的派单块，执行时按同一合同恢复、核对并验收交付。它不拥有新的状态目录；Goal Plan、Ticket、Evidence 和 change 状态仍由调用 work 写入。
+
+## 输入
+
+- `operation`：`plan` 或 `execute`；
+- `execution_model`：`direct`、`native-subagent` 或 `external-web-subagent`；
+- Lead、Ticket、Goal Plan、Spec、适用 ADR/CONTEXT、Wave/Gate 和依赖 Evidence；
+- 项目写、只读和 shared 路径，验证矩阵与当前源码基线；
+- provider、会话或 workspace locator、源码交付方式，以及用户当前明确授权。
+
+缺失 Goal Plan 的 `direct` Ticket 可以由 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>` 按 Ticket 契约执行；其他输入缺失时返回调用方补齐，不猜测 checkpoint、权限或验收结果。
+
+## 流程
+
+### 1. 固定 Lead、模型与权限
+
+一个交付链只有一个 Lead。Lead 保留需求解释、仓库保护、Wave/Gate、shared owner、权限控制、交付集成、独立验收和最终状态同步责任。
+
+将本次请求解析为逐动作授权：local changes、commit、push、PR、merge、deploy、migration、production configuration、production feature 和 real user data。未明确授权的动作记为 `not-authorized`；项目指令、历史授权和 Agent 建议不扩大权限。
+
+**完成标准**：`operation` 和 `execution_model` 唯一；Lead、授权动作、目标和条件均可判定。
+
+### 2. 固定源码与恢复基线
+
+记录不可变 `base_sha` 或等价本地基线、分支、`workspace_ref`、工作区状态和适用外部合同版本。GitHub 是源码事实来源时，加载 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/references/github-checkpoints.md</Path>`；需要固定附件、私有上下文或未提交改动时，再加载 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/references/source-package.md</Path>`。
+
+`workspace_ref`、session locator 和附件 locator 必须可迁移，不写机器绝对路径、认证秘密或真实用户数据。
+
+**完成标准**：每次派单、恢复、修正和验收都能定位到同一源码与合同版本。
+
+### 3. 加载执行分支
+
+- `direct`：直接使用 Ticket、Goal Plan、`<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>` 和 Evidence 合同，不加载 provider 规则；
+- `native-subagent`：加载 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/references/native-subagent.md</Path>`，完成隔离派单、恢复和返回；
+- `external-web-subagent`：加载 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/references/external-web-subagent.md</Path>`，完成能力探测、会话恢复、候选交付与修正。
+
+**完成标准**：只加载当前执行模型和实际源码交付方式需要的 reference。
+
+### 4. 规划或执行交付合同
+
+`operation=plan` 时，向调用方返回：里程碑级 Delivery Contract，以及每个 Ticket 的独立 Dispatch Packet。每个派单块必须包含目标、权威输入、边界优先级、路径合同、依赖证据、基线、验证与反向验证、授权、恢复 locator、最多修正轮次和返回字段。调用方将它写入 `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`，不复制完整历史对话或 Ticket 全文。
+
+`operation=execute` 时，先核对派单块与当前 Goal Plan、Ticket、基线和权限；再接收原生 Worker 或外部 provider 的候选交付，检查范围与事实声明，由 Lead 运行适用验证，并把结果写入 `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>`。外部声明、截图或模拟结果在 Lead 复核前保持 `unverified`。
+
+**完成标准**：规划结果可独立投递；执行结果的每个 `pass` 都有 Lead 可复查证据。
+
+### 5. 收敛、阻塞与恢复
+
+同一验收项连续失败达到 Goal Plan 的 `max_correction_rounds` 后停止该 Ticket，记录最后基线、失败命令、最小错误、已通过行为、责任方和恢复条件。默认上限为 3；不得通过跳过测试、放宽断言、吞错、删除检查或越过路径合同制造完成。
+
+恢复时读取 Goal Plan 的派单块、Ticket、最新 Evidence 和 change/worktree 状态，从最后已验证 checkpoint 继续，不重新决定已锁定事项。完成或阻塞后向调用方返回 Ticket 状态、Evidence 完整路径、workspace/session locator、checkpoint、commit/PR 引用、未验证项和待 Lead E2E。
+
+**完成标准**：交付结束于 `review`、`done`、`blocked` 或 `deviated`；状态、Evidence、源码引用和恢复信息一致。
+

package/template/workflows/specdev/common/skills/subagent-delivery/references/external-web-subagent.md

@@ -0,0 +1,32 @@
+# 外部网页 Subagent 交付
+
+用户或已批准 Goal Plan 明确选择网页模型时加载；原生能力不足本身不授权向外部 provider 发送上下文。外部输出是候选交付，Lead 的本地核对决定验收状态。
+
+## 能力探测与会话
+
+首次使用或界面变化时实测并记录：provider、稳定 session locator、仓库访问、附件上传与返回、长任务状态和认证交接。Provider 名称只是标识；只有能力差异改变交付路径时才产生分支。
+
+登录、账号选择、密码、验证码、Passkey、两步验证、恢复码和 CAPTCHA 由用户在界面内完成。认证秘密不进入派单、源码包、Goal Plan 或 Evidence；发送仓库链接、源码或附件前还必须确认 provider 和内容范围已获授权。
+
+每个独立复杂 Ticket 使用独立会话；强耦合修正可以复用原会话。会话记录绑定 Ticket、branch、checkpoint、附件 hash、最近完整交付和修正轮次。恢复时先定位最后完整输出并核对 checkpoint；不可恢复时，新会话携带旧 locator、当前 checkpoint、已验收摘要和剩余事项。
+
+## 工程派单
+
+派单块必须提供：
+
+1. repository locator、branch、不可变 checkpoint 和源码包 hash；
+2. 用户结果、里程碑位置、相关模块、公共契约和领域不变量；
+3. allowed/read-only/shared 路径、保留行为和依赖策略；
+4. 需要返回的方案、修改清单、patch/源码、测试、实际命令和风险；
+5. 当前授权矩阵与逐项验收标准；
+6. 未实际运行的检查必须标记 `unverified`。
+
+公开仓库 URL 使用 `<Url>https://example.com/owner/repository</Url>` 形式并同时给出 branch 与 checkpoint。Provider 无法读取仓库、需要私有上下文或固定工作区快照时使用 source-package 分支。
+
+## 候选交付与修正
+
+Lead 在隔离工作区从派单 checkpoint 应用候选交付，核对附件 hash、修改范围、依赖与锁文件、数据和安全边界，再运行 Ticket 与 Goal Plan 要求的验证。模拟结果、provider 自报测试和静态推断分别标记，不替代本地或目标环境证据。
+
+修正请求必须包含未通过项、checkpoint、命令与退出状态、最小错误、项目位置、正确约束和必须保留的已通过行为。每轮重新核对 checkpoint、范围、受影响检查和验收矩阵；达到修正上限后形成 blocker。
+
+**完成标准**：每轮会话和候选交付绑定唯一基线；每个 `pass` 有 Lead 独立证据，未验证项保持显式。

package/template/workflows/specdev/common/skills/subagent-delivery/references/github-checkpoints.md

@@ -0,0 +1,24 @@
+# GitHub Checkpoint
+
+GitHub 仓库、Issue、PR 或分支是源码事实来源时加载。所有派单、源码包、修正和验收绑定精确 commit SHA，不使用浮动的“最新代码”。
+
+## 建立基线
+
+1. 解析 repository、目标 branch、remote、访问身份和获授权写入目标；
+2. 使用非 shallow clone，或证明现有 clone 具备任务所需历史；
+3. 读取项目 Agent 指令、构建清单、锁文件、CI 和相关源码/测试；
+4. 记录 local HEAD、tracking ref、远程 SHA 和工作区状态；
+5. 工作区有受保护改动时使用独立 worktree 或经批准的 checkpoint，不覆盖现有改动。
+
+```text
+REPO_CHECKPOINT repository=<owner/repo> branch=<branch>
+local_head=<sha> tracking_head=<sha> remote_head=<sha>
+working_tree=<clean|protected-changes> kind=<baseline|local|pushed|verified>
+```
+
+## 漂移与远程动作
+
+远程推进后先比较旧、新 SHA 的改动路径和影响，再决定重放、重派或拒绝旧交付。commit、push、PR、merge 各自只在授权矩阵允许时执行；远程写入后重新读取远程 SHA，并在本地与远程一致时建立下一 checkpoint。
+
+**完成标准**：每轮交付对应唯一 SHA；远程漂移和受保护改动不会静默改变基线。
+

package/template/workflows/specdev/common/skills/subagent-delivery/references/native-subagent.md

@@ -0,0 +1,35 @@
+# 原生 Subagent 交付
+
+当前 Lead 能直接创建和管理隔离 Agent 时加载。
+
+## 派单与隔离
+
+每个 Ticket 使用唯一 Agent 标识，并接收一个独立 Dispatch Packet：
+
+```text
+DISPATCH ticket=<id> wave=<wave> gate=<gate>
+baseline=<sha> branch=<branch> workspace=<workspace-ref>
+ticket_path=<full-ticket-path> evidence_path=<full-evidence-path>
+```
+
+派单块还必须给出项目 `writable_paths`、`read_only_paths`、`shared_paths`、完成的依赖 Evidence、合同 ID、验证矩阵、反向验证、权限和偏差升级方式。Agent 先核对基线与路径，再用不超过 10 行的开工回执记录目标、顺序和最大风险；回执写入 Ticket Evidence，不新增进度文件。
+
+并行写代码时由 Lead 调用 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`。所有并行 Ticket 固定同一 `base_sha`，使用独立分支和 `workspace_ref`；Agent 只修改获准项目路径，只把 Ticket 推进到 `review`。
+
+## 审查与修正
+
+候选交付必须同时通过：
+
+- 标准轴：正确性、架构、错误处理、安全、依赖和测试质量；
+- 规范轴：Spec、ADR、Ticket、Goal Plan、路径合同和验收映射；
+- Lead 复跑的定向验证与适用回归；
+- 对可能静默失效的门禁执行一次受控反向验证，并恢复绿色基线。
+
+失败时沿用同一 Agent 或建立明确继任者，返回失败标准、命令与退出状态、最小错误、文件位置、正确约束、当前 checkpoint 和必须保留的已通过行为。达到修正上限后标记 blocker，不无限重派。
+
+## 返回
+
+Agent 返回 Ticket 状态、`<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>`、`workspace_ref`、checkpoint、commit/PR 引用和待 Lead E2E。Lead 负责应用或集成、回归、Gate 判断和状态同步；逻辑冲突返回契约 owner，不机械选择某一侧版本。
+
+**完成标准**：派单、工作区、路径修改、审查、修正和返回均可由 Goal Plan、Evidence 与 change 状态恢复。
+

package/template/workflows/specdev/common/skills/subagent-delivery/references/source-package.md

@@ -0,0 +1,17 @@
+# Source Package
+
+外部 Agent 需要固定附件、私有上下文或受保护的未提交改动，且用户已授权目标 provider 与内容范围时加载。包位于调用方授权的临时位置；SpecDev 只在 Goal Plan 或 Evidence 记录可迁移 locator、manifest 摘要和 hash。
+
+## 范围与排除
+
+包应包含理解、修改和验证 Ticket 所需的最小完整源码、直接依赖、构建配置、锁文件、schema、测试、项目 Agent 指令，以及 Spec/Ticket/ADR/CONTEXT 的相关摘录。
+
+排除版本控制内部数据、依赖缓存、构建产物、日志、数据库、转储、浏览器状态、真实用户数据、环境文件、token、cookie、私钥、证书私钥、验证码和恢复码。环境说明只保留无真实值的示例。
+
+## 生成与核对
+
+优先从已提交 checkpoint 生成；包含受保护工作区改动时，manifest 必须列出基线和差异范围。使用仓库已有或可用的密钥扫描器，随后验证包可解压、文件清单、字节数和 SHA-256。
+
+Manifest 至少记录 repository、branch、checkpoint、工作区状态、包 locator、size、SHA-256、secret scan、included、excluded 和 workspace diff。源码变化后生成新 locator 和 hash，不覆盖旧包或沿用旧 manifest。
+
+**完成标准**：包可完整读取，来源与范围可复现，不包含凭据、运行状态或真实用户数据。