principles-disciple 1.59.0 → 1.61.0

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "principles-disciple",
   "name": "Principles Disciple",
   "description": "Evolutionary programming agent framework with strategic guardrails and reflection loops.",
-  "version": "1.59.0",
+  "version": "1.61.0",
   "skills": [
     "./skills"
   ],
@@ -76,8 +76,8 @@
     }
   },
   "buildFingerprint": {
-    "gitSha": "f37ee1dec538",
-    "bundleMd5": "f578c460a9849e9b6e6c573d13e48f12",
-    "builtAt": "2026-04-18T07:51:05.292Z"
+    "gitSha": "b300ef0761c5",
+    "bundleMd5": "3c16a5198f3559b097d028b6e987cf5b",
+    "builtAt": "2026-04-18T11:02:10.525Z"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "1.59.0",
+  "version": "1.61.0",
   "description": "Native OpenClaw plugin for Principles Disciple",
   "type": "module",
   "main": "./dist/bundle.js",

package/src/commands/archive-impl.ts

@@ -19,6 +19,7 @@ import {
 } from '../core/principle-tree-ledger.js';
 import type { Implementation, ImplementationLifecycleState } from '../types/principle-tree-schema.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
 /**
  * Get all implementations from the ledger.
@@ -43,7 +44,7 @@ function canArchive(state: ImplementationLifecycleState): boolean {
  *   /pd-archive-impl list       - List archivable implementations
  */
 export function handleArchiveImplCommand(ctx: PluginCommandContext): PluginCommandResult {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'archive-impl');
   const {stateDir} = WorkspaceContext.fromHookContext({ ...ctx, workspaceDir });
   const lang = (ctx.config?.language as string) || 'en';
   const isZh = lang === 'zh';

package/src/commands/capabilities.ts

@@ -4,6 +4,7 @@ import * as path from 'path';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 import { atomicWriteFileSync } from '../utils/io.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
 const TOOLS_TO_SCAN = [
   { name: 'rg', cmd: ['rg', '--version'] },
@@ -50,7 +51,7 @@ function scanEnvironment(wctx: WorkspaceContext): any {
 }
 
 export function handleBootstrapTools(ctx: PluginCommandContext): PluginCommandResult {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'capabilities');
   const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });
 
   try {

package/src/commands/context.ts

@@ -2,6 +2,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 import { atomicWriteFileSync } from '../utils/io.js';
 import type { ContextInjectionConfig} from '../types.js';
 import { defaultContextConfig } from '../types.js';
@@ -11,11 +12,8 @@ import { loadContextInjectionConfig } from '../hooks/prompt.js';
  * Get workspace directory from context
  */
 function getWorkspaceDir(ctx: PluginCommandContext): string {
-    const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
-    if (!workspaceDir) {
-        throw new Error('[PD:Context] workspaceDir is required but not provided');
-    }
-    return workspaceDir;
+    // resolvePluginCommandWorkspaceDir throws on failure — never returns falsy
+    return resolvePluginCommandWorkspaceDir(ctx, 'context');
 }
 
 /**

package/src/commands/disable-impl.ts

@@ -21,6 +21,7 @@ import {
 } from '../core/principle-tree-ledger.js';
 import type { Implementation, ImplementationLifecycleState } from '../types/principle-tree-schema.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
 /**
  * Get all implementations from the ledger.
@@ -133,7 +134,7 @@ function _handleDisableImpl(
  */
      
 export function handleDisableImplCommand(ctx: PluginCommandContext): PluginCommandResult {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'disable-impl');
   const {stateDir} = WorkspaceContext.fromHookContext({ ...ctx, workspaceDir });
   const lang = (ctx.config?.language as string) || 'en';
   const isZh = lang === 'zh';

package/src/commands/evolution-status.ts

@@ -4,6 +4,7 @@ import { WorkspaceContext } from '../core/workspace-context.js';
 import { normalizeLanguage } from '../i18n/commands.js';
 import type { PluginCommandContext } from '../openclaw-sdk.js';
 import { RuntimeSummaryService } from '../service/runtime-summary-service.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
 function formatNumber(value: number | null): string {
   if (value === null || Number.isNaN(value)) {
@@ -168,7 +169,7 @@ function buildChineseOutput(
 }
 
 export function handleEvolutionStatusCommand(ctx: PluginCommandContext): { text: string } {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'evolution-status');
   const sessionId = (ctx as { sessionId?: string | null }).sessionId ?? null;
   // #207/#210: Use WorkspaceContext to get evolutionReducer with stateDir
   const wctx = WorkspaceContext.fromHookContext({ workspaceDir });

package/src/commands/export.ts

@@ -1,5 +1,6 @@
 import { WorkspaceContext } from '../core/workspace-context.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 import { exportORPOSamples, listExports } from '../core/nocturnal-export.js';
 
 function isZh(ctx: PluginCommandContext): boolean {
@@ -7,7 +8,7 @@ function isZh(ctx: PluginCommandContext): boolean {
 }
 
 export function handleExportCommand(ctx: PluginCommandContext): PluginCommandResult {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'export');
   const zh = isZh(ctx);
   const args = (ctx.args || '').trim();
   const parts = args.split(/\s+/).filter(Boolean);

package/src/commands/focus.ts

@@ -13,6 +13,7 @@ import * as path from 'path';
 import type { PluginCommandContext, PluginCommandResult, OpenClawPluginApi } from '../openclaw-sdk.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 import { atomicWriteFileSync } from '../utils/io.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 import {
   getHistoryDir,
   backupToHistory,
@@ -28,11 +29,7 @@ import {
  * 获取工作区目录
  */
 function getWorkspaceDir(ctx: PluginCommandContext): string {
-  const workspaceDir = ctx.config?.workspaceDir as string | undefined;
-  if (!workspaceDir) {
-    throw new Error('[PD:Focus] workspaceDir is required but not provided');
-  }
-  return workspaceDir;
+  return resolvePluginCommandWorkspaceDir(ctx, 'focus');
 }
 
 /**

package/src/commands/nocturnal-review.ts

@@ -34,6 +34,7 @@ import {
 } from '../core/nocturnal-dataset.js';
 import { getPrincipleState, setPrincipleState } from '../core/principle-training-state.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
 function isZh(ctx: PluginCommandContext): boolean {
   return String(ctx.config?.language || 'en').startsWith('zh');
@@ -91,7 +92,7 @@ function statusLabel(status: NocturnalReviewStatus, zh: boolean): string {
 }
 
 export function handleNocturnalReviewCommand(ctx: PluginCommandContext): PluginCommandResult {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'nocturnal-review');
   const zh = isZh(ctx);
   const args = (ctx.args || '').trim();
   const parts = args.split(/\s+/).filter(Boolean);

package/src/commands/nocturnal-rollout.ts

@@ -25,6 +25,7 @@
  */
 
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 import {
   evaluatePromotionGate,
   advancePromotion,
@@ -99,7 +100,7 @@ function formatConstraintCheck(
 }
 
 export function handleNocturnalRolloutCommand(ctx: PluginCommandContext): PluginCommandResult {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'nocturnal-rollout');
   const zh = isZh(ctx);
   const args = (ctx.args || '').trim();
   const parts = args.split(/\s+/).filter(Boolean);

package/src/commands/nocturnal-train.ts

@@ -28,6 +28,7 @@ import { execFileSync, spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { atomicWriteFileSync } from '../utils/io.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 import {
   type TrainerBackendKind,
   type HardwareTier,
@@ -100,7 +101,7 @@ function formatTrainingRun(run: ReturnType<typeof getTrainingRun>, zh: boolean):
 }
 
 export async function handleNocturnalTrainCommand(ctx: PluginCommandContext): Promise<PluginCommandResult> {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'nocturnal-train');
   const zh = isZh(ctx);
   const args = (ctx.args || '').trim();
   const parts = args.split(/\s+/).filter(Boolean);

package/src/commands/pain.ts

@@ -1,6 +1,7 @@
 import { resetFriction, getSession } from '../core/session-tracker.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 import type { EmpathyEventStats } from '../types/event-types.js';
 
 /**
@@ -92,7 +93,7 @@ interface SessionAwareCommandContext extends PluginCommandContext {
  * Handles the /pd-status command
  */
 export function handlePainCommand(ctx: PluginCommandContext): PluginCommandResult {
-    const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+    const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'pain');
     
     const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });
     const lang = (ctx.config?.language as string) || 'en';

package/src/commands/pd-reflect.ts

@@ -8,6 +8,7 @@
 import type { PluginCommandDefinition, PluginCommandContext, PluginCommandResult, OpenClawPluginApi } from '../openclaw-sdk.js';
 import { acquireQueueLock, EVOLUTION_QUEUE_LOCK_SUFFIX } from '../service/evolution-worker.js';
 import { atomicWriteFileSync } from '../utils/io.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 import * as fs from 'fs';
 import * as path from 'path';
 
@@ -23,11 +24,7 @@ export const handlePdReflect: PluginCommandDefinition = {
   requireAuth: false,
   handler: async (ctx: PdReflectContext): Promise<PluginCommandResult> => {
     try {
-       
-      const workspaceDir = ctx.workspaceDir;
-      if (!workspaceDir) {
-        return { text: 'Cannot determine workspace directory. Ensure you are in an active workspace.', isError: true };
-      }
+      const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'pd-reflect');
 
       const stateDir = path.join(workspaceDir, '.state');
       const queuePath = path.join(stateDir, 'evolution_queue.json');
@@ -80,9 +77,10 @@ export const handlePdReflect: PluginCommandDefinition = {
       return {
         text: `Nocturnal reflection task enqueued: \`${taskId}\`\n\nIt will be processed in the next evolution worker cycle (~15s). Check .state/nocturnal/samples/ for results.`,
       };
-    } catch (error) {
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err);
       return {
-        text: `Failed to trigger reflection: ${String(error)}`,
+        text: `Failed to trigger reflection: ${message}`,
         isError: true,
       };
     }

package/src/commands/principle-rollback.ts

@@ -1,9 +1,10 @@
 import { WorkspaceContext } from '../core/workspace-context.js';
 import type { PluginCommandContext } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
      
 export function handlePrincipleRollbackCommand(ctx: PluginCommandContext): { text: string } {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'principle-rollback');
   const argText = (ctx.args || '').trim();
   const [principleId = '', ...reasonParts] = argText.split(/\s+/);
   const reason = (reasonParts.join(' ') || 'manual rollback').trim();

package/src/commands/promote-impl.ts

@@ -28,6 +28,7 @@ import {
 } from '../core/principle-tree-ledger.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 import type { Implementation, ImplementationLifecycleState } from '../types/principle-tree-schema.js';
 import { withLock } from '../utils/file-lock.js';
 import { atomicWriteFileSync } from '../utils/io.js';
@@ -250,7 +251,7 @@ function _handlePromoteImpl(options: PromoteImplOptions): PluginCommandResult {
 }
 
 export function handlePromoteImplCommand(ctx: PluginCommandContext): PluginCommandResult {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'promote-impl');
   const {stateDir} = WorkspaceContext.fromHookContext({ ...ctx, workspaceDir });
   const lang = (ctx.config?.language as string) || 'en';
   const isZh = lang === 'zh';

package/src/commands/rollback-impl.ts

@@ -25,6 +25,7 @@ import {
 } from '../core/principle-tree-ledger.js';
 import type { Implementation } from '../types/principle-tree-schema.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
 /**
  * Get all implementations from the ledger.
@@ -44,7 +45,7 @@ function getAllImplementations(stateDir: string): Implementation[] {
  */
      
 export function handleRollbackImplCommand(ctx: PluginCommandContext): PluginCommandResult {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'rollback-impl');
   const {stateDir} = WorkspaceContext.fromHookContext({ ...ctx, workspaceDir });
   const lang = (ctx.config?.language as string) || 'en';
   const isZh = lang === 'zh';

package/src/commands/rollback.ts

@@ -1,6 +1,7 @@
 import { WorkspaceContext } from '../core/workspace-context.js';
 import { resetFriction } from '../core/session-tracker.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
 /**
  * Extended context interface that includes sessionId injected by the plugin framework.
@@ -18,7 +19,7 @@ interface SessionAwareCommandContext extends PluginCommandContext {
  *   /pd-rollback last        - Rollback the last empathy event in current session
  */
 export function handleRollbackCommand(ctx: PluginCommandContext): PluginCommandResult {
-    const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+    const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'rollback');
     
     const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });
     const lang = (ctx.config?.language as string) || 'en';

package/src/commands/samples.ts

@@ -1,12 +1,13 @@
 import { WorkspaceContext } from '../core/workspace-context.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
 function isZh(ctx: PluginCommandContext): boolean {
   return String(ctx.config?.language || 'en').startsWith('zh');
 }
 
 export function handleSamplesCommand(ctx: PluginCommandContext): PluginCommandResult {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'samples');
   const zh = isZh(ctx);
   const args = (ctx.args || '').trim();
   const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });

package/src/commands/strategy.ts

@@ -1,8 +1,9 @@
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 
 export function handleInitStrategy(ctx: PluginCommandContext): PluginCommandResult {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'strategy');
   const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });
 
   const okrDir = wctx.resolve('OKR_DIR').replace(workspaceDir, '').replace(/^\/+/, '');
@@ -20,7 +21,7 @@ export function handleInitStrategy(ctx: PluginCommandContext): PluginCommandResu
 }
 
 export function handleManageOkr(ctx: PluginCommandContext): PluginCommandResult {
-  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'strategy:manageOkr');
   const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });
 
   const focusPath = wctx.resolve('CURRENT_FOCUS').replace(workspaceDir, '').replace(/^\/+/, '');

package/src/commands/thinking-os.ts

@@ -1,10 +1,11 @@
  
 import * as fs from 'fs';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 
 function getWorkspaceDir(ctx: PluginCommandContext): string {
-    return (ctx.config?.workspaceDir as string) || process.cwd();
+    return resolvePluginCommandWorkspaceDir(ctx, 'thinking-os');
 }
 
 function getModels(wctx: WorkspaceContext): Record<string, string> {

package/src/commands/workflow-debug.ts

@@ -1,5 +1,6 @@
 import { WorkflowStore } from '../service/subagent-workflow/workflow-store.js';
 import type { PluginCommandContext } from '../openclaw-sdk.js';
+import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
 function formatTimestamp(ts: number | null | undefined): string {
     if (!ts) return '--';
@@ -85,7 +86,7 @@ function buildOutput(
 export function handleWorkflowDebugCommand(
     ctx: PluginCommandContext & { args?: string }
 ): { text: string } {
-    const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+    const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'workflow-debug');
     
     // Parse workflow ID from args
     const args = (ctx as { args?: string }).args?.trim() || '';

package/src/core/diagnostician-task-store.ts

@@ -37,6 +37,8 @@ export interface DiagnosticianTask {
   prompt: string;
   createdAt: string;
   status: 'pending' | 'completed';
+  /** Number of times task was retried due to marker exists but JSON report missing (#366) */
+  reportMissingRetries?: number;
 }
 
 export interface DiagnosticianTaskStore {
@@ -86,10 +88,12 @@ export async function addDiagnosticianTask(
      
      
     const store = readTaskStoreSync(filePath);
+    const existing = store.tasks[taskId];
     store.tasks[taskId] = {
       prompt,
-      createdAt: new Date().toISOString(),
+      createdAt: existing?.createdAt ?? new Date().toISOString(),
       status: 'pending',
+      reportMissingRetries: existing?.reportMissingRetries ?? 0,
     };
     atomicWriteFileSync(filePath, JSON.stringify(store, null, 2));
   });
@@ -153,3 +157,36 @@ export function hasPendingDiagnosticianTasks(stateDir: string): boolean {
   const store = readTaskStore(stateDir);
   return Object.values(store.tasks).some(t => t.status === 'pending');
 }
+
+/**
+ * Re-queue a diagnostician task with an incremented reportMissingRetries counter.
+ * Used when a task has a marker file but no JSON report — the worker re-injects
+ * the task for the LLM to retry (up to MAX_REPORT_MISSING_RETRIES times).
+ *
+ * Idempotent: if the task doesn't exist, does nothing.
+ */
+export async function requeueDiagnosticianTask(
+  stateDir: string,
+  taskId: string,
+  maxRetries = 3,
+): Promise<{ requeued: boolean; maxRetriesReached: boolean }> {
+  const filePath = resolveTasksPath(stateDir);
+  return withLockAsync(filePath, async () => {
+    const store = readTaskStoreSync(filePath);
+    const existing = store.tasks[taskId];
+    if (!existing) {
+      return { requeued: false, maxRetriesReached: false };
+    }
+    const retries = (existing.reportMissingRetries ?? 0) + 1;
+    if (retries > maxRetries) {
+      return { requeued: false, maxRetriesReached: true };
+    }
+    store.tasks[taskId] = {
+      ...existing,
+      status: 'pending',
+      reportMissingRetries: retries,
+    };
+    atomicWriteFileSync(filePath, JSON.stringify(store, null, 2));
+    return { requeued: true, maxRetriesReached: false };
+  });
+}

package/src/core/event-log.ts

@@ -197,7 +197,14 @@ export class EventLog {
   }
 
   recordDiagnosticianReport(data: DiagnosticianReportEventData): void {
-    this.record('diagnostician_report', data.success ? 'completed' : 'failure', undefined, data);
+    // Map three-state category to EventCategory
+    // Both missing_json and incomplete_fields map to 'failure' in EventCategory
+    const categoryMap: Record<DiagnosticianReportEventData['category'], EventCategory> = {
+      success: 'completed',
+      missing_json: 'failure',
+      incomplete_fields: 'failure',
+    };
+    this.record('diagnostician_report', categoryMap[data.category], undefined, data);
   }
 
   recordPrincipleCandidate(data: PrincipleCandidateEventData): void {
@@ -356,8 +363,19 @@ export class EventLog {
     } else if (entry.type === 'heartbeat_diagnosis') {
       stats.evolution.heartbeatsInjected++;
     } else if (entry.type === 'diagnostician_report') {
-      if (entry.category === 'completed') {
-        stats.evolution.diagnosticianReportsWritten++;
+      const data = entry.data as unknown as DiagnosticianReportEventData;
+      // Backward compat: handle old events with success:boolean and new events with category:string
+      if ('category' in data) {
+        // New format: category is 'success' | 'missing_json' | 'incomplete_fields'
+        if (data.category === 'success' || data.category === 'incomplete_fields') {
+          stats.evolution.diagnosticianReportsWritten++;
+        }
+        if (data.category === 'missing_json') {
+          stats.evolution.reportsMissingJson++;
+        }
+        if (data.category === 'incomplete_fields') {
+          stats.evolution.reportsIncompleteFields++;
+        }
       }
     } else if (entry.type === 'principle_candidate') {
       stats.evolution.principleCandidatesCreated++;

package/src/service/evolution-worker.ts

@@ -12,7 +12,7 @@ import { SystemLogger } from '../core/system-logger.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 import type { EventLog } from '../core/event-log.js';
 import { initPersistence, flushAllSessions } from '../core/session-tracker.js';
-import { addDiagnosticianTask, completeDiagnosticianTask } from '../core/diagnostician-task-store.js';
+import { addDiagnosticianTask, completeDiagnosticianTask, requeueDiagnosticianTask } from '../core/diagnostician-task-store.js';
 import { getEvolutionLogger } from '../core/evolution-logger.js';
 import type { TaskKind, TaskPriority } from '../core/trajectory-types.js';
 import type { PrincipleEvaluability } from '../types/principle-tree-schema.js';
@@ -923,12 +923,49 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
 
                 let principlesGenerated = 0;
                 // C: Track report success for event recording
+                // FIX: Use reportParsed flag so reportSuccess=false when JSON is missing/garbled
                 let reportSuccess = false;
+                let reportParsed = false;
                 // Create principle from the diagnostician's JSON report.
                 const reportPath = path.join(wctx.stateDir, `.diagnostician_report_${task.id}.json`);
                 if (fs.existsSync(reportPath)) {
                     try {
-                        const reportData = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
+                        const raw = fs.readFileSync(reportPath, 'utf8');
+                        if (!raw || raw.trim().length === 0) {
+                            throw new Error('Report file is empty');
+                        }
+                        const reportData = JSON.parse(raw);
+                        if (!reportData) {
+                            throw new Error('JSON parsed but content is null/undefined');
+                        }
+                        // Report is valid JSON — mark as parsed
+                        reportParsed = true;
+
+                        // FIX: Validate phase completeness before accepting the report
+                        // A report missing critical phases is considered failed (not silently accepted).
+                        // The diagnostician must produce all 4 diagnostic phases.
+                        const phases = reportData?.phases || reportData?.diagnosis_report?.phases || {};
+                        const requiredPhases = [
+                            'evidence_gathering',
+                            'causal_chain',
+                            'root_cause_classification',
+                            'principle_extraction',
+                        ];
+                        const presentPhases = requiredPhases.filter(p =>
+                            phases && Object.keys(phases).length > 0 && phases[p]
+                        );
+                        if (presentPhases.length < requiredPhases.length) {
+                            const missing = requiredPhases.filter(p => !phases[p]);
+                            if (logger) logger.warn(`[PD:EvolutionWorker] Report for task ${task.id} incomplete — missing phases: ${missing.join(', ')} (present: ${presentPhases.length}/${requiredPhases.length})`);
+                            // Treat as retryable failure: don't mark success, let retry logic kick in
+                            reportParsed = false;
+                            // Also delete the incomplete marker so next heartbeat re-runs the diagnostician
+                            try { fs.unlinkSync(completeMarker); } catch { /* ignore if already gone */ }
+                            task.status = 'pending';
+                            task.resolution = undefined;
+                            queueChanged = true;
+                            continue;
+                        }
 
                         // ── Step 3: Noise Classification Filter ──
                         // Skip principle creation for low-value noise categories that don't represent
@@ -1048,15 +1085,52 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
                     } catch (err) {
                         logger.warn(`[PD:EvolutionWorker] Failed to parse diagnostician report for task ${task.id}: ${String(err)}`);
                     }
-                    // C: Report was found and processed (try block succeeded or had non-fatal issues)
-                    reportSuccess = true;
+                    // FIX: Only mark success if JSON was actually parsed and non-empty
+                    // If JSON was missing, garbled, or empty — reportSuccess stays false
+                    reportSuccess = reportParsed;
                 } else {
-                    logger.warn(`[PD:EvolutionWorker] No diagnostician report found for completed task ${task.id} (expected: .diagnostician_report_${task.id}.json)`);
+                    // ── #366: Marker exists but JSON report missing — retry logic ──
+                    // Do NOT mark completed yet. Re-inject the task for the next heartbeat cycle.
+                    // Read retry count from marker file content.
+                    const MAX_REPORT_MISSING_RETRIES = 3;
+                    let markerRetries = 0;
+                    try {
+                        const markerContent = fs.readFileSync(completeMarker, 'utf8');
+                        const match = markerContent.match(/report_missing_retries:(\d+)/);
+                        if (match) markerRetries = parseInt(match[1], 10);
+                    } catch { /* marker may not be readable, use 0 */ }
+
+                    if (markerRetries < MAX_REPORT_MISSING_RETRIES) {
+                        // Re-inject: keep task in queue (don't mark completed), update marker with incremented count
+                        const newRetries = markerRetries + 1;
+                        if (logger) logger.info(`[PD:EvolutionWorker] Task ${task.id}: marker found but report missing — re-queuing (retry ${newRetries}/${MAX_REPORT_MISSING_RETRIES})`);
+                        // FIX: Update store's reportMissingRetries BEFORE deleting the marker.
+                        // This ensures the store's retry count is persisted even if the
+                        // diagnostician session crashes before re-adding the task.
+                        await requeueDiagnosticianTask(wctx.stateDir, task.id, MAX_REPORT_MISSING_RETRIES);
+                        // Also update the task in the main queue to keep it alive
+                        task.status = 'pending';
+                        task.resolution = undefined;
+                        queueChanged = true;
+                        // Delete the marker so the next heartbeat sees no marker
+                        // and re-processes the task as a fresh diagnostician run.
+                        try {
+                            fs.unlinkSync(completeMarker);
+                        } catch { /* ignore if already deleted */ }
+                        // Skip the completion/unlink block below — task is still pending
+                        continue;
+                    } else {
+                        // Max retries reached — accept that no report was produced
+                        if (logger) logger.warn(`[PD:EvolutionWorker] Task ${task.id}: max retries (${MAX_REPORT_MISSING_RETRIES}) reached — marking as failed_max_retries`);
+                        task.status = 'completed';
+                        task.completed_at = new Date().toISOString();
+                        task.resolution = 'failed_max_retries';
+                    }
                 }
 
-                task.status = 'completed';
-                task.completed_at = new Date().toISOString();
-                // resolution already set by each branch (noise_classified | marker_detected)
+                // Only reached if JSON existed or max retries reached:
+                task.status = task.status || 'completed';
+                task.completed_at = task.completed_at || new Date().toISOString();
                 if (!task.resolution) task.resolution = 'marker_detected';
                 try {
                     fs.unlinkSync(completeMarker);
@@ -1073,10 +1147,16 @@ async function processEvolutionQueue(wctx: WorkspaceContext, logger: PluginLogge
 
                 // C: Record diagnostician_report event for observability
                 if (eventLog) {
+                    // Map to three-state category:
+                    // - reportSuccess=true → 'success' (JSON exists, parsed, principle found)
+                    // - reportSuccess=false, reportParsed=true → 'incomplete_fields' (JSON existed but principle missing)
+                    // - reportSuccess=false, reportParsed=false → 'missing_json' (JSON never existed)
+                    const reportCategory: 'success' | 'missing_json' | 'incomplete_fields' =
+                        reportSuccess ? 'success' : reportParsed ? 'incomplete_fields' : 'missing_json';
                     eventLog.recordDiagnosticianReport({
                         taskId: task.id,
                         reportPath,
-                        success: reportSuccess,
+                        category: reportCategory,
                     });
                 }
 

package/src/service/runtime-summary-service.ts

@@ -69,6 +69,10 @@ export interface RuntimeSummary {
     tasksWrittenToday: number;
     /** Total diagnostician reports written (today from event log) */
     reportsWrittenToday: number;
+    /** Total diagnostician reports that were missing JSON (category=missing_json) */
+    reportsMissingJsonToday: number;
+    /** Total diagnostician reports with incomplete fields (category=incomplete_fields) */
+    reportsIncompleteFieldsToday: number;
     /** Total principle candidates created from heartbeat chain (today from event log) */
     candidatesCreatedToday: number;
     /** Heartbeats that injected diagnostician tasks (today from event log) */
@@ -194,6 +198,8 @@ export class RuntimeSummaryService {
       evolution?: {
         diagnosisTasksWritten?: number;
         diagnosticianReportsWritten?: number;
+        reportsMissingJson?: number;
+        reportsIncompleteFields?: number;
         principleCandidatesCreated?: number;
         heartbeatsInjected?: number;
         [key: string]: unknown;
@@ -265,6 +271,8 @@ export class RuntimeSummaryService {
       pendingTasks: pendingDiagTasks.length,
       tasksWrittenToday: diagDailyStats?.diagnosisTasksWritten ?? 0,
       reportsWrittenToday: diagDailyStats?.diagnosticianReportsWritten ?? 0,
+      reportsMissingJsonToday: diagDailyStats?.reportsMissingJson ?? 0,
+      reportsIncompleteFieldsToday: diagDailyStats?.reportsIncompleteFields ?? 0,
       candidatesCreatedToday: diagDailyStats?.principleCandidatesCreated ?? 0,
       heartbeatsInjectedToday: diagDailyStats?.heartbeatsInjected ?? 0,
     };

package/src/types/event-types.ts

@@ -209,7 +209,12 @@ export interface DiagnosisTaskEventData {
 export interface DiagnosticianReportEventData {
   taskId: string;
   reportPath: string;
-  success: boolean;
+  /** Three-state category replacing boolean success field.
+   * - 'success': JSON exists and has principle field
+   * - 'missing_json': marker exists but JSON does not (Issue #366, LLM output truncation)
+   * - 'incomplete_fields': JSON exists but missing principle field
+   */
+  category: 'success' | 'missing_json' | 'incomplete_fields';
 }
 
 /**
@@ -326,6 +331,8 @@ export interface EvolutionStats {
   diagnosisTasksWritten: number;
   heartbeatsInjected: number;
   diagnosticianReportsWritten: number;
+  reportsMissingJson: number;
+  reportsIncompleteFields: number;
   principleCandidatesCreated: number;
   rulesEnforced: number;
 }
@@ -490,6 +497,8 @@ export function createEmptyDailyStats(date: string): DailyStats {
       diagnosisTasksWritten: 0,
       heartbeatsInjected: 0,
       diagnosticianReportsWritten: 0,
+      reportsMissingJson: 0,
+      reportsIncompleteFields: 0,
       principleCandidatesCreated: 0,
       rulesEnforced: 0,
     },

package/src/utils/workspace-resolver.ts

@@ -4,7 +4,7 @@
  * Shared helpers for resolving workspace directories across commands and hooks.
  */
 
-import type { OpenClawPluginApi } from '../openclaw-sdk.js';
+import type { OpenClawPluginApi, PluginCommandContext } from '../openclaw-sdk.js';
 import { validateWorkspaceDir, type WorkspaceResolutionContext } from '../core/workspace-dir-validation.js';
 import { resolveWorkspaceDir } from '../core/workspace-dir-service.js';
 import { resolveWorkspaceDirFromApi } from '../core/path-resolver.js';
@@ -25,7 +25,10 @@ export function resolveCommandWorkspaceDir(
   if (ctx.workspaceDir) {
     const issue = validateWorkspaceDir(ctx.workspaceDir);
     if (!issue) return ctx.workspaceDir;
-    api.logger.error(`[PD:Command] ctx.workspaceDir="${ctx.workspaceDir}" is invalid: ${issue}`);
+    // Validation failed — fail immediately, do not silently fall back
+    const errorMsg = `[PD:Command] ctx.workspaceDir="${ctx.workspaceDir}" is invalid: ${issue}`;
+    api.logger.error(errorMsg);
+    throw new Error(errorMsg);
   }
 
   // 2. Official OpenClaw API → env vars → config file
@@ -34,13 +37,51 @@ export function resolveCommandWorkspaceDir(
 
   // CRITICAL FAILURE: Cannot determine workspace directory
   const errorMsg = `[PD:Command] CRITICAL: Cannot resolve workspace directory. ` +
-    `ctx.workspaceDir="${ctx.workspaceDir}" is invalid, and all fallbacks failed. ` +
+    `ctx.workspaceDir="${ctx.workspaceDir ?? ''}" is invalid, and all fallbacks failed. ` +
     `Commands will NOT execute to prevent data corruption.`;
   api.logger.error(errorMsg);
 
   throw new Error(errorMsg);
 }
 
+/**
+ * Resolve workspace directory for plugin command execution.
+ *
+ * Chain: ctx.workspaceDir (canonical) → ctx.config.workspaceDir (dispatcher fallback)
+ *
+ * CRITICAL: Throws if workspaceDir cannot be resolved. Commands must NEVER silently
+ * fall back to process.cwd() as this masks configuration errors and can corrupt
+ * the wrong workspace.
+ *
+ * @param ctx - Plugin command context (has workspaceDir + config properties)
+ * @param source - Source label for error messages (e.g. 'evolution-status', 'pain')
+ */
+export function resolvePluginCommandWorkspaceDir(
+  ctx: PluginCommandContext,
+  source: string,
+): string {
+  // 1. Canonical workspaceDir field (set by OpenClaw command dispatcher)
+  if (ctx.workspaceDir) {
+    const issue = validateWorkspaceDir(ctx.workspaceDir);
+    if (!issue) return ctx.workspaceDir;
+    throw new Error(`[PD:Command:${source}] ctx.workspaceDir="${ctx.workspaceDir}" is invalid: ${issue}`);
+  }
+
+  // 2. Dispatcher may also put workspaceDir in config (legacy/alternative path)
+  const configWorkspaceDir = ctx.config?.workspaceDir as string | undefined;
+  if (configWorkspaceDir) {
+    const issue = validateWorkspaceDir(configWorkspaceDir);
+    if (!issue) return configWorkspaceDir;
+    throw new Error(`[PD:Command:${source}] ctx.config.workspaceDir="${configWorkspaceDir}" is invalid: ${issue}`);
+  }
+
+  // CRITICAL FAILURE: No workspace directory available
+  throw new Error(
+    `[PD:Command:${source}] CRITICAL: workspaceDir is not set in ctx.workspaceDir or ctx.config.workspaceDir. ` +
+    `Commands cannot execute without a valid workspace. Set OPENCLAW_WORKSPACE_DIR env var or ensure the workspace is properly initialized.`,
+  );
+}
+
 /**
  * Resolve workspace directory for tool hook execution (safe version).
  * Returns undefined instead of throwing if resolution fails.

package/templates/langs/en/skills/pd-diagnostician/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 # Diagnostician - Root Cause Analysis Agent
 
-You are a professional root cause analysis expert. You MUST strictly follow the **five-phase protocol** (Phase 0 optional + Phase 1-4 mandatory) below to execute analysis and output **JSON format** results.
+You are a professional root cause analysis expert. You MUST strictly follow the **six-phase protocol** (Phase 0 optional + Phase 1-5 mandatory) below to execute analysis and **immediately write results to the report file after each Phase completes**.
 
 ---
 
@@ -106,6 +106,20 @@ You are a professional root cause analysis expert. You MUST strictly follow the
 }
 ```
 
+**⚠️ Write Report File Immediately After Phase 1**:
+Once Phase 1 is complete, **immediately** write the result to the report file (do NOT wait until the end):
+```
+write: .state/.diagnostician_report_<TASK_ID>.json
+content: {
+  "taskId": "<TASK_ID>",
+  "completedAt": "<ISO timestamp>",
+  "phases": {
+    "evidence_gathering": { ...Phase 1 result... }
+  }
+}
+```
+If the file already exists (a previous Phase was already written), read the existing content, merge the new Phase result into it, then overwrite.
+
 ---
 
 ### Phase 2: Causal Chain Construction [Required]
@@ -145,6 +159,9 @@ You are a professional root cause analysis expert. You MUST strictly follow the
 }
 ```
 
+**⚠️ Write Report File Immediately After Phase 2**:
+Once Phase 2 is complete, **immediately** merge the result into the report file (overwrite, do not lose Phase 1 content).
+
 ---
 
 ### Phase 3: Root Cause Classification [Required]
@@ -178,6 +195,9 @@ You are a professional root cause analysis expert. You MUST strictly follow the
 }
 ```
 
+**⚠️ Write Report File Immediately After Phase 3**:
+Once Phase 3 is complete, **immediately** merge the result into the report file.
+
 ---
 
 ### Phase 4: Principle Extraction [Required]
@@ -264,9 +284,32 @@ You are a professional root cause analysis expert. You MUST strictly follow the
 - "External dependency availability must be validated before invocation"
 - "Code modifications must go through Issue process, ensuring traceability and rollback"
 
-**Reference Existing Principle Styles** (you'll see existing principle entries in HEARTBEAT.md, keep consistent style):
-- P-10: Process as Authority — "When having technical capability to execute operations directly, must check if agreed-upon process exists"
-- P-11: Pre-write Validation — "Before writing to any high-risk path, first read to confirm file's current actual content"
+**Phase 4 Output Fields** (also write immediately after completing Phase 4 — merge with previous Phases):
+```json
+{
+  "taskId": "<TASK_ID>",
+  "completedAt": "<ISO timestamp>",
+  "phases": {
+    "context_extraction": { ... Phase 0 result ... },
+    "evidence_gathering": { ... Phase 1 result ... },
+    "causal_chain": { ... Phase 2 result ... },
+    "root_cause_classification": { ... Phase 3 result ... },
+    "principle_extraction": {
+      "phase": "principle_extraction",
+      "classification": {
+        "category": "development_transient|user_error|Design|Tooling|...",
+        "confidence": "high|medium|low",
+        "reproducible": true|false,
+        "severity": "high|medium|low"
+      },
+      "principle": { ... }
+    }
+  }
+}
+```
+
+**⚠️ Write Report File Immediately After Phase 4**:
+Once Phase 4 is complete, **immediately** merge the result (with `classification` and `principle`) into the report file. This is the final write — all Phases must now be present.
 
 ---
 
@@ -285,20 +328,27 @@ Your diagnostic report will be **auto-parsed as JSON**. Any format errors will c
 
 **Self-check method**: Before outputting, mentally verify: every `"` must have matching `"` after it, if content contains `"` it must be escaped as `\"`.
 
-Merge outputs from all four phases into one JSON object:
+The final report (written incrementally by each Phase) should look like:
 
 ```json
 {
-  "diagnosis_report": {
-    "task_id": "...",
-    "timestamp": "2026-03-24T...",
-    "summary": "One-sentence summary of root cause",
-    "phases": {
-      "context_extraction": { "session_id": "...", "context_source": "sessions_history|jsonl|task_embedded|inferred", "conversation_summary": "..." },
-      "evidence_gathering": { ... },
-      "causal_chain": { ... },
-      "root_cause_classification": { ... },
-      "principle_extraction": { ... }
+  "taskId": "<TASK_ID>",
+  "completedAt": "2026-03-24T10:30:00Z",
+  "phases": {
+    "context_extraction": { "phase": "context_extraction", "session_id": "...", "context_source": "...", "conversation_summary": "..." },
+    "evidence_gathering": { "phase": "evidence_gathering", "evidence": { ... } },
+    "causal_chain": { "phase": "causal_chain", "chain": [...], "terminated_at": 3, "termination_reason": "..." },
+    "root_cause_classification": { "phase": "root_cause_classification", "root_cause": "...", "category": "Design", "guardrail_analysis": { ... } },
+    "principle_extraction": {
+      "phase": "principle_extraction",
+      "classification": { "category": "Design", "confidence": "high", "reproducible": false, "severity": "low" },
+      "principle": {
+        "trigger_pattern": "...",
+        "action": "...",
+        "abstracted_principle": "...",
+        "duplicate": false,
+        "coreAxiomId": "T-02"
+      }
     }
   }
 }
@@ -306,6 +356,38 @@ Merge outputs from all four phases into one JSON object:
 
 ---
 
+## ✅ Completion Protocol
+
+### ✅ Checklist (ALL must be satisfied before writing marker)
+
+Before writing the marker file, you MUST confirm all of the following:
+
+1. **Report file exists**: `.diagnostician_report_<TASK_ID>.json` has been written to disk
+2. **All Phase fields present**:
+   - [ ] `phases.context_extraction` ✅
+   - [ ] `phases.evidence_gathering` ✅
+   - [ ] `phases.causal_chain` ✅
+   - [ ] `phases.root_cause_classification` ✅
+   - [ ] `phases.principle_extraction` ✅
+3. **Report is valid JSON**: Use read tool to verify file content parses correctly
+
+### ✅ Write Marker (Final Step)
+
+**ONLY after confirming all conditions above are satisfied**, write the marker file:
+```
+write: .state/.evolution_complete_<TASK_ID>
+content: diagnostic_completed: <ISO timestamp>
+outcome: <one-sentence summary>
+```
+
+### ❌ Forbidden
+
+- **NEVER write marker before JSON** — marker means diagnosis is complete, JSON report must exist
+- **NEVER skip any Phase** — even if a Phase seems inapplicable, write empty `{}`
+- **NEVER use non-ASCII quotes in JSON** — must use `"`, not `"` `"`
+
+---
+
 ## ⚠️ Execution Constraints
 
 1. **NO skipping phases**: MUST attempt Phase 0 (context acquisition), then execute Phase 1 → 2 → 3 → 4 in order
@@ -313,6 +395,7 @@ Merge outputs from all four phases into one JSON object:
 3. **NO vague conclusions**: Root cause must be specific and fixable
 4. **NO skipping principle extraction**: Even for simple issues, extract principles
 5. **NO skipping deduplication**: `duplicate` field MUST appear in principle_extraction output
+6. **NO writing marker before all Phases complete**: Marker comes LAST, only after every Phase is written to JSON
 
 ---
 

package/tests/commands/pd-reflect.test.ts

@@ -20,7 +20,7 @@ describe('pd-reflect command', () => {
   it('requires an explicit resolved workspace directory', async () => {
     const result = await handlePdReflect.handler({} as any);
     expect(result.isError).toBe(true);
-    expect(result.text).toContain('Cannot determine workspace directory');
+    expect(result.text).toContain('workspaceDir is not set');
   });
 
   it('enqueues into the provided active workspace', async () => {