gsd-lite 0.6.2 → 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.2",
+      "version": "0.6.4",
       "keywords": [
         "orchestration",
         "mcp",

package/.claude-plugin/plugin.json

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

package/hooks/gsd-session-init.cjs

@@ -13,10 +13,8 @@ const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 
-const pluginRoot = path.resolve(__dirname, '..');
 const claudeDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
 const settingsPath = path.join(claudeDir, 'settings.json');
-const statuslineScript = path.join(pluginRoot, 'hooks', 'gsd-statusline.cjs');
 
 // Safety: exit after 4s regardless (hook timeout is 5s)
 setTimeout(() => process.exit(0), 4000).unref();
@@ -49,21 +47,38 @@ setTimeout(() => process.exit(0), 4000).unref();
   } catch { /* silent */ }
 
   // ── Phase 2: StatusLine auto-registration ──
+  // StatusLine is a top-level settings.json config that the plugin system
+  // (hooks.json) cannot manage. Self-heal if not registered.
   try {
-    if (fs.existsSync(statuslineScript)) {
+    const stableStatuslinePath = path.join(claudeDir, 'hooks', 'gsd-statusline.cjs');
+    if (fs.existsSync(stableStatuslinePath)) {
       let settings = {};
       try {
         settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
       } catch { /* Can't read settings — skip registration */ }
 
-      if (settings && !settings.statusLine?.command) {
-        settings.statusLine = {
-          type: 'command',
-          command: `node ${JSON.stringify(statuslineScript)}`
-        };
-        const tmpPath = settingsPath + `.gsd-tmp-${process.pid}`;
-        fs.writeFileSync(tmpPath, JSON.stringify(settings, null, 2) + '\n');
-        fs.renameSync(tmpPath, settingsPath);
+      if (settings) {
+        const current = settings.statusLine?.command || '';
+
+        if (current.includes('gsd-statusline')) {
+          // Already registered — nothing to do
+        } else if (!current) {
+          // No statusLine — register directly
+          settings.statusLine = {
+            type: 'command',
+            command: `node ${JSON.stringify(stableStatuslinePath)}`
+          };
+          const tmpPath = settingsPath + `.gsd-tmp-${process.pid}`;
+          fs.writeFileSync(tmpPath, JSON.stringify(settings, null, 2) + '\n');
+          fs.renameSync(tmpPath, settingsPath);
+        } else if (current.includes('statusline-composite')) {
+          // Composite system (e.g., code-graph) — register as provider
+          try {
+            const { registerProvider } = require('./lib/statusline-composite.cjs');
+            registerProvider(stableStatuslinePath);
+          } catch { /* composite helper not available */ }
+        }
+        // else: some other statusLine, don't overwrite
       }
     }
   } catch { /* silent */ }

package/hooks/lib/statusline-composite.cjs

@@ -0,0 +1,110 @@
+'use strict';
+// Detect and register with composite statusline systems (e.g., code-graph).
+// Used by install.js, gsd-session-init.cjs, and uninstall.js.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+// Known composite statusline registry paths
+const REGISTRY_PATHS = [
+  path.join(os.homedir(), '.cache', 'code-graph', 'statusline-registry.json'),
+];
+
+function isCompositeStatusLine(command) {
+  return typeof command === 'string' && command.includes('statusline-composite');
+}
+
+function findCompositeRegistry() {
+  for (const p of REGISTRY_PATHS) {
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * Register GSD as a provider in the composite statusline registry.
+ * Idempotent: updates existing entry or inserts before code-graph.
+ * @param {string} statuslineScriptPath - Absolute path to gsd-statusline.cjs
+ * @returns {boolean} true if registered/updated
+ */
+function registerProvider(statuslineScriptPath) {
+  let registryPath = findCompositeRegistry();
+
+  // If composite statusLine is configured but registry file is missing,
+  // create it if the parent directory exists (e.g., code-graph installed
+  // but registry was deleted or not yet created).
+  if (!registryPath) {
+    for (const candidate of REGISTRY_PATHS) {
+      const dir = path.dirname(candidate);
+      if (fs.existsSync(dir)) {
+        registryPath = candidate;
+        break;
+      }
+    }
+    if (!registryPath) return false;
+  }
+
+  try {
+    let registry;
+    try {
+      registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+    } catch {
+      registry = []; // File missing or corrupt — start fresh
+    }
+    if (!Array.isArray(registry)) return false;
+
+    const command = `node ${JSON.stringify(statuslineScriptPath)}`;
+    const provider = { id: 'gsd', command, needsStdin: true };
+
+    // Find existing GSD entry (by id or command)
+    const idx = registry.findIndex(p =>
+      p.id === 'gsd' || p.command?.includes('gsd-statusline'));
+
+    if (idx >= 0) {
+      registry[idx] = provider;
+    } else {
+      // Insert before code-graph for display priority
+      const cgIdx = registry.findIndex(p => p.id === 'code-graph');
+      if (cgIdx >= 0) registry.splice(cgIdx, 0, provider);
+      else registry.unshift(provider);
+    }
+
+    // Atomic write
+    const tmp = registryPath + `.${process.pid}-${Date.now()}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(registry, null, 2) + '\n');
+    fs.renameSync(tmp, registryPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Remove GSD entry from composite statusline registry.
+ * @returns {boolean} true if an entry was removed
+ */
+function removeProvider() {
+  const registryPath = findCompositeRegistry();
+  if (!registryPath) return false;
+
+  try {
+    const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+    if (!Array.isArray(registry)) return false;
+
+    const idx = registry.findIndex(p =>
+      p.id === 'gsd' || p.command?.includes('gsd-statusline'));
+    if (idx < 0) return false;
+
+    registry.splice(idx, 1);
+
+    const tmp = registryPath + `.${process.pid}-${Date.now()}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(registry, null, 2) + '\n');
+    fs.renameSync(tmp, registryPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { isCompositeStatusLine, findCompositeRegistry, registerProvider, removeProvider };

package/install.js

@@ -11,6 +11,7 @@ import { createRequire } from 'node:module';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const _require = createRequire(import.meta.url);
 const { semverSortComparator } = _require('./hooks/lib/semver-sort.cjs');
+const { isCompositeStatusLine, registerProvider: registerCompositeProvider } = _require('./hooks/lib/statusline-composite.cjs');
 const CLAUDE_DIR = process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
 const RUNTIME_DIR = join(CLAUDE_DIR, 'gsd');
 const DRY_RUN = process.argv.includes('--dry-run');
@@ -39,16 +40,35 @@ function isInstalledAsPlugin(claudeDir) {
 
 function registerStatusLine(settings, statuslineScriptPath) {
   const command = `node ${JSON.stringify(statuslineScriptPath)}`;
-  // Don't overwrite non-GSD statusLine
-  if (settings.statusLine && typeof settings.statusLine === 'object'
-      && !settings.statusLine.command?.includes('gsd-statusline')) {
-    log('  ! Preserved existing statusLine');
-    return false;
-  }
-  settings.statusLine = { type: 'command', command };
+
   // Clean up legacy format (was incorrectly placed in hooks)
   if (settings.hooks?.StatusLine) delete settings.hooks.StatusLine;
-  return true;
+
+  const current = settings.statusLine?.command || '';
+
+  // Already GSD → update command path
+  if (current.includes('gsd-statusline')) {
+    settings.statusLine = { type: 'command', command };
+    return true;
+  }
+
+  // No statusLine → set GSD directly
+  if (!current) {
+    settings.statusLine = { type: 'command', command };
+    return true;
+  }
+
+  // Composite statusLine (e.g., code-graph) → register as provider
+  if (isCompositeStatusLine(current)) {
+    if (registerCompositeProvider(statuslineScriptPath)) {
+      log('  ✓ Registered GSD in composite statusLine registry');
+      return true;
+    }
+  }
+
+  // Other statusLine → don't overwrite
+  log('  ! Preserved existing statusLine');
+  return false;
 }
 
 function registerHookEntry(hooks, { hookType, identifier, matcher, timeout }) {
@@ -214,15 +234,16 @@ export function main() {
       log('  ✓ MCP server registered in settings.json');
     }
 
-    // Register statusLine (top-level setting) and hooks
-    // When installed as a plugin, hooks are managed by hooks.json via the plugin system.
+    // StatusLine is a top-level setting that the plugin system (hooks.json)
+    // cannot manage. Always register, regardless of install method.
+    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.
-    let statusLineRegistered = false;
     let hooksRegistered = false;
     if (!isPluginInstall) {
       if (!settings.hooks) settings.hooks = {};
-      const statuslinePath = join(CLAUDE_DIR, 'hooks', 'gsd-statusline.cjs');
-      statusLineRegistered = registerStatusLine(settings, statuslinePath);
       for (const config of HOOK_REGISTRY) {
         if (registerHookEntry(settings.hooks, config)) hooksRegistered = true;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-lite",
-  "version": "0.6.2",
+  "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/uninstall.js

@@ -5,6 +5,7 @@ import { existsSync, rmSync, readFileSync, writeFileSync, renameSync } from 'nod
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
 
 const CLAUDE_DIR = process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
 const RUNTIME_DIR = join(CLAUDE_DIR, 'gsd');
@@ -27,6 +28,16 @@ function removeDir(path, label) {
 export function main() {
   log('GSD-Lite Uninstaller\n');
 
+  // Clean up GSD entry from composite statusLine registry before removing files
+  try {
+    const _require = createRequire(import.meta.url);
+    const compositeLib = join(CLAUDE_DIR, 'hooks', 'lib', 'statusline-composite.cjs');
+    if (existsSync(compositeLib)) {
+      const { removeProvider } = _require(compositeLib);
+      if (removeProvider()) log('  ✓ Removed GSD from composite statusLine registry');
+    }
+  } catch { /* best effort */ }
+
   log('Removing files...');
 
   removeDir(join(CLAUDE_DIR, 'commands', 'gsd'), 'commands/gsd/');
@@ -49,10 +60,12 @@ export function main() {
   const hookLibDir = join(CLAUDE_DIR, 'hooks', 'lib');
   if (existsSync(hookLibDir)) {
     // Only remove GSD-owned files, not other plugins' libs
-    const gsdLibFile = join(hookLibDir, 'gsd-finder.cjs');
-    if (existsSync(gsdLibFile)) {
-      rmSync(gsdLibFile);
-      log('  ✓ Removed hooks/lib/gsd-finder.cjs');
+    for (const libFile of ['gsd-finder.cjs', 'statusline-composite.cjs', 'semver-sort.cjs']) {
+      const fullPath = join(hookLibDir, libFile);
+      if (existsSync(fullPath)) {
+        rmSync(fullPath);
+        log(`  ✓ Removed hooks/lib/${libFile}`);
+      }
     }
   }
 

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