principles-disciple 1.83.0 → 1.84.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.83.0",
+  "version": "1.84.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

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

package/src/hooks/prompt.ts

@@ -192,7 +192,7 @@ export function loadContextInjectionConfig(workspaceDir: string): ContextInjecti
     const raw = cachedReadFile(profilePath);
     if (raw) {
       const profile = JSON.parse(raw);
-      if (profile.contextInjection) {
+      if (profile && typeof profile === 'object' && profile.contextInjection && typeof profile.contextInjection === 'object') {
         const contextInjection = profile.contextInjection as Partial<ContextInjectionConfig>;
         return {
           ...defaultContextConfig,
@@ -360,6 +360,9 @@ export async function handleBeforePromptBuild(
   }
 
   // ──── 1. prependSystemContext: Minimal Agent Identity ────
+  // EvolutionWorker-era INTERNAL SYSTEM LAYOUT removed per PRI-294.
+  // The EVOLUTION_WORKER PathResolver key and system layout reference are
+  // not MVP-Core; agents discover what they need via tool calls.
   prependSystemContext = `## 【AGENT IDENTITY】
 
 You are a **self-evolving AI agent** powered by Principles Disciple.
@@ -377,10 +380,6 @@ You are a **self-evolving AI agent** powered by Principles Disciple.
 - Use the current session for the normal user reply.
 - Use sessions_send for cross-session messaging.
 - Use agents_list / sessions_list for peer-agent or peer-session orchestration.
-
-## 🔧 INTERNAL SYSTEM LAYOUT
-- Your core plugin logic is rooted at: ${PathResolver.getExtensionRoot() || 'EXTENSION_ROOT (unresolved)'}
-- If you need self-inspection, prioritize the worker entry pointed by PathResolver key: EVOLUTION_WORKER
 `;
 
   // ──── 2. Empathy Observer Spawn (async sidecar)

package/src/index.ts

@@ -58,7 +58,7 @@ import { migrateDirectoryStructure } from './core/migration.js';
 import { migrateStaleWorkspaceGuidance } from './core/workspace-guidance-migrator.js';
 import { SystemLogger } from './core/system-logger.js';
 import { PathResolver } from './core/path-resolver.js';
-import { resolveCommandWorkspaceDir, resolveToolHookWorkspaceDirSafe } from './utils/workspace-resolver.js';
+import { resolveCommandWorkspaceDir, resolveToolHookWorkspaceDirSafe, resolveHookWorkspaceDir } from './utils/workspace-resolver.js';
 import { computeRuntimeShadowTaskFingerprint, PD_LOCAL_PROFILES } from './utils/shadow-fingerprint.js';
 import type { WorkerProfile } from './core/model-deployment-registry.js';
 import { validateWorkspaceDir } from './core/workspace-dir-validation.js';
@@ -68,10 +68,6 @@ import { checkSurfaceGuard, guardHook, guardService } from './core/surface-guard
 // Track started workspaces — one-time init + evolution worker per workspace
 const startedWorkspaces = new Set<string>();
 
-const HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION =
-  'verify gateway plugin activation and hook workspace binding; ' +
-  'migrate live hook workspace resolution to PD-owned canonical configuration before relying on config-based recovery';
-
 // Map from childSessionKey → shadowObservationId
 // Used to complete shadow observations when subagent ends
 const pendingShadowObservations = new Map<string, string>();
@@ -235,17 +231,20 @@ const plugin = {
     api.on(
       'before_prompt_build',
       guardHook('hook:before_prompt_build', api.logger, async (event: PluginHookBeforePromptBuildEvent, ctx: PluginHookAgentContext): Promise<PluginHookBeforePromptBuildResult | void> => {
-        const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'before_prompt_build');
-        if (!workspaceDir) {
+        const wsResult = resolveHookWorkspaceDir(ctx, api, 'before_prompt_build');
+        if (!wsResult.ok) {
           api.logger.error(
             `[PD:before_prompt_build] workspaceDir resolution failed. ` +
-            `agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'} ` +
-            `sessionKey=${ctx.sessionKey ?? '(missing)'}. ` +
+            `reason=${wsResult.reason} agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'}. ` +
             `Hook skipped — no mutation will occur. ` +
-            `NextAction: ${HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION}`,
+            `NextAction: ${wsResult.nextAction}`,
           );
           return;
         }
+        const workspaceDir = wsResult.workspaceDir;
+        if (wsResult.consistencyWarning) {
+          api.logger.warn(`[PD:before_prompt_build] ${wsResult.consistencyWarning}`);
+        }
         try {
           if (!startedWorkspaces.has(workspaceDir)) {
             startedWorkspaces.add(workspaceDir);
@@ -313,17 +312,20 @@ const plugin = {
     api.on(
       'before_tool_call',
       guardHook('hook:before_tool_call', api.logger, (event: PluginHookBeforeToolCallEvent, ctx: PluginHookToolContext): PluginHookBeforeToolCallResult | void => {
-        const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'before_tool_call');
-        if (!workspaceDir) {
+        const wsResult = resolveHookWorkspaceDir(ctx, api, 'before_tool_call');
+        if (!wsResult.ok) {
           api.logger.error(
             `[PD:before_tool_call] workspaceDir resolution failed. ` +
-            `agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'} ` +
-            `sessionKey=${ctx.sessionKey ?? '(missing)'}. ` +
+            `reason=${wsResult.reason} agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'}. ` +
             `Hook skipped — security gate bypassed. ` +
-            `NextAction: ${HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION}`,
+            `NextAction: ${wsResult.nextAction}`,
           );
           return;
         }
+        const workspaceDir = wsResult.workspaceDir;
+        if (wsResult.consistencyWarning) {
+          api.logger.warn(`[PD:before_tool_call] ${wsResult.consistencyWarning}`);
+        }
         try {
           const pluginConfig = api.pluginConfig ?? {};
           const {logger} = api;
@@ -348,17 +350,20 @@ const plugin = {
     api.on(
       'after_tool_call',
       guardHook('hook:after_tool_call', api.logger, (event: PluginHookAfterToolCallEvent, ctx: PluginHookToolContext): void => {
-        const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'after_tool_call');
-        if (!workspaceDir) {
+        const wsResult = resolveHookWorkspaceDir(ctx, api, 'after_tool_call');
+        if (!wsResult.ok) {
           api.logger.error(
             `[PD:after_tool_call] workspaceDir resolution failed. ` +
-            `agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'} ` +
-            `sessionKey=${ctx.sessionKey ?? '(missing)'}. ` +
+            `reason=${wsResult.reason} agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'}. ` +
             `Hook skipped — pain detection bypassed. ` +
-            `NextAction: ${HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION}`,
+            `NextAction: ${wsResult.nextAction}`,
           );
           return;
         }
+        const workspaceDir = wsResult.workspaceDir;
+        if (wsResult.consistencyWarning) {
+          api.logger.warn(`[PD:after_tool_call] ${wsResult.consistencyWarning}`);
+        }
         try {
           const pluginConfig = api.pluginConfig ?? {};
           // Pass api separately to handleAfterToolCall to maintain type safety
@@ -381,17 +386,21 @@ const plugin = {
     api.on(
       'llm_output',
       guardHook('hook:llm_output', api.logger, (event: PluginHookLlmOutputEvent, ctx: PluginHookAgentContext): void => {
-        const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'llm_output');
-        if (!workspaceDir) {
+        const wsResult = resolveHookWorkspaceDir(ctx, api, 'llm_output');
+        if (!wsResult.ok) {
           api.logger.error(
             `[PD:llm_output] workspaceDir resolution failed. ` +
-            `agentId=${ctx.agentId ?? '(missing)'} ` +
+            `reason=${wsResult.reason} agentId=${ctx.agentId ?? '(missing)'} ` +
             `sessionId=${ctx.sessionId ?? '(missing)'}. ` +
             `Hook skipped — LLM analysis bypassed. ` +
-            `NextAction: ${HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION}`,
+            `NextAction: ${wsResult.nextAction}`,
           );
           return;
         }
+        const workspaceDir = wsResult.workspaceDir;
+        if (wsResult.consistencyWarning) {
+          api.logger.warn(`[PD:llm_output] ${wsResult.consistencyWarning}`);
+        }
         try {
           handleLlmOutput(event, { ...ctx, workspaceDir });
 
@@ -525,49 +534,59 @@ const plugin = {
 
     // ── Hook: Lifecycle ──
     api.on('before_reset', guardHook('hook:before_reset', api.logger, (event: PluginHookBeforeResetEvent, ctx: PluginHookAgentContext) => {
-      const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'before_reset');
-      if (!workspaceDir) {
+      const wsResult = resolveHookWorkspaceDir(ctx, api, 'before_reset');
+      if (!wsResult.ok) {
         api.logger.error(
           `[PD:before_reset] workspaceDir resolution failed. ` +
-          `agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'}. ` +
-          `Hook skipped. NextAction: ${HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION}`,
+          `reason=${wsResult.reason} agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'}. ` +
+          `Hook skipped. NextAction: ${wsResult.nextAction}`,
         );
         return;
       }
-      return handleBeforeReset(event, { ...ctx, workspaceDir });
+      if (wsResult.consistencyWarning) {
+        api.logger.warn(`[PD:before_reset] ${wsResult.consistencyWarning}`);
+      }
+      return handleBeforeReset(event, { ...ctx, workspaceDir: wsResult.workspaceDir });
     }));
     
     api.on('before_compaction', guardHook('hook:before_compaction', api.logger, (event: PluginHookBeforeCompactionEvent, ctx: PluginHookAgentContext) => {
-      const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'before_compaction');
-      if (!workspaceDir) {
+      const wsResult = resolveHookWorkspaceDir(ctx, api, 'before_compaction');
+      if (!wsResult.ok) {
         api.logger.error(
           `[PD:before_compaction] workspaceDir resolution failed. ` +
-          `agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'}. ` +
-          `Hook skipped. NextAction: ${HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION}`,
+          `reason=${wsResult.reason} agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'}. ` +
+          `Hook skipped. NextAction: ${wsResult.nextAction}`,
         );
         return;
       }
-      return handleBeforeCompaction(event, { ...ctx, workspaceDir });
+      if (wsResult.consistencyWarning) {
+        api.logger.warn(`[PD:before_compaction] ${wsResult.consistencyWarning}`);
+      }
+      return handleBeforeCompaction(event, { ...ctx, workspaceDir: wsResult.workspaceDir });
     }));
     
     api.on('after_compaction', guardHook('hook:after_compaction', api.logger, (event: PluginHookAfterCompactionEvent, ctx: PluginHookAgentContext) => {
-      const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'after_compaction');
-      if (!workspaceDir) {
+      const wsResult = resolveHookWorkspaceDir(ctx, api, 'after_compaction');
+      if (!wsResult.ok) {
         api.logger.error(
           `[PD:after_compaction] workspaceDir resolution failed. ` +
-          `agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'}. ` +
-          `Hook skipped. NextAction: ${HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION}`,
+          `reason=${wsResult.reason} agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'}. ` +
+          `Hook skipped. NextAction: ${wsResult.nextAction}`,
         );
         return;
       }
-      return handleAfterCompaction(event, { ...ctx, workspaceDir });
+      if (wsResult.consistencyWarning) {
+        api.logger.warn(`[PD:after_compaction] ${wsResult.consistencyWarning}`);
+      }
+      return handleAfterCompaction(event, { ...ctx, workspaceDir: wsResult.workspaceDir });
     }));
 
-    // ── Service: Background Evolution Worker ──
+    // ── Service Registration (surface-guarded) ──
+    // PRI-294: EvolutionWorker service registration removed — it starts via
+    // before_prompt_build hook gate, not via api.registerService. The surface
+    // guard already prevents registration when disabled (enabledByDefault=false).
+    // Dead pre-assignment of EvolutionWorkerService.api removed.
     try {
-      EvolutionWorkerService.api = api;
-      const guardedEvolutionWorker = guardService('service:evolution-worker', EvolutionWorkerService, api.logger);
-      if (guardedEvolutionWorker) api.registerService(guardedEvolutionWorker);
       const guardedCorrectionObserver = guardService('service:correction-observer', CorrectionObserverService, api.logger);
       if (guardedCorrectionObserver) api.registerService(guardedCorrectionObserver);
       const guardedTrajectory = guardService('service:trajectory', TrajectoryService, api.logger);

package/src/utils/workspace-resolver.ts

@@ -2,13 +2,19 @@
  * Workspace Directory Resolution Utilities
  *
  * Shared helpers for resolving workspace directories across commands and hooks.
+ *
+ * Hook resolution priority (PRI-259): PD canonical config → OpenClaw fallback.
+ * PD canonical sources: PD_WORKSPACE_DIR env → OPENCLAW_WORKSPACE env →
+ * principles-disciple.json → ~/.openclaw/workspace default.
+ * OpenClaw fallback: ctx.workspaceDir → api.runtime.agent.resolveAgentWorkspaceDir().
  */
 
 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';
 import * as path from 'path';
+import * as os from 'os';
+import * as fs from 'fs';
 
 /**
  * Resolve workspace directory for command execution.
@@ -83,16 +89,258 @@ export function resolvePluginCommandWorkspaceDir(
   );
 }
 
+// ── PD Canonical Workspace Config Resolution (PRI-259) ──────────────────
+
+export type CanonicalWorkspaceSource = 'pd_env' | 'openclaw_env' | 'pd_config' | 'pd_default';
+
+export interface CanonicalWorkspaceResult {
+  workspaceDir: string;
+  source: CanonicalWorkspaceSource;
+}
+
+const PD_CONFIG_FILENAME = 'principles-disciple.json';
+
+function loadWorkspaceFromPdConfigFile(): string | null {
+  const candidates = [
+    path.join(os.homedir(), '.openclaw', PD_CONFIG_FILENAME),
+    path.join(os.homedir(), '.principles', PD_CONFIG_FILENAME),
+    path.join(process.cwd(), PD_CONFIG_FILENAME),
+  ];
+
+  for (const configPath of candidates) {
+    if (!fs.existsSync(configPath)) continue;
+    try {
+      const raw = fs.readFileSync(configPath, 'utf8');
+      const parsed: unknown = JSON.parse(raw);
+      if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        if (Object.hasOwn(parsed, 'workspace')) {
+          const workspaceValue = (parsed as Record<string, unknown>)['workspace'];
+          if (typeof workspaceValue === 'string' && workspaceValue.trim()) {
+            return workspaceValue.trim();
+          }
+        }
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+export function resolveCanonicalWorkspaceDir(): CanonicalWorkspaceResult | null {
+  const pdEnv = process.env.PD_WORKSPACE_DIR;
+  if (pdEnv && pdEnv.trim()) {
+    const dir = path.resolve(pdEnv.trim());
+    if (!validateWorkspaceDir(dir)) {
+      return { workspaceDir: dir, source: 'pd_env' };
+    }
+  }
+
+  const ocEnv = process.env.OPENCLAW_WORKSPACE;
+  if (ocEnv && ocEnv.trim()) {
+    const dir = path.resolve(ocEnv.trim());
+    if (!validateWorkspaceDir(dir)) {
+      return { workspaceDir: dir, source: 'openclaw_env' };
+    }
+  }
+
+  const configWorkspace = loadWorkspaceFromPdConfigFile();
+  if (configWorkspace) {
+    const dir = path.resolve(configWorkspace);
+    if (!validateWorkspaceDir(dir)) {
+      return { workspaceDir: dir, source: 'pd_config' };
+    }
+  }
+
+  const defaultDir = path.join(os.homedir(), '.openclaw', 'workspace');
+  if (!validateWorkspaceDir(defaultDir)) {
+    return { workspaceDir: defaultDir, source: 'pd_default' };
+  }
+
+  return null;
+}
+
+/**
+ * Resolve only PD explicit sources (env vars + config file), excluding pd_default.
+ * Used by hook resolution to ensure ctx.workspaceDir takes priority over the
+ * hardcoded default fallback.
+ */
+function resolveExplicitPdSources(): CanonicalWorkspaceResult | null {
+  const pdEnv = process.env.PD_WORKSPACE_DIR;
+  if (pdEnv && pdEnv.trim()) {
+    const dir = path.resolve(pdEnv.trim());
+    if (!validateWorkspaceDir(dir)) {
+      return { workspaceDir: dir, source: 'pd_env' };
+    }
+  }
+
+  const ocEnv = process.env.OPENCLAW_WORKSPACE;
+  if (ocEnv && ocEnv.trim()) {
+    const dir = path.resolve(ocEnv.trim());
+    if (!validateWorkspaceDir(dir)) {
+      return { workspaceDir: dir, source: 'openclaw_env' };
+    }
+  }
+
+  const configWorkspace = loadWorkspaceFromPdConfigFile();
+  if (configWorkspace) {
+    const dir = path.resolve(configWorkspace);
+    if (!validateWorkspaceDir(dir)) {
+      return { workspaceDir: dir, source: 'pd_config' };
+    }
+  }
+
+  return null;
+}
+
+// ── Hook Workspace Resolution (PRI-259) ────────────────────────────────
+
+export type HookWorkspaceSource = CanonicalWorkspaceSource | 'openclaw_context' | 'openclaw_api';
+
+export interface HookWorkspaceResolutionSuccess {
+  ok: true;
+  workspaceDir: string;
+  source: HookWorkspaceSource;
+  consistencyWarning?: string;
+}
+
+export interface HookWorkspaceResolutionFailure {
+  ok: false;
+  reason: string;
+  nextAction: string;
+  message: string;
+}
+
+export type HookWorkspaceResolutionResult =
+  | HookWorkspaceResolutionSuccess
+  | HookWorkspaceResolutionFailure;
+
+function tryResolveFromOpenClawApi(
+  api: OpenClawPluginApi,
+  agentId: string | undefined,
+): string | undefined {
+  try {
+    const resolved = api.runtime?.agent?.resolveAgentWorkspaceDir?.(api.config, agentId ?? 'main');
+    if (resolved && !validateWorkspaceDir(resolved)) {
+      return resolved;
+    }
+  } catch {
+    // Fall through
+  }
+  return undefined;
+}
+
+export interface HookWorkspaceResolutionOptions {
+  canonicalResolver?: () => CanonicalWorkspaceResult | null;
+  explicitPdResolver?: () => CanonicalWorkspaceResult | null;
+}
+
+export function resolveHookWorkspaceDir(
+  ctx: WorkspaceResolutionContext,
+  api: OpenClawPluginApi,
+  source: string,
+  options?: HookWorkspaceResolutionOptions,
+): HookWorkspaceResolutionResult {
+  // Priority 1: PD explicit sources (env vars + config file) — these are
+  // owner-declared and intentionally override the live session context.
+  const resolveExplicit = options?.explicitPdResolver ?? resolveExplicitPdSources;
+  const explicit = resolveExplicit();
+
+  if (explicit) {
+    let consistencyWarning: string | undefined;
+
+    if (ctx.workspaceDir) {
+      const normalizedCtx = path.resolve(ctx.workspaceDir);
+      const normalizedExplicit = path.resolve(explicit.workspaceDir);
+      if (normalizedCtx !== normalizedExplicit) {
+        consistencyWarning =
+          `PD explicit workspace (${explicit.source}: ${explicit.workspaceDir}) ` +
+          `differs from OpenClaw context (${ctx.workspaceDir}). Using PD explicit.`;
+      }
+    }
+
+    return {
+      ok: true,
+      workspaceDir: explicit.workspaceDir,
+      source: explicit.source,
+      consistencyWarning,
+    };
+  }
+
+  // Priority 2: OpenClaw live context — the real session workspace.
+  // This MUST take priority over pd_default (the hardcoded fallback).
+  if (ctx.workspaceDir) {
+    const issue = validateWorkspaceDir(ctx.workspaceDir);
+    if (!issue) {
+      return {
+        ok: true,
+        workspaceDir: ctx.workspaceDir,
+        source: 'openclaw_context',
+      };
+    }
+  }
+
+  // Priority 3: OpenClaw API resolution
+  const apiResolved = tryResolveFromOpenClawApi(api, ctx.agentId);
+  if (apiResolved) {
+    return {
+      ok: true,
+      workspaceDir: apiResolved,
+      source: 'openclaw_api',
+    };
+  }
+
+  // Priority 4: pd_default (hardcoded fallback) — only when nothing else works
+  const resolveCanonical = options?.canonicalResolver ?? resolveCanonicalWorkspaceDir;
+  const canonical = resolveCanonical();
+  if (canonical && canonical.source === 'pd_default') {
+    return {
+      ok: true,
+      workspaceDir: canonical.workspaceDir,
+      source: 'pd_default',
+      consistencyWarning:
+        'Using hardcoded default workspace (~/.openclaw/workspace). ' +
+        'Set PD_WORKSPACE_DIR or create ~/.openclaw/principles-disciple.json for stable resolution.',
+    };
+  }
+
+  return {
+    ok: false,
+    reason: 'workspace_dir_unresolvable',
+    nextAction:
+      'Set PD_WORKSPACE_DIR environment variable, create ~/.openclaw/principles-disciple.json ' +
+      'with a "workspace" field, or ensure OpenClaw provides workspaceDir in hook context.',
+    message:
+      `[PD:${source}] Cannot resolve workspace directory from any source. ` +
+      `PD explicit config (PD_WORKSPACE_DIR, principles-disciple.json) ` +
+      `and OpenClaw fallback (ctx.workspaceDir, api.resolveAgentWorkspaceDir, ~/.openclaw/workspace) all failed.`,
+  };
+}
+
 /**
  * Resolve workspace directory for tool hook execution (safe version).
  * Returns undefined instead of throwing if resolution fails.
+ *
+ * PRI-259: Uses PD canonical config as primary source, OpenClaw as fallback.
  */
 export function resolveToolHookWorkspaceDirSafe(
   ctx: WorkspaceResolutionContext,
   api: OpenClawPluginApi,
   source: string,
+  options?: HookWorkspaceResolutionOptions,
 ): string | undefined {
-  return resolveWorkspaceDir(api, ctx, { source });
+  const result = resolveHookWorkspaceDir(ctx, api, source, options);
+
+  if (!result.ok) {
+    api.logger.warn(result.message);
+    return undefined;
+  }
+
+  if (result.consistencyWarning) {
+    api.logger.warn(`[PD:${source}] ${result.consistencyWarning}`);
+  }
+
+  return result.workspaceDir;
 }
 
 export class WorkspaceResolutionError extends Error {

package/tests/core/workspace-guidance-migrator.test.ts

@@ -13,6 +13,15 @@ const mockFs = {
 
 vi.mock('fs', () => mockFs);
 
+// Mock heavy core module to avoid slow re-imports and to control staleness detection
+const mockMigrateWorkspaceGuidance = vi.fn<(content: string, relativePath: string) => { changed: boolean; migrated: string }>();
+const mockContainsStalePlanMdGuidance = vi.fn<(content: string, relativePath: string) => boolean>();
+
+vi.mock('@principles/core/runtime-v2', () => ({
+  migrateWorkspaceGuidance: (...args: unknown[]) => mockMigrateWorkspaceGuidance(...(args as [string, string])),
+  containsStalePlanMdGuidance: (...args: unknown[]) => mockContainsStalePlanMdGuidance(...(args as [string, string])),
+}));
+
 const WORKSPACE_GUIDANCE_MIGRATOR_PATH = '../../src/core/workspace-guidance-migrator.js';
 
 describe('workspace-guidance-migrator', () => {
@@ -41,6 +50,13 @@ describe('workspace-guidance-migrator', () => {
     mockFs.writeFileSync.mockReturnValue(undefined);
     mockFs.readdirSync.mockReturnValue([]);
 
+    // Default: content is NOT stale
+    mockContainsStalePlanMdGuidance.mockReturnValue(false);
+    mockMigrateWorkspaceGuidance.mockImplementation((content: string) => ({
+      changed: false,
+      migrated: content,
+    }));
+
     const module = await import(WORKSPACE_GUIDANCE_MIGRATOR_PATH);
     migrateStaleWorkspaceGuidance = module.migrateStaleWorkspaceGuidance;
   });
@@ -63,6 +79,7 @@ describe('workspace-guidance-migrator', () => {
     it('skips files with no stale guidance', () => {
       mockFs.existsSync.mockReturnValue(true);
       mockFs.readFileSync.mockReturnValue('# Clean AGENTS.md\nNo stale references here.');
+      // Default: containsStalePlanMdGuidance returns false
 
       const result = migrateStaleWorkspaceGuidance(mockApi, '/workspace');
 
@@ -76,6 +93,14 @@ describe('workspace-guidance-migrator', () => {
       mockFs.readFileSync.mockReturnValue(
         '# Agent Instructions\nPhysical interception ensures safety.',
       );
+      // First call (AGENTS.md) is stale, second (MEMORY.md) is not
+      mockContainsStalePlanMdGuidance
+        .mockReturnValueOnce(true)
+        .mockReturnValueOnce(false);
+      mockMigrateWorkspaceGuidance.mockImplementation((content: string) => ({
+        changed: true,
+        migrated: content.replace('Physical interception', 'MIGRATED'),
+      }));
 
       const result = migrateStaleWorkspaceGuidance(mockApi, '/workspace');
 
@@ -88,6 +113,11 @@ describe('workspace-guidance-migrator', () => {
       mockFs.readFileSync.mockReturnValue(
         '# Agent Instructions\nPhysical interception ensures safety.',
       );
+      mockContainsStalePlanMdGuidance.mockReturnValue(true);
+      mockMigrateWorkspaceGuidance.mockImplementation((content: string) => ({
+        changed: true,
+        migrated: content.replace('Physical interception', 'MIGRATED'),
+      }));
 
       migrateStaleWorkspaceGuidance(mockApi, '/workspace');
 
@@ -102,6 +132,11 @@ describe('workspace-guidance-migrator', () => {
       mockFs.readFileSync.mockReturnValue(
         '# Agent Instructions\nPhysical interception ensures safety.',
       );
+      mockContainsStalePlanMdGuidance.mockReturnValue(true);
+      mockMigrateWorkspaceGuidance.mockImplementation((content: string) => ({
+        changed: true,
+        migrated: content.replace('Physical interception', 'MIGRATED'),
+      }));
 
       migrateStaleWorkspaceGuidance(mockApi, '/workspace');
 
@@ -126,6 +161,11 @@ describe('workspace-guidance-migrator', () => {
       const originalContent = '# Agent Instructions\nPhysical interception ensures safety.';
       mockFs.existsSync.mockReturnValue(true);
       mockFs.readFileSync.mockReturnValue(originalContent);
+      mockContainsStalePlanMdGuidance.mockReturnValue(true);
+      mockMigrateWorkspaceGuidance.mockImplementation((content: string) => ({
+        changed: true,
+        migrated: content.replace('Physical interception', 'MIGRATED'),
+      }));
 
       let callCount = 0;
       mockFs.writeFileSync.mockImplementation((path: string, content: string) => {
@@ -154,8 +194,9 @@ describe('workspace-guidance-migrator', () => {
     });
 
     it('discovers skill files in .principles/skills directory', () => {
+      const skillsPattern = path.join('.principles', 'skills');
       mockFs.existsSync.mockImplementation((p: string) => {
-        if (String(p).includes('.principles/skills')) return true;
+        if (String(p).includes(skillsPattern)) return true;
         return false;
       });
       mockFs.readdirSync.mockReturnValue([
@@ -165,6 +206,11 @@ describe('workspace-guidance-migrator', () => {
       mockFs.readFileSync.mockReturnValue(
         'Ensure `PLAN.md` contains `## Target Files` heading.',
       );
+      mockContainsStalePlanMdGuidance.mockReturnValue(true);
+      mockMigrateWorkspaceGuidance.mockImplementation((content: string) => ({
+        changed: true,
+        migrated: content.replace('## Target Files', '## Targets'),
+      }));
 
       const result = migrateStaleWorkspaceGuidance(mockApi, '/workspace');
 
@@ -182,8 +228,9 @@ describe('workspace-guidance-migrator', () => {
     });
 
     it('handles skills directory read error gracefully', () => {
+      const skillsPattern = path.join('.principles', 'skills');
       mockFs.existsSync.mockImplementation((p: string) => {
-        if (String(p).includes('.principles/skills')) return true;
+        if (String(p).includes(skillsPattern)) return true;
         return false;
       });
       mockFs.readdirSync.mockImplementation(() => {