@goodandready/dsh-goal 0.2.26 → 0.2.28

package/README.md

@@ -136,6 +136,19 @@ Handles `/goal` commands and subcommands:
 * **Quick Launch Button**: Floating launcher for rapid goal formulation without typing slash commands.
 * **Plugin Settings Card**: Schemastery-backed settings UI registered via `settings.plugin.item`.
 
+### 5. Two-Phase Goal Execution: Plan Mode ⇄ Act Mode (#162)
+
+### 6. Acceptance Gate & Critic Verification (#163)
+* **Automated Phase Verification**: Attach an optional `verificationCommand` (e.g. `npm test`, `pytest`, `cargo test`) to any milestone.
+* **Failure Blocking & Diagnostic Feedback**: When the agent attempts to complete a milestone via `goal_milestones action: 'complete'` or `goal_update_progress status: 'completed'`, the command executes inside confined `safeCwd`. If tests fail (`exitCode !== 0`), completion is blocked, the milestone remains open, and diagnostic failure output is returned as actionable feedback to the agent.
+* **Atomic Completion & Snapshots**: Git checkpoint snapshotting and issue checklist synchronization only trigger once the verification command passes with exit code 0.
+* **UI Visual Badges**: Visual indicator `🛡️ <command>` and failure alerts rendered in the Goal Details modal.
+
+
+* **Plan Mode (Read-Only Planning Phase)**: The agent explores the codebase, searches the web, and decomposes tasks into structured milestones and checklists. All file mutating tools (`write_to_file`, `replace_file_content`, mutating shell commands) are strictly blocked by `lib/tool-guard.js`.
+* **Act Mode (Implementation Phase)**: The operator reviews and approves the plan directly via the banner or details modal with «Approve & Execute», unlocking mutating capabilities and resuming the agent.
+* **REST API & Quick Launch**: Toggle modes on demand via `POST /dsh-goal/action` (`set_mode`, `approve_plan`), or select initial mode directly in the Quick Launch dialog.
+
 ---
 
 ## 📦 Installation

package/README.ru.md

@@ -53,6 +53,8 @@
 * 🤖 **Инструменты агента**: `goal_set_milestones`, `goal_update_progress` и `goal_finish` для самостоятельной работы ИИ.
 * 🔄 **Перехват и замещение инструментов ядра DSH (*Добавлено в v0.1.10*)**: Бесшовная совместимость для моделей, вызывающих стандартные инструменты DSH (`update_goal`, `get_goal`, `create_goal`). Перехватывает действия (`complete`, `pause`, `resume`, `edit`, `blocked`), устраняет падения ядра (`complete and blocked require a direct human turn`) и синхронизирует состояние напрямую с GoalEngine.
 * 🛡️ **Защитные лимиты**: настраиваемое ограничение `maxIterations` для предотвращения бесконечных циклов.
+* 🛡️ **Двухфазный режим «Plan Mode ⇄ Act Mode» (*#162*)**: Разделение жизненного цикла цели на фазу проектирования и планирования (только чтение и формирование этапов через `goal_milestones`, блокировка записи файлов и мутирующих команд) и фазу реализации (`Act Mode`), активируемую по кнопке «Утвердить план и запустить» (Approve & Execute).
+* 🛡️ **Автоматический приёмочный гейт этапа (Critic Verification) (*#163*)**: Опциональное поле `verificationCommand` на этапе (например, `npm test`, `pytest`). При попытке закрыть этап команда автоматически запускается в изолированном `safeCwd`. В случае сбоя (`exitCode != 0`) этап остаётся открытым, а диагностический вывод возвращается модели в качестве обратной связи. Git-снимки и синхронизация задач создаются только при коде возврата 0.
 
 ---
 

package/README.zh.md

@@ -54,6 +54,8 @@
 * 🔄 **DSH 核心目标工具无缝拦截与兼容 (*v0.1.10 新增*)**: 为使用原生 DSH 目标控制指令的模型提供完美向下兼容，透明接管 `update_goal`、`get_goal`、`create_goal`。拦截并处理 `complete`、`pause`、`resume`、`edit`、`blocked` 等操作，彻底解决原生工具抛出的 `complete and blocked require a direct human turn` 权限崩溃错误，所有状态直接同步至 GoalEngine。
 * 🛡️ **安全防护机制**：支持自定义最大迭代次数（`maxIterations`）以及智能卡顿检测（Smart Progress Guard）。
 * 🔔 **Web Audio 提示音**：任务完成或失败时，通过 Web Audio API 播放舒缓的合成音效。
+* 📋 **两阶段目标模式：Plan Mode ⇄ Act Mode (*#162*)**：分离规划设计与落地执行。只读规划阶段严格限制文件变更与危险命令，待操作者在横幅或弹窗点击“批准并执行 (Approve & Execute)”后切入执行阶段。
+* 🛡️ **自动化验收门禁与评审检验 (Critic Verification) (*#163*)**：里程碑可配置 `verificationCommand` 验证命令（如 `npm test`、`pytest`）。智能体尝试关闭阶段时，在受控 `safeCwd` 中自动执行检查；若失败（`exitCode != 0`）则阻断关闭并向模型反馈错误输出，仅当命令返回 0 时方可进入完成态并创建 Git 检查点。
 
 ---
 

package/lib/client.js

@@ -730,6 +730,66 @@ window.__ModuleLoader__.load({
 
       }
 
+      .dsh-goal-badge-plan {
+
+        border-color: var(--dsw-alias-brand-primary);
+
+        color: var(--dsw-alias-brand-primary);
+
+        background: var(--dsw-alias-bg-hover);
+
+      }
+
+      .dsh-goal-badge-act {
+
+        border-color: var(--dsw-alias-state-success-primary);
+
+        color: var(--dsw-alias-state-success-primary);
+
+        background: var(--dsw-alias-bg-hover);
+
+      }
+
+      .dsh-goal-btn-approve {
+
+        background: var(--dsw-alias-state-success-primary) !important;
+
+        color: var(--dsw-alias-bg-layer-3) !important;
+
+        font-weight: 600 !important;
+
+        border: none !important;
+
+        cursor: pointer;
+
+      }
+
+      .dsh-goal-btn-approve:hover {
+
+        opacity: 0.88;
+
+      }
+
+      .dsh-goal-plan-banner {
+
+        display: flex;
+
+        align-items: center;
+
+        justify-content: space-between;
+
+        padding: 8px 12px;
+
+        margin-bottom: 12px;
+
+        border-radius: 6px;
+
+        background: var(--dsw-alias-bg-hover);
+
+        border: 1px solid var(--dsw-alias-brand-primary);
+
+      }
+
       .dsh-goal-label {
 
         font-weight: 600;
@@ -1580,6 +1640,29 @@ window.__ModuleLoader__.load({
         margin-left: 6px;
       }
 
+      .dsh-goal-gate-badge {
+        font-size: 10px;
+        padding: 1px 6px;
+        border-radius: 4px;
+        background: var(--dsw-alias-bg-layer-4);
+        color: var(--dsw-alias-brand-primary);
+        border: 1px solid var(--dsw-alias-brand-primary);
+        margin-left: 6px;
+        display: inline-flex;
+        align-items: center;
+        gap: 3px;
+      }
+
+      .dsh-goal-gate-error {
+        font-size: 11px;
+        color: var(--dsw-alias-state-danger-primary);
+        margin-top: 3px;
+        padding: 2px 6px;
+        border-radius: 3px;
+        background: var(--dsw-alias-bg-layer-2);
+        font-family: monospace;
+      }
+
     `;
 
     function injectStylesOnce() {
@@ -1855,6 +1938,7 @@ window.__ModuleLoader__.load({
       const milestones = state.milestones || [];
 
       const isCompleted = state.state === 'COMPLETED';
+      const isPlanMode = state.mode === 'plan' || state.state === 'PLANNING';
 
       const [copied, setCopied] = useState(false);
 
@@ -1992,6 +2076,36 @@ window.__ModuleLoader__.load({
 
             ),
 
+            isPlanMode && !isCompleted
+              ? React.createElement(
+                  'div',
+                  { className: 'dsh-goal-plan-banner' },
+                  React.createElement(
+                    'div',
+                    { style: { display: 'flex', flexDirection: 'column', gap: 2 } },
+                    React.createElement(
+                      'div',
+                      { style: { display: 'flex', alignItems: 'center', gap: 6 } },
+                      React.createElement('span', { className: 'dsh-goal-badge dsh-goal-badge-plan' }, t('planMode') || 'Plan Mode'),
+                      React.createElement('strong', { style: { fontSize: 13, color: 'var(--dsw-alias-brand-primary)' } }, t('planningPhase') || 'Planning Phase (Read-Only)')
+                    ),
+                    React.createElement('span', { style: { fontSize: 12, color: 'var(--dsw-alias-label-secondary)' } }, t('planPhaseNotice') || 'Agent is formulating the plan. File modifications are guarded until operator approval.')
+                  ),
+                  React.createElement(
+                    'button',
+                    {
+                      type: 'button',
+                      className: 'dsh-goal-btn dsh-goal-btn-approve',
+                      style: { padding: '6px 14px', fontSize: 12 },
+                      onClick: async () => {
+                        await onAction('approve_plan');
+                      },
+                    },
+                    '✓ ' + (t('approveAndExecute') || 'Approve & Execute')
+                  )
+                )
+              : null,
+
             !isCompleted
 
               ? React.createElement(
@@ -2287,16 +2401,33 @@ window.__ModuleLoader__.load({
                           },
 
                           `${i + 1}. ${m.title}`,
-                            Array.isArray(m.dependsOn) && m.dependsOn.some((depId) => {
-                              const prereq = milestones.find((x) => x.id === depId || x.title === depId);
-                              return prereq && prereq.status !== 'completed';
-                            })
-                              ? React.createElement('span', { className: 'dsh-goal-lock-badge' }, `🔒 ${t('waitingPrereq') || 'waiting for prereq'}`)
-                              : null,
+                          m.verificationCommand
+                            ? React.createElement(
+                                'span',
+                                {
+                                  className: 'dsh-goal-gate-badge',
+                                  title: `${t('verificationGate') || 'Acceptance gate'}: ${m.verificationCommand}`,
+                                },
+                                `🛡️ ${m.verificationCommand}`
+                              )
+                            : null,
+                          Array.isArray(m.dependsOn) && m.dependsOn.some((depId) => {
+                            const prereq = milestones.find((x) => x.id === depId || x.title === depId);
+                            return prereq && prereq.status !== 'completed';
+                          })
+                            ? React.createElement('span', { className: 'dsh-goal-lock-badge' }, `🔒 ${t('waitingPrereq') || 'waiting for prereq'}`)
+                            : null,
 
                         ),
 
                         m.notes ? React.createElement('div', { style: { fontSize: 12, color: 'var(--dsw-alias-label-tertiary)', marginTop: 2 } }, m.notes) : null,
+                        m.verificationError
+                          ? React.createElement(
+                              'div',
+                              { className: 'dsh-goal-gate-error' },
+                              `⚠️ ${t('verificationFailed') || 'Gate failed'}: ${m.verificationError}`
+                            )
+                          : null,
 
                         Array.isArray(m.checklist) && m.checklist.length > 0
                           ? React.createElement(
@@ -2561,6 +2692,20 @@ window.__ModuleLoader__.load({
 
               : null,
 
+            isPlanMode && !isCompleted
+              ? React.createElement(
+                  'button',
+                  {
+                    type: 'button',
+                    className: 'dsh-goal-btn dsh-goal-btn-approve',
+                    onClick: async () => {
+                      await onAction('approve_plan');
+                    },
+                  },
+                  '✓ ' + (t('approveAndExecute') || 'Approve & Execute')
+                )
+              : null,
+
             React.createElement(
 
               'button',
@@ -2590,6 +2735,7 @@ window.__ModuleLoader__.load({
     function QuickLaunchModal({ onClose, onStart, t }) {
 
       const [title, setTitle] = useState('');
+      const [launchMode, setLaunchMode] = useState('act');
       const [showTemplates, setShowTemplates] = useState(false);
       const [backendTemplates, setBackendTemplates] = useState([]);
       const [selectedTpl, setSelectedTpl] = useState(null);
@@ -2649,7 +2795,7 @@ window.__ModuleLoader__.load({
 
         if (trimmed) {
 
-          onStart(trimmed);
+          onStart(trimmed, { mode: launchMode });
 
         }
 
@@ -2727,6 +2873,34 @@ window.__ModuleLoader__.load({
 
               ),
 
+              React.createElement(
+                'div',
+                { style: { display: 'flex', alignItems: 'center', gap: 8, marginBottom: 10 } },
+                React.createElement('span', { style: { fontSize: 12, fontWeight: 600, color: 'var(--dsw-alias-label-secondary)' } }, t('launchModeLabel') || 'Mode:'),
+                React.createElement(
+                  'button',
+                  {
+                    type: 'button',
+                    className: `dsh-goal-chip-btn ${launchMode === 'act' ? 'active' : ''}`,
+                    style: launchMode === 'act' ? { fontWeight: 600, borderColor: 'var(--dsw-alias-state-success-primary)', color: 'var(--dsw-alias-state-success-primary)' } : {},
+                    onClick: () => setLaunchMode('act'),
+                    title: t('actModeDesc') || 'Direct execution right away',
+                  },
+                  '⚡ ' + (t('actMode') || 'Act Mode')
+                ),
+                React.createElement(
+                  'button',
+                  {
+                    type: 'button',
+                    className: `dsh-goal-chip-btn ${launchMode === 'plan' ? 'active' : ''}`,
+                    style: launchMode === 'plan' ? { fontWeight: 600, borderColor: 'var(--dsw-alias-brand-primary)', color: 'var(--dsw-alias-brand-primary)' } : {},
+                    onClick: () => setLaunchMode('plan'),
+                    title: t('planModeDesc') || 'Plan first, review milestones, then execute',
+                  },
+                  '📋 ' + (t('planMode') || 'Plan Mode')
+                )
+              ),
+
               React.createElement(
 
                 'div',
@@ -3504,9 +3678,9 @@ window.__ModuleLoader__.load({
 
                 onClose: () => setIsQuickLaunchOpen(false),
 
-                onStart: async (title) => {
+                onStart: async (title, opts) => {
 
-                  await handleAction('start', { title });
+                  await handleAction('start', { title, mode: opts?.mode });
 
                   setIsQuickLaunchOpen(false);
 
@@ -3526,6 +3700,8 @@ window.__ModuleLoader__.load({
 
       const isCompleted = state.state === 'COMPLETED';
 
+      const isPlanMode = state.mode === 'plan' || state.state === 'PLANNING';
+
       const formatElapsed = (totalSeconds) => {
         const s = Math.max(0, Math.floor(Number(totalSeconds) || 0));
         if (s < 60) return `${s}s`;
@@ -3580,11 +3756,21 @@ window.__ModuleLoader__.load({
                 ),
                 React.createElement(
                   'span',
-                  { className: `dsh-goal-badge ${isCompleted ? 'dsh-goal-badge-ok' : isPaused ? 'dsh-goal-badge-warn' : ''}` },
-                  isCompleted ? (t('goalCompleted') || 'Done') : isPaused ? (t('paused') || 'Paused') : (t('goalLabel') || 'Goal')
+                  { className: `dsh-goal-badge ${isCompleted ? 'dsh-goal-badge-ok' : isPlanMode ? 'dsh-goal-badge-plan' : isPaused ? 'dsh-goal-badge-warn' : ''}` },
+                  isCompleted ? (t('goalCompleted') || 'Done') : isPlanMode ? (t('planMode') || 'Plan Mode') : isPaused ? (t('paused') || 'Paused') : (t('goalLabel') || 'Goal')
                 ),
                 React.createElement('span', { className: 'dsh-goal-title', title: state.title }, state.title),
                 React.createElement('span', { className: 'dsh-goal-time' }, `⏱ ${liveElapsedStr}`),
+                isPlanMode && !isCompleted ? React.createElement(
+                  'button',
+                  {
+                    className: 'dsh-goal-btn dsh-goal-btn-approve',
+                    style: { padding: '2px 6px', height: 22, fontSize: 11 },
+                    title: t('approveAndExecute') || 'Approve & Execute',
+                    onClick: () => handleAction('approve_plan'),
+                  },
+                  '✓ ' + (t('approveAndExecute') || 'Approve')
+                ) : null,
                 !isCompleted ? React.createElement(
                   'button',
                   {
@@ -3644,11 +3830,11 @@ window.__ModuleLoader__.load({
 
                 {
 
-                  className: `dsh-goal-badge ${isCompleted ? 'dsh-goal-badge-ok' : isPaused ? 'dsh-goal-badge-warn' : ''}`,
+                  className: `dsh-goal-badge ${isCompleted ? 'dsh-goal-badge-ok' : isPlanMode ? 'dsh-goal-badge-plan' : isPaused ? 'dsh-goal-badge-warn' : ''}`,
 
                 },
 
-                isCompleted ? (t('goalCompleted') || 'Goal completed') : isPaused ? (t('paused') || 'Paused') : (t('goalLabel') || 'Current goal'),
+                isCompleted ? (t('goalCompleted') || 'Goal completed') : isPlanMode ? (t('planMode') || 'Plan Mode') : isPaused ? (t('paused') || 'Paused') : (t('goalLabel') || 'Current goal'),
 
               ),
 
@@ -3672,6 +3858,18 @@ window.__ModuleLoader__.load({
 
               ),
 
+              isPlanMode && !isCompleted
+                ? React.createElement(
+                    'button',
+                    {
+                      className: 'dsh-goal-btn dsh-goal-btn-approve',
+                      style: { fontSize: 12, padding: '2px 8px' },
+                      title: t('approveAndExecute') || 'Approve & Execute',
+                      onClick: () => handleAction('approve_plan'),
+                    },
+                    '✓ ' + (t('approveAndExecute') || 'Approve & Execute')
+                  )
+                : null,
               !isCompleted
 
                 ? React.createElement(
@@ -4883,6 +5081,9 @@ window.__ModuleLoader__.load({
         mergeBranch: 'Merge Branch',
         discardBranch: 'Discard Branch',
         retrospectiveTitle: 'Goal Retrospective',
+        verificationGate: 'Acceptance gate',
+        verificationPassed: 'Verified',
+        verificationFailed: 'Gate failed',
         templatesTitle: 'Goal Templates',
         waitingPrereq: 'waiting for prereq',
 
@@ -4983,6 +5184,15 @@ window.__ModuleLoader__.load({
         toolFailHint: 'Auto-pause goal if N consecutive turns hit tool execution errors (0 to disable)',
 
         notifLabel: 'Native browser desktop notifications on completion',
+        planMode: 'Plan Mode',
+        actMode: 'Act Mode',
+        approveAndExecute: 'Approve & Execute',
+        switchToPlan: 'Switch to Plan Mode',
+        planningPhase: 'Planning Phase (Read-Only)',
+        planPhaseNotice: 'Agent is formulating the plan. File modifications are guarded until operator approval.',
+        launchModeLabel: 'Launch Mode:',
+        planModeDesc: 'Plan first, review milestones, then execute',
+        actModeDesc: 'Direct execution right away',
 
       },
 
@@ -5022,6 +5232,9 @@ window.__ModuleLoader__.load({
         mergeBranch: '合并分支',
         discardBranch: '放弃分支',
         retrospectiveTitle: '目标复盘报告',
+        verificationGate: '验收门禁',
+        verificationPassed: '已验证',
+        verificationFailed: '门禁未通过',
         templatesTitle: '目标模板',
         waitingPrereq: '等待前置依赖',
 
@@ -5122,6 +5335,15 @@ window.__ModuleLoader__.load({
         toolFailHint: '连续 N 轮遭遇工具调用错误时自动暂停（0 表示禁用）',
 
         notifLabel: '目标完成时发送浏览器桌面原生通知',
+        planMode: '规划模式',
+        actMode: '执行模式',
+        approveAndExecute: '批准并执行',
+        switchToPlan: '切换到规划模式',
+        planningPhase: '规划阶段（只读）',
+        planPhaseNotice: '智能体正在制定方案与里程碑。在操作者批准前，禁止修改文件。',
+        launchModeLabel: '启动模式：',
+        planModeDesc: '先制定里程碑方案，人工确认后再执行',
+        actModeDesc: '立即开始编码与任务执行',
 
       },
 

package/lib/engine-milestones.js

@@ -74,11 +74,13 @@ export function parseMilestoneItems(milestonesList, startingCount = 0) {
 
     count += 1;
     const mId = typeof item === 'object' && item?.id ? item.id : ('m-' + count);
+    const vCmd = typeof item === 'object' && (item?.verificationCommand || item?.verification_command);
     const mObj = {
       id: String(mId),
       title: itemTitle.trim(),
       status: typeof item === 'object' && item?.status ? item.status : MilestoneStatus.PENDING,
       notes: typeof item === 'object' && item?.notes ? String(item.notes) : '',
+      verificationCommand: vCmd ? String(vCmd).trim() : null,
       dependsOn: typeof item === 'object' && Array.isArray(item?.dependsOn) ? item.dependsOn.map(String) : [],
     };
     if (typeof item === 'object' && Array.isArray(item?.checklist)) {
@@ -116,6 +118,10 @@ export function applyMilestoneUpdate(target, status, notes = '', checklist = nul
     }
   }
 
+  if (options.verificationCommand !== undefined) {
+    target.verificationCommand = options.verificationCommand ? String(options.verificationCommand).trim() : null;
+  }
+
   if (status) {
     if (validStatuses.length > 0 && !validStatuses.includes(status)) {
       return {

package/lib/engine-sessions.js

@@ -1,4 +1,4 @@
-import { GoalState } from './goal-engine-constants.js';
+import { GoalMode, GoalState } from './goal-engine-constants.js';
 
 /**
  * Prune inactive sessions when exceeding maxSessions threshold
@@ -81,3 +81,80 @@ export function extendGoalBudget(goal, addTokens = 50000, defaultBudget = 0) {
   if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
   return newBudget;
 }
+
+/**
+ * Set mode for a goal
+ */
+export function setGoalMode(goal, mode, recordActivity) {
+  if (mode !== GoalMode.PLAN && mode !== GoalMode.ACT) {
+    throw new Error(`Invalid mode: ${mode}. Must be one of: plan, act`);
+  }
+  if (!goal) {
+    throw new Error('No active goal found');
+  }
+  const previousMode = goal.mode || GoalMode.ACT;
+  goal.mode = mode;
+  if (mode === GoalMode.ACT && goal.state === GoalState.PLANNING) {
+    goal.state = GoalState.RUNNING;
+  } else if (mode === GoalMode.PLAN && goal.state === GoalState.RUNNING) {
+    goal.state = GoalState.PLANNING;
+  }
+  const message = mode === GoalMode.ACT
+    ? 'Plan approved by operator, switched to Act Mode'
+    : 'Switched to Plan Mode (read-only planning phase)';
+  goal.logs.push({ timestamp: Date.now(), type: 'info', message });
+  if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+  if (typeof recordActivity === 'function') {
+    recordActivity(goal, { type: 'control', tool: 'setMode', status: 'info', details: `${previousMode} -> ${mode}` });
+  }
+  return goal;
+}
+
+/**
+ * Pause active goal
+ */
+export function pauseGoal(goal, reason, recordActivity) {
+  if (!goal || goal.state !== GoalState.RUNNING) return false;
+  goal.state = GoalState.PAUSED;
+  goal.pausedAt = Date.now();
+  if (typeof recordActivity === 'function') {
+    recordActivity(goal, { type: 'control', tool: 'pause', status: 'warning', details: reason });
+  }
+  goal.logs.push({ timestamp: Date.now(), type: 'warning', message: `Paused: ${reason}` });
+  if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+  return true;
+}
+
+/**
+ * Resume paused goal
+ */
+export function resumeGoal(goal, recordActivity) {
+  if (!goal || goal.state !== GoalState.PAUSED) return false;
+  const now = Date.now();
+  if (goal.pausedAt) {
+    goal.totalPausedDurationMs += now - goal.pausedAt;
+    goal.pausedAt = null;
+  }
+  goal.state = GoalState.RUNNING;
+  if (typeof recordActivity === 'function') {
+    recordActivity(goal, { type: 'control', tool: 'resume', status: 'info', details: 'Resumed by user' });
+  }
+  goal.logs.push({ timestamp: now, type: 'info', message: 'Goal resumed' });
+  if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+  return true;
+}
+
+/**
+ * Cancel active goal
+ */
+export function cancelGoal(goal, reason, recordActivity) {
+  if (!goal) return false;
+  goal.state = GoalState.CANCELLED;
+  goal.completedAt = Date.now();
+  if (typeof recordActivity === 'function') {
+    recordActivity(goal, { type: 'control', tool: 'cancel', status: 'warning', details: reason });
+  }
+  goal.logs.push({ timestamp: Date.now(), type: 'warning', message: `Cancelled: ${reason}` });
+  if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+  return true;
+}

package/lib/engine-verification.js

@@ -0,0 +1,129 @@
+import { spawnSync } from 'node:child_process';
+import { getSafeCwd } from './goal-engine-constants.js';
+
+/**
+ * Execute a verification command in a confined working directory with timeout and output capture
+ * @param {string} command Shell command to execute
+ * @param {string} [targetCwd] Working directory
+ * @param {object} [options]
+ * @param {number} [options.timeoutMs=30000] Timeout in milliseconds
+ * @param {number} [options.maxBuffer=1048576] Max stdout/stderr buffer in bytes (1MB)
+ * @param {object} [options.env={}] Additional environment variables
+ * @returns {{ ok: boolean, exitCode: number, stdout: string, stderr: string, error?: string }}
+ */
+export function runMilestoneVerification(command, targetCwd, options = {}) {
+  if (!command || typeof command !== 'string' || !command.trim()) {
+    return {
+      ok: false,
+      exitCode: 1,
+      stdout: '',
+      stderr: '',
+      error: 'Empty or invalid verification command',
+    };
+  }
+
+  const safeCwd = getSafeCwd(targetCwd) || process.cwd();
+  const timeoutMs = typeof options.timeoutMs === 'number' ? options.timeoutMs : 30000;
+  const maxBuffer = typeof options.maxBuffer === 'number' ? options.maxBuffer : 1024 * 1024;
+
+  try {
+    const res = spawnSync(command.trim(), {
+      shell: true,
+      cwd: safeCwd,
+      timeout: timeoutMs,
+      maxBuffer,
+      encoding: 'utf8',
+      env: { ...process.env, ...options.env },
+    });
+
+    if (res.error) {
+      if (res.error.code === 'ETIMEDOUT') {
+        return {
+          ok: false,
+          exitCode: 124,
+          stdout: res.stdout || '',
+          stderr: res.stderr || '',
+          error: `Verification command timed out after ${timeoutMs}ms`,
+        };
+      }
+      return {
+        ok: false,
+        exitCode: res.status ?? 1,
+        stdout: res.stdout || '',
+        stderr: res.stderr || '',
+        error: res.error.message || 'Verification command failed to execute',
+      };
+    }
+
+    if (res.status !== 0) {
+      const output = (res.stderr || res.stdout || '').trim();
+      return {
+        ok: false,
+        exitCode: res.status ?? 1,
+        stdout: res.stdout || '',
+        stderr: res.stderr || '',
+        error: `Verification command failed with exit code ${res.status}${output ? ': ' + output.slice(0, 500) : ''}`,
+      };
+    }
+
+    return {
+      ok: true,
+      exitCode: 0,
+      stdout: res.stdout || '',
+      stderr: res.stderr || '',
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      exitCode: 1,
+      stdout: '',
+      stderr: '',
+      error: err?.message || 'Unexpected verification failure',
+    };
+  }
+}
+
+/**
+ * Run acceptance gate check on a milestone target and record diagnostic logs/activities
+ * @param {object} target Milestone object
+ * @param {string} targetCwd Working directory
+ * @param {object} [goal] Goal engine state
+ * @param {Function} [recordActivity] Activity recorder function
+ * @param {object} [options]
+ * @returns {{ ok: boolean, verified: boolean, error?: string, output?: string, passedAt?: number }}
+ */
+export function verifyMilestoneAcceptance(target, targetCwd, goal = null, recordActivity = null, options = {}) {
+  if (!target || !target.verificationCommand) {
+    return { ok: true, verified: false };
+  }
+
+  const vRes = runMilestoneVerification(target.verificationCommand, targetCwd, options);
+  if (!vRes.ok) {
+    target.verificationError = vRes.error;
+    target.verificationOutput = (vRes.stderr || vRes.stdout || '').trim();
+    if (goal) {
+      if (typeof recordActivity === 'function') {
+        recordActivity(goal, {
+          type: 'milestone',
+          tool: 'updateMilestone',
+          status: 'error',
+          details: `Verification failed: ${vRes.error}`,
+        });
+      }
+      if (Array.isArray(goal.logs)) {
+        goal.logs.push({
+          timestamp: Date.now(),
+          type: 'error',
+          message: `Acceptance gate failed for [${target.title}]: ${vRes.error}`,
+        });
+        if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+      }
+    }
+    return { ok: false, verified: true, error: vRes.error, output: target.verificationOutput };
+  }
+
+  target.verificationError = null;
+  target.verificationOutput = null;
+  target.verificationPassedAt = Date.now();
+  return { ok: true, verified: true, passedAt: target.verificationPassedAt };
+}

package/lib/goal-engine-constants.js

@@ -4,6 +4,11 @@ import path from "node:path";
  * Enums and helpers for DSH Goal Engine
  */
 
+export const GoalMode = {
+  PLAN: 'plan',
+  ACT: 'act',
+};
+
 export const GoalState = {
   IDLE: 'IDLE',
   PLANNING: 'PLANNING',
@@ -144,6 +149,7 @@ export function buildSnapshot(goal, sid, engine) {
     return {
       sessionId: sid,
       hasActiveGoal: false,
+      mode: GoalMode.ACT,
       state: GoalState.IDLE,
       title: '',
       startedAt: null,
@@ -199,6 +205,7 @@ export function buildSnapshot(goal, sid, engine) {
     sessionId: sid,
     hasActiveGoal: true,
     id: goal.id,
+    mode: goal.mode || (goal.state === GoalState.PLANNING ? GoalMode.PLAN : GoalMode.ACT),
     state: goal.state,
     title: goal.title,
     description: goal.description,

package/lib/goal-engine.js

@@ -1,4 +1,5 @@
-import { GoalState, MilestoneStatus, formatElapsed, formatETA, detectLanguage, sessionIdOf, calculateElapsedSeconds, calculateRemainingSeconds, buildSnapshot, getSafeCwd } from './goal-engine-constants.js';
+import { verifyMilestoneAcceptance } from './engine-verification.js';
+import { GoalMode, GoalState, MilestoneStatus, formatElapsed, formatETA, detectLanguage, sessionIdOf, calculateElapsedSeconds, calculateRemainingSeconds, buildSnapshot, getSafeCwd } from './goal-engine-constants.js';
 import { getGitCurrentCommit, exportReportMarkdown, exportReportGitHubPR, createMilestoneCheckpoint, rollbackToCheckpoint, saveGoalArtifact } from './engine-reports.js';
 import { EngineStore } from './engine-store.js';
 import { buildStatePromptInjection } from './engine-prompt.js';
@@ -8,9 +9,9 @@ import { createGoalBranch, sanitizeBranchSlug, getCurrentGitBranch, mergeGoalBra
 import { parseIssueRef, parseIssueChecklist, syncMilestoneWithIssue } from './engine-issue-sync.js';
 import { generateRetrospectiveData } from './engine-retrospective.js';
 import { generatePreplanDraft } from './engine-templates.js';
-import { pruneInactiveSessions, addNudgeToGoal, consumeGoalNudge, extendGoalBudget } from './engine-sessions.js';
+import { pruneInactiveSessions, addNudgeToGoal, consumeGoalNudge, extendGoalBudget, setGoalMode, pauseGoal, resumeGoal, cancelGoal } from './engine-sessions.js';
 
-export { GoalState, MilestoneStatus, formatElapsed, formatETA, detectLanguage, sessionIdOf, matchMilestone, parseIssueChecklist };
+export { GoalMode, GoalState, MilestoneStatus, formatElapsed, formatETA, detectLanguage, sessionIdOf, matchMilestone, parseIssueChecklist };
 export { getGitCurrentCommit, exportReportMarkdown, exportReportGitHubPR, createMilestoneCheckpoint, rollbackToCheckpoint, saveGoalArtifact };
 
 /**
@@ -193,6 +194,9 @@ export class GoalEngine {
       ? options.gitStartCommit
       : getGitCurrentCommit(options.cwd);
 
+    const initialMode = options.mode === GoalMode.PLAN ? GoalMode.PLAN : GoalMode.ACT;
+    const initialState = initialMode === GoalMode.PLAN ? GoalState.PLANNING : GoalState.RUNNING;
+
     const goal = {
       id: `goal-${now}-${Math.random().toString(36).substring(2, 7)}`,
       sessionId: sid,
@@ -200,7 +204,8 @@ export class GoalEngine {
       description: options.description?.trim() || '',
       lang: options.lang || detectLanguage(cleanTitle),
       cwd: options.cwd ? getSafeCwd(options.cwd) : null,
-      state: GoalState.RUNNING,
+      mode: initialMode,
+      state: initialState,
       startedAt: now,
       pausedAt: null,
       totalPausedDurationMs: 0,
@@ -265,13 +270,7 @@ export class GoalEngine {
   pause(reason = 'User requested pause', sessionId = 'default') {
     const sid = sessionId || 'default';
     const goal = this.goals.get(sid);
-    if (!goal || goal.state !== GoalState.RUNNING) return this.getSnapshot(sid);
-
-    goal.state = GoalState.PAUSED;
-    goal.pausedAt = Date.now();
-    recordActivity(goal, { type: 'control', tool: 'pause', status: 'warning', details: reason });
-    goal.logs.push({ timestamp: Date.now(), type: 'warning', message: `Paused: ${reason}` });
-    if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+    if (!pauseGoal(goal, reason, recordActivity)) return this.getSnapshot(sid);
     this.emit(sid, true);
     return this.getSnapshot(sid);
   }
@@ -279,18 +278,8 @@ export class GoalEngine {
   resume(sessionId = 'default') {
     const sid = sessionId || 'default';
     const goal = this.goals.get(sid);
-    if (!goal || goal.state !== GoalState.PAUSED) return this.getSnapshot(sid);
-
-    const now = Date.now();
-    if (goal.pausedAt) {
-      goal.totalPausedDurationMs += now - goal.pausedAt;
-      goal.pausedAt = null;
-    }
-    goal.state = GoalState.RUNNING;
+    if (!resumeGoal(goal, recordActivity)) return this.getSnapshot(sid);
     this.stallCounters.set(sid, 0);
-    recordActivity(goal, { type: 'control', tool: 'resume', status: 'info', details: 'Resumed by user' });
-    goal.logs.push({ timestamp: now, type: 'info', message: 'Goal resumed' });
-    if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
     this.emit(sid, true);
     return this.getSnapshot(sid);
   }
@@ -298,13 +287,7 @@ export class GoalEngine {
   cancel(reason = 'Cancelled by user', sessionId = 'default') {
     const sid = sessionId || 'default';
     const goal = this.goals.get(sid);
-    if (!goal) return null;
-
-    goal.state = GoalState.CANCELLED;
-    goal.completedAt = Date.now();
-    recordActivity(goal, { type: 'control', tool: 'cancel', status: 'warning', details: reason });
-    goal.logs.push({ timestamp: Date.now(), type: 'warning', message: `Cancelled: ${reason}` });
-    if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+    if (!cancelGoal(goal, reason, recordActivity)) return null;
     this.emit(sid, true);
     return this.getSnapshot(sid);
   }
@@ -375,21 +358,22 @@ export class GoalEngine {
     const target = goal.milestones.find((m) => matchMilestone(m, id));
     if (!target) return false;
 
+    if (status === MilestoneStatus.COMPLETED && target.verificationCommand) {
+      const vRes = verifyMilestoneAcceptance(target, goal.cwd || process.cwd(), goal, recordActivity);
+      if (!vRes.ok) {
+        this.emit(sid);
+        return false;
+      }
+    }
+
     const res = applyMilestoneUpdate(target, status, notes, checklist, Object.values(MilestoneStatus), {
       enforceDependencies: this.enableMilestoneDependencies,
       allMilestones: goal.milestones,
     });
     if (res.invalidStatus || res.blocked) {
-      if (res.invalidStatus) {
-        this.logger?.warn?.(`[dsh-goal] Invalid milestone status "${status}" for milestone ${id}`);
-      }
+      if (res.invalidStatus) this.logger?.warn?.(`[dsh-goal] Invalid milestone status "${status}" for milestone ${id}`);
       if (res.blocked) {
-        recordActivity(goal, {
-          type: 'milestone',
-          tool: 'updateMilestone',
-          status: 'error',
-          details: `Milestone ${id} blocked by ${res.missingDependencies?.join(', ')}`,
-        });
+        recordActivity(goal, { type: 'milestone', tool: 'updateMilestone', status: 'error', details: `Milestone ${id} blocked by ${res.missingDependencies?.join(', ')}` });
       }
       return false;
     }
@@ -580,4 +564,26 @@ export class GoalEngine {
     const goal = this.goals.get(sid);
     if (goal) recordActivity(goal, { type: 'tool', tool, status, details });
   }
+
+  setMode(mode, sessionId = 'default') {
+    const sid = sessionId || 'default';
+    const goal = this.goals.get(sid);
+    if (!goal) throw new Error(`No active goal for session "${sid}"`);
+    setGoalMode(goal, mode, recordActivity);
+    this.emit(sid, true);
+    return this.getSnapshot(sid);
+  }
+
+  approvePlan(sessionId = 'default') {
+    return this.setMode(GoalMode.ACT, sessionId);
+  }
+
+  getActiveGoal(sessionId = 'default') {
+    return this.goals.get(sessionId || 'default') || null;
+  }
+
+  isPlanMode(sessionId = 'default') {
+    const goal = this.goals.get(sessionId || 'default');
+    return Boolean(goal && (goal.mode === GoalMode.PLAN || goal.state === GoalState.PLANNING));
+  }
 }

package/lib/index.js

@@ -19,6 +19,7 @@ import { GitSnapshotManager } from './git-snapshot-manager.js';
 import { MilestoneManager } from './milestone-manager.js';
 import { registerRoutes } from './routes.js';
 import { registerTools } from './tools.js';
+import { registerPlanModeGuard, createPlanModeGuard, isPermittedInPlanMode } from './tool-guard.js';
 import { saveGoalReportFile } from './engine-reports.js';
 import { registerPluginUpdater } from './updater.js';
 import { GoalEngine, GoalState } from './goal-engine.js';
@@ -168,6 +169,7 @@ export function apply(ctx, config = {}) {
       enableMilestoneDependencies: currentSettings.enableMilestoneDependencies,
       logger,
     });
+    registerPlanModeGuard(ctx, { engine: fallbackEngine, logger });
   }
 
   // 1. One-click auto-updater registration (Issue #99)
@@ -414,3 +416,5 @@ export function apply(ctx, config = {}) {
     engine: fallbackEngine,
   };
 }
+
+export { registerPlanModeGuard, createPlanModeGuard, isPermittedInPlanMode };

package/lib/milestone-manager.js

@@ -1,4 +1,5 @@
 import { syncMilestoneWithIssue } from './engine-issue-sync.js';
+import { runMilestoneVerification } from './engine-verification.js';
 
 /**
  * Milestone and checklist coordinator for active core goals
@@ -24,6 +25,7 @@ export class MilestoneManager {
       completed: Boolean(m.completed),
       completedAt: m.completedAt || null,
       notes: m.notes || '',
+      verificationCommand: m.verificationCommand || m.verification_command ? String(m.verificationCommand || m.verification_command).trim() : null,
       dependsOn: Array.isArray(m.dependsOn) ? m.dependsOn : [],
       checklist: Array.isArray(m.checklist) ? m.checklist.map((c, cIdx) => ({
         id: c.id || `cl-${idx + 1}-${cIdx + 1}`,
@@ -35,16 +37,18 @@ export class MilestoneManager {
     return sanitized;
   }
 
-  addMilestone(goalId, { title, checklist = [], dependsOn = [] }) {
+  addMilestone(goalId, { title, checklist = [], dependsOn = [], verificationCommand = null, verification_command = null }) {
     if (!goalId || !this.store) throw new Error('Missing goalId or store');
     const list = this.getMilestones(goalId);
     const id = `m-${list.length + 1}`;
+    const vCmd = verificationCommand || verification_command;
     const newM = {
       id,
       title: title || `Milestone ${list.length + 1}`,
       completed: false,
       completedAt: null,
       notes: '',
+      verificationCommand: vCmd ? String(vCmd).trim() : null,
       dependsOn: Array.isArray(dependsOn) ? dependsOn : [],
       checklist: (checklist || []).map((c, cIdx) => ({
         id: `cl-${list.length + 1}-${cIdx + 1}`,
@@ -74,6 +78,20 @@ export class MilestoneManager {
       }
     }
 
+    // Acceptance Gate (Critic Verification) - Issue #163
+    if (m.verificationCommand) {
+      const vResult = runMilestoneVerification(m.verificationCommand, workspaceRoot);
+      if (!vResult.ok) {
+        m.verificationError = vResult.error;
+        m.verificationOutput = (vResult.stderr || vResult.stdout || '').trim();
+        this.store.setMilestones(goalId, list);
+        throw new Error(`Acceptance gate failed for milestone "${milestoneId}" (${m.verificationCommand}): ${vResult.error}`);
+      }
+      m.verificationError = null;
+      m.verificationOutput = null;
+      m.verificationPassedAt = Date.now();
+    }
+
     m.completed = true;
     m.completedAt = Date.now();
     if (notes) m.notes = notes;
@@ -110,6 +128,33 @@ export class MilestoneManager {
     return { milestone: m, snapshot };
   }
 
+  updateMilestone(goalId, milestoneId, { status, notes = '', checklist = null, verificationCommand = null, cwd = null } = {}) {
+    if (!goalId || !milestoneId) throw new Error('goalId and milestoneId are required');
+    const list = this.getMilestones(goalId);
+    const m = list.find(item => item.id === milestoneId);
+    if (!m) return null;
+
+    if (verificationCommand !== undefined && verificationCommand !== null) {
+      m.verificationCommand = String(verificationCommand).trim() || null;
+    }
+
+    if (status === 'completed') {
+      return this.completeMilestone(goalId, milestoneId, notes, cwd);
+    }
+
+    if (status) m.status = status;
+    if (notes) m.notes = notes;
+    if (Array.isArray(checklist)) {
+      m.checklist = checklist.map((c, cIdx) => ({
+        id: typeof c === 'object' && c?.id ? c.id : `cl-${milestoneId}-${cIdx + 1}`,
+        text: typeof c === 'string' ? c : (c?.text || ''),
+        done: Boolean(c?.done),
+      }));
+    }
+    this.store.setMilestones(goalId, list);
+    return m;
+  }
+
   toggleChecklist(goalId, milestoneId, index, done) {
     if (!goalId || !milestoneId) throw new Error('goalId and milestoneId are required');
     const list = this.getMilestones(goalId);
@@ -139,7 +184,8 @@ export class MilestoneManager {
     if (uncompletedChecklist.length > 0) {
       clText = ` | Next items: ${uncompletedChecklist.map(c => `[ ] ${c.text}`).join(', ')}`;
     }
+    const gateText = active.verificationCommand ? ` [Gate: "${active.verificationCommand}"]` : '';
 
-    return `[Goal Milestones]: Current step: "${active.title}"${clText}`;
+    return `[Goal Milestones]: Current step: "${active.title}"${gateText}${clText}`;
   }
 }

package/lib/routes.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { MilestoneStatus, detectLanguage, sessionIdOf, isPathInsideOrEqual, getSafeCwd } from './goal-engine-constants.js';
+import { MilestoneStatus, GoalMode, detectLanguage, sessionIdOf, isPathInsideOrEqual, getSafeCwd } from './goal-engine-constants.js';
 import { isValidGitRef } from './engine-git-branch.js';
 import { saveGoalArtifact, rollbackToCheckpoint } from './engine-reports.js';
 import { getTemplatesCatalogue, instantiateTemplate } from './engine-templates.js';
@@ -467,24 +467,32 @@ export function registerRoutes(ctx, {
                       lang: detectedLang,
                       cwd: safeStartCwd,
                       issueBody: data.issueBody,
+                      mode: data.mode,
                     }, sid);
                   } else {
                     let parsedMilestones = [];
                     if (data.issueBody) {
                       parsedMilestones = parseIssueChecklist(data.issueBody);
                     }
+                    const initialMode = data.mode === 'plan' ? 'plan' : 'act';
                     result = {
                       title: cleanTitle,
                       sessionId: sid,
                       hasActiveGoal: true,
-                      state: 'RUNNING',
+                      mode: initialMode,
+                      state: initialMode === 'plan' ? 'PLANNING' : 'RUNNING',
                       milestones: parsedMilestones,
                     };
                   }
 
-                  const startPrompt = detectedLang === 'zh'
-                    ? `🎯 目标已确立：“${cleanTitle}”。请立即通过 goal_milestones 制定工作计划并开始执行。`
-                    : `🎯 Goal established: "${cleanTitle}". Formulate milestones via goal_milestones and proceed.`;
+                  const isPlan = result?.mode === 'plan' || (engine && typeof engine.isPlanMode === 'function' && engine.isPlanMode(sid));
+                  const startPrompt = isPlan
+                    ? (detectedLang === 'zh'
+                      ? `🎯 目标已确立（规划模式/Plan Mode）：“${cleanTitle}”。请通过 goal_milestones 制定工作计划并列出检查清单。在操作者批准前，请勿进行写文件等变更操作。`
+                      : `🎯 Goal established in Plan Mode: "${cleanTitle}". Formulate milestones and checklist via goal_milestones and goal_checklist. Do not modify files until the operator approves the plan.`)
+                    : (detectedLang === 'zh'
+                      ? `🎯 目标已确立：“${cleanTitle}”。请立即通过 goal_milestones 制定工作计划并开始执行。`
+                      : `🎯 Goal established: "${cleanTitle}". Formulate milestones via goal_milestones and proceed.`);
 
                   if (typeof resumeActiveAgent === 'function') {
                     resumeActiveAgent(startPrompt, sid);
@@ -714,6 +722,55 @@ export function registerRoutes(ctx, {
                   break;
                 }
 
+                case 'set_mode': {
+                  const targetMode = data.mode;
+                  if (targetMode !== GoalMode.PLAN && targetMode !== GoalMode.ACT) {
+                    res.statusCode = 400;
+                    return res.end(JSON.stringify({ error: `Invalid mode "${targetMode}". Must be "plan" or "act".` }));
+                  }
+                  if (engine) {
+                    const snap = engine.getSnapshot(sid);
+                    if (!snap || !snap.hasActiveGoal) {
+                      res.statusCode = 404;
+                      return res.end(JSON.stringify({ error: 'No active goal found to set mode' }));
+                    }
+                    result = engine.setMode(targetMode, sid);
+                    if (targetMode === GoalMode.ACT) {
+                      const detectedLang = snap.lang || 'en';
+                      const prompt = detectedLang === 'zh'
+                        ? '⚡ 执行模式（Act Mode）已激活。请继续推进目标任务。'
+                        : '⚡ Act Mode activated by operator. Proceed with task execution.';
+                      if (typeof resumeActiveAgent === 'function') {
+                        resumeActiveAgent(prompt, sid);
+                      }
+                    }
+                  } else {
+                    result = { mode: targetMode, state: targetMode === GoalMode.PLAN ? 'PLANNING' : 'RUNNING' };
+                  }
+                  break;
+                }
+
+                case 'approve_plan': {
+                  if (engine) {
+                    const snap = engine.getSnapshot(sid);
+                    if (!snap || !snap.hasActiveGoal) {
+                      res.statusCode = 404;
+                      return res.end(JSON.stringify({ error: 'No active goal found to approve plan' }));
+                    }
+                    result = engine.approvePlan(sid);
+                    const detectedLang = snap.lang || 'en';
+                    const prompt = detectedLang === 'zh'
+                      ? '✅ 操作者已批准计划。执行模式（Act Mode）已激活。请立即开始具体代码与任务实现。'
+                      : '✅ Plan approved by operator. Act Mode activated. Proceed with implementation.';
+                    if (typeof resumeActiveAgent === 'function') {
+                      resumeActiveAgent(prompt, sid);
+                    }
+                  } else {
+                    result = { mode: GoalMode.ACT, state: 'RUNNING', approved: true };
+                  }
+                  break;
+                }
+
                 case 'branch_action': {
                   const op = String(data.operation || data.branchOperation || 'merge').toLowerCase();
                   const targetBranch = String(data.targetBranch || 'main');

package/lib/tool-guard.js

@@ -0,0 +1,147 @@
+/**
+ * Plan Mode tool execution guard for @goodandready/dsh-goal.
+ * Blocks mutating file operations and commands during the planning phase.
+ */
+
+export const READ_ONLY_TOOLS = new Set([
+  'view_file',
+  'read_file',
+  'read_url_content',
+  'search_web',
+  'search',
+  'grep',
+  'glob',
+  'find',
+  'list_dir',
+  'dir_list',
+  'code_search',
+  'read_resource',
+  'list_resources',
+  'brain_recall',
+  'brain_list',
+  'brain_status',
+  'brain_remember',
+  'ask_question',
+  'send_message',
+  'schedule',
+  'manage_task',
+  'get_goal',
+]);
+
+export const FILE_WRITER_TOOLS = new Set([
+  'write_to_file',
+  'replace_file_content',
+  'edit_file',
+  'apply_diff',
+  'patch',
+  'create_file',
+  'delete_file',
+  'remove_file',
+]);
+
+const SAFE_COMMAND_PATTERN = /^(git\s+(status|diff|log|branch|show)|ls|dir|pwd|cat|head|tail|grep|find|wc|echo|which|where)(\s+|$)/i;
+const MUTATING_COMMAND_PATTERN = /(\b(rm|rmdir|mv|cp|mkdir|touch|chmod|chown|sed\s+-i|git\s+(commit|checkout\s+-b|push|merge|rebase|reset|restore))\b|[>|&;])/i;
+
+/**
+ * Check whether a tool is permitted in Plan Mode.
+ * @param {string} toolName
+ * @param {object} [args]
+ * @returns {boolean}
+ */
+export function isPermittedInPlanMode(toolName, args = {}) {
+  if (!toolName || typeof toolName !== 'string') return false;
+
+  // Milestone and checklist tools are explicitly permitted in plan mode
+  if (toolName === 'goal_milestones' || toolName === 'goal_checklist') {
+    return true;
+  }
+
+  // Explicit file writing tools are strictly blocked
+  if (FILE_WRITER_TOOLS.has(toolName)) {
+    return false;
+  }
+
+  // Check command execution
+  if (toolName === 'run_command' || toolName === 'execute_command' || toolName === 'bash') {
+    const rawCmd = (args.CommandLine || args.command || args.cmd || '').trim();
+    if (!rawCmd) return true;
+    if (SAFE_COMMAND_PATTERN.test(rawCmd) && !MUTATING_COMMAND_PATTERN.test(rawCmd)) {
+      return true;
+    }
+    return false;
+  }
+
+  // Allow known read-only inspection tools
+  if (READ_ONLY_TOOLS.has(toolName)) {
+    return true;
+  }
+
+  // Default fail-closed for unknown tools in plan mode
+  return false;
+}
+
+/**
+ * Create a tool guard function for Cordis ctx.tools.guard.
+ * @param {import('./goal-engine.js').GoalEngine} engine
+ * @param {object} [logger]
+ * @returns {(execution: object) => string | undefined}
+ */
+export function createPlanModeGuard(engine, logger = console) {
+  return function planModeGuard(execution) {
+    if (!engine || typeof engine.isPlanMode !== 'function') return undefined;
+
+    const sid = execution?.sessionId || execution?.session?.id || 'default';
+    if (!engine.isPlanMode(sid)) {
+      return undefined;
+    }
+
+    const toolName = execution?.name || execution?.tool || '';
+    if (isPermittedInPlanMode(toolName, execution?.arguments)) {
+      return undefined;
+    }
+
+    const rejection = `[Plan Mode Active] Tool "${toolName}" is blocked in Plan Mode. The goal is in the planning phase and file modifications are restricted until the plan is approved by the operator. Use goal_milestones to define the milestones and ask the operator to approve the plan or switch to Act Mode.`;
+    logger?.warn?.(`[dsh-goal] Blocked tool execution in Plan Mode: ${toolName}`);
+    return rejection;
+  };
+}
+
+/**
+ * Register the plan mode guard with Cordis context.
+ * @param {any} ctx
+ * @param {object} options
+ * @param {import('./goal-engine.js').GoalEngine} options.engine
+ * @param {object} [options.logger]
+ */
+export function registerPlanModeGuard(ctx, { engine, logger = console } = {}) {
+  if (!ctx || !engine) return;
+
+  const guard = createPlanModeGuard(engine, logger);
+
+  // 1. Cordis tools service guard
+  ctx.inject(['tools'], (tctx) => {
+    if (typeof tctx.tools?.guard === 'function') {
+      try {
+        const unguard = tctx.tools.guard(guard);
+        if (typeof unguard === 'function' && typeof tctx.effect === 'function') {
+          tctx.effect(() => () => {
+            try { unguard(); } catch (e) { /* ignore */ }
+          }, 'dsh-goal: plan mode tool guard');
+        }
+      } catch (err) {
+        logger?.warn?.('[dsh-goal] Failed to register tools guard:', err.message);
+      }
+    }
+  });
+
+  // 2. Pre-execute event hook if present
+  if (typeof ctx.on === 'function') {
+    ctx.on('tools/pre-execute', (execution, next) => {
+      const decision = guard(execution);
+      if (decision !== undefined) {
+        return { kind: 'deny', reason: decision };
+      }
+      return typeof next === 'function' ? next() : undefined;
+    });
+  }
+}

package/lib/tools.js

@@ -76,6 +76,7 @@ export function registerTools(ctx, { milestoneManager, goalsService, logger = co
           title: args.title,
           checklist: args.checklist,
           dependsOn: args.dependsOn || args.depends_on,
+          verificationCommand: args.verificationCommand || args.verification_command,
         });
         return { ok: true, goalId, milestone: item };
       }
@@ -124,6 +125,7 @@ export function registerTools(ctx, { milestoneManager, goalsService, logger = co
                   },
                 },
                 dependsOn: { type: 'array', items: { type: 'string' } },
+                verificationCommand: { type: 'string', description: 'Optional shell command to verify milestone completion' },
               },
               required: ['title'],
             },
@@ -136,6 +138,10 @@ export function registerTools(ctx, { milestoneManager, goalsService, logger = co
             items: { type: 'string' },
             description: 'Initial checklist items for added milestone',
           },
+          verificationCommand: {
+            type: 'string',
+            description: 'Verification command when action is "add"',
+          },
         },
         required: ['action'],
       },
@@ -230,7 +236,12 @@ export function registerTools(ctx, { milestoneManager, goalsService, logger = co
         const completed = await mm.completeMilestone(goalId, milestoneId, notes, safeCwd);
         return { ok: true, goalId, milestoneId, status: 'completed', milestone: completed };
       }
-      const updated = mm.updateMilestone(goalId, milestoneId, { status, notes, checklist: args.checklist });
+      const updated = mm.updateMilestone(goalId, milestoneId, {
+        status,
+        notes,
+        checklist: args.checklist,
+        verificationCommand: args.verificationCommand || args.verification_command,
+      });
       return { ok: true, goalId, milestoneId, status, milestone: updated };
     };
 
@@ -244,6 +255,7 @@ export function registerTools(ctx, { milestoneManager, goalsService, logger = co
           status: { type: 'string', enum: ['pending', 'in_progress', 'completed', 'blocked'], description: 'Milestone status' },
           notes: { type: 'string', description: 'Brief outcome or status notes' },
           checklist: { type: 'array', items: { type: 'string' }, description: 'Subtask items' },
+          verificationCommand: { type: 'string', description: 'Optional verification command to set or update' },
         },
         required: ['milestone_id', 'status'],
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-goal",
-  "version": "0.2.26",
+  "version": "0.2.28",
   "description": "Core Goal Addon (Token Budget, Milestones, Git Snapshots & Retrospective Reports) for DeepSeek Harness",
   "type": "module",
   "main": "./lib/index.js",
@@ -18,10 +18,6 @@
     "cordis.patch.yml",
     "LICENSE"
   ],
-  "scripts": {
-    "build:client": "node scripts/build-client.mjs",
-    "test": "node scripts/build-client.mjs --check && NODE_ENV=test node --test test/*.test.mjs"
-  },
   "keywords": [
     "dsh",
     "dsh-plugin",
@@ -60,5 +56,9 @@
   },
   "devDependencies": {
     "@deepseek-ai/schemastery": "^3.18.4"
+  },
+  "scripts": {
+    "build:client": "node scripts/build-client.mjs",
+    "test": "node scripts/build-client.mjs --check && NODE_ENV=test node --test test/*.test.mjs"
   }
-}
+}