principles-disciple 1.72.0 → 1.73.0

package/src/commands/context.ts

@@ -3,7 +3,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 { atomicWriteFileSync, normalizeCommandArgs } from '../utils/io.js';
 import type { ContextInjectionConfig} from '../types.js';
 import { defaultContextConfig } from '../types.js';
 import { loadContextInjectionConfig } from '../hooks/prompt.js';
@@ -305,7 +305,7 @@ function showHelp(isZh: boolean): string {
      
 export function handleContextCommand(ctx: PluginCommandContext): PluginCommandResult {
     const workspaceDir = getWorkspaceDir(ctx);
-    const args = (ctx.args || '').trim().split(/\s+/);
+    const args = normalizeCommandArgs(ctx.args).trim().split(/\s+/);
     const subCommand = args[0]?.toLowerCase() || 'status';
     const value = args[1]?.toLowerCase() || '';
     

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 { normalizeCommandArgs } from '../utils/io.js';
 import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
 /**
@@ -139,7 +140,7 @@ export function handleDisableImplCommand(ctx: PluginCommandContext): PluginComma
   const lang = (ctx.config?.language as string) || 'en';
   const isZh = lang === 'zh';
 
-  const args = (ctx.args || '').trim();
+  const args = normalizeCommandArgs(ctx.args).trim();
 
   // Parse args: [implId] [--reason "..."]
   const parts = args.split(/\s+/);

package/src/commands/evolution-status.ts

@@ -1,6 +1,6 @@
 import * as path from 'path';
 import type { EvolutionReducerImpl } from '../core/evolution-reducer.js';
-import type { InternalizationRouteRecommendation } from '../core/principle-internalization/internalization-routing-policy.js';
+import type { LifecycleRouteRecommendation } from '@principles/core/runtime-v2';
 import { WorkflowFunnelLoader } from '../core/workflow-funnel-loader.js';
 import { resolvePdPath } from '../core/paths.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
@@ -33,7 +33,7 @@ function formatSources(
 }
 
 function formatRouteRecommendations(
-  recommendations: InternalizationRouteRecommendation[],
+  recommendations: LifecycleRouteRecommendation[],
   emptyLabel: string,
 ): string {
   if (recommendations.length === 0) {
@@ -57,7 +57,7 @@ function buildEnglishOutput(
   warnings: string[],
   stats: ReturnType<EvolutionReducerImpl['getStats']>,
   summary: ReturnType<typeof RuntimeSummaryService.getSummary>,
-  recommendations: InternalizationRouteRecommendation[],
+  recommendations: LifecycleRouteRecommendation[],
 ): string {
   const lines: string[] = [
     'Evolution Status',
@@ -78,13 +78,13 @@ function buildEnglishOutput(
     `- Phase 3: ready ${summary.phase3.phase3ShadowEligible ? 'yes' : 'no'}, queueTruthReady ${summary.phase3.queueTruthReady ? 'yes' : 'no'}, eligible ${summary.phase3.evolutionEligible}, reference_only ${summary.phase3.evolutionReferenceOnly}, rejected ${summary.phase3.evolutionRejected}${summary.phase3.evolutionReferenceOnlyReasons.length > 0 ? ` (reference ${summary.phase3.evolutionReferenceOnlyReasons.slice(0, 2).join(', ')})` : ''}${summary.phase3.evolutionRejectedReasons.length > 0 ? ` (${summary.phase3.evolutionRejectedReasons.slice(0, 3).join(', ')})` : ''}`,
     `- Phase 3 Legacy Directive File: ${summary.phase3.directiveStatus} (${summary.phase3.directiveIgnoredReason})`,
     '',
-    // D: Heartbeat Diagnostician chain — separated from evolution/nocturnal
+    // D: Heartbeat Diagnostician chain
     'Heartbeat Diagnostician (Pain → Principle)',
-    `- Pending tasks: ${summary.heartbeatDiagnosis.pendingTasks}`,
-    `- Tasks written today: ${summary.heartbeatDiagnosis.tasksWrittenToday}`,
-    `- Reports written today: ${summary.heartbeatDiagnosis.reportsWrittenToday}`,
-    `- Candidates created today: ${summary.heartbeatDiagnosis.candidatesCreatedToday}`,
-    `- Heartbeats injected today: ${summary.heartbeatDiagnosis.heartbeatsInjectedToday}`,
+    `- Pending tasks: ${summary.runtimeDiagnosis.pendingTasks}`,
+    `- Tasks written today: ${summary.runtimeDiagnosis.tasksWrittenToday}`,
+    `- Reports written today: ${summary.runtimeDiagnosis.reportsWrittenToday}`,
+    `- Candidates created today: ${summary.runtimeDiagnosis.candidatesCreatedToday}`,
+    `- Heartbeats injected today: ${summary.runtimeDiagnosis.heartbeatsInjectedToday}`,
     '',
     'Principles',
     `- candidate principles: ${stats.candidateCount}`,
@@ -129,7 +129,7 @@ function buildChineseOutput(
   warnings: string[],
   stats: ReturnType<EvolutionReducerImpl['getStats']>,
   summary: ReturnType<typeof RuntimeSummaryService.getSummary>,
-  recommendations: InternalizationRouteRecommendation[],
+  recommendations: LifecycleRouteRecommendation[],
 ): string {
   const lines: string[] = [
     '进化状态',
@@ -150,13 +150,13 @@ function buildChineseOutput(
     `- Phase 3: ready ${summary.phase3.phase3ShadowEligible ? 'yes' : 'no'}，queueTruthReady ${summary.phase3.queueTruthReady ? 'yes' : 'no'}，eligible ${summary.phase3.evolutionEligible}，reference_only ${summary.phase3.evolutionReferenceOnly}，rejected ${summary.phase3.evolutionRejected}${summary.phase3.evolutionReferenceOnlyReasons.length > 0 ? ` (reference ${summary.phase3.evolutionReferenceOnlyReasons.slice(0, 2).join(', ')})` : ''}${summary.phase3.evolutionRejectedReasons.length > 0 ? ` (${summary.phase3.evolutionRejectedReasons.slice(0, 3).join(', ')})` : ''}`,
     `- Phase 3 Legacy Directive File: ${summary.phase3.directiveStatus} (${summary.phase3.directiveIgnoredReason})`,
     '',
-    // D: Heartbeat Diagnostician chain — separated from evolution/nocturnal
+    // D: Heartbeat Diagnostician chain
     '心跳诊断链路（Pain → 原则）',
-    `- 等待处理: ${summary.heartbeatDiagnosis.pendingTasks}`,
-    `- 今日写入任务: ${summary.heartbeatDiagnosis.tasksWrittenToday}`,
-    `- 今日写入报告: ${summary.heartbeatDiagnosis.reportsWrittenToday}`,
-    `- 今日创建候选: ${summary.heartbeatDiagnosis.candidatesCreatedToday}`,
-    `- 今日心跳注入: ${summary.heartbeatDiagnosis.heartbeatsInjectedToday}`,
+    `- 等待处理: ${summary.runtimeDiagnosis.pendingTasks}`,
+    `- 今日写入任务: ${summary.runtimeDiagnosis.tasksWrittenToday}`,
+    `- 今日写入报告: ${summary.runtimeDiagnosis.reportsWrittenToday}`,
+    `- 今日创建候选: ${summary.runtimeDiagnosis.candidatesCreatedToday}`,
+    `- 今日心跳注入: ${summary.runtimeDiagnosis.heartbeatsInjectedToday}`,
     '',
     '原则统计',
     `- 候选原则: ${stats.candidateCount}`,

package/src/commands/export.ts

@@ -1,7 +1,7 @@
 import { WorkspaceContext } from '../core/workspace-context.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { normalizeCommandArgs } from '../utils/io.js';
 import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
-import { exportORPOSamples, listExports } from '../core/nocturnal-export.js';
 
 function isZh(ctx: PluginCommandContext): boolean {
   return String(ctx.config?.language || 'en').startsWith('zh');
@@ -10,77 +10,17 @@ function isZh(ctx: PluginCommandContext): boolean {
 export function handleExportCommand(ctx: PluginCommandContext): PluginCommandResult {
   const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'export');
   const zh = isZh(ctx);
-  const args = (ctx.args || '').trim();
+  const args = normalizeCommandArgs(ctx.args).trim();
   const parts = args.split(/\s+/).filter(Boolean);
   const [subcommand = 'corrections'] = parts;
   const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });
 
   try {
-    if (subcommand === 'orpo') {
-      // Nocturnal ORPO export
-      // Usage: pd-export orpo [--family=<targetModelFamily>]
-      const familyArg = parts.find((p) => p.startsWith('--family='));
-      const targetModelFamily = familyArg ? familyArg.split('=')[1] : undefined;
-
-      const result = exportORPOSamples(workspaceDir, targetModelFamily);
-
-      if (!result.success) {
-        const reasonMap: Record<string, string> = {
-          no_approved_samples: zh
-            ? '没有已批准的样本'
-            : 'No approved samples',
-          family_mismatch: zh
-            ? '没有找到指定模型家族的已批准样本'
-            : 'No approved samples for the specified target model family',
-          all_samples_missing_artifacts: zh
-            ? '所有样本的 artifact 文件都缺失'
-            : 'All sample artifact files are missing',
-        };
-        return {
-          text: zh
-            ? `ORPO 导出失败: ${reasonMap[result.emptyReason ?? ''] ?? result.error}`
-            : `ORPO export failed: ${reasonMap[result.emptyReason ?? ''] ?? result.error}`,
-        };
-      }
-
-       
-       
-      return {
-        text: zh
-          ? `已导出 ORPO 决策点样本到 ${result.manifest!.exportPath}，` +  
-              `共 ${result.manifest!.sampleCount} 条，模型家族: ${result.manifest!.targetModelFamily}，` +  
-              `数据集指纹: ${result.manifest!.datasetFingerprint.substring(0, 16)}...`  
-          : `Exported ORPO decision-point samples to ${result.manifest!.exportPath}, ` +  
-              `${result.manifest!.sampleCount} samples, target: ${result.manifest!.targetModelFamily}, ` +  
-              `dataset fingerprint: ${result.manifest!.datasetFingerprint.substring(0, 16)}...`,  
-      };
-    }
-
-    if (subcommand === 'orpo-list') {
-      // List previous ORPO exports
-      const exports = listExports(workspaceDir);
-      if (exports.length === 0) {
-        return {
-          text: zh
-            ? '没有找到 ORPO 导出记录。'
-            : 'No ORPO exports found.',
-        };
-      }
-      const lines = exports.slice(0, 10).map((e) =>
-        `- ${e.exportId.substring(0, 8)}... | ${e.sampleCount} samples | ${e.targetModelFamily} | ${new Date(e.createdAt).toLocaleDateString()}`
-      );
-      return {
-        text: zh
-          ? `ORPO 导出记录:\n${lines.join('\n')}`
-          : `ORPO exports:\n${lines.join('\n')}`,
-      };
-    }
-
     if (subcommand !== 'analytics' && subcommand !== 'corrections') {
       return {
         text: zh
-          ? '无效的导出类型。请使用 `analytics`、`corrections [--redacted]` 或 `orpo [--family=<target>]`。'
-          : 'Invalid export target. Use `analytics`, `corrections [--redacted]`, or `orpo [--family=<target>]`',
+          ? '无效的导出类型。请使用 `analytics` 或 `corrections [--redacted]`。'
+          : 'Invalid export target. Use `analytics` or `corrections [--redacted]`',
       };
     }
 
@@ -104,11 +44,16 @@ export function handleExportCommand(ctx: PluginCommandContext): PluginCommandRes
         ? `已导出纠错样本到 ${result.filePath}，模式 ${result.mode}，共 ${result.count} 条。`
         : `Exported correction samples to ${result.filePath} (mode=${result.mode}, count=${result.count}).`,
     };
-  } catch {
+  } catch (err) {
+    console.error('[pd-export] Export failed:', {
+      subcommand,
+      error: err instanceof Error ? err.message : String(err),
+      stack: err instanceof Error ? err.stack : undefined,
+    });
     return {
       text: zh
-        ? '导出失败，请检查日志。'
-        : 'Export failed. Check logs.',
+        ? `导出失败 (${subcommand}): ${err instanceof Error ? err.message : String(err)}`
+        : `Export failed (${subcommand}): ${err instanceof Error ? err.message : String(err)}`,
     };
   }
 }

package/src/commands/pain.ts

@@ -1,8 +1,12 @@
 import { resetFriction, getSession } from '../core/session-tracker.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { normalizeCommandArgs } from '../utils/io.js';
 import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 import type { EmpathyEventStats } from '../types/event-types.js';
+import type { EvolutionLoopEvent } from '../core/evolution-types.js';
+import { computeHash } from '../utils/hashing.js';
+import { PainToPrincipleService, PrincipleTreeLedgerAdapter } from '@principles/core/runtime-v2';
 
 /**
  * Creates a visual progress bar (e.g., [██████░░░░])
@@ -100,7 +104,7 @@ export function handlePainCommand(ctx: PluginCommandContext): PluginCommandResul
     const isZh = lang === 'zh';
     const { sessionId } = ctx as SessionAwareCommandContext;
 
-    const args = (ctx.args || '').trim();
+    const args = normalizeCommandArgs(ctx.args).trim();
 
     // Handle empathy subcommand
     if (args.startsWith('empathy')) {
@@ -267,3 +271,89 @@ function handleEmpathySubcommand(
 
     return { text };
 }
+
+export async function handlePainReportCommand(ctx: PluginCommandContext): Promise<PluginCommandResult> {
+  const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'pain-report');
+  const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });
+  const lang = (ctx.config?.language as string) || 'en';
+  const isZh = lang === 'zh';
+  const { sessionId } = ctx as SessionAwareCommandContext;
+  const args = normalizeCommandArgs(ctx.args).trim();
+
+  if (!args) {
+    return {
+      text: isZh
+        ? '❌ 请提供 pain reason。用法: `/pd-pain <描述你遇到的问题>`'
+        : '❌ Please provide a pain reason. Usage: `/pd-pain <describe the issue you encountered>`',
+    };
+  }
+
+  if (!sessionId || sessionId === 'unknown') {
+    return {
+      text: isZh
+        ? '❌ 无法获取当前会话 ID。请在 OpenClaw 对话会话中使用此命令。'
+        : '❌ Session ID not available. Please use this command in an OpenClaw chat session.',
+    };
+  }
+
+  const painId = `manual_${Date.now()}_${computeHash(sessionId).slice(0, 8)}`;
+  const painData = {
+    painId,
+    painType: 'user_frustration' as const,
+    source: 'manual',
+    reason: args,
+    score: 90,
+    sessionId,
+    agentId: 'openclaw-host',
+    provenance: 'openclaw_context_bound' as const,
+  };
+
+  try {
+    const ledgerAdapter = new PrincipleTreeLedgerAdapter({ stateDir: wctx.stateDir });
+    const service = new PainToPrincipleService({
+      workspaceDir: wctx.workspaceDir,
+      stateDir: wctx.stateDir,
+      ledgerAdapter,
+      owner: 'openclaw-plugin',
+      autoIntakeEnabled: true,
+    });
+
+    const result = await service.recordPain({
+      painId: painData.painId,
+      painType: painData.painType,
+      source: painData.source,
+      reason: painData.reason,
+      score: painData.score,
+      sessionId: painData.sessionId,
+      agentId: painData.agentId,
+      provenance: painData.provenance,
+      recordObservability: true,
+    });
+
+    if (result.status === 'succeeded') {
+      wctx.evolutionReducer.emitSync({
+        ts: new Date().toISOString(),
+        type: 'pain_detected',
+        data: painData,
+      } as EvolutionLoopEvent);
+
+      return {
+        text: isZh
+          ? `✅ Pain 已记录 (context-bound)\n\n📋 **Pain ID**: ${painId}\n📝 **Reason**: ${args}\n🔗 **Provenance**: openclaw_context_bound\n📌 **Session**: ${sessionId}\n\n系统将基于当前会话上下文进行诊断。`
+          : `✅ Pain recorded (context-bound)\n\n📋 **Pain ID**: ${painId}\n📝 **Reason**: ${args}\n🔗 **Provenance**: openclaw_context_bound\n📌 **Session**: ${sessionId}\n\nThe system will diagnose using current session context.`,
+      };
+    }
+
+    return {
+      text: isZh
+        ? `⚠️ Pain 记录未成功 (status: ${result.status})。请检查系统日志或使用 \`/pd-status\` 查看状态。`
+        : `⚠️ Pain recording not accepted (status: ${result.status}). Check system logs or use \`/pd-status\` for status.`,
+    };
+  } catch (err) {
+    return {
+      text: isZh
+        ? `❌ Pain 记录失败: ${String(err)}。请检查系统日志或重试。`
+        : `❌ Failed to record pain: ${String(err)}. Check system logs or try again.`,
+    };
+  }
+}

package/src/commands/principle-rollback.ts

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

package/src/commands/promote-impl.ts

@@ -14,6 +14,9 @@
  * VALIDATION:
  *   - Candidate must have at least one replay report with 'pass' decision
  *   - Only candidate -> active is valid for promotion
+ *   - NOTE (PRI-230): The legacy replay generation path has been retired.
+ *     This command is temporarily unavailable for implementations without
+ *     pre-existing replay reports until a Runtime V2 replay entry is wired.
  */
 
 import * as fs from 'fs';
@@ -28,6 +31,7 @@ import {
 } from '../core/principle-tree-ledger.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { normalizeCommandArgs } from '../utils/io.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';
@@ -99,35 +103,6 @@ function _handleShowReport(
   return { text: formatReplayReport(report) };
 }
 
-interface RunReplayOptions {
-  workspaceDir: string;
-  stateDir: string;
-  implId: string;
-  isZh: boolean;
-}
-
-function _handleRunReplay(options: RunReplayOptions): PluginCommandResult {
-  const { workspaceDir, stateDir, implId, isZh } = options;
-  const engine = new ReplayEngine(workspaceDir, stateDir);
-
-  try {
-    const report = engine.runReplayForImplementation(implId);
-    let text = formatReplayReport(report);
-    if (report.sampleFingerprints.length === 0) {
-      text += isZh
-        ? '\n⚠️ 未找到已分类的 replay 样本。报告已生成，但当前结果只反映空样本集。\n'
-        : '\n⚠️ No classified replay samples were found. The report was generated, but it only reflects an empty sample set.\n';
-    }
-    return { text };
-  } catch (error: unknown) {
-    return {
-      text: isZh
-        ? `❌ 回放评估失败: ${String(error)}`
-        : `❌ Replay evaluation failed: ${String(error)}`,
-    };
-  }
-}
-
 interface PromoteImplOptions {
   workspaceDir: string;
   stateDir: string;
@@ -162,8 +137,8 @@ function _handlePromoteImpl(options: PromoteImplOptions): PluginCommandResult {
   if (!engine.hasPassingReport(implId)) {
     return {
       text: isZh
-        ? `❌ 实现 ${implId} 没有通过的回放报告，无法晋升。\n\n请先运行回放评估。`
-        : `❌ Implementation ${implId} has no passing replay report. Promotion rejected.\n\nPlease run a replay evaluation first.`,
+        ? `❌ 实现 ${implId} 没有通过的回放报告，晋升被拒绝。\n\nLegacy replay 生成路径已在 PRI-230 退役，当前无可用的 replay 证据生成入口。该命令暂不可用于没有既有 replay 报告的实现。`
+        : `❌ Implementation ${implId} has no passing replay report. Promotion rejected.\n\nThe legacy replay generation path was retired in PRI-230; no replay evidence generation entry is currently available. This command is temporarily unavailable for implementations without pre-existing replay reports.`,
     };
   }
 
@@ -256,7 +231,7 @@ export function handlePromoteImplCommand(ctx: PluginCommandContext): PluginComma
   const lang = (ctx.config?.language as string) || 'en';
   const isZh = lang === 'zh';
 
-  const args = (ctx.args || '').trim().split(/\s+/);
+  const args = normalizeCommandArgs(ctx.args).trim().split(/\s+/);
   const subcommand = args[0] || '';
   const implId = args[1] || '';
 
@@ -275,16 +250,5 @@ export function handlePromoteImplCommand(ctx: PluginCommandContext): PluginComma
     return _handleShowReport(stateDir, implId, isZh);
   }
 
-  if (subcommand === 'eval') {
-    if (!implId) {
-      return {
-        text: isZh
-          ? '请指定要评估的实现ID: /pd-promote-impl eval <implId>'
-          : 'Please specify an implementation ID: /pd-promote-impl eval <implId>',
-      };
-    }
-    return _handleRunReplay({ workspaceDir, stateDir, implId, isZh });
-  }
-
   return _handlePromoteImpl({ workspaceDir, stateDir, implId: subcommand, isZh });
 }

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 { normalizeCommandArgs } from '../utils/io.js';
 import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
 /**
@@ -50,7 +51,7 @@ export function handleRollbackImplCommand(ctx: PluginCommandContext): PluginComm
   const lang = (ctx.config?.language as string) || 'en';
   const isZh = lang === 'zh';
 
-  const args = (ctx.args || '').trim();
+  const args = normalizeCommandArgs(ctx.args).trim();
 
   // Parse args
   const subcommand = args.split(/\s+/)[0] || '';

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 { normalizeCommandArgs } from '../utils/io.js';
 import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
 /**
@@ -26,7 +27,7 @@ export function handleRollbackCommand(ctx: PluginCommandContext): PluginCommandR
     const isZh = lang === 'zh';
     const { sessionId } = ctx as SessionAwareCommandContext;
 
-    const args = (ctx.args || '').trim();
+    const args = normalizeCommandArgs(ctx.args).trim();
 
     if (!args) {
         return {

package/src/commands/samples.ts

@@ -1,5 +1,6 @@
 import { WorkspaceContext } from '../core/workspace-context.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { normalizeCommandArgs } from '../utils/io.js';
 import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 
 function isZh(ctx: PluginCommandContext): boolean {
@@ -9,7 +10,7 @@ function isZh(ctx: PluginCommandContext): boolean {
 export function handleSamplesCommand(ctx: PluginCommandContext): PluginCommandResult {
   const workspaceDir = resolvePluginCommandWorkspaceDir(ctx, 'samples');
   const zh = isZh(ctx);
-  const args = (ctx.args || '').trim();
+  const args = normalizeCommandArgs(ctx.args).trim();
   const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });
 
   if (args.startsWith('review ')) {

package/src/commands/thinking-os.ts

@@ -1,6 +1,7 @@
  
 import * as fs from 'fs';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import { normalizeCommandArgs } from '../utils/io.js';
 import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 
@@ -162,7 +163,7 @@ function formatAuditReport(wctx: WorkspaceContext): string {
 export function handleThinkingOs(ctx: PluginCommandContext): PluginCommandResult {
     const workspaceDir = getWorkspaceDir(ctx);
     const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });
-    const args = (ctx.args || '').trim();
+    const args = normalizeCommandArgs(ctx.args).trim();
     const subCommand = args.split(/\s+/)[0]?.toLowerCase();
     const rest = args.slice(subCommand?.length || 0).trim();
 

package/src/config/errors.ts

@@ -1,6 +1,6 @@
 /**
  * Domain-Specific Errors for Principles Disciple
- * 
+ *
  * These errors provide semantic meaning to failure modes,
  * making it easier to distinguish between:
  * - Lock contention (resource busy)
@@ -9,18 +9,34 @@
  * - Configuration issues
  */
 
+import type { PDErrorCategory } from '@principles/core';
+
+/** Maps legacy PdError codes to canonical PDErrorCategory values. */
+const codeToCategory: Record<string, PDErrorCategory> = {
+  LOCK_UNAVAILABLE: 'lease_conflict',
+  PATH_RESOLUTION_ERROR: 'workspace_invalid',
+  WORKSPACE_NOT_FOUND: 'workspace_invalid',
+  SAMPLE_NOT_FOUND: 'storage_unavailable',
+  CONFIGURATION_ERROR: 'input_invalid',
+  DEPENDENCY_ERROR: 'runtime_unavailable',
+  EVOLUTION_PROCESSING_ERROR: 'execution_failed',
+  TRAJECTORY_ERROR: 'storage_unavailable',
+};
+
 /**
  * Base class for all Principles Disciple errors
  */
 export class PdError extends Error {
+  readonly category: PDErrorCategory;
+
   constructor(
     message: string,
-     
     public readonly code: string,
     options?: { cause?: unknown }
   ) {
     super(message, options);
     this.name = 'PdError';
+    this.category = codeToCategory[code] ?? 'execution_failed';
   }
 }
 

package/src/constants/diagnostician.ts

@@ -1,7 +1,7 @@
 /**
  * Diagnostician 协议常量
  *
- * 用于 evolution-worker.ts（后台心跳）和 prompt.ts（实时路径）
+ * 用于 Runtime V2 diagnostician prompt
  * 与 templates/langs/zh/skills/pd-diagnostician/SKILL.md 保持一致
  */
 
@@ -13,7 +13,7 @@
 export const DIAGNOSTICIAN_PROTOCOL_SUMMARY = `## Diagnostic Protocol (5 Whys)
 
 **Phase 1 - Evidence Gathering**:
-- Read .state/.pain_flag for full pain context
+- Use the task input/context provided by Runtime V2 for pain context
 - Read .state/logs/events.jsonl recent entries
 - Search codebase for error patterns from Reason field
 - Record all evidence sources (file:line)

package/src/constants/tools.ts

@@ -58,4 +58,5 @@ export const WRITE_TOOLS = new Set<string>([
   ...LOW_RISK_WRITE_TOOL_NAMES,
   'delete_file',
   'move_file',
-]);
+]);
+