gsd-lite 0.1.0

package/references/questioning.md

@@ -0,0 +1,103 @@
+# 提问技巧参考 (Questioning Reference)
+
+> 本文档供编排器在需求讨论阶段 (`/gsd:start` STEP 1) 使用。
+> 目标: 通过结构化提问，将模糊需求转化为可执行规格。
+
+---
+
+## 1. 提问类型
+
+### 开放式问题 (Open-ended)
+用于初始探索，让用户自由表达意图。
+
+| 场景 | 模板 |
+|------|------|
+| 项目启动 | "你想做什么？解决什么问题？" |
+| 功能探索 | "这个功能的理想使用场景是什么？" |
+| 约束发现 | "有没有什么限制或偏好需要考虑？" |
+
+### 封闭式问题 (Closed)
+用于确认具体决策，减少歧义。每个选项附简短理由，推荐项标 ⭐。
+
+```
+技术栈选择:
+- A) Next.js App Router ⭐ — 全栈 + SSR，适合大多数 Web 项目
+- B) Vite + React — 纯 SPA，适合不需要 SSR 的场景
+- C) 其他 — 请说明
+```
+
+---
+
+## 2. 消除模糊的技巧
+
+### 2.1 具象化 (Concretize)
+把抽象需求转为具体场景。
+
+| 模糊表述 | 追问 |
+|----------|------|
+| "要快" | "目标响应时间是多少？ 200ms? 1s?" |
+| "要安全" | "需要哪些安全措施？认证? 授权? 数据加密?" |
+| "用户管理" | "用户的核心操作有哪些？注册/登录/角色/权限?" |
+
+### 2.2 边界探测 (Boundary Probing)
+- "最多支持多少用户/数据量？"
+- "离线场景需要考虑吗？"
+- "需要支持哪些浏览器/设备？"
+
+### 2.3 挑战假设 (Challenge Assumptions)
+- "你提到 X，是因为 Y 吗？还是有其他原因？"
+- "这个功能一定需要实时吗？异步处理是否可接受？"
+- "是否考虑过更简单的方案？"
+
+---
+
+## 3. 何时追问 vs 何时推进
+
+### 必须追问
+- 用户需求存在歧义 (同一表述有多种合理解读)
+- 架构级决策缺失 (数据库/认证/部署方案未确定)
+- 存在相互矛盾的需求
+
+### 可以推进 (无需追问)
+- 决策属于实现细节 (文件命名、内部函数设计)
+- 有明确的行业最佳实践
+- 用户已明确表达偏好
+- → 推进时用 `[DECISION]` 标注你的选择和理由
+
+### 判断规则
+```
+该决策是否影响用户可见的行为？
+├── 是 → 追问
+└── 否 → 该决策是否可逆？
+    ├── 是 → 合理选择 + [DECISION] 标注
+    └── 否 → 追问
+```
+
+---
+
+## 4. 推荐选项标识 ⭐
+
+提供选项时: ⭐ 标识推荐项 + 附简短理由 | 无明确推荐 → 说明 trade-off
+
+---
+
+## 5. 常见场景问题模板
+
+| 场景 | 问题示例 |
+|------|---------|
+| 技术栈 | "目标平台？" / "现有代码库或偏好？" / "团队最熟悉什么？" |
+| 架构 | "数据关系复杂吗？" / "需要实时更新？" / "预期用户规模？" |
+| 范围 | "MVP 包含哪些功能？" / "有 deadline 吗？" / "需要外部集成？" |
+
+---
+
+## 6. 提问节奏
+
+```
+轮次 1: 开放式 — 理解意图和背景
+轮次 2: 封闭式 — 确认关键决策 (技术栈/架构/范围)
+轮次 3: 边界 — 探测约束和非功能需求
+轮次 4: 确认 — 总结理解，用户确认
+→ 大多数项目 2-4 轮即可完成需求收集
+→ 避免过度追问: 每轮最多 3-5 个问题
+```

package/references/testing-patterns.md

@@ -0,0 +1,110 @@
+# 测试模式与覆盖率指南 (Testing Patterns Reference)
+
+> 本文档供 executor 在编写测试时参考。
+> 核心原则: 测试的目的是 **证明行为正确**，不是追求覆盖率数字。
+
+---
+
+## 1. TDD 循环: RED-GREEN-REFACTOR
+
+```
+RED    → 写一个失败的测试 (定义期望行为)
+GREEN  → 写最小代码让测试通过 (不要多写)
+REFACTOR → 清理代码，保持测试通过 → 重复
+```
+
+- **RED:** 测试必须真的失败。立刻通过 → 测试有问题或功能已存在。
+- **GREEN:** 只写让测试通过的最小代码。不要提前优化。
+- **REFACTOR:** 只重构不加功能。测试必须持续通过。
+
+### TDD 例外 (不需要先写失败测试)
+配置文件 | CSS/样式 | 数据库迁移 | 纯文档 | CI/CD | 环境变量/部署配置
+→ 改为: 实现 → 验证生效 → checkpoint commit
+
+---
+
+## 2. 测试粒度
+
+| 层级 | 范围 | 速度 | 占比 | 何时用 |
+|------|------|------|------|--------|
+| Unit | 单个函数/模块 | 快 (ms) | ~70% | 纯逻辑、工具函数、数据转换 |
+| Integration | 模块间交互 | 中 (s) | ~20% | API 端点、数据库操作、服务间调用 |
+| E2E | 完整用户流程 | 慢 (10s+) | ~10% | 关键路径、支付流程、认证流程 |
+
+### 粒度选择规则
+```
+该功能是纯计算/转换？ → Unit
+该功能涉及多个模块协作？ → Integration
+该功能是用户可见的完整流程？ → E2E
+拿不准？ → 从 Unit 开始，必要时补 Integration
+```
+
+---
+
+## 3. 测什么 vs 不测什么
+
+### 应该测试
+- 业务逻辑 (计算、规则、状态转换)
+- 边界条件 (空输入、极值、边界值)
+- 错误路径 (异常处理、错误消息、降级行为)
+- 公共 API 契约 (输入/输出/错误码)
+- 状态变更 (数据库写入、文件系统操作)
+
+### 不应该测试
+- 框架/库的内部行为 (React 渲染机制、Express 路由匹配)
+- 第三方 API 的具体实现 (mock 它)
+- 私有方法的实现细节 (通过公共接口间接测试)
+- 简单的 getter/setter (除非有逻辑)
+- 常量和配置值 (除非有验证逻辑)
+
+---
+
+## 4. Mock/Stub 策略
+
+| 场景 | 策略 |
+|------|------|
+| 外部服务 (HTTP/DB/文件系统) | Unit 测试中 mock |
+| 时间/随机数 | mock `Date.now()` / `Math.random()` |
+| Integration 测试 | 尽量用真实依赖 (test DB, in-memory store) |
+| 模块内部协作 | 不 mock 自己的代码 |
+
+原则: Mock 外部边界，不 Mock 内部逻辑。Mock 数量 ≤ 3/文件，超过则考虑重构。
+
+---
+
+## 5. 测试命名规范
+
+格式: `describe('<被测模块>') → it('should <期望行为> when <条件>')`
+
+```
+describe('UserService')
+  it('should return user when valid ID is provided')
+  it('should throw NotFoundError when user does not exist')
+```
+
+规则: 描述行为不描述实现 | 包含条件和期望结果 | 用业务语言
+
+---
+
+## 6. 常见测试反模式
+
+| 反模式 | 正确做法 |
+|--------|---------|
+| 测试间共享可变状态 | `beforeEach` 重置状态 |
+| 测试实现细节 (重构就破) | 只测公共行为和输出 |
+| 忽略异步错误 (假通过) | 正确 `await` / 验证 rejection |
+| 只测 happy path | 为每个错误场景写测试 |
+| Snapshot 滥用 | 只在 UI 渲染稳定后使用 |
+| 测试中有逻辑 (if/loop) | 测试应线性: 准备 → 执行 → 断言 |
+
+---
+
+## 7. 覆盖率指南
+
+| 代码类别 | 目标 | 示例 |
+|----------|------|------|
+| 关键路径 | 100% | 认证/支付/数据持久化/核心业务规则 |
+| 一般代码 | ≥ 80% | API 端点/工具函数/状态管理 |
+| 低风险代码 | ≥ 60% | UI 组件 (用 E2E 补充)/配置/日志 |
+
+注意: 覆盖率 ≠ 质量。关注有意义的断言，不要为追求数字写低质量测试。

package/src/schema.js

@@ -0,0 +1,471 @@
+// State schema + lifecycle validation
+
+export const WORKFLOW_MODES = [
+  'planning',
+  'executing_task',
+  'reviewing_task',
+  'reviewing_phase',
+  'awaiting_clear',
+  'awaiting_user',
+  'paused_by_user',
+  'reconcile_workspace',
+  'replan_required',
+  'research_refresh_needed',
+  'completed',
+  'failed',
+];
+
+export const TASK_LIFECYCLE = {
+  pending:              ['running', 'blocked'],
+  running:              ['checkpointed', 'blocked', 'failed'],
+  checkpointed:         ['accepted', 'needs_revalidation'],
+  accepted:             ['needs_revalidation'],
+  blocked:              ['pending'],
+  failed:               [],
+  needs_revalidation:   ['pending'],
+};
+
+export const PHASE_LIFECYCLE = {
+  pending:    ['active'],
+  active:     ['reviewing', 'blocked', 'failed'],
+  reviewing:  ['accepted', 'active'],
+  accepted:   [],
+  blocked:    ['active'],
+  failed:     [],
+};
+
+const PHASE_REVIEW_STATUS = ['pending', 'reviewing', 'accepted', 'rework_required'];
+
+export const CANONICAL_FIELDS = [
+  'project',
+  'workflow_mode',
+  'plan_version',
+  'git_head',
+  'current_phase',
+  'current_task',
+  'current_review',
+  'total_phases',
+  'phases',
+  'decisions',
+  'context',
+  'research',
+  'evidence',
+];
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function validateResearchSourcesArray(sources, errors, path = 'sources') {
+  if (!Array.isArray(sources)) {
+    errors.push(`${path} must be array`);
+    return;
+  }
+
+  for (const source of sources) {
+    if (!isPlainObject(source)) {
+      errors.push(`${path} entries must be objects`);
+      continue;
+    }
+    if (typeof source.id !== 'string' || source.id.length === 0) errors.push(`${path}[].id must be non-empty string`);
+    if (typeof source.type !== 'string' || source.type.length === 0) errors.push(`${path}[].type must be non-empty string`);
+    if (typeof source.ref !== 'string' || source.ref.length === 0) errors.push(`${path}[].ref must be non-empty string`);
+  }
+}
+
+export function validateResearchDecisionIndex(decisionIndex, requiredIds = []) {
+  const errors = [];
+  if (!isPlainObject(decisionIndex)) {
+    errors.push('decision_index must be an object');
+    return { valid: false, errors };
+  }
+
+  for (const id of requiredIds) {
+    if (!isPlainObject(decisionIndex[id])) {
+      errors.push(`decision_index.${id} must be an object`);
+    }
+  }
+
+  for (const [id, entry] of Object.entries(decisionIndex)) {
+    if (!isPlainObject(entry)) {
+      errors.push(`decision_index.${id} must be an object`);
+      continue;
+    }
+    if (typeof entry.summary !== 'string' || entry.summary.length === 0) {
+      errors.push(`decision_index.${id}.summary must be a non-empty string`);
+    }
+    if ('source' in entry && (typeof entry.source !== 'string' || entry.source.length === 0)) {
+      errors.push(`decision_index.${id}.source must be a non-empty string`);
+    }
+    if ('expires_at' in entry && (typeof entry.expires_at !== 'string' || entry.expires_at.length === 0)) {
+      errors.push(`decision_index.${id}.expires_at must be a non-empty string`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+export function validateResearchArtifacts(artifacts, { decisionIds = [], volatility, expiresAt } = {}) {
+  const errors = [];
+  if (!isPlainObject(artifacts)) {
+    return { valid: false, errors: ['artifacts must be an object'] };
+  }
+
+  const requiredFiles = ['STACK.md', 'ARCHITECTURE.md', 'PITFALLS.md', 'SUMMARY.md'];
+  for (const fileName of requiredFiles) {
+    if (typeof artifacts[fileName] !== 'string' || artifacts[fileName].trim().length === 0) {
+      errors.push(`artifacts.${fileName} must be a non-empty string`);
+    }
+  }
+
+  const summary = typeof artifacts['SUMMARY.md'] === 'string' ? artifacts['SUMMARY.md'] : '';
+  if (volatility && !summary.includes(volatility)) {
+    errors.push('artifacts.SUMMARY.md must mention volatility');
+  }
+  if (expiresAt && !summary.includes(expiresAt)) {
+    errors.push('artifacts.SUMMARY.md must mention expires_at');
+  }
+  for (const id of decisionIds) {
+    if (!summary.includes(id)) {
+      errors.push(`artifacts.SUMMARY.md must mention decision id ${id}`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+export function validateTransition(entity, from, to) {
+  const transitions = entity === 'task' ? TASK_LIFECYCLE : PHASE_LIFECYCLE;
+  if (!transitions[from]) {
+    return { valid: false, error: `Unknown ${entity} state: ${from}` };
+  }
+  if (!transitions[from].includes(to)) {
+    return { valid: false, error: `Invalid ${entity} transition: ${from} → ${to}` };
+  }
+  return { valid: true };
+}
+
+export function validateState(state) {
+  const errors = [];
+  if (!state.project || typeof state.project !== 'string') {
+    errors.push('project must be a non-empty string');
+  }
+  if (!WORKFLOW_MODES.includes(state.workflow_mode)) {
+    errors.push(`Invalid workflow_mode: ${state.workflow_mode}`);
+  }
+  if (typeof state.plan_version !== 'number') {
+    errors.push('plan_version must be a number');
+  }
+  if (typeof state.current_phase !== 'number') {
+    errors.push('current_phase must be a number');
+  }
+  if (state.git_head !== null && typeof state.git_head !== 'string') {
+    errors.push('git_head must be a string or null');
+  }
+  if (typeof state.total_phases !== 'number') {
+    errors.push('total_phases must be a number');
+  }
+  if (!Array.isArray(state.phases)) {
+    errors.push('phases must be an array');
+  }
+  if (!Array.isArray(state.decisions)) {
+    errors.push('decisions must be an array');
+  }
+  if (!isPlainObject(state.context)) {
+    errors.push('context must be an object');
+  } else {
+    if (typeof state.context.last_session !== 'string') {
+      errors.push('context.last_session must be a string');
+    }
+    if (typeof state.context.remaining_percentage !== 'number') {
+      errors.push('context.remaining_percentage must be a number');
+    }
+  }
+  if (state.research !== null && !isPlainObject(state.research)) {
+    errors.push('research must be null or an object');
+  }
+  if (isPlainObject(state.research) && 'decision_index' in state.research && !isPlainObject(state.research.decision_index)) {
+    errors.push('research.decision_index must be an object');
+  }
+  if (isPlainObject(state.research)) {
+    if ('volatility' in state.research && !['low', 'medium', 'high'].includes(state.research.volatility)) {
+      errors.push('research.volatility must be low|medium|high');
+    }
+    if ('expires_at' in state.research
+      && (typeof state.research.expires_at !== 'string' || state.research.expires_at.length === 0)) {
+      errors.push('research.expires_at must be a non-empty string');
+    }
+    if ('files' in state.research && !Array.isArray(state.research.files)) {
+      errors.push('research.files must be an array');
+    }
+    if (Array.isArray(state.research.files)) {
+      for (const fileName of state.research.files) {
+        if (typeof fileName !== 'string' || fileName.length === 0) {
+          errors.push('research.files entries must be non-empty strings');
+          break;
+        }
+      }
+    }
+    if ('sources' in state.research) {
+      validateResearchSourcesArray(state.research.sources, errors, 'research.sources');
+    }
+    if ('decision_index' in state.research) {
+      const decisionIndexValidation = validateResearchDecisionIndex(state.research.decision_index);
+      errors.push(...decisionIndexValidation.errors.map((error) => `research.${error}`));
+    }
+  }
+  if (!isPlainObject(state.evidence)) {
+    errors.push('evidence must be an object');
+  }
+  if (Array.isArray(state.phases)) {
+    if (typeof state.total_phases === 'number' && state.total_phases !== state.phases.length) {
+      errors.push(`total_phases (${state.total_phases}) does not match phases.length (${state.phases.length})`);
+    }
+    for (const phase of state.phases) {
+      if (!isPlainObject(phase)) {
+        errors.push('phase must be an object');
+        continue;
+      }
+      if (typeof phase.id !== 'number') {
+        errors.push('phase.id must be a number');
+      }
+      if (!phase.name || typeof phase.name !== 'string') {
+        errors.push(`Phase ${phase.id}: name must be a non-empty string`);
+      }
+      if (!PHASE_LIFECYCLE[phase.lifecycle]) {
+        errors.push(`Phase ${phase.id}: invalid lifecycle ${phase.lifecycle}`);
+      }
+      if (!isPlainObject(phase.phase_review)) {
+        errors.push(`Phase ${phase.id}: phase_review must be an object`);
+      } else {
+        if (!PHASE_REVIEW_STATUS.includes(phase.phase_review.status)) {
+          errors.push(`Phase ${phase.id}: invalid phase_review.status ${phase.phase_review.status}`);
+        }
+        if (typeof phase.phase_review.retry_count !== 'number') {
+          errors.push(`Phase ${phase.id}: phase_review.retry_count must be a number`);
+        }
+      }
+      if (typeof phase.tasks !== 'number') {
+        errors.push(`Phase ${phase.id}: tasks must be a number`);
+      }
+      if (typeof phase.done !== 'number') {
+        errors.push(`Phase ${phase.id}: done must be a number`);
+      }
+      if (!Array.isArray(phase.todo)) {
+        errors.push(`Phase ${phase.id}: todo must be an array`);
+        continue;
+      }
+      if (!isPlainObject(phase.phase_handoff)) {
+        errors.push(`Phase ${phase.id}: phase_handoff must be an object`);
+      } else {
+        if (typeof phase.phase_handoff.required_reviews_passed !== 'boolean') {
+          errors.push(`Phase ${phase.id}: phase_handoff.required_reviews_passed must be boolean`);
+        }
+        if (typeof phase.phase_handoff.tests_passed !== 'boolean') {
+          errors.push(`Phase ${phase.id}: phase_handoff.tests_passed must be boolean`);
+        }
+        if (typeof phase.phase_handoff.critical_issues_open !== 'number') {
+          errors.push(`Phase ${phase.id}: phase_handoff.critical_issues_open must be a number`);
+        }
+        if ('direction_ok' in phase.phase_handoff && typeof phase.phase_handoff.direction_ok !== 'boolean') {
+          errors.push(`Phase ${phase.id}: phase_handoff.direction_ok must be boolean when present`);
+        }
+      }
+      for (const task of phase.todo) {
+        if (!isPlainObject(task)) {
+          errors.push(`Phase ${phase.id}: task must be an object`);
+          continue;
+        }
+        if (!task.id || typeof task.id !== 'string') {
+          errors.push('task.id must be a non-empty string');
+        }
+        if (!task.name || typeof task.name !== 'string') {
+          errors.push(`Task ${task.id}: name must be a non-empty string`);
+        }
+        if (!TASK_LIFECYCLE[task.lifecycle]) {
+          errors.push(`Task ${task.id}: invalid lifecycle ${task.lifecycle}`);
+        }
+        if (typeof task.level !== 'string') {
+          errors.push(`Task ${task.id}: level must be a string`);
+        }
+        if (!Array.isArray(task.requires)) {
+          errors.push(`Task ${task.id}: requires must be an array`);
+        }
+        if (typeof task.retry_count !== 'number') {
+          errors.push(`Task ${task.id}: retry_count must be a number`);
+        }
+        if (typeof task.review_required !== 'boolean') {
+          errors.push(`Task ${task.id}: review_required must be a boolean`);
+        }
+        if (typeof task.verification_required !== 'boolean') {
+          errors.push(`Task ${task.id}: verification_required must be a boolean`);
+        }
+        if (task.checkpoint_commit !== null && typeof task.checkpoint_commit !== 'string') {
+          errors.push(`Task ${task.id}: checkpoint_commit must be a string or null`);
+        }
+        if (!Array.isArray(task.research_basis)) {
+          errors.push(`Task ${task.id}: research_basis must be an array`);
+        }
+        if (!Array.isArray(task.evidence_refs)) {
+          errors.push(`Task ${task.id}: evidence_refs must be an array`);
+        }
+      }
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Validate an executor result against the agent contract.
+ */
+export function validateExecutorResult(r) {
+  const errors = [];
+  if (!r.task_id) errors.push('missing task_id');
+  if (!['checkpointed', 'blocked', 'failed'].includes(r.outcome)) errors.push('invalid outcome');
+  if (typeof r.summary !== 'string' || r.summary.length === 0) errors.push('summary must be non-empty string');
+  if ('checkpoint_commit' in r && r.checkpoint_commit !== null && typeof r.checkpoint_commit !== 'string') {
+    errors.push('checkpoint_commit must be string or null');
+  }
+  if (!Array.isArray(r.files_changed)) errors.push('files_changed must be array');
+  if (!Array.isArray(r.decisions)) errors.push('decisions must be array');
+  if (!Array.isArray(r.blockers)) errors.push('blockers must be array');
+  if (typeof r.contract_changed !== 'boolean') errors.push('contract_changed must be boolean');
+  if (!Array.isArray(r.evidence)) errors.push('evidence must be array');
+  if (r.outcome === 'checkpointed' && typeof r.checkpoint_commit !== 'string') {
+    errors.push('checkpointed outcome requires checkpoint_commit');
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Validate a reviewer result against the agent contract.
+ */
+export function validateReviewerResult(r) {
+  const errors = [];
+  if (!['task', 'phase'].includes(r.scope)) errors.push('invalid scope');
+  if (!(typeof r.scope_id === 'string' || typeof r.scope_id === 'number') || r.scope_id === '') {
+    errors.push('missing scope_id');
+  }
+  if (!['L2', 'L1-batch'].includes(r.review_level)) errors.push('invalid review_level');
+  if (typeof r.spec_passed !== 'boolean') errors.push('spec_passed must be boolean');
+  if (typeof r.quality_passed !== 'boolean') errors.push('quality_passed must be boolean');
+  if (!Array.isArray(r.critical_issues)) errors.push('critical_issues must be array');
+  if (!Array.isArray(r.important_issues)) errors.push('important_issues must be array');
+  if (!Array.isArray(r.minor_issues)) errors.push('minor_issues must be array');
+  if (!Array.isArray(r.accepted_tasks)) errors.push('accepted_tasks must be array');
+  if (!Array.isArray(r.rework_tasks)) errors.push('rework_tasks must be array');
+  if (!Array.isArray(r.evidence)) errors.push('evidence must be array');
+
+  for (const issue of r.critical_issues || []) {
+    if (!isPlainObject(issue)) {
+      errors.push('critical_issues entries must be objects');
+      continue;
+    }
+    if (typeof issue.reason !== 'string' || issue.reason.length === 0) {
+      errors.push('critical_issues[].reason must be non-empty string');
+    }
+    if ('task_id' in issue && typeof issue.task_id !== 'string') {
+      errors.push('critical_issues[].task_id must be string');
+    }
+    if ('invalidates_downstream' in issue && typeof issue.invalidates_downstream !== 'boolean') {
+      errors.push('critical_issues[].invalidates_downstream must be boolean');
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Validate a researcher result against the agent contract.
+ */
+export function validateResearcherResult(r) {
+  const errors = [];
+  if (!Array.isArray(r.decision_ids)) errors.push('decision_ids must be array');
+  if (!['low', 'medium', 'high'].includes(r.volatility)) errors.push('invalid volatility');
+  if (typeof r.expires_at !== 'string' || r.expires_at.length === 0) errors.push('missing expires_at');
+  validateResearchSourcesArray(r.sources, errors, 'sources');
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Validate a debugger result against the agent contract.
+ */
+export function validateDebuggerResult(r) {
+  const errors = [];
+  if (!r.task_id) errors.push('missing task_id');
+  if (!['root_cause_found', 'fix_suggested', 'failed'].includes(r.outcome)) errors.push('invalid outcome');
+  if (typeof r.root_cause !== 'string' || r.root_cause.length === 0) errors.push('root_cause must be non-empty string');
+  if (!Array.isArray(r.evidence)) errors.push('evidence must be array');
+  if (!Array.isArray(r.hypothesis_tested)) errors.push('hypothesis_tested must be array');
+  if (typeof r.fix_direction !== 'string' || r.fix_direction.length === 0) errors.push('fix_direction must be non-empty string');
+  if (!Number.isInteger(r.fix_attempts) || r.fix_attempts < 0) errors.push('fix_attempts must be non-negative integer');
+  if (!Array.isArray(r.blockers)) errors.push('blockers must be array');
+  if (typeof r.architecture_concern !== 'boolean') errors.push('architecture_concern must be boolean');
+  if (r.fix_attempts >= 3 && r.outcome !== 'failed') errors.push('fix_attempts >= 3 requires failed outcome');
+
+  for (const hypothesis of r.hypothesis_tested || []) {
+    if (!isPlainObject(hypothesis)) {
+      errors.push('hypothesis_tested entries must be objects');
+      continue;
+    }
+    if (typeof hypothesis.hypothesis !== 'string' || hypothesis.hypothesis.length === 0) {
+      errors.push('hypothesis_tested[].hypothesis must be non-empty string');
+    }
+    if (!['confirmed', 'rejected'].includes(hypothesis.result)) {
+      errors.push('hypothesis_tested[].result must be confirmed or rejected');
+    }
+    if (typeof hypothesis.evidence !== 'string' || hypothesis.evidence.length === 0) {
+      errors.push('hypothesis_tested[].evidence must be non-empty string');
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+export function createInitialState({ project, phases }) {
+  return {
+    project,
+    workflow_mode: 'executing_task',
+    plan_version: 1,
+    git_head: null,
+    current_phase: 1,
+    current_task: null,
+    current_review: null,
+    total_phases: phases.length,
+    phases: phases.map((p, i) => ({
+      id: i + 1,
+      name: p.name,
+      lifecycle: i === 0 ? 'active' : 'pending',
+      phase_review: { status: 'pending', retry_count: 0 },
+      tasks: p.tasks ? p.tasks.length : 0,
+      done: 0,
+      todo: (p.tasks || []).map((t, ti) => ({
+        id: `${i + 1}.${t.index || ti + 1}`,
+        name: t.name,
+        lifecycle: 'pending',
+        level: t.level || 'L1',
+        requires: t.requires || [],
+        retry_count: 0,
+        review_required: t.review_required !== false,
+        verification_required: t.verification_required !== false,
+        checkpoint_commit: null,
+        research_basis: t.research_basis || [],
+        evidence_refs: [],
+        ...(t.blocked_reason ? { blocked_reason: t.blocked_reason } : {}),
+        ...(t.invalidate_downstream_on_change ? { invalidate_downstream_on_change: true } : {}),
+      })),
+      phase_handoff: {
+        required_reviews_passed: false,
+        tests_passed: false,
+        critical_issues_open: 0,
+      },
+    })),
+    decisions: [],
+    context: {
+      last_session: new Date().toISOString(),
+      remaining_percentage: 100,
+    },
+    research: null,
+    evidence: {},
+  };
+}