principles-disciple 1.74.0 → 1.75.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.74.0",
+  "version": "1.75.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

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

package/src/core/workspace-guidance-migrator.ts

@@ -0,0 +1,179 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import type { OpenClawPluginApi } from '../openclaw-sdk.js';
+import { migrateWorkspaceGuidance, containsStalePlanMdGuidance } from '@principles/core/runtime-v2';
+
+const WORKSPACE_GUIDANCE_FILES = [
+    'AGENTS.md',
+    'MEMORY.md',
+] as const;
+
+const PRINCIPLES_SUBDIR_FILES = [
+    'THINKING_OS.md',
+] as const;
+
+const SKILLS_DIR = path.join('.principles', 'skills');
+const PRINCIPLES_DIR = '.principles';
+const BACKUP_SUFFIX = '.pre-pri286.bak';
+
+interface MigrationError {
+    file: string;
+    error: string;
+}
+
+export interface MigrationResult {
+    migratedFiles: string[];
+    skippedFiles: string[];
+    errors: MigrationError[];
+}
+
+function readFileContent(filePath: string): string | null {
+    try {
+        const raw: unknown = fs.readFileSync(filePath, 'utf-8');
+        if (typeof raw !== 'string') {
+            return null;
+        }
+        return raw;
+    } catch {
+        return null;
+    }
+}
+
+function writeBackup(filePath: string, content: string): boolean {
+    const backupPath = filePath + BACKUP_SUFFIX;
+    try {
+        fs.writeFileSync(backupPath, content, 'utf-8');
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+interface DiscoverResult {
+    files: string[];
+    error?: MigrationError;
+}
+
+function discoverSkillFiles(workspaceDir: string): DiscoverResult {
+    const skillsDir = path.join(workspaceDir, SKILLS_DIR);
+    if (!fs.existsSync(skillsDir)) {
+        return { files: [] };
+    }
+    try {
+        const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+        const skillFiles: string[] = [];
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                const skillMd = path.join(skillsDir, entry.name, 'SKILL.md');
+                if (fs.existsSync(skillMd)) {
+                    skillFiles.push(skillMd);
+                }
+            }
+        }
+        return { files: skillFiles };
+    } catch (err: unknown) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        return {
+            files: [],
+            error: {
+                file: SKILLS_DIR,
+                error: `Failed to enumerate skills directory: ${errMsg}`,
+            },
+        };
+    }
+}
+
+function collectCandidateFiles(workspaceDir: string, result: MigrationResult): string[] {
+    const candidates: string[] = [];
+
+    for (const filename of WORKSPACE_GUIDANCE_FILES) {
+        candidates.push(path.join(workspaceDir, filename));
+    }
+
+    for (const filename of PRINCIPLES_SUBDIR_FILES) {
+        candidates.push(path.join(workspaceDir, PRINCIPLES_DIR, filename));
+    }
+
+    const skillDiscovery = discoverSkillFiles(workspaceDir);
+    if (skillDiscovery.error) {
+        result.errors.push(skillDiscovery.error);
+    }
+    candidates.push(...skillDiscovery.files);
+
+    return candidates;
+}
+
+export function migrateStaleWorkspaceGuidance(
+    api: OpenClawPluginApi,
+    workspaceDir: string,
+): MigrationResult {
+    const result: MigrationResult = {
+        migratedFiles: [],
+        skippedFiles: [],
+        errors: [],
+    };
+
+    const candidates = collectCandidateFiles(workspaceDir, result);
+
+    for (const filePath of candidates) {
+        const relativePath = path.relative(workspaceDir, filePath);
+
+        if (!fs.existsSync(filePath)) {
+            continue;
+        }
+
+        const content = readFileContent(filePath);
+        if (content === null) {
+            result.errors.push({
+                file: relativePath,
+                error: 'Failed to read file content',
+            });
+            continue;
+        }
+
+        if (!containsStalePlanMdGuidance(content, relativePath)) {
+            result.skippedFiles.push(relativePath);
+            continue;
+        }
+
+        const migrationResult = migrateWorkspaceGuidance(content, relativePath);
+        if (!migrationResult.changed) {
+            result.skippedFiles.push(relativePath);
+            continue;
+        }
+
+        const migrated = migrationResult.migrated;
+
+        const backupOk = writeBackup(filePath, content);
+        if (!backupOk) {
+            result.errors.push({
+                file: relativePath,
+                error: 'Failed to create backup file before migration',
+            });
+            continue;
+        }
+
+        try {
+            fs.writeFileSync(filePath, migrated, 'utf-8');
+            result.migratedFiles.push(relativePath);
+            api.logger.info(`[PD:GuidanceMigration] Migrated ${relativePath} (backup at ${relativePath}${BACKUP_SUFFIX})`);
+        } catch (writeErr: unknown) {
+            const errMsg = writeErr instanceof Error ? writeErr.message : String(writeErr);
+            result.errors.push({
+                file: relativePath,
+                error: `Failed to write migrated content: ${errMsg}`,
+            });
+            try {
+                fs.writeFileSync(filePath, content, 'utf-8');
+            } catch {
+                api.logger.error(`[PD:GuidanceMigration] CRITICAL: Failed to restore original content for ${relativePath} after write failure`);
+            }
+        }
+    }
+
+    if (result.migratedFiles.length > 0) {
+        api.logger.info(`[PD:GuidanceMigration] Migration complete: ${result.migratedFiles.length} migrated, ${result.skippedFiles.length} skipped, ${result.errors.length} errors`);
+    }
+
+    return result;
+}

package/src/index.ts

@@ -51,6 +51,7 @@ import { PDTaskService } from './core/pd-task-service.js';
 import { CentralSyncService } from './service/central-sync-service.js';
 import { ensureWorkspaceTemplates } from './core/init.js';
 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';
@@ -59,9 +60,7 @@ import type { WorkerProfile } from './core/model-deployment-registry.js';
 import { validateWorkspaceDir } from './core/workspace-dir-validation.js';
 import { resolveWorkspaceDirFromApi } from './core/path-resolver.js';
 
-// Track initialization to avoid repeated calls
-let workspaceInitialized = false;
-// Track started evolution workers — one per workspace
+// Track started workspaces — one-time init + evolution worker per workspace
 const startedWorkspaces = new Set<string>();
 
 const HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION =
@@ -113,19 +112,16 @@ const plugin = {
           return;
         }
         try {
-          if (!workspaceInitialized) {
+          if (!startedWorkspaces.has(workspaceDir)) {
+            startedWorkspaces.add(workspaceDir);
             migrateDirectoryStructure(api, workspaceDir);
+            migrateStaleWorkspaceGuidance(api, workspaceDir);
             ensureWorkspaceTemplates(api, workspaceDir, language);
             SystemLogger.log(workspaceDir, 'SYSTEM_BOOT', `Principles Disciple online. Language: ${language}`);
-            workspaceInitialized = true;
-          }
 
-          // ── Start EvolutionWorker for THIS workspace ──
-          // Each agent has its own heartbeat task. When before_prompt_build fires,
-          // it fires for the current agent's workspaceDir. Start one EvolutionWorker
-          // per workspace so each agent's pain signals are processed independently.
-          if (!startedWorkspaces.has(workspaceDir)) {
-            startedWorkspaces.add(workspaceDir);
+            // ── Start EvolutionWorker for THIS workspace ──
+            // One EvolutionWorker per workspace so each agent's pain signals
+            // are processed independently.
             EvolutionWorkerService.api = api;
             EvolutionWorkerService.start({
               config: api.config,

package/templates/langs/en/core/BOOTSTRAP.md

@@ -183,7 +183,7 @@ openclaw cron add --name "pd-grooming-daily" \
 openclaw cron add --name "health-check" \
   --every 4h \
   --session main \
-  --system-event 'Health check: Verify core tools (rg, node, python) are available. Check if PLAN.md state matches actual progress.'
+  --system-event 'Health check: Verify core tools (rg, node, python) are available. Check if workspace state matches actual progress.'
 ```
 
 ### 3. Strategy Alignment (Daily at 9 AM)

package/templates/langs/en/principles/THINKING_OS.md

@@ -19,7 +19,7 @@ LLMs are highly sensitive to XML tags; this structure is designed to boost instr
 
   <directive id="T-02" name="PHYSICAL_MEMORY_PERSISTENCE">
     <trigger>When reasoning across multiple files, facing complex debugging, or when the conversation context grows long (>5 turns).</trigger>
-    <must>TRUST FILES, NOT YOUR CONTEXT WINDOW. You MUST actively write your intermediate conclusions, breakpoints, and next steps to `memory/.scratchpad.md` or `PLAN.md`.</must>
+    <must>TRUST FILES, NOT YOUR CONTEXT WINDOW. You MUST actively write your intermediate conclusions, breakpoints, and next steps to `memory/.scratchpad.md`.</must>
     <forbidden>Relying on your internal "brain memory" to hold complex state, which will inevitably be wiped by context compression.</forbidden>
   </directive>
 

package/templates/langs/en/skills/admin/SKILL.md

@@ -15,7 +15,7 @@ You are now the "Evolutionary System Administrator". Your responsibility is to m
 ### 1. `diagnose` (System Diagnosis)
 **Action**: Check the integrity of the "bare-bones" architecture.
 - **Core Components**: Check if `.claude/hooks/hook_runner.py` exists and is executable.
-- **Documentation Integrity**: Check if `.principles/PROFILE.json`, `PLAN.md` etc. exist.
+- **Documentation Integrity**: Check if `.principles/PROFILE.json` etc. exist.
 - **Tool Awareness**: Check `.state/SYSTEM_CAPABILITIES.json`. If missing, prompt user: "⚠️ Toolchain upgrade not performed. Recommend running `/bootstrap-tools` to significantly enhance system capabilities."
 - **Memory Mount**: Check if `CLAUDE.md` contains `System Integration` section.
 - **Output**: Generate a health report listing missing or abnormal items.
@@ -23,7 +23,7 @@ You are now the "Evolutionary System Administrator". Your responsibility is to m
 ### 2. `repair` (System Repair)
 **Action**: 
 - **Config Recovery**: If `PROFILE.json` is missing or corrupted, attempt recovery from `.claude/templates/PROFILE.json`.
-- **Structure Completion**: Ensure `PLAN.md` contains `## Target Files` heading.
+- **Structure Completion**: Ensure workspace structure is complete.
 - **Forced Cleanup**: Delete `.pain_flag`, `.verdict.json`, `.user_verdict.json`, `.pending_reflection` and other temporary markers.
 
 ### 3. `reset` (Force Reset)

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

@@ -24,7 +24,7 @@ When performing cleanup operations, you MUST strictly adhere to the following wh
 ### 🌟 Core Assets
 **These files must remain in the root directory. Do not touch:**
 - `AGENTS.md`, `SOUL.md`, `HEARTBEAT.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `MEMORY.md`
-- `README.md`, `PLAN.md`
+- `README.md`
 - `.principles/`, `.state/`
 
 ### 🎯 Targets for Grooming

package/templates/langs/en/skills/reflection/SKILL.md

@@ -12,7 +12,7 @@ disable-model-invocation: false
 Please execute the following reflection steps:
 
 ## 1. Status Scan
-- **Goal**: What was our original objective? (Check `PLAN.md` or early conversation)
+- **Goal**: What was our original objective? (Check early conversation context)
 - **Status**: How much is completed now? Where are we stuck?
 - **Cost**: We've consumed significant tokens. Is the output matching the cost?
 
@@ -37,4 +37,4 @@ If pain detected, must execute:
 
 ## 5. Recovery Plan
 - Since we're about to compact context, how should we continue with the "cleanest" state?
-- Update `PLAN.md`, mark current progress, ensure seamless continuation after compaction.
+- Update `memory/.scratchpad.md`, mark current progress, ensure seamless continuation after compaction.

package/templates/langs/en/skills/report/SKILL.md

@@ -10,4 +10,4 @@ User (the boss) requests an immediate work report.
 
 ## Execution Action
 1. Immediately delegate ``pd_spawn_agent(reporter)``.
-2. Task description: "The boss wants to know the current situation. Please analyze current conversation context, `PLAN.md`, and recent `memory/ISSUE_LOG.md` to write an elegant report for the boss. Remember to check their profile first!"
+2. Task description: "The boss wants to know the current situation. Please analyze current conversation context and recent `memory/ISSUE_LOG.md` to write an elegant report for the boss. Remember to check their profile first!"

package/templates/langs/zh/core/BOOTSTRAP.md

@@ -183,7 +183,7 @@ openclaw cron add --name "pd-grooming-daily" \
 openclaw cron add --name "health-check" \
   --every 4h \
   --session main \
-  --system-event '环境健康检查：验证核心工具（rg, node, python）是否可用，检查 PLAN.md 状态与实际进度是否一致。'
+  --system-event '环境健康检查：验证核心工具（rg, node, python）是否可用，检查工作区状态与实际进度是否一致。'
 ```
 
 ### 3. 战略对齐检查（每天上午 9 点）

package/templates/langs/zh/principles/THINKING_OS.md

@@ -19,7 +19,7 @@
 
   <directive id="T-02" name="PHYSICAL_MEMORY_PERSISTENCE">
     <trigger>在跨越多个文件进行推理、面临复杂的 Debug、或当对话上下文变得很长（>5 轮）时。</trigger>
-    <must>信任文件，而不是你的上下文窗口。你必须主动将中间结论、断点和后续步骤写入 `memory/.scratchpad.md` 或 `PLAN.md`。</must>
+    <must>信任文件，而不是你的上下文窗口。你必须主动将中间结论、断点和后续步骤写入 `memory/.scratchpad.md`。</must>
     <forbidden>依赖你内部的“大脑记忆”来保持复杂状态，这些状态必然会被上下文压缩机制抹除。</forbidden>
   </directive>
 

package/templates/langs/zh/skills/admin/SKILL.md

@@ -15,7 +15,7 @@ disable-model-invocation: true
 ### 1. `diagnose` (系统诊断)
 **动作**: 检查“毛坯房”架构的完整性。
 - **核心组件**: 检查 `.claude/hooks/hook_runner.py` 是否存在且可执行。
-- **文档完整性**: 检查 `.principles/PROFILE.json`, `PLAN.md` 等是否存在。
+- **文档完整性**: 检查 `.principles/PROFILE.json` 等是否存在。
 - **工具感知**: 检查 `.state/SYSTEM_CAPABILITIES.json`。若缺失，提示用户："⚠️ 尚未进行工具链升级。建议运行 `/bootstrap-tools` 以大幅提升系统能力。"
 - **记忆挂载**: 检查 `CLAUDE.md` 是否包含 `System Integration` 章节。
 - **输出**: 生成一份健康报告，列出缺失或异常的项目。
@@ -23,7 +23,7 @@ disable-model-invocation: true
 ### 2. `repair` (系统修复)
 **动作**: 
 - **配置恢复**: 如果 `PROFILE.json` 缺失或损坏，尝试从 `.claude/templates/PROFILE.json` 恢复。
-- **结构补全**: 确保 `PLAN.md` 包含 `## Target Files` 标题。
+- **结构补全**: 确保工作区结构完整。
 - **强制清理**: 删除 `.pain_flag`, `.verdict.json`, `.user_verdict.json`, `.pending_reflection` 等临时标记。
 
 ### 3. `reset` (强制重置)

package/templates/langs/zh/skills/pd-grooming/SKILL.md

@@ -24,7 +24,7 @@ description: 执行工作区"大扫除"，将散落的临时文件归档或清
 ### 🌟 核心资产区 (Core Assets)
 **这些文件必须留在根目录，不可触碰：**
 - `AGENTS.md`, `SOUL.md`, `HEARTBEAT.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `MEMORY.md`
-- `README.md`, `PLAN.md`
+- `README.md`
 - `.principles/`, `.state/`
 
 ### 🎯 可处理区 (Targets for Grooming)

package/templates/langs/zh/skills/reflection/SKILL.md

@@ -12,7 +12,7 @@ disable-model-invocation: false
 请执行以下反思步骤：
 
 ## 1. 现状扫描 (Status Scan)
-- **Goal**: 我们最初的目标是什么？(Check `PLAN.md` or early conversation)
+- **Goal**: 我们最初的目标是什么？(检查早期对话上下文)
 - **Status**: 现在完成了多少？卡在哪里？
 - **Cost**: 我们消耗了大量 Token，产出是否匹配？
 
@@ -37,4 +37,4 @@ disable-model-invocation: false
 
 ## 5. 恢复计划 (Recovery)
 - 既然要压缩上下文，我们下一步该如何以“最干净”的状态继续？
-- 更新 `PLAN.md`，标记当前进度，确保压缩后能无缝衔接。
+- 更新 `memory/.scratchpad.md`，标记当前进度，确保压缩后能无缝衔接。

package/templates/langs/zh/skills/report/SKILL.md

@@ -10,4 +10,4 @@ disable-model-invocation: true
 
 ## 执行动作
 1. 立即委派 ``pd_spawn_agent(reporter)``。
-2. 任务描述：“老板想知道当前的情况。请分析当前的对话上下文、`PLAN.md` 和最近的 `memory/ISSUE_LOG.md`，为老板写一份优雅的汇报。请记住先看他的画像！”
+2. 任务描述：“老板想知道当前的情况。请分析当前的对话上下文和最近的 `memory/ISSUE_LOG.md`，为老板写一份优雅的汇报。请记住先看他的画像！”

package/tests/core-anti-growth.test.ts

@@ -122,6 +122,7 @@ describe('PRI-212 plugin core anti-growth guard', () => {
     'evolution-logger.ts',
     'evolution-engine.ts',
     'runtime-v2-prompt-activation-reader.ts',
+    'workspace-guidance-migrator.ts',
   ] as const;
 
   // Category 6: Test files

package/templates/workspace/PLAN.md

@@ -1,2 +0,0 @@
-STATUS: DRAFT
-Steps...