gsd-lite 0.3.5 → 0.3.6

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.3.4",
+      "version": "0.3.6",
       "keywords": ["orchestration", "mcp", "tdd", "task-management"],
       "category": "Development workflows"
     }

package/.claude-plugin/plugin.json

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

package/agents/debugger.md

@@ -1,7 +1,7 @@
 ---
 name: debugger
 description: Systematic debugging with root cause analysis
-tools: Read, Write, Edit, Bash, Grep, Glob
+tools: Read, Bash, Grep, Glob
 ---
 
 <role>
@@ -54,11 +54,11 @@ Phase 3 假设测试:
   2. 最小变更测试 (一次只改一个变量)
   3. 验证: 有效 → Phase 4 / 无效 → 新假设
 
-Phase 4 实施修复:
-  1. 写失败测试 (复现 bug)
-  2. 修复根因 (不是症状)
-  3. 验证测试通过 + 无回归
-  → 3 次修复失败 → 停止。质疑架构。报告给编排器。
+Phase 4 修复方向建议:
+  1. 提出修复方案 (针对根因，不是症状)
+  2. 建议失败测试用例 (供 executor 实现)
+  3. 评估修复影响范围 (哪些下游可能受影响)
+  → 3 次修复方向均被 executor 验证无效 → 停止。标记 architecture_concern: true。报告给编排器。
 </four_phases>
 
 <result_contract>

package/agents/researcher.md

@@ -39,3 +39,12 @@ tools: Read, Write, Bash, WebSearch, WebFetch, mcp__plugin_context7_context7__*
 ```
 </result_contract>
 </research_output>
+
+<uncertainty_handling>
+## 遇到不确定性时
+子代理不能直接与用户交互。遇到不确定性时:
+1. 来源冲突 → 报告双方立场及置信度，让编排器决定。在 result 中标注 "[DECISION] 选择了X因为Y"
+2. 所有来源不可用 (Context7 + WebSearch + 官方文档均失败) → 返回 "[BLOCKED] 需要: 研究来源不可用，请提供替代信息或缩小范围"
+3. 研究范围过广无法收敛 → 返回 "[BLOCKED] 需要: 研究范围过广，请指定重点领域"
+4. 发现结论与已有 decisions 矛盾 → 在 result 中标注冲突，让编排器决定是否更新 decision
+</uncertainty_handling>

package/commands/prd.md

@@ -100,12 +100,16 @@ argument-hint: File path to requirements doc, or inline description text
 
 → 自审修正后再展示给用户
 
+<HARD-GATE id="plan-confirmation">
 ## STEP 9: 展示计划，等待用户确认
 
 - 展示完整分阶段计划
 - 用户指出问题 → 调整 → 再展示
 - 用户确认 → 继续
 
+⛔ 不得在用户确认前执行 STEP 10-12。未确认 = 不写文件、不执行代码。
+</HARD-GATE>
+
 ## STEP 10: 生成文档
 
 - 创建 .gsd/ 目录

package/commands/resume.md

@@ -35,17 +35,18 @@ description: Resume project execution from saved state with workspace validation
      - 不一致 → 覆写 `workflow_mode = reconcile_workspace`
 
 2. **计划版本校验:**
-   - 如果本地 plan.md 或 phases/*.md 被手动修改，且 `plan_version` 不匹配
+   - 如果本地 plan.md 或 phases/*.md 被手动修改 (mtime > last_session)
    - → 覆写 `workflow_mode = replan_required`
 
-3. **研究过期校验:**
+3. **方向漂移校验:**
+   - 如果当前或任何未完成 phase 的 `phase_handoff.direction_ok === false`
+   - → 覆写 `workflow_mode = awaiting_user`
+
+4. **研究过期校验:**
    - 如果 `research.expires_at` 已过期 (早于当前时间)
+   - 或 research.decision_index 中有条目的 expires_at 已过期
    - → 覆写 `workflow_mode = research_refresh_needed`
 
-4. **工作区冲突校验:**
-   - 运行 `git status` 检查是否存在冲突或脏工作区
-   - 存在未解决的合并冲突 → 覆写 `workflow_mode = awaiting_user`
-
 5. **全部通过:**
    - 保持原 `workflow_mode` 不变
 
@@ -176,6 +177,14 @@ description: Resume project execution from saved state with workspace validation
 
 ---
 
+### `planning` — 计划中断
+
+- 计划编制过程中被中断
+- 告知用户: "项目仍在计划阶段。请运行 /gsd:start 或 /gsd:prd 重新启动计划流程"
+- 不自动执行
+
+---
+
 ### `failed` — 已失败
 
 - 展示失败信息:

package/commands/start.md

@@ -30,7 +30,7 @@ argument-hint: Optional feature or project description
 ## STEP 4 — 需求追问
 
 用户回答后，跟进追问直到需求清晰:
-- 使用 `references/questioning.md` 技巧 (挑战模糊、具象化、发现边界)
+- 使用 Read 工具读取 `references/questioning.md`，按其中的技巧进行提问 (挑战模糊、具象化、发现边界)
 - 每个问题提供选项，标识 ⭐ 推荐选项
 - 多轮对话直到需求清晰 (通常 2-4 轮)
 - 每轮最多 3-5 个问题，避免过度追问
@@ -113,12 +113,17 @@ argument-hint: Optional feature or project description
 
 → 自审修正后再展示给用户。
 
+<HARD-GATE id="plan-confirmation">
 ## STEP 9 — 用户确认计划
 
 展示计划给用户，等待确认:
 - 用户指出问题 → 调整计划 → 重新展示
 - 用户确认 → 继续
 
+⛔ 不得在用户确认前执行 STEP 10-12。未确认 = 不写文件、不执行代码。
+</HARD-GATE>
+
+<HARD-GATE id="docs-written">
 ## STEP 10 — 生成文档
 
 1. 创建 `.gsd/` 目录
@@ -141,6 +146,13 @@ argument-hint: Optional feature or project description
 - `phases/*.md` 是 task 规格的唯一 source of truth
 - `plan.md` 不包含 task 级细节，避免与 `phases/*.md` 重复
 
+□ state.json 已写入且包含所有 canonical fields
+□ plan.md 已写入
+□ phases/*.md 已写入 (每个 phase 一个文件)
+□ 所有 task 都有 lifecycle / level / requires / review_required
+→ 全部满足才可继续
+</HARD-GATE>
+
 ## STEP 11 — 自动执行主路径
 
 进入执行主循环。phase = 管理边界，task = 执行边界。

package/commands/stop.md

@@ -11,8 +11,9 @@ description: Save current state and pause project execution
 
 ## STEP 1: 保存完整状态
 
-读取并更新 `.gsd/state.json`:
+读取 `.gsd/state.json`:
 - 如果文件不存在 → 告知用户 "未找到 GSD 项目状态，无需停止"，停止
+- 如果 `workflow_mode` 已是 `completed` 或 `failed` → 告知用户 "项目已终结 ({workflow_mode})，无需停止"，停止
 
 确保以下信息已保存到 state.json:
 - `current_phase` / `current_task` — 当前执行位置

package/hooks/context-monitor.js

@@ -31,10 +31,10 @@ export function postToolUse(basePath) {
     const gsdDir = join(basePath || process.cwd(), '.gsd');
     const health = parseInt(readFileSync(join(gsdDir, '.context-health'), 'utf-8'), 10);
 
-    if (health < 25) {
+    if (health <= 25) {
       return `🛑 CONTEXT EMERGENCY (${health}% remaining): Save state NOW. Set workflow_mode = awaiting_clear. Tell user to /clear then /gsd:resume.`;
     }
-    if (health < 35) {
+    if (health <= 35) {
       return `⚠️ CONTEXT LOW (${health}% remaining): Complete current task, save state, set workflow_mode = awaiting_clear. Tell user to /clear then /gsd:resume.`;
     }
   } catch (err) {

package/hooks/gsd-context-monitor.cjs

@@ -68,14 +68,18 @@ process.stdin.on('end', () => {
       process.exit(0);
     }
 
+    // Non-GSD sessions: don't interfere — let Claude's auto-compaction handle it
+    const isGsdActive = metrics.has_gsd === true;
+    if (!isGsdActive) {
+      process.exit(0);
+    }
+
     // Debounce logic
     const warnPath = path.join(tmpDir, `gsd-ctx-${sessionId}-warned.json`);
     let warnData = { callsSinceWarn: 0, lastLevel: null };
-    let firstWarn = true;
 
     try {
       warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
-      firstWarn = false;
     } catch {
       // No prior warning state — first warning this session
     }
@@ -85,25 +89,24 @@ process.stdin.on('end', () => {
     const isCritical = remaining <= CRITICAL_THRESHOLD;
     const currentLevel = isCritical ? 'critical' : 'warning';
 
-    // Severity escalation bypasses debounce
+    // Atomic debounce state write helper
+    const writeWarnData = (data) => {
+      const tmpFile = warnPath + `.${process.pid}-${Date.now()}.tmp`;
+      fs.writeFileSync(tmpFile, JSON.stringify(data));
+      fs.renameSync(tmpFile, warnPath);
+    };
+
+    // Severity escalation bypasses debounce (lastLevel null = first warning, always fire)
     const severityEscalated = currentLevel === 'critical' && warnData.lastLevel === 'warning';
-    if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
-      fs.writeFileSync(warnPath, JSON.stringify(warnData));
+    if (warnData.lastLevel !== null && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
+      writeWarnData(warnData);
       process.exit(0);
     }
 
     // Reset debounce
     warnData.callsSinceWarn = 0;
     warnData.lastLevel = currentLevel;
-    fs.writeFileSync(warnPath, JSON.stringify(warnData));
-
-    // Use bridge data to avoid extra filesystem check
-    const isGsdActive = metrics.has_gsd === true;
-
-    // Non-GSD sessions: don't interfere — let Claude's auto-compaction handle it
-    if (!isGsdActive) {
-      process.exit(0);
-    }
+    writeWarnData(warnData);
 
     let message;
     if (isCritical) {

package/hooks/gsd-statusline.cjs

@@ -7,6 +7,25 @@ const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 
+/**
+ * Walk from startDir up to filesystem root looking for a .gsd directory.
+ * Returns the absolute path to .gsd if found, or null.
+ */
+function findGsdDir(startDir) {
+  let dir = startDir;
+  while (true) {
+    const candidate = path.join(dir, '.gsd');
+    try {
+      fs.statSync(candidate);
+      return candidate;
+    } catch {
+      const parent = path.dirname(dir);
+      if (parent === dir) return null; // reached filesystem root
+      dir = parent;
+    }
+  }
+}
+
 let input = '';
 const stdinTimeout = setTimeout(() => process.exit(0), 3000);
 process.stdin.setEncoding('utf8');
@@ -24,7 +43,7 @@ process.stdin.on('end', () => {
     // Current GSD task from state.json
     let task = '';
     let hasGsd = false;
-    const gsdDir = path.join(cwd, '.gsd');
+    const gsdDir = findGsdDir(cwd);
     try {
       const state = JSON.parse(fs.readFileSync(path.join(gsdDir, 'state.json'), 'utf8'));
       hasGsd = true;
@@ -71,21 +90,24 @@ process.stdin.on('end', () => {
       }
 
       // Also write to .gsd/.context-health for MCP server reads (atomic, skip if unchanged)
-      try {
-        const healthPath = path.join(gsdDir, '.context-health');
-        let needsHealthWrite = true;
+      // Only write if a .gsd directory was found — never create .gsd from the hook
+      if (gsdDir) {
         try {
-          const current = fs.readFileSync(healthPath, 'utf8').trim();
-          if (current === String(remaining)) needsHealthWrite = false;
-        } catch { /* file doesn't exist yet */ }
-        if (needsHealthWrite) {
-          fs.mkdirSync(gsdDir, { recursive: true });
-          const tmpHealth = path.join(gsdDir, `.context-health.${process.pid}-${Date.now()}.tmp`);
-          fs.writeFileSync(tmpHealth, String(remaining));
-          fs.renameSync(tmpHealth, healthPath);
+          const healthPath = path.join(gsdDir, '.context-health');
+          let needsHealthWrite = true;
+          try {
+            const current = fs.readFileSync(healthPath, 'utf8').trim();
+            if (current === String(remaining)) needsHealthWrite = false;
+          } catch { /* file doesn't exist yet */ }
+          if (needsHealthWrite) {
+            fs.mkdirSync(gsdDir, { recursive: true });
+            const tmpHealth = path.join(gsdDir, `.context-health.${process.pid}-${Date.now()}.tmp`);
+            fs.writeFileSync(tmpHealth, String(remaining));
+            fs.renameSync(tmpHealth, healthPath);
+          }
+        } catch (e) {
+          if (process.env.GSD_DEBUG) process.stderr.write(`gsd-statusline: context-health write failed: ${e.message}\n`);
         }
-      } catch (e) {
-        if (process.env.GSD_DEBUG) process.stderr.write(`gsd-statusline: context-health write failed: ${e.message}\n`);
       }
 
       // Progress bar (10 segments)

package/package.json

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

package/references/evidence-spec.md

@@ -102,13 +102,12 @@ if (Object.keys(state.evidence).length > MAX_EVIDENCE_ENTRIES) {
 
 `_pruneEvidenceFromState(state, currentPhase, gsdDir)`:
 
-1. 计算阈值: `threshold = currentPhase - 1`
-2. 遍历所有 evidence 条目
-3. 对每条 evidence 调用 `parseScopePhase(entry.scope)` 提取 phase 编号
-4. 如果 `phaseNum !== null && phaseNum < threshold` -> 标记为待归档
-5. 其余保留 (包括 scope 无法解析的条目)
+1. 遍历所有 evidence 条目
+2. 对每条 evidence 调用 `parseScopePhase(entry.scope)` 提取 phase 编号
+3. 如果 `phaseNum !== null && phaseNum < currentPhase` -> 标记为待归档
+4. 其余保留 (包括 scope 无法解析的条目)
 
-规则: 保留当前 phase 和前一个 phase 的 evidence，归档更早 phase 的 evidence。
+规则: 仅保留当前 phase 的 evidence，归档所有更早 phase 的 evidence。
 
 ## 归档生命周期
 

package/references/execution-loop.md

@@ -123,7 +123,7 @@ executor 上下文传递协议 (orchestrator → executor):
 阶段完成后，编排器批量更新 state.json:
 - 更新 phase lifecycle → `accepted`
 - 更新 phase_handoff 信息
-- 归档旧 phase 的 evidence (只保留当前 phase 和上一 phase)
+- 归档旧 phase 的 evidence (仅保留当前 phase)
 - 推进 `current_phase` 到下一个 pending phase
 
 **规则:** 只有编排器写 state.json，避免并发竞态。
@@ -133,13 +133,13 @@ executor 上下文传递协议 (orchestrator → executor):
 每次派发子代理前和阶段切换时检查上下文健康度:
 
 ```
-remaining < 35%:
+remaining <= 35%:
   1. 保存完整状态到 state.json
   2. workflow_mode = awaiting_clear
-  3. 输出: "上下文剩余 <35%，已保存进度。请执行 /clear 然后 /gsd:resume 继续"
+  3. 输出: "上下文剩余 <=35%，已保存进度。请执行 /clear 然后 /gsd:resume 继续"
   4. 停止执行
 
-remaining < 25%:
+remaining <= 25%:
   1. 紧急保存状态到 state.json
   2. workflow_mode = awaiting_clear
   3. 输出: "上下文即将耗尽，已保存进度。请立即执行 /clear 然后 /gsd:resume"

package/src/schema.js

@@ -36,6 +36,8 @@ export const PHASE_LIFECYCLE = {
   failed:     [],
 };
 
+export const TASK_LEVELS = ['L0', 'L1', 'L2', 'L3'];
+
 export const PHASE_REVIEW_STATUS = ['pending', 'reviewing', 'accepted', 'rework_required'];
 
 export const CANONICAL_FIELDS = [
@@ -387,8 +389,8 @@ export function validateState(state) {
         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 (!TASK_LEVELS.includes(task.level)) {
+          errors.push(`Task ${task.id}: level must be one of ${TASK_LEVELS.join(', ')}`);
         }
         if (!Array.isArray(task.requires)) {
           errors.push(`Task ${task.id}: requires must be an array`);

package/src/tools/orchestrator.js

@@ -15,6 +15,7 @@ import { validateDebuggerResult, validateExecutorResult, validateResearcherResul
 import { getGitHead, getGsdDir } from '../utils.js';
 
 const MAX_DEBUG_RETRY = 3;
+const MAX_RESUME_DEPTH = 3;
 const CONTEXT_RESUME_THRESHOLD = 40;
 
 function isTerminalWorkflowMode(workflowMode) {
@@ -482,7 +483,11 @@ async function resumeExecutingTask(state, basePath) {
   };
 }
 
-export async function resumeWorkflow({ basePath = process.cwd() } = {}) {
+export async function resumeWorkflow({ basePath = process.cwd(), _depth = 0 } = {}) {
+  if (_depth >= MAX_RESUME_DEPTH) {
+    return { error: true, message: `resumeWorkflow recursive depth limit exceeded (max ${MAX_RESUME_DEPTH})` };
+  }
+
   const state = await read({ basePath });
   if (state.error) {
     return state;
@@ -540,7 +545,7 @@ export async function resumeWorkflow({ basePath = process.cwd() } = {}) {
           current_review: null,
         });
         if (persistError) return persistError;
-        const resumed = await resumeWorkflow({ basePath });
+        const resumed = await resumeWorkflow({ basePath, _depth: _depth + 1 });
         if (resumed.error) return resumed;
         return { ...resumed, auto_unblocked: autoUnblock.autoUnblocked };
       }
@@ -614,17 +619,48 @@ export async function resumeWorkflow({ basePath = process.cwd() } = {}) {
         total_phases: state.total_phases,
         message: 'Workflow already completed',
       };
-    case 'failed':
+    case 'failed': {
+      const failedPhases = [];
+      const failedTasks = [];
+      for (const phase of state.phases || []) {
+        if (phase.lifecycle === 'failed') failedPhases.push({ id: phase.id, name: phase.name });
+        for (const t of phase.todo || []) {
+          if (t.lifecycle === 'failed') {
+            failedTasks.push({
+              id: t.id,
+              name: t.name,
+              phase_id: phase.id,
+              retry_count: t.retry_count || 0,
+              last_failure_summary: t.last_failure_summary || null,
+              debug_context: t.debug_context || null,
+            });
+          }
+        }
+      }
       return {
         success: true,
-        action: 'noop',
+        action: 'await_recovery_decision',
         workflow_mode: state.workflow_mode,
-        failed_phases: (state.phases || []).filter((phase) => phase.lifecycle === 'failed').map((phase) => phase.id),
-        failed_tasks: (state.phases || []).flatMap((phase) =>
-          (phase.todo || []).filter((task) => task.lifecycle === 'failed').map((task) => task.id)),
-        message: 'Workflow is in failed state',
+        failed_phases: failedPhases,
+        failed_tasks: failedTasks,
+        recovery_options: ['retry_failed', 'skip_failed', 'replan'],
+        message: 'Workflow is in failed state. Recovery options available.',
       };
+    }
     case 'paused_by_user':
+      return {
+        success: true,
+        action: 'await_manual_intervention',
+        workflow_mode: state.workflow_mode,
+        resume_to: state.current_review?.scope === 'phase'
+          ? 'reviewing_phase'
+          : state.current_review?.scope === 'task'
+            ? 'reviewing_task'
+            : 'executing_task',
+        current_review: state.current_review || null,
+        current_task: state.current_task || null,
+        message: 'Project is paused. Confirm to resume execution.',
+      };
     case 'planning':
     case 'reconcile_workspace':
     case 'replan_required':

package/src/tools/state.js

@@ -160,6 +160,15 @@ export async function update({ updates, basePath = process.cwd() } = {}) {
     }
     const state = result.data;
 
+    // Guard: reject workflow_mode changes FROM terminal states
+    if (updates.workflow_mode) {
+      const currentMode = state.workflow_mode;
+      if ((currentMode === 'completed' || currentMode === 'failed')
+          && updates.workflow_mode !== currentMode) {
+        return { error: true, message: `Cannot change workflow_mode from terminal state '${currentMode}'` };
+      }
+    }
+
     // Validate lifecycle transitions before merging
     if (updates.phases && Array.isArray(updates.phases)) {
       for (const newPhase of updates.phases) {
@@ -388,6 +397,9 @@ export async function phaseComplete({
       if (nextPhase && nextPhase.lifecycle === 'pending') {
         nextPhase.lifecycle = 'active';
       }
+    } else if (state.current_phase === phase_id && phase_id >= state.total_phases) {
+      // Final phase completed — mark workflow as completed
+      state.workflow_mode = 'completed';
     }
 
     // Update git_head to current commit
@@ -454,13 +466,12 @@ export async function addEvidence({ id, data, basePath = process.cwd() }) {
 async function _pruneEvidenceFromState(state, currentPhase, gsdDir) {
   if (!state.evidence) return 0;
 
-  const threshold = currentPhase - 1;
   const toArchive = {};
   const toKeep = {};
 
   for (const [id, entry] of Object.entries(state.evidence)) {
     const phaseNum = parseScopePhase(entry.scope);
-    if (phaseNum !== null && phaseNum < threshold) {
+    if (phaseNum !== null && phaseNum < currentPhase) {
       toArchive[id] = entry;
     } else {
       toKeep[id] = entry;
@@ -483,7 +494,7 @@ async function _pruneEvidenceFromState(state, currentPhase, gsdDir) {
 }
 
 /**
- * Prune evidence: archive entries from phases older than currentPhase - 1.
+ * Prune evidence: archive entries from phases before currentPhase (keep only current phase).
  * Scope format is "task:X.Y" where X is the phase number.
  */
 export async function pruneEvidence({ currentPhase, basePath = process.cwd() }) {
@@ -930,11 +941,10 @@ export async function storeResearch({ result, artifacts, decision_index, basePat
       throw err;
     }
 
-    const { decision_index: _, ...nextResearchBase } = {
+    const nextResearchBase = {
       volatility: result.volatility,
       expires_at: result.expires_at,
       sources: result.sources,
-      decision_index,
       files: RESEARCH_FILES,
       updated_at: new Date().toISOString(),
     };