specline 1.3.0 → 1.3.1

package/templates/.cursor/skills/specline-pipeline/references/error-recovery-details.md

@@ -0,0 +1,49 @@
+# Hook 约束与速查表参考
+
+## Purpose
+
+本文档提供 Specline Pipeline 的 Hook 约束体系说明和关键约束速查表，供编排者在遇到 Hook 阻断、阶段不匹配等场景时查阅。内容对应原 SKILL.md 的附录 D（Hook 约束体系）和附录 E（关键约束速查表）。
+
+## Hook 约束体系
+
+Specline 通过 Cursor Hooks 提供了三层自动约束，确保在长对话中 Agent 不偏离流水线逻辑：
+
+```
+sessionStart   → specline-session-start.sh
+                 新会话启动时检测活跃 pipeline，自动注入阶段上下文到 Agent 系统提示
+
+preToolUse     → specline-phase-guard.sh
+                 操作前检查：SPEC 阶段拦截代码编辑、阶段不匹配的子Agent 启动
+
+postToolUse    → specline-reminder.sh
+                 关键操作后注入提醒：更新 tasks.md checkbox、运行 Gate 脚本
+```
+
+### 对编排者的影响
+
+1. **总是先检查** - preToolUse 会阻止不匹配当前阶段的操作，所以你在行动前自然会考虑阶段
+2. **被提醒下一步** - postToolUse 在子Agent完成后提醒你更新 checkbox 和运行 Gate
+3. **非流水线会话无影响** - 所有 Hook 的第一步检查「是否有活跃 pipeline」，无则透明放行
+
+### 约束策略表
+
+| 场景 | 策略 | 原因 |
+|------|------|------|
+| SPEC 阶段编辑代码文件 | **硬拦截 (deny)** | 明确违规 |
+| SPEC 阶段启动编码 Agent | **硬拦截 (deny)** | 阶段不匹配 |
+| CODING 阶段直接编辑代码 | **软提醒 (postToolUse)** | Hook 无法区分编排者和子Agent的 Write |
+| 子Agent完成后忘记 Gate | **软提醒 (postToolUse)** | 操作后注入下一步提醒 |
+
+> 注意：CODING 阶段 Orchestrator 直接编辑代码文件不会被 Hook 硬拦截（因为子Agent 也需要 Write 权限），但 SKILL 指令和 sessionStart 注入的上下文会持续提醒你「编码应通过子 Agent」。如果你发现自己想直接编辑代码，停一下，改用 Task 工具。
+
+## 关键约束速查表
+
+| # | 约束 | 说明 |
+|---|------|------|
+| 1 | **不做判断，只做编排** | 不评估代码质量、需求好坏、测试覆盖——这些由子 Agent 和 Gate 脚本负责 |
+| 2 | **所有门禁通过 Gate 脚本** | 调用 `specline-pipeline-gate.sh`，不要自己写 grep/检查逻辑 |
+| 3 | **状态文件是唯一真相源** | 所有决策基于 `.pipeline-state.json` 的当前值 |
+| 4 | **人工确认点必须尊重策略** | 根据 `pipeline.human_gate_policy` 配置决定是否暂停，不要无条件跳过或强制暂停 human_gate |
+| 5 | **测试 Agent 必须黑盒** | 不给 specline-test-writer 传递源代码文件路径 |
+| 6 | **Hook 阻断绝不静默降级** | 子 Agent 被 hook 阻止时，必须先诊断、沟通、修复后重试 |
+| 7 | **接受 Hook 约束** | preToolUse/postToolUse/sessionStart Hook 会自动校验和提醒，不要试图绕过 |

package/templates/.cursor/skills/specline-pipeline/references/event-log-spec.md

@@ -0,0 +1,59 @@
+# 事件日志与状态写入规范
+
+## Purpose
+
+定义 Pipeline 编排者写入状态和事件日志的规范——谁在何时写入什么内容。这是编排者在 SPE 编码阶段（Step 7）和异常恢复阶段（Layer 3）写入 `.pipeline-state.json` 和 `pipeline-events.jsonl` 时必须遵循的规则。
+
+## 状态写入规则
+
+> 所有状态写入由 Gate 脚本或 Skill 编排逻辑完成，**不使用 LLM 写入状态**。
+
+| 写入时机 | 写入方 | 写入内容 |
+|---------|--------|---------|
+| Gate 通过 | Gate 脚本 | `gate.passed = true` |
+| 子 Agent 完成 | Skill 编排逻辑 | `completed_at`（时间戳） |
+| 代码修复后 | Skill 编排逻辑 | 重置相关 gates 为 `null` |
+
+## 结构化事件日志
+
+每个关键事件追加写入 `specline/changes/<name>/pipeline-events.jsonl`（JSON Lines 格式，每行一个事件）。
+
+### 事件格式
+
+```json
+{"ts":"...","event":"pipeline_start","change":"<name>"}
+{"ts":"...","event":"phase_transition","from":"spec","to":"coding"}
+{"ts":"...","event":"agent_start","agent":"specline-spec-creator","task":null}
+{"ts":"...","event":"agent_done","agent":"specline-spec-creator","result":"completed"}
+{"ts":"...","event":"agent_start","agent":"specline-frontend-dev","task":"1","type":"frontend"}
+{"ts":"...","event":"agent_done","agent":"specline-frontend-dev","task":"1","result":"completed","files_changed":["..."],"duration_ms":45200}
+{"ts":"...","event":"gate_run","phase":"build","exit_code":0,"passed":true}
+{"ts":"...","event":"gate_run","phase":"lint","exit_code":1,"passed":false,"stderr":"..."}
+{"ts":"...","event":"conflict_detected","tasks":["1","2"],"overlap_files":["src/utils/api.ts"]}
+{"ts":"...","event":"retry","phase":"coding","task":"3","attempt":2,"reason":"build_failure"}
+{"ts":"...","event":"pipeline_pause","reason":"human_gate_1"}
+{"ts":"...","event":"pipeline_resume","from_phase":"coding"}
+{"ts":"...","event":"pipeline_complete","change":"<name>"}
+```
+
+### 事件类型列表
+
+| 事件类型 | 触发时机 |
+|---------|---------|
+| `pipeline_start` | 流水线开始 |
+| `phase_transition` | 阶段切换（spec→coding→review→test→archive） |
+| `agent_start` | 子 Agent 启动 |
+| `agent_done` | 子 Agent 完成 |
+| `gate_run` | Gate 脚本执行完毕 |
+| `conflict_detected` | 检测到文件冲突 |
+| `retry` | 任务重试 |
+| `pipeline_pause` | 流水线暂停（人工检查点） |
+| `pipeline_resume` | 流水线恢复 |
+| `pipeline_complete` | 流水线完成 |
+
+### 写入原则
+
+- 每个事件一行，JSON 对象结尾无逗号
+- 任何编排动作（启动 agent、运行 gate、状态转换）都写入事件日志
+- Gate 脚本不写事件日志（Gate 是无状态的），仅编排层写入
+- 事件日志用于人工排查问题和统计分析，不影响流水线决策

package/templates/.cursor/skills/specline-pipeline/references/pipeline-state-schema.md

@@ -0,0 +1,87 @@
+# Pipeline 状态文件 Schema 参考
+
+## Purpose
+
+本文档定义 `.pipeline-state.json` 的完整 JSON Schema 和关键字段说明。编排者在初始化流水线或需要理解状态文件结构时查阅。
+
+## 完整 JSON Schema
+
+```json
+{
+  "version": 1,
+  "change_name": "<name>",
+  "created_at": "<ISO8601>",
+  "updated_at": "<ISO8601>",
+  "current_phase": "spec",
+  "current_step": "specline-spec-creator",
+  "phases": {
+    "spec": {
+      "status": "in_progress",
+      "retry_count": 0,
+      "sub_phases": {},
+      "gates": {
+        "spec_gate": { "passed": null },
+        "human_gate_1": { "passed": null }
+      }
+    },
+    "coding": {
+      "status": "pending",
+      "tasks": [],
+      "sub_phases": {},
+      "gates": {
+        "build_gate": { "passed": null }
+      }
+    },
+    "code_review": {
+      "status": "pending",
+      "retry_count": 0,
+      "gates": {
+        "lint_gate": { "passed": null },
+        "human_gate_2": { "passed": null }
+      }
+    },
+    "test": {
+      "status": "pending",
+      "framework": null,
+      "sub_phases": {
+        "unit": {
+          "status": "pending",
+          "gates": { "test_unit_gate": { "passed": null } }
+        },
+        "integration": {
+          "status": "pending",
+          "gates": { "test_integration_gate": { "passed": null } }
+        },
+        "e2e": {
+          "status": "pending",
+          "gates": { "test_e2e_gate": { "passed": null } }
+        }
+      }
+    },
+    "archive": {
+      "status": "pending",
+      "gates": {
+        "human_gate_3": { "passed": null },
+        "archive_gate": { "passed": null }
+      }
+    }
+  }
+}
+```
+
+## 关键字段说明
+
+| 字段 | 说明 |
+|------|------|
+| `version` | Schema 版本号，当前为 1 |
+| `change_name` | 变更名称，与 `specline/changes/<name>/` 目录名一致 |
+| `created_at` | 流水线创建时间（ISO 8601 格式） |
+| `updated_at` | 流水线最后更新时间（ISO 8601 格式） |
+| `current_phase` | 当前阶段（spec / coding / code_review / test / archive） |
+| `current_step` | 当前正在执行的步骤名称（如 `specline-spec-creator`） |
+| `phases.<phase>.status` | 阶段状态（pending / in_progress / completed） |
+| `phases.<phase>.retry_count` | 该阶段重试次数 |
+| `phases.<phase>.gates.<gate_name>.passed` | 门禁通过状态（null / true / false） |
+| `phases.coding.tasks[]` | 编码任务列表（含 id / type / deps / batch / status / files） |
+| `phases.test.framework` | 测试框架名称，由 test-writer 确认后填入 |
+| `phases.test.sub_phases.<type>.status` | 测试子阶段状态（unit / integration / e2e） |

package/templates/.cursor/skills/specline-pipeline/templates/subagent-prompts.md

@@ -0,0 +1,221 @@
+# 子 Agent Prompt 模板
+
+## Purpose
+
+3 套子 Agent prompt 模板，供 SKILL.md Step 7 的编排者按需读取。编排者根据 `task.type` 和 `task.testable` 选择对应模板，填充 `${变量}` 后作为子 Agent 的 prompt。
+
+## 使用说明
+
+编排者在 Step 7 中执行以下逻辑：
+
+1. 读取本文件（`templates/subagent-prompts.md`）
+2. 根据 `task.type` 和 `task.testable` 选择模板：
+
+| 条件 | 模板 |
+|------|------|
+| `task.testable === true`（type 为 frontend/backend/infra/db） | Template 1: TDD Prompt |
+| `task.testable === false` 且 type 为 frontend/backend/infra/db | Template 2: Standard Coding Prompt |
+| type 为 config 或 docs | Template 3: Config/Docs Prompt |
+
+3. 用任务数据填充模板中的 `${变量}` 占位符（见各模板头部的变量列表）
+4. 将填充后的内容作为子 Agent 的 system prompt 传入
+
+**注意**：如果模板中使用了 `${变量}` 但任务数据中无对应字段，编排者应报 WARNING 事件日志并使用空字符串兜底。
+
+---
+
+## Template 1: TDD Prompt（Testable: true）
+
+**适用条件**：`task.testable === true`，type 为 `frontend`/`backend`/`infra`/`db`
+
+**所需变量**：
+
+| 变量 | 来源 | 说明 |
+|------|------|------|
+| `${changeName}` | 流水线上下文 | 当前 change 名称 |
+| `${capability}` | 流水线上下文 | 当前 capability 名称 |
+| `${task.id}` | `task.id` | 任务 ID |
+| `${task.type}` | `task.type` | 任务类型（frontend/backend/infra/db） |
+| `${task.covers}` | `task.covers` | 覆盖的需求声明 |
+| `${task.files}` | `task.files` | 预期产出文件 |
+| `${task.content}` | `task.content` | 从 tasks.md 提取的任务完整描述 |
+
+### Prompt 模板
+
+```
+你收到一个编码任务（Type: ${task.type}, Testable: true），请按 TDD（测试驱动开发）方式实现本任务范围内的代码。
+
+## 上下文文件（只读参考）
+- Spec: specline/changes/${changeName}/specs/${capability}/spec.md
+- Design: specline/changes/${changeName}/design.md
+- Tasks: specline/changes/${changeName}/tasks.md
+
+## 当前任务（只实现这个）
+任务 ID: ${task.id}
+覆盖需求: ${task.covers}
+预期文件: ${task.files}
+
+从 tasks.md 中提取的任务 ${task.id} 的完整描述：
+---
+${task.content}
+---
+
+## TDD 约束（RED-GREEN-REFACTOR）
+
+你必须按以下 TDD 循环编写代码：
+
+### RED 阶段
+1. 分析 Spec 中本任务覆盖的 Scenario，提取需要测试的逻辑单元
+2. 在 tests/unit/<module>/test_<feature>.{ext} 下编写测试文件
+3. 每个 Scenario 至少 1 个测试函数/方法
+4. 覆盖：Happy Path + 边界条件（空值、极值、边界值）+ 异常路径（错误输入、异常状态）
+5. 运行测试，确认全部 FAIL（RED）
+
+### GREEN 阶段
+6. 编写最小实现代码，只使当前测试通过
+7. 不编写测试未覆盖的逻辑
+8. 运行测试，确认全部 PASS（GREEN）
+
+### REFACTOR 阶段
+9. 重构实现代码改善结构（提取方法、消除重复、优化命名）
+10. 运行测试，确保持续 PASS
+11. 如果需要，补充缺失的边界条件测试
+
+## 关键约束
+1. 只修改本任务 Files 范围内的文件
+2. 不修改其他任务负责的文件
+3. 与已完成任务的接口约定必须遵守（参考已生成的接口/类型定义文件）
+4. 确认过 design.md 中的技术决策后再动手
+5. 测试文件只能写入 tests/unit/ 或 tests/models/ 目录
+6. 不得修改 tests/integration/ 或 tests/e2e/ 目录下的文件（属于 test-writer）
+7. **完成后必须将 tasks.md 中本任务的 `[ ]` 改为 `[x]`**（方便断点续跑识别进度）
+
+## 产出报告
+完成后在 specline/changes/${changeName}/.tmp/task-${task.id}-result.json 写入：
+{
+  "task_id": "${task.id}",
+  "type": "${task.type}",
+  "testable": true,
+  "covers": "${task.covers}",
+  "status": "completed",
+  "files_changed": [...],
+  "test_files": ["tests/unit/...", ...],
+  "tests_passed": true,
+  "summary": "..."
+}
+```
+
+---
+
+## Template 2: Standard Coding Prompt（Testable: false，有代码逻辑）
+
+**适用条件**：`task.testable === false`，type 为 `frontend`/`backend`/`infra`/`db`
+
+**所需变量**：
+
+| 变量 | 来源 | 说明 |
+|------|------|------|
+| `${changeName}` | 流水线上下文 | 当前 change 名称 |
+| `${capability}` | 流水线上下文 | 当前 capability 名称 |
+| `${task.id}` | `task.id` | 任务 ID |
+| `${task.type}` | `task.type` | 任务类型（frontend/backend/infra/db） |
+| `${task.covers}` | `task.covers` | 覆盖的需求声明 |
+| `${task.files}` | `task.files` | 预期产出文件 |
+| `${task.content}` | `task.content` | 从 tasks.md 提取的任务完整描述 |
+
+### Prompt 模板
+
+```
+你收到一个编码任务（Type: ${task.type}, Testable: false），请只实现本任务范围内的代码。
+
+## 上下文文件（只读参考）
+- Spec: specline/changes/${changeName}/specs/${capability}/spec.md
+- Design: specline/changes/${changeName}/design.md
+- Tasks: specline/changes/${changeName}/tasks.md
+
+## 当前任务（只实现这个）
+任务 ID: ${task.id}
+覆盖需求: ${task.covers}
+预期文件: ${task.files}
+
+从 tasks.md 中提取的任务 ${task.id} 的完整描述：
+---
+${task.content}
+---
+
+## 约束
+1. 只修改本任务 Files 范围内的文件
+2. 不修改其他任务负责的文件
+3. 与已完成任务的接口约定必须遵守（参考已生成的接口/类型定义文件）
+4. 确认过 design.md 中的技术决策后再动手
+5. **完成后必须将 tasks.md 中本任务的 `[ ]` 改为 `[x]`**（方便断点续跑识别进度）
+
+## 产出报告
+完成后在 specline/changes/${changeName}/.tmp/task-${task.id}-result.json 写入：
+{
+  "task_id": "${task.id}",
+  "type": "${task.type}",
+  "testable": false,
+  "covers": "${task.covers}",
+  "status": "completed",
+  "files_changed": [...],
+  "summary": "..."
+}
+```
+
+---
+
+## Template 3: Config/Docs Prompt（config/docs 类型）
+
+**适用条件**：type 为 `config` 或 `docs`
+
+**所需变量**：
+
+| 变量 | 来源 | 说明 |
+|------|------|------|
+| `${changeName}` | 流水线上下文 | 当前 change 名称 |
+| `${capability}` | 流水线上下文 | 当前 capability 名称 |
+| `${task.id}` | `task.id` | 任务 ID |
+| `${task.type}` | `task.type` | 任务类型（config/docs） |
+| `${task.covers}` | `task.covers` | 覆盖的需求声明 |
+| `${task.files}` | `task.files` | 预期产出文件 |
+| `${task.content}` | `task.content` | 从 tasks.md 提取的任务完整描述 |
+
+### Prompt 模板
+
+```
+你收到一个编码任务（Type: ${task.type}），请只实现本任务范围内的代码。
+
+## 上下文文件（只读参考）
+- Spec: specline/changes/${changeName}/specs/${capability}/spec.md
+- Design: specline/changes/${changeName}/design.md
+- Tasks: specline/changes/${changeName}/tasks.md
+
+## 当前任务（只实现这个）
+任务 ID: ${task.id}
+覆盖需求: ${task.covers}
+预期文件: ${task.files}
+
+从 tasks.md 中提取的任务 ${task.id} 的完整描述：
+---
+${task.content}
+---
+
+## 约束
+1. 只修改本任务 Files 范围内的文件
+2. 不修改其他任务负责的文件
+3. 与已完成任务的接口约定必须遵守（参考已生成的接口/类型定义文件）
+4. 确认过 design.md 中的技术决策后再动手
+5. **完成后必须将 tasks.md 中本任务的 `[ ]` 改为 `[x]`**（方便断点续跑识别进度）
+
+## 产出报告
+完成后在 specline/changes/${changeName}/.tmp/task-${task.id}-result.json 写入：
+{
+  "task_id": "${task.id}",
+  "type": "${task.type}",
+  "covers": "${task.covers}",
+  "status": "completed",
+  "files_changed": [...],
+  "summary": "..."
+}
+```