principles-disciple 1.60.0 → 1.61.0

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "principles-disciple",
   "name": "Principles Disciple",
   "description": "Evolutionary programming agent framework with strategic guardrails and reflection loops.",
-  "version": "1.60.0",
+  "version": "1.61.0",
   "skills": [
     "./skills"
   ],

package/package.json

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

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

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

package/src/core/event-log.ts

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

package/src/service/evolution-worker.ts

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

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

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

package/src/types/event-types.ts

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

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

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