gsd-lite 0.6.3 → 0.6.5

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.5",
       "keywords": [
         "orchestration",
         "mcp",

package/.claude-plugin/plugin.json

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

package/hooks/hooks.json

@@ -1,41 +1,4 @@
 {
-  "description": "GSD-Lite hooks: statusline + context monitor + session lifecycle",
-  "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "startup",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-session-init.cjs\"",
-            "timeout": 5
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-context-monitor.cjs\"",
-            "timeout": 3
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-session-stop.cjs\"",
-            "timeout": 5
-          }
-        ]
-      }
-    ]
-  }
+  "description": "GSD-Lite hooks — authoritative registration is in settings.json via install.js. This file cleared to prevent double execution if the plugin system also loads it.",
+  "hooks": {}
 }

package/install.js

@@ -21,7 +21,7 @@ const HOOK_FILES = ['gsd-session-init.cjs', 'gsd-auto-update.cjs', 'gsd-context-
 
 // Hook registration config: hookType → { file identifier, matcher, timeout? }
 const HOOK_REGISTRY = [
-  { hookType: 'SessionStart', identifier: 'gsd-session-init', matcher: 'startup', timeout: 5 },
+  { hookType: 'SessionStart', identifier: 'gsd-session-init', matcher: 'startup|clear|compact', timeout: 5 },
   { hookType: 'PostToolUse', identifier: 'gsd-context-monitor', matcher: '*' },
   { hookType: 'Stop', identifier: 'gsd-session-stop', matcher: '*', timeout: 3 },
 ];
@@ -239,33 +239,13 @@ export function main() {
     const statuslinePath = join(CLAUDE_DIR, 'hooks', 'gsd-statusline.cjs');
     let statusLineRegistered = registerStatusLine(settings, statuslinePath);
 
-    // Hooks are managed by hooks.json via the plugin system for plugin installs.
-    // Only register in settings.json for manual installs to avoid double execution.
+    // Always register hooks in settings.json regardless of install method.
+    // The plugin system's hooks.json auto-loading is unreliable — settings.json
+    // is the only reliable hook registration path (consistent with claude-mem-lite).
     let hooksRegistered = false;
-    if (!isPluginInstall) {
-      if (!settings.hooks) settings.hooks = {};
-      for (const config of HOOK_REGISTRY) {
-        if (registerHookEntry(settings.hooks, config)) hooksRegistered = true;
-      }
-    } else {
-      // Clean up stale manual hook entries left from previous install.js runs
-      if (settings.hooks) {
-        let cleaned = false;
-        for (const [hookType, identifier] of [
-          ['PostToolUse', 'gsd-context-monitor'],
-          ['SessionStart', 'gsd-session-init'],
-          ['Stop', 'gsd-session-stop'],
-        ]) {
-          if (Array.isArray(settings.hooks[hookType])) {
-            const before = settings.hooks[hookType].length;
-            settings.hooks[hookType] = settings.hooks[hookType].filter(e =>
-              !e.hooks?.some(h => h.command?.includes(identifier)));
-            if (settings.hooks[hookType].length < before) cleaned = true;
-            if (settings.hooks[hookType].length === 0) delete settings.hooks[hookType];
-          }
-        }
-        if (cleaned) log('  ✓ Removed stale manual hook entries (plugin hooks.json handles registration)');
-      }
+    if (!settings.hooks) settings.hooks = {};
+    for (const config of HOOK_REGISTRY) {
+      if (registerHookEntry(settings.hooks, config)) hooksRegistered = true;
     }
 
     const tmpSettings = settingsPath + `.${process.pid}-${Date.now()}.tmp`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-lite",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "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'],
@@ -285,12 +285,33 @@ async function dispatchToolCall(name, args) {
     case 'state-read':
       result = await read(args || {});
       break;
-    case 'state-update':
-      result = await update(args);
+    case 'state-update': {
+      const updateResult = await update(args);
+      // Strip full state from response to save tokens — keep only _version for optimistic concurrency
+      if (updateResult.success && updateResult.state) {
+        result = { success: true, _version: updateResult.state._version };
+      } else {
+        result = updateResult;
+      }
       break;
-    case 'phase-complete':
-      result = await phaseComplete(args);
+    }
+    case 'phase-complete': {
+      const pcResult = await phaseComplete(args);
+      // Enrich sparse success response with progress info
+      if (pcResult.success && !pcResult.action) {
+        const st = await read({ fields: ['current_phase', 'total_phases', 'workflow_mode'] });
+        result = {
+          ...pcResult,
+          phase_completed: args.phase_id,
+          current_phase: st.current_phase,
+          total_phases: st.total_phases,
+          workflow_mode: st.workflow_mode,
+        };
+      } else {
+        result = pcResult;
+      }
       break;
+    }
     case 'state-patch':
       result = await patchPlan(args);
       break;
@@ -316,9 +337,20 @@ async function dispatchToolCall(name, args) {
   return result;
 }
 
+// Strip result_contract from orchestrator responses — it's static reference data
+// already available in MCP tool descriptions. Saves ~200 tokens per call.
+function stripResultContract(result) {
+  if (result && typeof result === 'object' && 'result_contract' in result) {
+    const { result_contract, ...rest } = result;
+    return rest;
+  }
+  return result;
+}
+
 export async function handleToolCall(name, args) {
   try {
-    return await dispatchToolCall(name, args);
+    const result = await dispatchToolCall(name, args);
+    return stripResultContract(result);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     return { error: true, message: `Tool execution failed: ${message}` };

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';
 
@@ -22,7 +23,7 @@ const RESULT_CONTRACTS = {
     summary: 'string — non-empty description of work done',
     checkpoint_commit: 'string — required when outcome="checkpointed"',
     files_changed: 'string[] — list of modified file paths',
-    decisions: '{ id, title, rationale }[] — architectural decisions made',
+    decisions: '{ id, summary|title, rationale }[] — architectural decisions (summary is canonical; title accepted as alias)',
     blockers: '{ description, type }[] — what blocked progress (when outcome="blocked")',
     contract_changed: 'boolean — true if external API/behavior contract changed',
     confidence: '"high" | "medium" | "low" (optional) — executor self-assessed confidence; affects review level',
@@ -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'
@@ -318,12 +336,14 @@ function buildDecisionEntries(decisions, phaseId, taskId, existingCount = 0) {
           task: taskId,
         };
       }
-      if (decision && typeof decision === 'object' && typeof decision.summary === 'string') {
+      if (decision && typeof decision === 'object' && (typeof decision.summary === 'string' || typeof decision.title === 'string')) {
+        const summary = decision.summary || decision.title;
         return {
           id: decision.id || `decision:${phaseId}:${taskId}:${existingCount + index + 1}`,
           phase: decision.phase ?? phaseId,
           task: decision.task ?? taskId,
           ...decision,
+          summary,
         };
       }
       return null;

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,
@@ -23,12 +23,28 @@ import {
 } from './constants.js';
 import { propagateInvalidation } from './logic.js';
 
+function friendlyReadError(rawError) {
+  if (rawError?.includes('ENOENT')) {
+    return 'No GSD project found (state.json missing). Run /gsd:start or /gsd:prd to begin.';
+  }
+  return rawError;
+}
+
 /**
  * Compute SHA-256 content hashes for an array of file paths.
  * 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 +131,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 {
@@ -144,7 +161,7 @@ export async function read({ fields, basePath = process.cwd(), validate = false
 
   const result = await readJson(statePath);
   if (!result.ok) {
-    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: result.error };
+    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: friendlyReadError(result.error) };
   }
   const state = migrateState(result.data);
 
@@ -197,7 +214,7 @@ export async function update({ updates, basePath = process.cwd(), expectedVersio
   return withStateLock(async () => {
     const result = await readJson(statePath);
     if (!result.ok) {
-      return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: result.error };
+      return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: friendlyReadError(result.error) };
     }
     const state = migrateState(result.data);
 
@@ -325,6 +342,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);
@@ -405,7 +432,7 @@ export async function phaseComplete({
   return withStateLock(async () => {
     const result = await readJson(statePath);
     if (!result.ok) {
-      return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: result.error };
+      return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: friendlyReadError(result.error) };
     }
     const state = migrateState(result.data);
 
@@ -580,7 +607,7 @@ export async function addEvidence({ id, data, basePath = process.cwd() }) {
   return withStateLock(async () => {
     const result = await readJson(statePath);
     if (!result.ok) {
-      return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: result.error };
+      return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: friendlyReadError(result.error) };
     }
     const state = migrateState(result.data);
 
@@ -661,7 +688,7 @@ export async function pruneEvidence({ currentPhase, basePath = process.cwd() })
   return withStateLock(async () => {
     const result = await readJson(statePath);
     if (!result.ok) {
-      return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: result.error };
+      return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: friendlyReadError(result.error) };
     }
     const state = migrateState(result.data);
 
@@ -701,7 +728,7 @@ export async function patchPlan({ operations, basePath = process.cwd() } = {}) {
   return withStateLock(async () => {
     const result = await readJson(statePath);
     if (!result.ok) {
-      return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: result.error };
+      return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: friendlyReadError(result.error) };
     }
     const state = migrateState(result.data);
 

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 — 最终报告