gsd-lite 0.6.3 → 0.6.4

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.6.3",
+      "version": "0.6.4",
       "keywords": [
         "orchestration",
         "mcp",

package/.claude-plugin/plugin.json

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

package/package.json

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

package/src/schema.js

@@ -22,9 +22,9 @@ export const WORKFLOW_MODES = [
 export const WORKFLOW_TRANSITIONS = {
   planning:                 ['executing_task', 'paused_by_user'],
   executing_task:           ['planning', 'reviewing_task', 'reviewing_phase', 'awaiting_user', 'awaiting_clear', 'paused_by_user', 'reconcile_workspace', 'replan_required', 'research_refresh_needed', 'failed'],
-  reviewing_task:           ['executing_task', 'reviewing_phase', 'awaiting_user', 'awaiting_clear', 'paused_by_user', 'failed'],
-  reviewing_phase:          ['executing_task', 'awaiting_user', 'awaiting_clear', 'paused_by_user', 'completed', 'failed'],
-  awaiting_user:            ['executing_task', 'reviewing_task', 'reviewing_phase', 'paused_by_user', 'awaiting_clear'],
+  reviewing_task:           ['executing_task', 'reviewing_phase', 'awaiting_user', 'awaiting_clear', 'paused_by_user', 'reconcile_workspace', 'replan_required', 'failed'],
+  reviewing_phase:          ['executing_task', 'awaiting_user', 'awaiting_clear', 'paused_by_user', 'reconcile_workspace', 'replan_required', 'completed', 'failed'],
+  awaiting_user:            ['executing_task', 'reviewing_task', 'reviewing_phase', 'paused_by_user', 'awaiting_clear', 'reconcile_workspace', 'replan_required'],
   awaiting_clear:           ['executing_task', 'paused_by_user'],
   paused_by_user:           ['executing_task', 'awaiting_user', 'awaiting_clear', 'reconcile_workspace', 'replan_required', 'research_refresh_needed', 'reviewing_task', 'reviewing_phase'],
   reconcile_workspace:      ['executing_task', 'paused_by_user'],
@@ -173,7 +173,7 @@ export function validateStateUpdate(state, updates) {
     switch (key) {
       case 'workflow_mode': {
         if (!WORKFLOW_MODES.includes(updates.workflow_mode)) {
-          errors.push(`Invalid workflow_mode: ${updates.workflow_mode}`);
+          errors.push(`Invalid workflow_mode: ${updates.workflow_mode} (valid: ${WORKFLOW_MODES.join(', ')})`);
           break;
         }
         // Transition whitelist — reject unlisted transitions
@@ -310,7 +310,7 @@ export function validateState(state) {
     errors.push('schema_version must be a finite number');
   }
   if (!WORKFLOW_MODES.includes(state.workflow_mode)) {
-    errors.push(`Invalid workflow_mode: ${state.workflow_mode}`);
+    errors.push(`Invalid workflow_mode: ${state.workflow_mode} (valid: ${WORKFLOW_MODES.join(', ')})`);
   }
   if (!Number.isFinite(state.plan_version)) {
     errors.push('plan_version must be a finite number');

package/src/server.js

@@ -119,7 +119,7 @@ const TOOLS = [
       properties: {
         updates: {
           type: 'object',
-          description: 'Key-value pairs of canonical fields: workflow_mode, current_phase, current_task, current_review, git_head, plan_version, schema_version, total_phases, project, decisions, context, evidence, research',
+          description: 'Key-value pairs of canonical fields: workflow_mode (planning|executing_task|reviewing_task|reviewing_phase|awaiting_clear|awaiting_user|paused_by_user|reconcile_workspace|replan_required|research_refresh_needed|completed|failed), current_phase, current_task, current_review, git_head, plan_version, schema_version, total_phases, project, decisions, context, evidence, research',
         },
       },
       required: ['updates'],

package/src/tools/orchestrator/helpers.js

@@ -5,6 +5,7 @@ import {
   update,
   buildExecutorContext,
   matchDecisionForBlocker,
+  computePlanHashes,
 } from '../state/index.js';
 import { getGitHead, getGsdDir } from '../../utils.js';
 
@@ -173,15 +174,32 @@ async function evaluatePreflight(state, basePath) {
     });
   }
 
-  const changed_files = await detectPlanDrift(basePath, state.context?.plan_hashes);
-  if (changed_files.length > 0) {
-    hints.push({
-      workflow_mode: 'replan_required',
-      action: 'await_manual_intervention',
-      updates: { workflow_mode: 'replan_required' },
-      changed_files,
-      message: 'Plan artifacts changed after the last recorded session',
-    });
+  // Plan drift detection — only run when no prior blocking hint (git_head mismatch)
+  // exists, because establishing a baseline in a suspect workspace state would
+  // anchor hashes to potentially wrong files.
+  if (hints.length === 0) {
+    const storedHashes = state.context?.plan_hashes;
+    if (!storedHashes || Object.keys(storedHashes).length === 0) {
+      // No baseline hashes — compute and persist them now (first resume after init).
+      // This avoids false drift when state-init creates placeholders that the agent
+      // subsequently overwrites with real plan content.
+      const freshHashes = await computePlanHashes(basePath);
+      if (Object.keys(freshHashes).length > 0) {
+        const hashPersistErr = await persist(basePath, { context: { plan_hashes: freshHashes } });
+        if (hashPersistErr) return { override: hashPersistErr };
+      }
+    } else {
+      const changed_files = await detectPlanDrift(basePath, storedHashes);
+      if (changed_files.length > 0) {
+        hints.push({
+          workflow_mode: 'replan_required',
+          action: 'await_manual_intervention',
+          updates: { workflow_mode: 'replan_required' },
+          changed_files,
+          message: 'Plan artifacts changed after the last recorded session',
+        });
+      }
+    }
   }
 
   const skipDirectionDrift = state.workflow_mode === 'awaiting_user'

package/src/tools/state/crud.js

@@ -1,9 +1,9 @@
 // State CRUD operations
 
 import { dirname, join, relative } from 'node:path';
-import { readFile, stat } from 'node:fs/promises';
+import { readFile, readdir, stat } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
-import { ensureDir, readJson, writeJson, writeAtomic, getStatePath, getGitHead, isPlainObject, clearGsdDirCache } from '../../utils.js';
+import { ensureDir, readJson, writeJson, writeAtomic, getStatePath, getGsdDir, getGitHead, isPlainObject, clearGsdDirCache } from '../../utils.js';
 import {
   CANONICAL_FIELDS,
   TASK_LEVELS,
@@ -28,7 +28,16 @@ import { propagateInvalidation } from './logic.js';
  * Returns an object mapping relative-to-gsdDir paths to hex hashes.
  * Missing/unreadable files are silently skipped.
  */
-async function computePlanHashes(filePaths, gsdDir) {
+export async function computePlanHashes(basePath) {
+  const gsdDir = await getGsdDir(basePath);
+  if (!gsdDir) return {};
+  const filePaths = [join(gsdDir, 'plan.md')];
+  try {
+    const phaseFiles = await readdir(join(gsdDir, 'phases'));
+    for (const f of phaseFiles) {
+      if (f.endsWith('.md')) filePaths.push(join(gsdDir, 'phases', f));
+    }
+  } catch { /* no phases dir */ }
   const hashes = {};
   for (const filePath of filePaths) {
     try {
@@ -115,8 +124,9 @@ export async function init({ project, phases, research, force = false, basePath
     // Date.toISOString() truncates to milliseconds. Without ceil, the stored timestamp
     // can be slightly less than the file's actual mtime, causing false plan-drift detection.
     state.context.last_session = new Date(Math.ceil(Math.max(...mtimes))).toISOString();
-    // Store content hashes for plan drift detection (hash-based, not mtime-based)
-    state.context.plan_hashes = await computePlanHashes(trackedFiles, gsdDir);
+    // plan_hashes left null — computed lazily on first orchestrator-resume
+    // after the agent writes actual plan.md / phases/*.md content (avoids
+    // false drift detection from hashing placeholder files).
     await writeJson(statePath, state);
 
     return {
@@ -325,6 +335,16 @@ export async function update({ updates, basePath = process.cwd(), expectedVersio
       }
     }
 
+    // Auto-refresh plan hashes when leaving replan_required — establishes a new
+    // baseline so the next resume doesn't re-trigger drift for already-acknowledged changes.
+    if (state.workflow_mode === 'replan_required'
+        && updates.workflow_mode && updates.workflow_mode !== 'replan_required') {
+      const freshHashes = await computePlanHashes(basePath);
+      if (Object.keys(freshHashes).length > 0) {
+        merged.context = { ...(merged.context || {}), plan_hashes: freshHashes };
+      }
+    }
+
     // Auto-prune evidence when entries exceed limit
     if (merged.evidence && Object.keys(merged.evidence).length > MAX_EVIDENCE_ENTRIES) {
       const gsdDir = dirname(statePath);

package/src/tools/state/index.js

@@ -1,5 +1,5 @@
 // State module — re-exports all public API
 
 export { ERROR_CODES, setLockPath } from './constants.js';
-export { init, read, update, phaseComplete, addEvidence, pruneEvidence, patchPlan } from './crud.js';
+export { init, read, update, phaseComplete, addEvidence, pruneEvidence, patchPlan, computePlanHashes } from './crud.js';
 export { selectRunnableTask, propagateInvalidation, buildExecutorContext, reclassifyReviewLevel, matchDecisionForBlocker, applyResearchRefresh, storeResearch } from './logic.js';

package/workflows/execution-flow.md

@@ -129,12 +129,47 @@
 
 **自动执行循环:** 进入执行后，持续循环直到遇到终止条件:
 1. 调用 `orchestrator-resume` 获取 action
-2. 按 action 派发对应子代理 (executor/reviewer/researcher/debugger)
-3. 收到结果后调用对应 `orchestrator-handle-*-result`
-4. 回到步骤 1
-5. 终止: action ∈ {idle, awaiting_user, completed, failed, await_manual_intervention}
-
-不要在循环中间停下来等用户确认 — 让编排器驱动。`complete_phase` action → 调 `phase-complete` MCP tool → 自动推进下一 phase。
+2. 按 action 执行对应操作 (见下方 action 处理表)
+3. 操作完成后回到步骤 1
+4. 终止: action ∈ {idle, awaiting_user, completed, failed, await_manual_intervention}
+
+不要在循环中间停下来等用户确认 — 让编排器驱动。
+
+**Action 处理表:**
+
+| action | 操作 |
+|--------|------|
+| `dispatch_executor` | 派发 `executor` 子代理执行 task → 结果调用 `orchestrator-handle-executor-result` |
+| `dispatch_reviewer` | 派发 `reviewer` 子代理审查 → 结果调用 `orchestrator-handle-reviewer-result` |
+| `dispatch_debugger` | 派发 `debugger` 子代理调试 → 结果调用 `orchestrator-handle-debugger-result` |
+| `dispatch_researcher` | 派发 `researcher` 子代理研究 → 结果调用 `orchestrator-handle-researcher-result` |
+| `retry_executor` | 重新派发 executor (带 retry 上下文)，同 dispatch_executor |
+| `complete_phase` | 调用 `phase-complete` MCP tool (参数见下方) → 自动推进下一 phase |
+| `rework_required` | 有 task 需要返工 → 继续循环 (resume 会自动选择返工 task) |
+| `review_accepted` | 审查通过 → 继续循环 |
+| `continue_execution` | L0/auto-accept 后 → 继续循环 |
+| `replan_required` | 计划文件被修改。**自动处理:** 确认计划无误后，调用 `state-update({updates: {workflow_mode: "executing_task"}})` → 继续循环 |
+| `reconcile_workspace` | Git HEAD 不一致。检查变更，调用 `state-update({updates: {git_head: "<当前HEAD>", workflow_mode: "executing_task"}})` → 继续循环 |
+| `rollback_to_dirty_phase` | 早期 phase 有失效 task。**自动处理:** 继续循环 (resume 已回滚 current_phase) |
+| `idle` | 当前 phase 无可运行 task。检查 task 状态和依赖关系，必要时向用户报告 |
+| `await_recovery_decision` | 工作流处于 failed 状态。向用户展示失败信息和恢复选项 (retry/skip/replan) |
+
+**`phase-complete` 参数:**
+```
+phase-complete({
+  phase_id: <当前 phase 编号>,
+  run_verify: true,          // 自动运行 lint/typecheck/test
+  direction_ok: true         // 方向校验通过 (如有偏差设为 false)
+})
+```
+如果没有 lint/typecheck/test 工具，可改用 `verification` 参数传入预计算结果:
+```
+phase-complete({
+  phase_id: <phase>,
+  verification: { lint: {exit_code: 0}, typecheck: {exit_code: 0}, test: {exit_code: 0} },
+  direction_ok: true
+})
+```
 </execution_loop>
 
 ## STEP 12 — 最终报告