@namewta/speculo 0.3.0 → 0.3.2

package/template/workflows/specdev/I-implement/deepening.md

@@ -1,37 +1,17 @@
-# 深化
+# 深化与依赖策略
 
-如何在给定依赖关系的情况下，安全地深化一组浅模块。假定你已掌握 `<Path>{roots.workflows}/specdev/I-implement/codebase-design-glossary.md</Path>` 中的词汇 — **module**（模块）、**interface**（接口）、**seam**（接缝）、**adapter**（适配器）。
+## 依赖分类
 
-## 依赖类别
+1. 进程内稳定依赖：直接调用通常足够。
+2. 本地可替换依赖：在真实替换/测试需要处建立接缝。
+3. 远程但自有：封装协议、超时、重试、幂等和可观测性。
+4. 真正外部：适配器隔离版本、失败、限流和不可控变化。
 
-在评估一个深化候选时，对其依赖进行分类。类别决定了深化后的模块如何通过其接缝进行测试。
+不要为了“可测试”给每个类加接口。接缝应服务真实变化轴或高价值验证。
 
-### 1. 进程内
+## 深化问题
 
-纯计算、内存状态、无 I/O。始终可深化 — 合并模块并通过新接口直接测试。不需要适配器。
-
-### 2. 本地可替换
-
-具有本地测试替代品的依赖（PGLite 替代 Postgres、内存文件系统）。如果存在替代品则可深化。深化后的模块在测试套件中使用运行的替代品进行测试。接缝是内部的；在模块的外部接口处不需要端口。
-
-### 3. 远程但自有（端口与适配器）
-
-跨网络边界的自有服务（微服务、内部 API）。在接缝处定义一个 **port**（端口，即接口）。深模块拥有逻辑；传输层作为 **adapter**（适配器）注入。测试使用内存适配器。生产环境使用 HTTP/gRPC/队列适配器。
-
-建议形式：*"在接缝处定义一个端口，为生产环境实现 HTTP 适配器，为测试实现内存适配器，这样逻辑就驻留在一个深模块中，即使它跨网络部署。"*
-
-### 4. 真正的外部依赖（Mock）
-
-你无法控制的第三方服务（Stripe、Twilio 等）。深化后的模块将外部依赖作为注入端口；测试提供一个 mock 适配器。
-
-## 接缝纪律
-
-- **一个适配器意味着假设性接缝。两个适配器意味着真正的接缝。** 除非至少有两个适配器是合理的（通常是生产 + 测试），否则不要引入端口。单一适配器的接缝只是间接层。
-- **内部接缝 vs 外部接缝。** 一个深模块可以既有内部接缝（对其实现私有，供其自身的测试使用），也有其接口处的外部接缝。不要仅仅因为测试使用了内部接缝就通过接口暴露它们。
-
-## 测试策略：替换，而非叠加
-
-- 一旦深化后模块接口的测试存在，旧有浅模块上的单元测试就变成了废料 — 删除它们。
-- 在深化后模块的接口处编写新测试。**接口就是测试表面**。
-- 测试通过接口断言可观察的结果，而非内部状态。
-- 测试应经受住内部重构 — 它们描述的是行为，而非实现。如果测试在实现改变时必须更改，那它就是在测试接口之后的东西。
+- 能否让调用者少知道一个状态、顺序或错误分支？
+- 能否把重复策略收进单一模块？
+- 是否把外部 SDK 类型泄漏到领域层？
+- 是否有至少两个真实消费者/适配器证明抽象成立？

package/template/workflows/specdev/I-implement/design-it-twice.md

@@ -1,44 +1,9 @@
-# 设计两次
+# Design It Twice
 
-当用户想要为选定的深化候选探索替代接口时，使用此并行子 Agent 模式。基于"Design It Twice"（Ousterhout）— 你的第一个想法不太可能是最好的。
+只在 Ticket 允许局部设计自由、且两个方案会显著影响模块深度或测试接缝时使用。
 
-使用 `<Path>{roots.workflows}/specdev/I-implement/codebase-design-glossary.md</Path>` 中的词汇 — **module**（模块）、**interface**（接口）、**seam**（接缝）、**adapter**（适配器）、**leverage**（杠杆）。
+1. 在不改代码的情况下提出两个最小接口草图。
+2. 比较调用者复杂度、信息隐藏、错误语义、迁移成本和测试策略。
+3. 选择更深、更局部、与 Ticket 契约一致的方案，并记录为局部实现决定。
 
-## 流程
-
-### 1. 界定问题空间
-
-在启动子 Agent 之前，为选定候选编写一份面向用户的问题空间说明：
-
-- 任何新接口需要满足的约束条件
-- 它将依赖的依赖项，以及它们属于哪个类别（参见 `<Path>{roots.workflows}/specdev/I-implement/deepening.md</Path>`）
-- 一个粗略的示例代码草图来使约束具体化 — 不是提案，只是让约束变得具体的一种方式
-
-将此展示给用户，然后立即进入第 2 步。用户在子 Agent 并行工作时阅读和思考。
-
-### 2. 启动子 Agent
-
-使用 Agent 工具并行启动 3+ 个子 Agent。每个子 Agent 必须为深化后的模块生成一个**截然不同的**接口。
-
-为每个子 Agent 提供一份独立的技术简报（文件路径、耦合细节、来自 `<Path>{roots.workflows}/specdev/I-implement/deepening.md</Path>` 的依赖类别、接缝背后的内容）。简报独立于第 1 步中面向用户的问题空间说明。给每个 Agent 一个不同的设计约束：
-
-- Agent 1："最小化接口 — 目标 1–3 个入口点。最大化每个入口点的杠杆。"
-- Agent 2："最大化灵活性 — 支持多种用例和扩展。"
-- Agent 3："为最常见的调用方优化 — 让默认情况变得简单。"
-- Agent 4（如适用）："围绕接缝设计端口与适配器，以处理跨接缝依赖。"
-
-在简报中同时包含 `<Path>{roots.workflows}/specdev/I-implement/codebase-design-glossary.md</Path>` 词汇和 CONTEXT.md 词汇，以便每个子 Agent 能使用架构语言和项目的领域语言一致地命名事物。
-
-每个子 Agent 输出：
-
-1. 接口（类型、方法、参数 — 以及不变量、排序、错误模式）
-2. 使用示例，展示调用方如何使用它
-3. 实现在接缝背后隐藏了什么
-4. 依赖策略和适配器（参见 `<Path>{roots.workflows}/specdev/I-implement/deepening.md</Path>`）
-5. 权衡 — 哪里杠杆高，哪里杠杆薄
-
-### 3. 展示和比较
-
-按顺序展示各个设计，让用户能够消化每一个，然后用文字进行比较。通过 **depth**（深度，接口处的杠杆）、**locality**（局部性，变更集中的位置）和 **seam placement**（接缝位置）来对比。
-
-比较之后，给出你自己的建议：你认为哪个设计最强以及原因。如果不同设计中的元素可以很好地组合，提出一个混合方案。要有主见 — 用户想要的是一个有力的判断，而不是一个菜单。
+若选择会改变公共接口、数据、兼容、范围或验收，停止并升级到 Ticket/ADR，而不是自行选择。

package/template/workflows/specdev/I-implement/evidence-template.md

@@ -0,0 +1,69 @@
+# Evidence: <Ticket ID> — <Ticket title>
+
+- **Change：** `<change>`
+- **Ticket：** `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`
+- **Spec：** `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- **Tickets Map：** `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
+- **Goal Plan：** `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>` / 不适用
+- **基线/分支：**
+- **Worktree 引用：** 不适用 / `<workspace_ref>`
+- **实现者：**
+- **开始/结束：**
+- **状态：** review / done / blocked / deviated
+
+## 1. 实现摘要
+
+用用户可观察行为和已锁定契约说明实际完成了什么，不复述提交日志。
+
+## 2. 修改范围
+
+| 路径 | 所有权 | 改动目的 |
+|---|---|---|
+| `<Path>src/example.ts</Path>` | writable / shared:<owner> | ... |
+
+## 3. 验收与合同映射
+
+| Contract / Acceptance ID | 验证接缝 | 证据 | 结果 |
+|---|---|---|---|
+| AC-... | ... | 测试、截图、日志或人工检查摘要 | pass / fail / not-run |
+
+每个 Ticket 验收项必须恰好落到一行；不能用“一般测试已通过”替代逐项证据。
+
+## 4. 验证执行
+
+| 命令或步骤 | 运行环境 | 结果 | 摘要或附件 |
+|---|---|---|---|
+| ... | ... | pass / fail / not-run | ... |
+
+- **失败后修复与重跑：** 无 / ...
+- **未运行检查：** 无 / 原因与风险 ...
+- **Lead E2E：** 不适用 / 待执行：场景与预期 / 通过 / 失败
+
+## 5. 路径所有权审计
+
+- **writable 内修改：**
+- **shared 修改与 owner 批准：** 无 / ...
+- **read-only 修改：** 无
+- **未声明路径：** 无
+- **生成文件或锁文件：** 无 / 来源与 owner ...
+
+## 6. 偏差与决策
+
+- **偏差：** 无 / `<deviation-id>`
+- **偏差记录：** `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` / 不适用
+- **批准人或决策来源：**
+- **对范围、契约、依赖或后续 Ticket 的影响：** 无 / ...
+
+偏差处理遵守 `<Path>{roots.workflows}/specdev/common/rules/deviation-control.md</Path>`，不得静默修改 Ticket 目标或验收。
+
+## 7. 残余风险与后续
+
+- **残余风险：** 无 / ...
+- **已知限制：** 无 / ...
+- **后续 Ticket：** 无 / `<ticket-id>`
+- **监控或回滚触发条件：** 不适用 / ...
+
+## 8. 交付定位
+
+- **Commit / PR：**
+- **Evidence 文件：** `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>`

package/template/workflows/specdev/I-implement/execution-preflight.md

@@ -0,0 +1,20 @@
+# Execution Preflight
+
+## 硬检查
+
+- [ ] Ticket frontmatter 可解析，`ready: true`，`status: ready`。
+- [ ] 所有 blocked_by Ticket 为 done 且证据存在。
+- [ ] Spec、ADR、Ticket 和 Goal Plan 无冲突。
+- [ ] 当前代码入口、接口和路径仍与 Ticket 假设一致。
+- [ ] writable_paths 无并发 owner 冲突。
+- [ ] 并行执行时，`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `worktrees` 中本 Ticket 为 `active`，`base_sha`、分支和 `workspace_ref` 与派单一致。
+- [ ] 验证命令/环境可用。
+- [ ] Deep Ticket 的批准点已满足。
+
+## 失效分类
+
+- **stale-navigation**：仅 expected_changes/行号过时，契约仍有效；更新导航后继续。
+- **local-implementation**：局部实现方式需调整，不改变契约；记录后继续。
+- **ticket-invalid**：范围、接口、依赖、验证或路径契约失效；停止并修 Ticket。
+- **spec-invalid**：外部行为/合同需改变；停止并修 Spec。
+- **adr-conflict**：架构决策冲突；停止并处理 ADR。

package/template/workflows/specdev/I-implement/tdd-examples.md

@@ -1,139 +1,14 @@
-# 好的测试与坏的测试
+# TDD 示例原则
 
-## 好的测试
+## 好
 
-**集成风格**：通过真实接口测试，而非 mock 内部部件。
+- 通过 HTTP/CLI/公共函数验证输入、输出、状态和错误。
+- 固定时间、随机、网络等非确定性依赖于真实接缝。
+- 回归测试先复现 diagnosis 的触发机制。
 
-```typescript
-// 好：测试可观察的行为
-test("user can checkout with valid cart", async () => {
-  const cart = createCart();
-  cart.add(product);
-  const result = await checkout(cart, paymentMethod);
-  expect(result.status).toBe("confirmed");
-});
-```
+## 坏
 
-特征：
-
-- 测试用户/调用方关心的行为
-- 仅使用公共 API
-- 经受住内部重构
-- 描述 WHAT（做什么），而非 HOW（怎么做）
-- 每个测试一个逻辑断言
-
-## 坏的测试
-
-**实现细节测试**：与内部结构耦合。
-
-```typescript
-// 坏：测试实现细节
-test("checkout calls paymentService.process", async () => {
-  const mockPayment = jest.mock(paymentService);
-  await checkout(cart, payment);
-  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
-});
-```
-
-危险信号：
-
-- Mock 内部协作者
-- 测试私有方法
-- 断言调用次数/顺序
-- 重构时测试失败但没有行为变化
-- 测试名称描述 HOW 而非 WHAT
-- 通过外部手段而非接口进行验证
-
-```typescript
-// 坏：绕过接口进行验证
-test("createUser saves to database", async () => {
-  await createUser({ name: "Alice" });
-  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
-  expect(row).toBeDefined();
-});
-
-// 好：通过接口进行验证
-test("createUser makes user retrievable", async () => {
-  const user = await createUser({ name: "Alice" });
-  const retrieved = await getUser(user.id);
-  expect(retrieved.name).toBe("Alice");
-});
-```
-
-**同义反复测试**：预期值重述了实现，因此测试在构造上就通过了。
-
-```typescript
-// 坏：预期值以与代码计算方式相同的方式重新计算
-test("calculateTotal sums line items", () => {
-  const items = [{ price: 10 }, { price: 5 }];
-  const expected = items.reduce((sum, i) => sum + i.price, 0);
-  expect(calculateTotal(items)).toBe(expected);
-});
-
-// 好：预期值是独立的、已知的字面量
-test("calculateTotal sums line items", () => {
-  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
-});
-```
-
----
-
-## 何时使用 Mock
-
-仅在**系统边界**处使用 Mock：
-
-- 外部 API（支付、邮件等）
-- 数据库（有时 — 优先使用测试数据库）
-- 时间/随机性
-- 文件系统（有时）
-
-不要 Mock：
-
-- 你自己的类/模块
-- 内部协作者
-- 任何你控制的东西
-
-## 为可 Mock 性设计
-
-在系统边界处，设计易于 mock 的接口：
-
-**1. 使用依赖注入**
-
-将外部依赖从外部传入，而不是在内部创建：
-
-```typescript
-// 易于 mock
-function processPayment(order, paymentClient) {
-  return paymentClient.charge(order.total);
-}
-
-// 难以 mock
-function processPayment(order) {
-  const client = new StripeClient(process.env.STRIPE_KEY);
-  return client.charge(order.total);
-}
-```
-
-**2. 偏好 SDK 风格接口而非通用获取器**
-
-为每个外部操作创建特定的函数，而不是带有条件逻辑的通用函数：
-
-```typescript
-// 好：每个函数可以独立 mock
-const api = {
-  getUser: (id) => fetch(`/users/${id}`),
-  getOrders: (userId) => fetch(`/users/${userId}/orders`),
-  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
-};
-
-// 坏：mock 需要在 mock 内部编写条件逻辑
-const api = {
-  fetch: (endpoint, options) => fetch(endpoint, options),
-};
-```
-
-SDK 方式的优点：
-- 每个 mock 返回一个特定的形态
-- 测试设置中无需条件逻辑
-- 更容易看出测试涉及哪些端点
-- 每个端点的类型安全
+- 断言私有辅助函数被调用。
+- 将生产代码逐行翻译成测试。
+- 全部依赖都 Mock，导致协议不兼容仍通过。
+- 只测 happy path，不覆盖 Ticket 明确的失败行为。

package/template/workflows/specdev/I-implement/tdd-rules.md

@@ -1,31 +1,15 @@
-# 测试驱动开发
+# TDD 规则
 
-TDD 是红 → 绿循环。此文件是该循环的参考指南，确保该循环产出的测试值得保留：什么是一个好的测试、测试放在哪里、反模式、以及循环的规则。每个章节在每次循环中都适用 —— 在循环之前和循环期间查阅，而不是之后。
+1. 从 Ticket 验收或验证矩阵选择下一条最小行为。
+2. 通过稳定接缝写失败测试，并确认失败原因正确。
+3. 只写使该行为通过的最小生产代码。
+4. 运行定向测试；通过后重构，保持绿色。
+5. 周期性运行受影响回归，完成时运行完整要求。
 
-在探索代码库时，读取 `{roots.state}/specdev/changes/{change}/CONTEXT.md`（如果存在），使测试名称和接口词汇与项目的领域语言保持一致，并尊重所涉及区域的 ADR。
+## 禁止
 
-## 什么是好的测试
-
-测试通过公共接口验证行为，而不是实现细节。代码可以完全改变；测试不应该。一个好的测试读起来像规范 —— "用户可以使用有效购物车结账" 准确地告诉你存在什么能力 —— 并且在重构后能够存活，因为它不关心内部结构。
-
-参见 `<Path>{roots.workflows}/specdev/I-implement/tdd-examples.md</Path>` 了解示例和 Mock 指南。
-
-## 接缝 —— 测试放置的位置
-
-**接缝（seam）** 是你进行测试的公共边界：你在该接口处观察行为而不触及内部。测试位于接缝处，绝不针对内部细节。
-
-**仅在预先约定的接缝处进行测试。** 在编写任何测试之前，写下要测试的接缝并与用户确认。没有在未确认的接缝处编写测试。你无法测试一切 —— 提前约定接缝可以确保测试工作集中在关键路径和复杂逻辑上，而不是每个边缘情况。
-
-问："公共接口是什么，我们应该在哪些接缝处进行测试？"
-
-## 反模式
-
-- **与实现耦合** —— mock 内部协作者、测试私有方法、或通过旁路通道验证（查询数据库而不是使用接口）。特征：当重构时代码行为未变但测试却失败了。
-- **同义反复** —— 断言以与代码相同的方式重新计算预期值（`expect(add(a, b)).toBe(a + b)`、以相同方式手动推导的快照、将常量断言为等于自身），因此它在构造上就必然通过，永远不可能与代码产生分歧。预期值必须来自独立的真相来源 —— 已知正确的字面量、手工计算示例、规范。
-- **水平切片** —— 先写所有测试，再写所有实现。批量测试验证的是*想象中*的行为：你测试的是事物的*形态*而非面向用户的行为，测试变得对真实变更不敏感，并且你在理解实现之前就锁定了测试结构。应采用**垂直切片** —— 一个测试 → 一个实现 → 重复，每个测试都是一颗**曳光弹**，响应上一个循环的反馈。
-
-## 循环的规则
-
-- **先红后绿。** 先写失败的测试，然后只写足以通过测试的代码。不要预测未来的测试或添加推测性功能。
-- **一次一个切片。** 每个循环一个接缝、一个测试、一个最小实现。
-- **重构不属于循环。** 它属于审查阶段（参见 `<Path>{roots.workflows}/specdev/I-implement/code-review-process.md</Path>`），而不是红 → 绿实现循环的一部分。
+- 先写大段实现再补测试；
+- Mock 被测对象内部实现；
+- 断言私有调用次数而非外部效果（除非调用本身是合同）；
+- 为通过测试而吞错、降低断言、跳过用例；
+- 把旧失败无证据地归因于环境。

package/template/workflows/specdev/I-init-setup/I-init-setup.md

@@ -3,130 +3,125 @@ id: specdev/init-setup
 type: workflow-entry
 workflow: specdev
 name: 初始化设置
-description: 为 specdev workflow 配置变更追踪、领域文档布局、状态标签和语言偏好。首次使用其他 specdev works 前运行一次。
-keywords: [初始化, 配置, 设置, setup]
+description: 初始化 SpecDev 的语言、配置、全局状态、追踪约定、领域知识布局、验证命令和并发治理。
+keywords: [初始化, 配置, status, tracking, 验证命令]
 ---
 
 # 初始化设置
 
-为 specdev workflow 搭建本地持久化配置——变更追踪约定、领域文档布局、状态标签映射和交互语言偏好。这是一个提示驱动的入口，先探索，展示发现结果，与用户确认，然后写入。
+首次使用 SpecDev、状态根不存在或治理契约发生变化后运行。此 work 只初始化 SpecDev 的状态与配置，不修改项目业务代码。
 
-所有配置产物写入 `<Path>{roots.state}/specdev/</Path>` 下：
+## 规范输入
 
-- **变更追踪约定** → `<Path>{roots.state}/specdev/.config/tracking.md</Path>` —— 变更以本地 markdown 目录形式管理
-- **领域文档布局** → `<Path>{roots.state}/specdev/.config/domain-layout.md</Path>` —— 三文件模型（ADR/LOG/CONTEXT）的读写规则
-- **状态标签映射** → `<Path>{roots.state}/specdev/.config/status-labels.md</Path>` —— 五个标准 triage 角色的标签字符串
-- **语言与配置** → `<Path>{roots.state}/specdev/config.json</Path>` —— 交互语言、报告语言和持久化设置
-
-首次使用 specdev 的任意 work 之前运行一次。之后可直接编辑 `<Path>{roots.state}/specdev/.config/</Path>` 下的文件进行调整，无需重新运行。
+- 工作流总览：`<Path>{roots.workflows}/specdev/INDEX.md</Path>`
+- 路径引用契约：`<Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>`
+- 配置模板：`<Path>{roots.workflows}/specdev/I-init-setup/config-template.json</Path>`
+- 配置 Schema：`<Path>{roots.workflows}/specdev/common/schemas/config.schema.json</Path>`
+- 全局状态模板：`<Path>{roots.workflows}/specdev/I-init-setup/status-template.json</Path>`
+- 全局状态 Schema：`<Path>{roots.workflows}/specdev/common/schemas/status.schema.json</Path>`
+- Change 状态模板：`<Path>{roots.workflows}/specdev/I-init-setup/change-status-template.json</Path>`
+- Change 状态 Schema：`<Path>{roots.workflows}/specdev/common/schemas/change-status.schema.json</Path>`
 
 ## 流程
 
-### 1. 探索
-
-查看当前仓库以了解 specdev 的初始配置状态。读取已有内容；不要假设：
-
-- `<Path>{roots.state}/specdev/config.json</Path>` —— 全局配置文件是否已存在？若存在，读取其内容
-- `<Path>{roots.state}/specdev/.config/tracking.md</Path>` —— 变更追踪约定是否已配置？
-- `<Path>{roots.state}/specdev/.config/domain-layout.md</Path>` —— 领域文档布局是否已配置？
-- `<Path>{roots.state}/specdev/.config/status-labels.md</Path>` —— 状态标签映射是否已配置？
-- `<Path>{roots.state}/specdev/status.json</Path>` —— 当前是否有活跃变更？
-- `<Path>{roots.state}/specdev/changes/</Path>` —— 已有哪些变更目录？
-- `<Path>{roots.state}/specdev/archive/</Path>` —— 归档了哪些历史变更？
-
-总结已存在的和缺失的内容。
-
-**完成标准**：当前 `<Path>{roots.state}/specdev/</Path>` 和已有配置已摸底，已存在的和缺失的内容已明确。
+### 1. 解析根目录
 
-然后进入配置阶段——**逐项**引导用户完成四项决策：展示一节，获得用户回答，然后进入下一节。不要一次抛出全部四项。每个配置阶段之前，简短解释它是什么、specdev 的 works 为什么需要它、选择不同会有什么变化。
+确认：
 
-### 2. 变更追踪
+- 工作流根可解析为 `<Path>{roots.workflows}/specdev/</Path>`；
+- 状态根可解析为 `<Path>{roots.state}/specdev/</Path>`；
+- 当前用户允许在状态根创建目录和工件。
 
-specdev 的变更追踪使用**本地 markdown** 作为唯一选项。变更以目录形式存放在 `<Path>{roots.state}/specdev/changes/<YYYY-MM-DD>-<topic>/</Path>` 下，通过 `<Path>{roots.state}/specdev/status.json</Path>` 的 `active` 数组追踪当前活跃变更。
+不得把真实绝对路径写回模板或治理文档；持久化引用继续使用根变量。
 
-变更追踪是 specdev 记录工作进度的地方。当你运行 `S-spec`、`I-implement`、`G-grill-with-docs` 等 work 时，它们会将产物写入当前变更目录。与 GitHub Issues 或 Jira 不同，本地 markdown 方式让所有工作产物（需求文档、设计决策、实现记录）与代码存放在同一仓库中，无需网络连接，且完全由 git 版本控制。
+### 2. 探测项目事实
 
-确认用户理解此约定后，将详细规则写入 `<Path>{roots.state}/specdev/.config/tracking.md</Path>`。
+只读检查仓库根、包管理方式、构建脚本、测试脚本、静态检查、CI、默认分支、项目级 Agent 指令与 worktree 约定。能从仓库发现的事实直接记录，不询问用户。
 
-详细约定参见 `<Path>{roots.workflows}/specdev/I-init-setup/tracking-convention.md</Path>`。
+至少探测：
 
-**完成标准**：变更追踪约定已确认并写入 `<Path>{roots.state}/specdev/.config/tracking.md</Path>`。
+- 项目测试、类型检查、lint 和构建命令；
+- 是否存在多包或多工作区结构；
+- 是否允许并行 worktree；
+- 共享高冲突路径的类型，例如根依赖清单、锁文件、全局导出、共享 schema、迁移索引和全局路由；
+- 项目中已有的提交、分支和发布约定。
 
-### 3. 领域文档布局
+### 3. 询问不可发现偏好
 
-specdev 使用**单上下文**布局。每个变更目录 `<Path>{roots.state}/specdev/changes/{change}/</Path>` 下维护三个文件：
+仅在上下文未提供时询问：
 
-- **CONTEXT.md** —— 项目领域术语与概念
-- **ADR.md** —— 架构决策记录（本变更相关的决策）
-- **LOG.md** —— 设计决策日志（按时间顺序记录每次设计调整）
+- 交互语言与持久化工件语言；
+- 是否允许自动提交；
+- 最大并发数；
+- Deep Ticket 的迁移、发布和不可逆操作是否必须人工批准；
+- 外部任务系统标签是否需要映射。
 
-部分 specdev work（如 `G-grill-with-docs`、`I-implement`）在探索代码库时会读取 CONTEXT.md 了解项目的领域语言，以及 ADR.md 了解过去的架构决策。单上下文意味着整个 specdev workflow 共享一套术语和决策记录，所有变更目录下的三文件模型均遵循相同约定。
+不询问可由仓库事实回答的文件位置、脚本名或默认分支。
 
-确认用户理解此布局后，将消费方规则写入 `<Path>{roots.state}/specdev/.config/domain-layout.md</Path>`。
+### 4. 写入配置
 
-详细约定参见 `<Path>{roots.workflows}/specdev/I-init-setup/domain-layout.md</Path>`。
+以 `<Path>{roots.workflows}/specdev/I-init-setup/config-template.json</Path>` 为模板写入 `<Path>{roots.state}/specdev/config.json</Path>`。
 
-**完成标准**：领域文档布局已确认——三文件（ADR/LOG/CONTEXT）持久化到 `<Path>{roots.state}/specdev/changes/{change}/</Path>`，消费方规则已写入。
+要求：
 
-### 4. 状态标签
+- 字段满足 `<Path>{roots.workflows}/specdev/common/schemas/config.schema.json</Path>`；
+- 验证命令来自仓库事实或显式用户决定；
+- 未确认命令写 `null`，不得虚构；
+- 不写入令牌、凭据、Cookie、个人隐私或敏感环境变量值；
+- 自动提交默认关闭，除非用户明确授权。
 
-specdev 使用五个标准状态角色来追踪工作项的生命周期：
+### 5. 初始化目录与状态
 
-| 角色 | 默认标签 | 含义 |
-|------|---------|------|
-| `needs-triage` | `needs-triage` | 需要评估 |
-| `needs-info` | `needs-info` | 等待补充信息 |
-| `ready-for-agent` | `ready-for-agent` | 可执行（agent 无需额外人工上下文即可领取） |
-| `ready-for-human` | `ready-for-human` | 需人工处理 |
-| `wontfix` | `wontfix` | 不处理 |
+创建或确认以下目录和文件：
 
-当 `T-triage` 分诊外部 issue 时，会将工作项移过一个状态机——需要评估、等待补充、可供 agent 领取、需人工处理、或不予处理。状态标签是这些状态在持久化文件中的字符串表示。默认每个角色的标签等于其名称，如果你的项目已有不同命名习惯，可以在此映射。
+- 以 `<Path>{roots.workflows}/specdev/I-init-setup/status-template.json</Path>` 生成 `<Path>{roots.state}/specdev/status.json</Path>`
+- `<Path>{roots.state}/specdev/.config/</Path>`
+- `<Path>{roots.state}/specdev/changes/</Path>`
+- `<Path>{roots.state}/specdev/adr/</Path>`
+- `<Path>{roots.state}/specdev/context/</Path>`
+- `<Path>{roots.state}/specdev/research/</Path>`
+- `<Path>{roots.state}/specdev/archive/</Path>`
 
-确认用户是否接受默认标签，或需要覆盖为自定义字符串。将映射写入 `<Path>{roots.state}/specdev/.config/status-labels.md</Path>`。
+从模板生成：
 
-详细约定参见 `<Path>{roots.workflows}/specdev/I-init-setup/status-labels.md</Path>`。
+- `<Path>{roots.workflows}/specdev/I-init-setup/tracking-template.md</Path>` → `<Path>{roots.state}/specdev/.config/tracking.md</Path>`
+- `<Path>{roots.workflows}/specdev/I-init-setup/domain-layout-template.md</Path>` → `<Path>{roots.state}/specdev/.config/domain-layout.md</Path>`
+- `<Path>{roots.workflows}/specdev/I-init-setup/status-labels-template.md</Path>` → `<Path>{roots.state}/specdev/.config/status-labels.md</Path>`
 
-**完成标准**：状态标签映射已确认并写入 `<Path>{roots.state}/specdev/.config/status-labels.md</Path>`。
+已有永久知识不得被初始化过程清空。已有配置应先验证和展示差异，再按用户授权更新。
 
-### 5. 语言与配置
+### 6. 验证初始化结果
 
-询问用户两项语言偏好：
+1. 解析 `<Path>{roots.state}/specdev/config.json</Path>` 和 `<Path>{roots.state}/specdev/status.json</Path>`；
+2. 对照 `<Path>{roots.workflows}/specdev/common/schemas/config.schema.json</Path>` 与 `<Path>{roots.workflows}/specdev/common/schemas/status.schema.json</Path>`；
+3. 确认 `<Path>{roots.workflows}/specdev/I-init-setup/change-status-template.json</Path>` 的字段与 `<Path>{roots.workflows}/specdev/common/schemas/change-status.schema.json</Path>` 对齐；实际创建 change 时替换模板占位符后再执行 Schema 验证；
+4. 确认所有必需目录存在；
+5. 确认三个配置文档均已从对应模板生成；
+6. 运行：
 
-- **交互语言** —— specdev 与用户交互时使用的语言。选项：`zh-CN`（简体中文）、`en`（英文）。默认：`zh-CN`。
-- **报告语言** —— AI 生成产物（Markdown 文档、issue 正文、报告）的默认语言。默认与交互语言相同。
-
-specdev 使用 `<Path>{roots.state}/specdev/config.json</Path>` 存储全局配置。所有 specdev works 在启动时读取此文件以自动选择交互语言和确认策略，无需每次手动指定。
-
-将配置写入 `<Path>{roots.state}/specdev/config.json</Path>`：
-
-```jsonc
-{
-  "schema_version": 1,
-  "language": "<用户选择的交互语言>",
-  "persistence": {
-    "root_override": null
-  },
-  "defaults": {
-    "confirm_before_external_write": true,
-    "report_language": "<用户选择的报告语言>"
-  }
-}
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --self-check
 ```
 
-如果 `<Path>{roots.state}/specdev/config.json</Path>` 已存在，仅更新用户本次修改的字段，保留其他现有值。
+### 7. 更新状态并汇报
 
-**完成标准**：语言偏好和配置已写入 `<Path>{roots.state}/specdev/config.json</Path>`。
+在 `<Path>{roots.state}/specdev/status.json</Path>` 中记录本 work 的开始、完成时间和结果。向用户汇报：状态根、语言、验证命令、并发策略、人工批准策略和任何仍为 `null` 的配置项。
 
----
+## 完成标准
 
-配置完成后，提醒用户可以直接编辑 `<Path>{roots.state}/specdev/.config/</Path>` 下的文件进行调整。只有在需要从头重新配置时才需重新运行本入口。
+- `<Path>{roots.state}/specdev/config.json</Path>` 与 `<Path>{roots.state}/specdev/status.json</Path>` 可解析且满足 Schema；
+- 状态目录、永久知识目录和归档目录齐全；
+- 三个配置文档已就位；
+- 验证命令与并发规则有来源；
+- 无敏感值被写入；
+- 包级自检无 error；
+- `<Path>{roots.state}/specdev/status.json</Path>` 已记录本 work 完成。
 
 ## 子文件引用
 
-以下子文件包含各配置阶段的详细约定和消费方规则，仅在对应步骤进入时加载：
-
-| 文件 | 内容 | 触发条件 |
-|------|------|---------|
-| `<Path>{roots.workflows}/specdev/I-init-setup/tracking-convention.md</Path>` | 本地 markdown 变更追踪的读写约定 | 步骤 2「变更追踪」进入时 |
-| `<Path>{roots.workflows}/specdev/I-init-setup/domain-layout.md</Path>` | 单上下文三文件模型的路径解析和消费方规则 | 步骤 3「领域文档布局」进入时 |
-| `<Path>{roots.workflows}/specdev/I-init-setup/status-labels.md</Path>` | 五个标准状态角色的标签字符串映射 | 步骤 4「状态标签」进入时 |
+- `<Path>{roots.workflows}/specdev/I-init-setup/config-template.json</Path>`
+- `<Path>{roots.workflows}/specdev/I-init-setup/status-template.json</Path>`
+- `<Path>{roots.workflows}/specdev/I-init-setup/change-status-template.json</Path>`
+- `<Path>{roots.workflows}/specdev/I-init-setup/tracking-template.md</Path>`
+- `<Path>{roots.workflows}/specdev/I-init-setup/domain-layout-template.md</Path>`
+- `<Path>{roots.workflows}/specdev/I-init-setup/status-labels-template.md</Path>`

package/template/workflows/specdev/I-init-setup/change-status-template.json

@@ -0,0 +1,15 @@
+{
+  "schema_version": 3,
+  "artifact": "change-status",
+  "change": "<YYYY-MM-DD-topic>",
+  "change_status": "active",
+  "current_work": null,
+  "created_at": "<ISO-8601>",
+  "updated_at": "<ISO-8601>",
+  "completed_at": null,
+  "archived": false,
+  "archive_path": null,
+  "blockers": [],
+  "deviations": [],
+  "worktrees": []
+}

package/template/workflows/specdev/I-init-setup/config-template.json

@@ -0,0 +1,26 @@
+{
+  "schema_version": 3,
+  "interaction_language": "zh-CN",
+  "artifact_language": "zh-CN",
+  "git": {
+    "auto_commit": false,
+    "default_branch": null,
+    "worktree_for_parallel": true
+  },
+  "execution": {
+    "max_parallel": 3,
+    "deep_ticket_human_approval": true,
+    "shared_path_owner": "lead"
+  },
+  "verification": {
+    "test": null,
+    "typecheck": null,
+    "lint": null,
+    "build": null
+  },
+  "planning": {
+    "default_depth": "standard",
+    "require_ready_gate": true,
+    "require_evidence": true
+  }
+}