gsd-lite 0.5.9 → 0.5.12

package/.claude-plugin/marketplace.json

@@ -13,7 +13,7 @@
       "name": "gsd",
       "source": "./",
       "description": "AI orchestration tool — GSD management shell + Superpowers quality core. 5 commands, 4 agents, 5 workflows, MCP server, context monitoring.",
-      "version": "0.5.9",
+      "version": "0.5.12",
       "keywords": [
         "orchestration",
         "mcp",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd",
-  "version": "0.5.9",
+  "version": "0.5.12",
   "description": "AI orchestration tool for Claude Code — GSD management shell + Superpowers quality core",
   "author": {
     "name": "sdsrss",

package/README.md

@@ -10,9 +10,9 @@ GSD-Lite is an AI orchestration tool for [Claude Code](https://docs.anthropic.co
 
 ### Structured Execution Engine
 - **Phase-based project management** — Break work into phases with ordered tasks, dependency tracking, and handoff gates
-- **State machine orchestration** — 11 workflow modes with precise state transitions, persistent to `state.json`
+- **State machine orchestration** — 12 workflow modes with precise state transitions, persistent to `state.json`
 - **Automatic task scheduling** — Gate-aware dependency resolution determines what runs next
-- **Session resilience** — Stop anytime, resume exactly where you left off — even across Claude Code restarts
+- **Session resilience** — Stop anytime, resume exactly where you left off — crash protection via Stop hook auto-saves state markers
 
 ### Quality Discipline (Built-in, Not Optional)
 - **TDD enforcement** — "No production code without a failing test first" baked into every executor dispatch
@@ -29,6 +29,7 @@ GSD-Lite is an AI orchestration tool for [Claude Code](https://docs.anthropic.co
 ### Context Protection
 - **Subagent isolation** — Each task runs in its own agent context, preventing cross-contamination
 - **StatusLine monitoring** — Real-time context health tracking via Claude Code StatusLine
+- **Session lifecycle hooks** — Stop hook writes crash marker; SessionStart injects project status into CLAUDE.md; resume detects non-graceful exits
 - **Evidence-based verification** — Every claim backed by command output, not assertions
 - **Research with TTL** — Research artifacts include volatility ratings and expiration dates
 
@@ -41,7 +42,7 @@ User → discuss + research (confirm requirements) → approve plan → auto-exe
                                               (code→review→verify→advance)
 ```
 
-### 5 Commands
+### 6 Commands
 
 | Command | Purpose |
 |---------|---------|
@@ -50,6 +51,7 @@ User → discuss + research (confirm requirements) → approve plan → auto-exe
 | `/gsd:resume` | Resume execution from saved state |
 | `/gsd:status` | View project progress dashboard |
 | `/gsd:stop` | Save state and pause execution |
+| `/gsd:doctor` | Diagnostic checks on GSD-Lite installation and project health |
 
 ### 4 Agents
 
@@ -60,7 +62,7 @@ User → discuss + research (confirm requirements) → approve plan → auto-exe
 | **researcher** | Ecosystem research (Context7 → official docs → web) | Confidence scoring + TTL |
 | **debugger** | 4-phase systematic root cause analysis | Root Cause Iron Law |
 
-### MCP Server (10 Tools)
+### MCP Server (11 Tools)
 
 | Tool | Purpose |
 |------|---------|
@@ -68,6 +70,7 @@ User → discuss + research (confirm requirements) → approve plan → auto-exe
 | `state-init` | Initialize `.gsd/` directory with project structure |
 | `state-read` | Read state with optional field filtering |
 | `state-update` | Update canonical fields with lifecycle validation |
+| `state-patch` | Incrementally modify plan (add/remove/reorder tasks, update fields, add dependencies) |
 | `phase-complete` | Complete a phase after verifying handoff gates |
 | `orchestrator-resume` | Resume orchestration from current state |
 | `orchestrator-handle-executor-result` | Process executor output, advance lifecycle |
@@ -202,33 +205,45 @@ All state lives in `.gsd/state.json` — a single source of truth with:
 
 | Dimension | GSD | GSD-Lite |
 |-----------|-----|----------|
-| Commands | 32 | **5** |
+| Commands | 32 | **6** |
 | Agents | 12 | **4** |
 | Source files | 100+ | **~35** |
 | Installer | 2465 lines | **~80 lines** |
 | User interactions | 6+ confirmations | **Typically 2** |
 | TDD / Anti-rationalization | No | **Yes** |
-| State machine recovery | Partial | **Full (11 modes)** |
+| State machine recovery | Partial | **Full (12 modes)** |
 | Evidence-based verification | No | **Yes** |
 
 ## Project Structure
 
 ```
 gsd-lite/
-├── src/                    # MCP Server + tools (~3300 lines)
-│   ├── server.js           # MCP Server entry (10 tools)
+├── src/                    # MCP Server + tools
+│   ├── server.js           # MCP Server entry (11 tools)
 │   ├── schema.js           # State schema + lifecycle validation
-│   ├── utils.js            # Shared utilities (atomic writes, git)
+│   ├── utils.js            # Shared utilities (atomic writes, git, file lock)
 │   └── tools/
-│       ├── state.js        # State CRUD + evidence + propagation
-│       ├── orchestrator.js # Orchestration logic + agent handlers
+│       ├── state/          # State management (modular)
+│       │   ├── constants.js  # Error codes, lock infrastructure
+│       │   ├── crud.js       # CRUD operations + plan patching
+│       │   ├── logic.js      # Task scheduling, propagation, research
+│       │   └── index.js      # Re-exports
+│       ├── orchestrator/   # Orchestration logic (modular)
+│       │   ├── helpers.js    # Shared constants, preflight, dispatch
+│       │   ├── resume.js     # Workflow resume state machine
+│       │   ├── executor.js   # Executor result handler
+│       │   ├── reviewer.js   # Reviewer result handler
+│       │   ├── debugger.js   # Debugger result handler
+│       │   ├── researcher.js # Researcher result handler
+│       │   └── index.js      # Re-exports
 │       └── verify.js       # lint/typecheck/test verification
-├── commands/               # 5 slash commands
-├── agents/                 # 4 subagent prompts
-├── workflows/              # 5 core workflows (TDD, review, debug, research, deviation)
-├── references/             # 8 reference docs (execution loop, state diagram, evidence spec, ...)
-├── hooks/                  # Context monitoring (StatusLine + PostToolUse)
-├── tests/                  # 674 tests (unit + simulation + E2E)
+├── commands/               # 6 slash commands (start, prd, resume, status, stop, doctor)
+├── agents/                 # 4 subagent prompts (executor, reviewer, researcher, debugger)
+├── workflows/              # 6 core workflows (TDD, review, debug, research, deviation, execution-flow)
+├── references/             # 8 reference docs
+├── hooks/                  # Session lifecycle (StatusLine + PostToolUse + SessionStart + Stop + AutoUpdate)
+│   └── lib/               # Shared hook utilities (gsd-finder)
+├── tests/                  # 804 tests (unit + simulation + E2E)
 ├── cli.js                  # Install/uninstall CLI entry
 ├── install.js              # Installation script
 └── uninstall.js            # Uninstall script
@@ -237,7 +252,7 @@ gsd-lite/
 ## Testing
 
 ```bash
-npm test                    # Run all 674 tests
+npm test                    # Run all 804 tests
 npm run test:coverage       # Tests + coverage report (94%+ lines, 81%+ branches)
 npm run lint                # Biome lint
 node --test tests/file.js   # Run a single test file

package/agents/researcher.md

@@ -27,6 +27,9 @@ tools: Read, Write, Bash, WebSearch, WebFetch, mcp__plugin_context7_context7__*
 关键推荐生成 decision id，供 plan/task 的 `research_basis` 引用
 
 <result_contract>
+编排器调用 `orchestrator-handle-researcher-result` 需要三个参数:
+
+**1. result** — 研究元数据:
 ```json
 {
   "decision_ids": ["decision:jwt-rotation"],
@@ -37,6 +40,27 @@ tools: Read, Write, Bash, WebSearch, WebFetch, mcp__plugin_context7_context7__*
   ]
 }
 ```
+
+**2. decision_index** — 以 decision id 为 key 的索引对象 (每个 decision_ids 中的 id 必须在此出现):
+```json
+{
+  "decision:jwt-rotation": {
+    "summary": "Use refresh token rotation for JWT auth",
+    "source": "Context7",
+    "expires_at": "2026-03-16T10:30:00Z"
+  }
+}
+```
+
+**3. artifacts** — 四个研究文档的 Markdown 内容 (上方 research_output 中的四个文件):
+```json
+{
+  "STACK.md": "# 技术栈推荐\n...",
+  "ARCHITECTURE.md": "# 架构模式\n...",
+  "PITFALLS.md": "# 领域陷阱\n...",
+  "SUMMARY.md": "# 摘要\n..."
+}
+```
 </result_contract>
 </research_output>
 

package/commands/resume.md

@@ -28,6 +28,14 @@ description: Resume project execution from saved state with workspace validation
 <HARD-GATE id="resume-preflight">
 必须在恢复执行前完成所有校验，按以下优先级顺序:
 
+0. **Session End 检查:**
+   - 检查 `.gsd/.session-end` 文件是否存在
+   - 如果存在:
+     - 读取内容，向用户展示: "⚠️ 上次 session 在 {ended_at} 非正常结束，当时处于 {workflow_mode_was} (Phase {current_phase} / Task {current_task})"
+     - 删除 `.session-end` 文件
+     - 继续后续校验 (不覆写 workflow_mode — 由下面的校验决定)
+   - 如果不存在 → 跳过，继续后续校验
+
 1. **Git HEAD 校验:**
    - 运行 `git rev-parse HEAD` 获取当前 HEAD
    - 如果与 state.json 中的 `git_head` 不同:

package/hooks/gsd-session-init.cjs

@@ -2,8 +2,10 @@
 // GSD-Lite SessionStart hook
 // 1. Cleans up stale temp files (throttled to once/day).
 // 2. Auto-registers statusLine in settings.json if not already configured.
-// 3. Shows notification if a previous background update completed or found a new version.
-// 4. Spawns background auto-update (detached, non-blocking).
+// 3. Self-heals .mcp.json if missing.
+// 4. Shows notification if a previous background update completed or found a new version.
+// 5. Spawns background auto-update (detached, non-blocking).
+// 6. Injects GSD project progress into stdout + CLAUDE.md (if active project found).
 // Idempotent: skips if statusLine already points to gsd-statusline, preserves
 // third-party statuslines.
 
@@ -124,4 +126,104 @@ setTimeout(() => process.exit(0), 4000).unref();
     );
     child.unref();
   } catch { /* silent — never block session start */ }
+
+  // ── Phase 6: GSD Project Progress Injection ──
+  // If an active GSD project exists, inject progress into stdout (additionalContext)
+  // and write a status block into CLAUDE.md for persistent visibility.
+  try {
+    const { findGsdDir, readState, getProgress } = require('./lib/gsd-finder.cjs');
+    const cwd = process.cwd();
+    const gsdDir = findGsdDir(cwd);
+    if (gsdDir) {
+      const state = readState(gsdDir);
+      const progress = getProgress(state);
+      if (progress) {
+        // Check for .session-end marker (previous non-graceful exit)
+        const markerPath = path.join(gsdDir, '.session-end');
+        let sessionEndInfo = null;
+        try {
+          if (fs.existsSync(markerPath)) {
+            sessionEndInfo = JSON.parse(fs.readFileSync(markerPath, 'utf8'));
+          }
+        } catch { /* skip */ }
+
+        // Stdout: only output session-end warning (crash recovery), skip routine progress
+        // Routine progress is handled by CLAUDE.md injection below — avoids noise
+        const shortHead = progress.gitHead ? progress.gitHead.substring(0, 7) : 'n/a';
+        if (sessionEndInfo) {
+          console.log(`⚠️ GSD: Previous session ended unexpectedly at ${sessionEndInfo.ended_at} (was: ${sessionEndInfo.workflow_mode_was}). Run /gsd:resume to recover.`);
+        }
+
+        // Write status block to CLAUDE.md
+        const projectRoot = path.dirname(gsdDir);
+        const claudeMdPath = path.join(projectRoot, 'CLAUDE.md');
+        const BEGIN_MARKER = '<!-- GSD-STATUS-BEGIN -->';
+        const END_MARKER = '<!-- GSD-STATUS-END -->';
+
+        const statusBlock = [
+          BEGIN_MARKER,
+          `### GSD Project: ${progress.project}`,
+          `- Phase: ${progress.currentPhase || '?'}/${progress.totalPhases} (${progress.phaseName})`,
+          `- Task: ${progress.currentTask || 'none'}${progress.taskName ? ` (${progress.taskName})` : ''}`,
+          `- Mode: ${progress.workflowMode}`,
+          `- Progress: ${progress.acceptedTasks}/${progress.totalTasks} tasks done`,
+          `- Last checkpoint: ${shortHead}`,
+          sessionEndInfo ? `- ⚠️ Previous session ended unexpectedly (${sessionEndInfo.ended_at})` : null,
+          END_MARKER,
+        ].filter(Boolean).join('\n');
+
+        try {
+          let content = '';
+          try {
+            content = fs.readFileSync(claudeMdPath, 'utf8');
+          } catch { /* file doesn't exist yet — will create */ }
+
+          const beginIdx = content.indexOf(BEGIN_MARKER);
+          const endIdx = content.indexOf(END_MARKER);
+
+          let newContent;
+          if (beginIdx !== -1 && endIdx !== -1) {
+            // Replace existing block
+            newContent = content.substring(0, beginIdx) + statusBlock + content.substring(endIdx + END_MARKER.length);
+          } else {
+            // Append to end (with blank line separator)
+            const separator = content.length > 0 && !content.endsWith('\n\n') ? (content.endsWith('\n') ? '\n' : '\n\n') : '';
+            newContent = content + separator + statusBlock + '\n';
+          }
+
+          // Only write if content changed
+          if (newContent !== content) {
+            const tmpClaude = claudeMdPath + `.gsd-tmp-${process.pid}`;
+            fs.writeFileSync(tmpClaude, newContent);
+            fs.renameSync(tmpClaude, claudeMdPath);
+          }
+        } catch (e) {
+          if (process.env.GSD_DEBUG) process.stderr.write(`gsd-session-init: CLAUDE.md write failed: ${e.message}\n`);
+        }
+      }
+    } else {
+      // No active GSD project — clean up stale CLAUDE.md block if it exists
+      try {
+        const claudeMdPath = path.join(cwd, 'CLAUDE.md');
+        const BEGIN_MARKER = '<!-- GSD-STATUS-BEGIN -->';
+        const END_MARKER = '<!-- GSD-STATUS-END -->';
+        const content = fs.readFileSync(claudeMdPath, 'utf8');
+        const beginIdx = content.indexOf(BEGIN_MARKER);
+        const endIdx = content.indexOf(END_MARKER);
+        if (beginIdx !== -1 && endIdx !== -1) {
+          // Remove the block and any trailing newline
+          let newContent = content.substring(0, beginIdx) + content.substring(endIdx + END_MARKER.length);
+          // Clean up extra blank lines left behind
+          newContent = newContent.replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+          if (newContent !== content) {
+            const tmpClaude = claudeMdPath + `.gsd-tmp-${process.pid}`;
+            fs.writeFileSync(tmpClaude, newContent);
+            fs.renameSync(tmpClaude, claudeMdPath);
+          }
+        }
+      } catch { /* no CLAUDE.md or no block to clean — skip */ }
+    }
+  } catch (e) {
+    if (process.env.GSD_DEBUG) process.stderr.write(`gsd-session-init phase 6: ${e.message}\n`);
+  }
 })().catch(() => {});

package/hooks/gsd-session-stop.cjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// GSD-Lite Stop hook — Crash Protection
+//
+// Runs when Claude Code session ends (exit, /clear, crash).
+// If an active GSD project is found, writes a .session-end marker file
+// so that /gsd:resume can detect the non-graceful exit and inform the user.
+//
+// Design decisions:
+// - Does NOT modify state.json directly (avoids bypassing schema validation)
+// - Uses a marker file (.gsd/.session-end) that resume preflight checks
+// - Only acts on active sessions (not completed/failed/paused)
+// - Timeout guard: exits after 4s (hook timeout is 5s)
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { findGsdDir, readState } = require('./lib/gsd-finder.cjs');
+
+// Safety: exit after 4s regardless
+setTimeout(() => process.exit(0), 4000).unref();
+
+const TERMINAL_MODES = ['completed', 'failed', 'paused_by_user'];
+
+(async () => {
+  const cwd = process.cwd();
+  const gsdDir = findGsdDir(cwd);
+  if (!gsdDir) process.exit(0);
+
+  const state = readState(gsdDir);
+  if (!state) process.exit(0);
+
+  // Only write marker for active (non-terminal, non-paused) sessions
+  if (TERMINAL_MODES.includes(state.workflow_mode)) process.exit(0);
+
+  // Get current git HEAD
+  let gitHead = state.git_head || '';
+  try {
+    const { execSync } = require('node:child_process');
+    gitHead = execSync('git rev-parse HEAD', {
+      cwd: path.dirname(gsdDir),
+      timeout: 2000,
+      encoding: 'utf8',
+    }).trim();
+  } catch { /* keep existing git_head */ }
+
+  // Write .session-end marker
+  const marker = {
+    ended_at: new Date().toISOString(),
+    workflow_mode_was: state.workflow_mode,
+    current_phase: state.current_phase,
+    current_task: state.current_task,
+    git_head: gitHead,
+    reason: 'session_stop',
+  };
+
+  const markerPath = path.join(gsdDir, '.session-end');
+  const tmpPath = markerPath + `.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(tmpPath, JSON.stringify(marker, null, 2) + '\n');
+    fs.renameSync(tmpPath, markerPath);
+  } catch (e) {
+    // Clean up tmp if rename failed
+    try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
+    if (process.env.GSD_DEBUG) {
+      process.stderr.write(`gsd-session-stop: ${e.message}\n`);
+    }
+  }
+})().catch(() => {});

package/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "GSD-Lite hooks: statusline auto-registration + context health monitor",
+  "description": "GSD-Lite hooks: statusline + context monitor + session lifecycle",
   "hooks": {
     "SessionStart": [
       {
@@ -24,6 +24,18 @@
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-session-stop.cjs\"",
+            "timeout": 5
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/lib/gsd-finder.cjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// Shared utilities for GSD hooks.
+// findGsdDir: walk up from startDir looking for .gsd/state.json
+// readState: parse .gsd/state.json, return null on failure
+// getProgress: compute progress summary from state
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Walk from startDir up to filesystem root looking for a .gsd directory
+ * that contains state.json. Returns the absolute path to .gsd or null.
+ */
+function findGsdDir(startDir) {
+  let dir = startDir;
+  while (true) {
+    const candidate = path.join(dir, '.gsd');
+    try {
+      if (fs.statSync(candidate).isDirectory()) {
+        // Only return if state.json exists (not just an empty .gsd dir)
+        if (fs.existsSync(path.join(candidate, 'state.json'))) return candidate;
+      }
+    } catch { /* skip */ }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Read and parse .gsd/state.json. Returns parsed object or null on any failure.
+ */
+function readState(gsdDir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(gsdDir, 'state.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compute progress summary from state object.
+ * Returns { project, workflowMode, currentPhase, totalPhases, currentTask,
+ *           phaseName, taskName, acceptedTasks, totalTasks, gitHead }
+ */
+function getProgress(state) {
+  if (!state) return null;
+
+  const phases = state.phases || [];
+  let acceptedTasks = 0;
+  let totalTasks = 0;
+  let phaseName = '';
+  let taskName = '';
+
+  for (const phase of phases) {
+    const todos = phase.todo || [];
+    totalTasks += todos.length;
+    acceptedTasks += todos.filter(t => t.lifecycle === 'accepted').length;
+    if (phase.id === state.current_phase) {
+      phaseName = phase.name || `Phase ${phase.id}`;
+      const task = todos.find(t => t.id === state.current_task);
+      if (task) {
+        taskName = task.name || '';
+      }
+    }
+  }
+
+  return {
+    project: state.project || 'Unknown',
+    workflowMode: state.workflow_mode || 'unknown',
+    currentPhase: state.current_phase,
+    totalPhases: state.total_phases || phases.length,
+    currentTask: state.current_task,
+    phaseName,
+    taskName,
+    acceptedTasks,
+    totalTasks,
+    gitHead: state.git_head || '',
+  };
+}
+
+module.exports = { findGsdDir, readState, getProgress };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-lite",
-  "version": "0.5.9",
+  "version": "0.5.12",
   "description": "AI orchestration tool for Claude Code — GSD management shell + Superpowers quality core",
   "type": "module",
   "bin": {

package/references/evidence-spec.md

@@ -79,14 +79,14 @@ task:3.1   -> phase 3, task 1
 
 此函数用于 evidence 归档时判断 evidence 所属 phase。
 
-来源: `parseScopePhase()` in `src/tools/state.js`
+来源: `parseScopePhase()` in `src/tools/state/`
 
 ## 容量限制与自动裁剪
 
 ### MAX_EVIDENCE_ENTRIES
 
 - 硬限制: `200` 条
-- 定义位置: `src/tools/state.js` 顶层常量
+- 定义位置: `src/tools/state/` 顶层常量
 
 ### 自动裁剪触发
 
@@ -163,4 +163,4 @@ _pruneEvidenceFromState()
 - 更新时机: executor checkpointed / blocked / failed 时从 result.evidence 覆写
 - 清空时机: `propagateInvalidation()` 或 reviewer 标记 rework 时清空为 `[]`
 
-来源: `addEvidence()`, `_pruneEvidenceFromState()`, `pruneEvidence()`, `phaseComplete()` in `src/tools/state.js`; `handleExecutorResult()`, `handleReviewerResult()` in `src/tools/orchestrator.js`
+来源: `addEvidence()`, `_pruneEvidenceFromState()`, `pruneEvidence()`, `phaseComplete()` in `src/tools/state/`; `handleExecutorResult()`, `handleReviewerResult()` in `src/tools/orchestrator.js`

package/references/review-classification.md

@@ -34,7 +34,7 @@ task.level 当前值?
     └── 否 -> 保持当前级别
 ```
 
-来源: `reclassifyReviewLevel()` in `src/tools/state.js`
+来源: `reclassifyReviewLevel()` in `src/tools/state/`
 
 ## 审查流程
 

package/references/state-diagram.md

@@ -215,4 +215,4 @@ stateDiagram-v2
 **Research 刷新后恢复**:
 `storeResearch()` 中: 如果 `workflow_mode === 'research_refresh_needed'`，调用 `inferWorkflowModeAfterResearch()` 根据 `current_review` 状态推断恢复到 `reviewing_phase` / `reviewing_task` / `executing_task`。
 
-来源: `WORKFLOW_MODES` in `src/schema.js`, `resumeWorkflow()`, `evaluatePreflight()` in `src/tools/orchestrator.js`, `storeResearch()` in `src/tools/state.js`
+来源: `WORKFLOW_MODES` in `src/schema.js`, `resumeWorkflow()`, `evaluatePreflight()` in `src/tools/orchestrator.js`, `storeResearch()` in `src/tools/state/`

package/src/schema.js

@@ -595,8 +595,8 @@ export function validateExecutorResult(r) {
 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 (!(typeof r.scope_id === 'string' || typeof r.scope_id === 'number') || r.scope_id === '' || r.scope_id === 0) {
+    errors.push('missing or invalid scope_id');
   }
   if (!['L2', 'L1-batch', 'L1'].includes(r.review_level)) errors.push('invalid review_level (expected L2, L1-batch, or L1)');
   if (typeof r.spec_passed !== 'boolean') errors.push('spec_passed must be boolean');
@@ -712,6 +712,8 @@ export function createInitialState({ project, phases }) {
   if (!Array.isArray(phases)) {
     return { error: true, message: 'phases must be an array' };
   }
+  // Note: empty phases is allowed here for internal/test use;
+  // the public API guard is in init() which rejects phases.length === 0.
   // Validate task names and uniqueness before creating state
   const seenIds = new Set();
   for (const [pi, p] of phases.entries()) {
@@ -741,6 +743,10 @@ export function createInitialState({ project, phases }) {
         if (!['task', 'phase'].includes(dep.kind)) {
           return { error: true, message: `Task ${taskId}: requires entry kind must be "task" or "phase" (got "${dep.kind}")` };
         }
+        const validGates = ['checkpoint', 'accepted', 'phase_complete'];
+        if (dep.gate && !validGates.includes(dep.gate)) {
+          return { error: true, message: `Task ${taskId}: requires entry gate must be one of ${validGates.join(', ')} (got "${dep.gate}")` };
+        }
         if (dep.kind === 'task' && !seenIds.has(String(dep.id))) {
           return { error: true, message: `Task ${taskId}: requires references non-existent task "${dep.id}" (valid IDs: ${[...seenIds].join(', ')})` };
         }