principles-disciple 1.78.0 → 1.80.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.78.0",
+  "version": "1.80.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

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

package/src/core/runtime-v2-prompt-activation-reader.ts

@@ -1,23 +1,11 @@
 import * as path from 'path';
 import * as fs from 'fs';
 import * as yaml from 'js-yaml';
-import { SqliteConnection, SqliteActivationStateStore, computeEffectiveFlags, DEFAULT_FEATURE_FLAGS } from '@principles/core/runtime-v2';
-import type { ActivationStatusRecord, EffectiveFeatureFlags } from '@principles/core/runtime-v2';
+import { SqliteConnection, SqliteActivationStateStore, computeEffectiveFlags, DEFAULT_FEATURE_FLAGS, filterPromptActivations, resolvePrincipleFromArtifact } from '@principles/core/runtime-v2';
+import type { EffectiveFeatureFlags, ActivatedPrinciple, PromptActivationReaderResult } from '@principles/core/runtime-v2';
 
-export const RUNTIME_V2_PRINCIPLE_BUDGET = 2000;
-
-export interface ActivatedPrinciple {
-  principleId: string;
-  text: string;
-  artifactId: string;
-  activationId: string;
-}
-
-export interface PromptActivationReaderResult {
-  principles: ActivatedPrinciple[];
-  warnings: string[];
-  source: 'runtime_v2';
-}
+export { RUNTIME_V2_PRINCIPLE_BUDGET } from '@principles/core/runtime-v2';
+export type { ActivatedPrinciple, PromptActivationReaderResult };
 
 export interface PromptActivationReaderDeps {
   logger?: { warn?: (msg: string) => void; info?: (msg: string) => void; error?: (msg: string) => void };
@@ -54,14 +42,29 @@ export class PromptActivationReader {
       sqliteConn = new SqliteConnection(this.workspaceDir);
       const store = new SqliteActivationStateStore(sqliteConn);
 
-      const activations = await store.listPromptActivations();
+      const allActivations = await store.listPromptActivations();
+      const promptActivations = filterPromptActivations(allActivations);
+
+      for (const activation of promptActivations) {
+        let artifactRow: unknown | null;
+        try {
+          artifactRow = this.queryArtifactRow(sqliteConn, activation.artifactId);
+        } catch (e) {
+          const msg = e instanceof Error ? e.message : String(e);
+          const warning = `artifact_query_failed: artifactId=${activation.artifactId} reason=${msg}; nextAction=check_pi_artifacts_table`;
+          warnings.push(warning);
+          this.deps.logger?.warn?.(`[PD:RuntimeV2] ${warning}`);
+          continue;
+        }
 
-      for (const activation of activations) {
-        if (activation.channel !== 'prompt' || activation.action !== 'prompt_activate') {
+        if (artifactRow === null) {
+          const warning = `artifact_not_found: artifactId=${activation.artifactId}; nextAction=check_pi_artifacts_table`;
+          warnings.push(warning);
+          this.deps.logger?.warn?.(`[PD:RuntimeV2] ${warning}`);
           continue;
         }
 
-        const result = this.resolvePrincipleFromActivation(sqliteConn, activation);
+        const result = resolvePrincipleFromArtifact(artifactRow, activation);
         if (result.ok) {
           principles.push(result.principle);
         } else {
@@ -85,6 +88,21 @@ export class PromptActivationReader {
     return { principles, warnings, source: 'runtime_v2' };
   }
 
+  private queryArtifactRow(sqliteConn: SqliteConnection, artifactId: string): unknown | null {
+    try {
+      const db = sqliteConn.getDb();
+      const row = db.prepare(`
+        SELECT artifact_id, artifact_kind, content_json, validation_status
+        FROM pi_artifacts
+        WHERE artifact_id = ?
+      `).get(artifactId);
+      return row ?? null;
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      throw new Error(`artifact_query_failed: artifactId=${artifactId} reason=${msg}; nextAction=check_pi_artifacts_table`);
+    }
+  }
+
   private loadFeatureFlags(): EffectiveFeatureFlags {
     const configPath = path.join(this.workspaceDir, '.pd', 'feature-flags.yaml');
 
@@ -141,91 +159,4 @@ export class PromptActivationReader {
     }
     return result;
   }
-
-  private resolvePrincipleFromActivation(
-    sqliteConn: SqliteConnection,
-    activation: ActivationStatusRecord,
-  ): { ok: true; principle: ActivatedPrinciple } | { ok: false; warning: string } {
-    const db = sqliteConn.getDb();
-
-    let contentJson: string;
-
-    try {
-      const row = db.prepare(`
-        SELECT artifact_id, artifact_kind, content_json, validation_status
-        FROM pi_artifacts
-        WHERE artifact_id = ?
-      `).get(activation.artifactId);
-
-      if (!isRecord(row)) {
-        return { ok: false, warning: `artifact_query_unexpected: artifactId=${activation.artifactId}; nextAction=check_pi_artifacts_table` };
-      }
-
-      const artifact_id = Object.hasOwn(row, 'artifact_id') && typeof row.artifact_id === 'string' && row.artifact_id.length > 0 ? row.artifact_id : null;
-      const artifact_kind = Object.hasOwn(row, 'artifact_kind') && typeof row.artifact_kind === 'string' ? row.artifact_kind : null;
-      const raw_content_json = Object.hasOwn(row, 'content_json') && typeof row.content_json === 'string' ? row.content_json : null;
-      const validation_status = Object.hasOwn(row, 'validation_status') && typeof row.validation_status === 'string' ? row.validation_status : null;
-
-      if (!artifact_id) {
-        return { ok: false, warning: `artifact_not_found: artifactId=${activation.artifactId} activationId=${activation.activationId}; nextAction=verify_artifact_exists_or_remove_stale_activation` };
-      }
-
-      if (artifact_kind !== 'principle') {
-        return { ok: false, warning: `artifact_not_principle: artifactId=${artifact_id} kind=${artifact_kind ?? 'missing'}; nextAction=skip_non_principle_activations` };
-      }
-
-      if (validation_status !== 'validated') {
-        return { ok: false, warning: `artifact_not_validated: artifactId=${artifact_id} status=${validation_status ?? 'missing'}; nextAction=skip_unvalidated_artifacts` };
-      }
-
-      if (raw_content_json === null) {
-        return { ok: false, warning: `artifact_missing_content_json: artifactId=${artifact_id}; nextAction=ensure_artifact_has_content_json` };
-      }
-
-      contentJson = raw_content_json;
-    } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
-      return { ok: false, warning: `artifact_query_failed: artifactId=${activation.artifactId} reason=${msg}; nextAction=check_pi_artifacts_table` };
-    }
-
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(contentJson);
-    } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
-      return { ok: false, warning: `artifact_content_json_parse_error: artifactId=${activation.artifactId} reason=${msg}; nextAction=fix_artifact_content_json` };
-    }
-
-    if (!isRecord(parsed)) {
-      return { ok: false, warning: `artifact_content_malformed: artifactId=${activation.artifactId} reason=parsed_to_non_object; nextAction=fix_artifact_content_json` };
-    }
-
-    const principleId = Object.hasOwn(parsed, 'principleId') && typeof parsed.principleId === 'string' ? parsed.principleId : undefined;
-    const text = Object.hasOwn(parsed, 'text') && typeof parsed.text === 'string' ? parsed.text : undefined;
-
-    const draftObj = Object.hasOwn(parsed, 'principleDraft') && isRecord(parsed.principleDraft) ? parsed.principleDraft : null;
-    const draftTitle = draftObj && Object.hasOwn(draftObj, 'title') && typeof draftObj.title === 'string' ? draftObj.title : undefined;
-    const draftStatement = draftObj && Object.hasOwn(draftObj, 'statement') && typeof draftObj.statement === 'string' ? draftObj.statement : undefined;
-
-    const resolvedPrincipleId = principleId && principleId.length > 0 ? principleId : draftTitle;
-    const resolvedText = text && text.length > 0 ? text : draftStatement;
-
-    if (!resolvedPrincipleId || resolvedPrincipleId.length === 0) {
-      return { ok: false, warning: `artifact_missing_principle_id: artifactId=${activation.artifactId}; nextAction=ensure_artifact_has_principleId_or_principleDraft_title` };
-    }
-
-    if (!resolvedText || resolvedText.length === 0) {
-      return { ok: false, warning: `artifact_missing_text: artifactId=${activation.artifactId} principleId=${resolvedPrincipleId}; nextAction=ensure_artifact_has_text_or_principleDraft_statement` };
-    }
-
-    return {
-      ok: true,
-      principle: {
-        principleId: resolvedPrincipleId,
-        text: resolvedText,
-        artifactId: activation.artifactId,
-        activationId: activation.activationId,
-      },
-    };
-  }
 }

package/src/hooks/prompt.ts

@@ -12,9 +12,9 @@ import { defaultContextConfig } from '../types.js';
 import { extractSummary, getHistoryVersions, parseWorkingMemorySection, workingMemoryToInjection, autoCompressFocus, safeReadCurrentFocus } from '../core/focus-history.js';
 import { PathResolver } from '../core/path-resolver.js';
 import { selectPrinciplesForInjection, DEFAULT_PRINCIPLE_BUDGET } from '../core/principle-injection.js';
-import { getCachedMaskedPrincipleSet, WorkflowFunnelLoader, PiAiRuntimeAdapter, EmpathyObserver, AgentScheduler } from '@principles/core/runtime-v2';
+import { getCachedMaskedPrincipleSet, WorkflowFunnelLoader, PiAiRuntimeAdapter, EmpathyObserver, AgentScheduler, RUNTIME_V2_PRINCIPLE_BUDGET, trimToBudget, renderPrinciplesToDirectives } from '@principles/core/runtime-v2';
 import { truncateInjectionToBudget } from '@principles/core/prompt-builder';
-import { PromptActivationReader, RUNTIME_V2_PRINCIPLE_BUDGET } from '../core/runtime-v2-prompt-activation-reader.js';
+import { PromptActivationReader } from '../core/runtime-v2-prompt-activation-reader.js';
 import {
   matchEmpathyKeywords,
   loadKeywordStore,
@@ -898,20 +898,12 @@ ${heartbeatChecklist}
     dedupedV2 = v2Result.principles.filter((p) => !legacyActiveIds.has(p.principleId));
 
     if (dedupedV2.length > 0) {
-      let remaining = RUNTIME_V2_PRINCIPLE_BUDGET;
-      const lines: string[] = [];
-      lines.push('Runtime V2 activated principles (owner-approved):');
-      remaining -= 'Runtime V2 activated principles (owner-approved):'.length;
-
-      for (const p of dedupedV2) {
-        const entry = `- [${escapeXml(p.principleId)}] ${escapeXml(p.text)}`;
-        if (remaining < entry.length + 1) {
-          logger?.info?.(`[PD:RuntimeV2] Principle budget reached (${RUNTIME_V2_PRINCIPLE_BUDGET}c) — truncating after ${lines.length - 1} principles`);
-          break;
-        }
-        lines.push(entry);
-        remaining -= entry.length + 1;
-        runtimeV2PrincipleIds.add(p.principleId);
+      const { lines, injectedIds, truncated } = trimToBudget(dedupedV2, RUNTIME_V2_PRINCIPLE_BUDGET, escapeXml);
+      if (truncated) {
+        logger?.info?.(`[PD:RuntimeV2] Principle budget reached (${RUNTIME_V2_PRINCIPLE_BUDGET}c) — truncating after ${injectedIds.size} principles`);
+      }
+      for (const id of injectedIds) {
+        runtimeV2PrincipleIds.add(id);
       }
       runtimeV2PrinciplesContent = lines.join('\n');
     }
@@ -984,24 +976,8 @@ ${empathySilenceConstraint}
   // PLACED IN prependSystemContext (before gateway system prompt) for highest LLM attention.
   // These are owner-reviewed, validated behavior constraints — not background context.
   if (runtimeV2PrincipleIds.size > 0) {
-    const directiveLines: string[] = [];
-    directiveLines.push('');
-    directiveLines.push('## 【OWNER-APPROVED BEHAVIOR DIRECTIVES】');
-    directiveLines.push('');
-    directiveLines.push('Owner-approved behavior directives are active operating constraints learned from prior owner corrections.');
-    directiveLines.push('These directives are mandatory for this session unless they conflict with safety, security, or higher-priority system policy.');
-    directiveLines.push('For ambiguous coding or file-changing tasks, follow these directives before using mutating tools.');
-    directiveLines.push('');
-    for (const p of dedupedV2) {
-      if (!runtimeV2PrincipleIds.has(p.principleId)) continue;
-      directiveLines.push(`<directive id="${escapeXml(p.principleId)}" source="runtime_v2_activation">`);
-      directiveLines.push(`MANDATORY: ${escapeXml(p.text)}`);
-      directiveLines.push('Apply this as an active behavior constraint. Do not treat this as background context.');
-      directiveLines.push('</directive>');
-      directiveLines.push('');
-    }
-    directiveLines.push('Note: These directives do not override safety, security, or core system policy.');
-    prependSystemContext += directiveLines.join('\n');
+    const directiveText = renderPrinciplesToDirectives(dedupedV2, runtimeV2PrincipleIds, escapeXml);
+    prependSystemContext += directiveText;
   }
 
   // Routing guidance removed per PRI-291 (MVP diet).

package/tests/core/surface-guard.test.ts

@@ -0,0 +1,198 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  checkSurfaceGuard,
+  isSurfaceEnabled,
+  guardHook,
+  guardService,
+  getSurfaceIdForHook,
+  getSurfaceIdForService,
+} from '../../src/core/surface-guard.js';
+import { PLUGIN_SURFACE_REGISTRY } from '@principles/core/runtime-v2';
+import type { OpenClawPluginService } from '../../src/openclaw-sdk.js';
+
+describe('surface-guard', () => {
+  describe('getSurfaceIdForHook', () => {
+    it('generates correct surface id without label', () => {
+      expect(getSurfaceIdForHook('before_tool_call')).toBe('hook:before_tool_call');
+    });
+
+    it('generates correct surface id with label', () => {
+      expect(getSurfaceIdForHook('after_tool_call', 'trajectory')).toBe('hook:after_tool_call.trajectory');
+    });
+  });
+
+  describe('getSurfaceIdForService', () => {
+    it('generates correct surface id for service', () => {
+      expect(getSurfaceIdForService('evolution-worker')).toBe('service:evolution-worker');
+    });
+  });
+
+  describe('checkSurfaceGuard', () => {
+    it('returns passed=true when registry is valid', () => {
+      const result = checkSurfaceGuard();
+      expect(result.passed).toBe(true);
+      expect(result.violations).toEqual([]);
+    });
+
+    it('includes enabled core surfaces', () => {
+      const result = checkSurfaceGuard();
+      expect(result.enabledCoreSurfaces.length).toBeGreaterThan(0);
+      for (const surfaceId of result.enabledCoreSurfaces) {
+        const entry = PLUGIN_SURFACE_REGISTRY.find(s => s.id === surfaceId);
+        expect(entry).toBeDefined();
+        expect(entry?.category).toBe('core');
+      }
+    });
+
+    it('includes disabled non-core surfaces', () => {
+      const result = checkSurfaceGuard();
+      expect(result.disabledNonCoreSurfaces.length).toBeGreaterThan(0);
+      for (const surfaceId of result.disabledNonCoreSurfaces) {
+        const entry = PLUGIN_SURFACE_REGISTRY.find(s => s.id === surfaceId);
+        expect(entry).toBeDefined();
+        expect(entry?.category).not.toBe('core');
+        expect(entry?.enabledByDefault).toBe(false);
+      }
+    });
+
+    it('returns violations when non-core surface is enabledByDefault', () => {
+      const result = checkSurfaceGuard();
+      const nonCoreEnabled = PLUGIN_SURFACE_REGISTRY.filter(
+        s => s.category !== 'core' && s.enabledByDefault,
+      );
+      if (nonCoreEnabled.length > 0) {
+        expect(result.violations.length).toBeGreaterThan(0);
+      }
+    });
+  });
+
+  describe('isSurfaceEnabled', () => {
+    it('returns enabled=true for core surface without override', () => {
+      const result = isSurfaceEnabled('hook:before_prompt_build');
+      expect(result.enabled).toBe(true);
+      expect(result.reason).toBeUndefined();
+    });
+
+    it('returns enabled=false for quiet surface without override', () => {
+      const result = isSurfaceEnabled('hook:after_tool_call.trajectory');
+      expect(result.enabled).toBe(false);
+      expect(result.reason).toBeDefined();
+    });
+
+    it('returns reason when surface not found', () => {
+      const result = isSurfaceEnabled('hook:nonexistent_hook');
+      expect(result.enabled).toBe(false);
+      expect(result.reason).toContain('not found in registry');
+    });
+
+    it('allows override for quiet surface', () => {
+      const result = isSurfaceEnabled('hook:after_tool_call.trajectory', {
+        'hook:after_tool_call.trajectory': true,
+      });
+      expect(result.enabled).toBe(true);
+    });
+
+    it('ignores non-boolean override', () => {
+      const result = isSurfaceEnabled('hook:before_prompt_build', {
+        'hook:before_prompt_build': 'yes' as unknown as boolean,
+      });
+      expect(result.enabled).toBe(true);
+    });
+
+    it('cannot disable core surface', () => {
+      const result = isSurfaceEnabled('hook:before_prompt_build', {
+        'hook:before_prompt_build': false,
+      });
+      expect(result.enabled).toBe(true);
+      expect(result.reason).toContain('core');
+    });
+
+    it('returns disabledReason for disabled surface', () => {
+      const result = isSurfaceEnabled('service:evolution-worker');
+      expect(result.enabled).toBe(false);
+      expect(result.reason).toContain('evolution_worker');
+    });
+  });
+
+  describe('guardHook', () => {
+    beforeEach(() => {
+      vi.clearAllMocks();
+    });
+
+    it('returns original handler for enabled surface', () => {
+      const mockHandler = vi.fn().mockReturnValue('result');
+      const guarded = guardHook('hook:before_prompt_build', undefined, mockHandler);
+      const result = guarded({}, {});
+      expect(mockHandler).toHaveBeenCalled();
+      expect(result).toBe('result');
+    });
+
+    it('returns no-op for disabled surface without logger', () => {
+      const mockHandler = vi.fn();
+      const guarded = guardHook('hook:after_tool_call.trajectory', undefined, mockHandler);
+      const result = guarded({}, {});
+      expect(mockHandler).not.toHaveBeenCalled();
+      expect(result).toBeUndefined();
+    });
+
+    it('logs when surface is disabled with logger', () => {
+      const mockLogger = { info: vi.fn(), debug: vi.fn() };
+      const mockHandler = vi.fn();
+      const guarded = guardHook('hook:after_tool_call.trajectory', mockLogger, mockHandler);
+      guarded({}, {});
+      expect(mockLogger.info).toHaveBeenCalled();
+      expect(mockHandler).not.toHaveBeenCalled();
+    });
+
+    it('does not log for enabled surface', () => {
+      const mockLogger = { info: vi.fn(), debug: vi.fn() };
+      const mockHandler = vi.fn();
+      const guarded = guardHook('hook:before_prompt_build', mockLogger, mockHandler);
+      guarded({}, {});
+      expect(mockLogger.info).not.toHaveBeenCalled();
+    });
+
+    it('guards unknown surface with not-found reason', () => {
+      const mockLogger = { info: vi.fn(), debug: vi.fn() };
+      const guarded = guardHook('hook:unknown_hook', mockLogger, vi.fn());
+      guarded({}, {});
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        expect.stringContaining('not found in registry'),
+      );
+    });
+  });
+
+  describe('guardService', () => {
+    beforeEach(() => {
+      vi.clearAllMocks();
+    });
+
+    it('returns original service for enabled surface', () => {
+      const mockService: OpenClawPluginService = { id: 'test-service' };
+      const result = guardService('hook:before_prompt_build', mockService);
+      expect(result).toBe(mockService);
+    });
+
+    it('returns null for disabled surface without logger', () => {
+      const mockService: OpenClawPluginService = { id: 'test-service' };
+      const result = guardService('hook:after_tool_call.trajectory', mockService);
+      expect(result).toBeNull();
+    });
+
+    it('logs when surface is disabled with logger', () => {
+      const mockLogger = { info: vi.fn(), debug: vi.fn() };
+      const mockService: OpenClawPluginService = { id: 'test-service' };
+      const result = guardService('hook:after_tool_call.trajectory', mockService, mockLogger);
+      expect(result).toBeNull();
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        expect.stringContaining('SKIP service'),
+      );
+    });
+
+    it('returns null for unknown surface', () => {
+      const mockService: OpenClawPluginService = { id: 'test-service' };
+      const result = guardService('service:nonexistent', mockService);
+      expect(result).toBeNull();
+    });
+  });
+});

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

@@ -0,0 +1,201 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import type { Dirent } from 'fs';
+import type { OpenClawPluginApi } from '../../src/openclaw-sdk.js';
+
+const mockFs = {
+  existsSync: vi.fn(),
+  readFileSync: vi.fn(),
+  writeFileSync: vi.fn(),
+  readdirSync: vi.fn(),
+};
+
+vi.mock('fs', () => mockFs);
+
+const WORKSPACE_GUIDANCE_MIGRATOR_PATH = '../../src/core/workspace-guidance-migrator.js';
+
+describe('workspace-guidance-migrator', () => {
+  let migrateStaleWorkspaceGuidance: (api: OpenClawPluginApi, workspaceDir: string) => {
+    migratedFiles: string[];
+    skippedFiles: string[];
+    errors: { file: string; error: string }[];
+  };
+
+  const mockLogger = {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  };
+
+  const mockApi = {
+    logger: mockLogger,
+  } as unknown as OpenClawPluginApi;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    vi.resetModules();
+
+    mockFs.existsSync.mockReturnValue(true);
+    mockFs.readFileSync.mockReturnValue('');
+    mockFs.writeFileSync.mockReturnValue(undefined);
+    mockFs.readdirSync.mockReturnValue([]);
+
+    const module = await import(WORKSPACE_GUIDANCE_MIGRATOR_PATH);
+    migrateStaleWorkspaceGuidance = module.migrateStaleWorkspaceGuidance;
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('migrateStaleWorkspaceGuidance', () => {
+    it('skips files that do not exist', () => {
+      mockFs.existsSync.mockReturnValue(false);
+
+      const result = migrateStaleWorkspaceGuidance(mockApi, '/workspace');
+
+      expect(result.migratedFiles).toEqual([]);
+      expect(result.skippedFiles).toEqual([]);
+      expect(result.errors).toEqual([]);
+    });
+
+    it('skips files with no stale guidance', () => {
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readFileSync.mockReturnValue('# Clean AGENTS.md\nNo stale references here.');
+
+      const result = migrateStaleWorkspaceGuidance(mockApi, '/workspace');
+
+      expect(result.migratedFiles).toEqual([]);
+      expect(result.skippedFiles.length).toBeGreaterThan(0);
+      expect(result.errors).toEqual([]);
+    });
+
+    it('migrates AGENTS.md with stale guidance', () => {
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readFileSync.mockReturnValue(
+        '# Agent Instructions\nPhysical interception ensures safety.',
+      );
+
+      const result = migrateStaleWorkspaceGuidance(mockApi, '/workspace');
+
+      expect(result.migratedFiles.some(f => f.includes('AGENTS.md'))).toBe(true);
+      expect(result.skippedFiles.some(f => f.includes('MEMORY.md'))).toBe(true);
+    });
+
+    it('creates backup before migration', () => {
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readFileSync.mockReturnValue(
+        '# Agent Instructions\nPhysical interception ensures safety.',
+      );
+
+      migrateStaleWorkspaceGuidance(mockApi, '/workspace');
+
+      const backupCalls = mockFs.writeFileSync.mock.calls.filter(
+        (call: unknown[]) => String(call[0]).includes('.pre-pri286.bak'),
+      );
+      expect(backupCalls.length).toBeGreaterThan(0);
+    });
+
+    it('logs migration progress', () => {
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readFileSync.mockReturnValue(
+        '# Agent Instructions\nPhysical interception ensures safety.',
+      );
+
+      migrateStaleWorkspaceGuidance(mockApi, '/workspace');
+
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        expect.stringContaining('[PD:GuidanceMigration]'),
+      );
+    });
+
+    it('handles read errors gracefully', () => {
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readFileSync.mockImplementation(() => {
+        throw new Error('Read error');
+      });
+
+      const result = migrateStaleWorkspaceGuidance(mockApi, '/workspace');
+
+      expect(result.errors.length).toBeGreaterThan(0);
+      expect(result.errors[0].error).toContain('Failed to read file content');
+    });
+
+    it('handles write errors and restores original', () => {
+      const originalContent = '# Agent Instructions\nPhysical interception ensures safety.';
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readFileSync.mockReturnValue(originalContent);
+
+      let callCount = 0;
+      mockFs.writeFileSync.mockImplementation((path: string, content: string) => {
+        callCount++;
+        if (path.includes('.pre-pri286.bak')) return;
+        if (callCount === 2) {
+          expect(content).toBe(originalContent);
+          return;
+        }
+        throw new Error('Write error');
+      });
+
+      const result = migrateStaleWorkspaceGuidance(mockApi, '/workspace');
+
+      expect(result.errors.length).toBeGreaterThan(0);
+      expect(callCount).toBeGreaterThanOrEqual(2);
+    });
+
+    it('skips non-guidance files', () => {
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readFileSync.mockReturnValue('# Random Content\nNo guidance here.');
+
+      const result = migrateStaleWorkspaceGuidance(mockApi, '/workspace');
+
+      expect(result.migratedFiles).toEqual([]);
+    });
+
+    it('discovers skill files in .principles/skills directory', () => {
+      mockFs.existsSync.mockImplementation((p: string) => {
+        if (String(p).includes('.principles/skills')) return true;
+        return false;
+      });
+      mockFs.readdirSync.mockReturnValue([
+        { isDirectory: () => true, name: 'admin' },
+        { isDirectory: () => true, name: 'reflection' },
+      ] as Dirent[]);
+      mockFs.readFileSync.mockReturnValue(
+        'Ensure `PLAN.md` contains `## Target Files` heading.',
+      );
+
+      const result = migrateStaleWorkspaceGuidance(mockApi, '/workspace');
+
+      expect(result.migratedFiles.length).toBeGreaterThan(0);
+    });
+
+    it('handles empty workspace directory', () => {
+      mockFs.existsSync.mockReturnValue(false);
+
+      const result = migrateStaleWorkspaceGuidance(mockApi, '/workspace');
+
+      expect(result.migratedFiles).toEqual([]);
+      expect(result.skippedFiles).toEqual([]);
+      expect(result.errors).toEqual([]);
+    });
+
+    it('handles skills directory read error gracefully', () => {
+      mockFs.existsSync.mockImplementation((p: string) => {
+        if (String(p).includes('.principles/skills')) return true;
+        return false;
+      });
+      mockFs.readdirSync.mockImplementation(() => {
+        throw new Error('Directory read error');
+      });
+      mockFs.readFileSync.mockReturnValue(
+        '# Agent Instructions\nPhysical interception ensures safety.',
+      );
+
+      const result = migrateStaleWorkspaceGuidance(mockApi, '/workspace');
+
+      expect(result.errors.length).toBeGreaterThan(0);
+    });
+  });
+});