principles-disciple 1.52.0 → 1.54.0

package/.planning/phases/01-basic-visualization/01-GAP-CLOSURE-VERIFICATION.md

@@ -0,0 +1,113 @@
+---
+phase: "01-basic-visualization"
+plan: "01-GAP-CLOSURE"
+verified: 2026-04-17T15:30:00Z
+status: passed
+score: "4/4 must-haves verified"
+overrides_applied: 0
+re_verification: false
+gaps: []
+deferred: []
+human_verification: []
+requirement_mismatch:
+  note: "Requirement IDs provided (SDK-CORE-03, SDK-ADP-07, SDK-ADP-08, SDK-TEST-02, SDK-TEST-03, SDK-MGMT-01, SDK-MGMT-02) are SDK Core Implementation Phase 1 requirements per REQUIREMENTS.md. This phase (01-basic-visualization) addresses VIZ-04 (Empty state optimization) - a different domain. Requirement coverage cannot be established for IDs that do not belong to this phase."
+---
+
+# Phase 01-basic-visualization: GAP-CLOSURE Verification Report
+
+**Phase Goal:** Close verification gaps from Phase 01 by implementing missing i18n fixes for LineChart component and coverage trend empty state.
+**Verified:** 2026-04-17T15:30:00Z
+**Status:** passed
+**Re-verification:** No — initial verification
+
+## Goal Achievement
+
+### Observable Truths
+
+| #   | Truth | Status | Evidence |
+| --- | ----- | ------ | -------- |
+| 1   | LineChart interface has emptyText prop for i18n | VERIFIED | `emptyText?: string;` at line 864 in charts.tsx |
+| 2   | LineChart renders emptyText prop instead of hardcoded '暂无数据' | VERIFIED | Conditional render at lines 878-885: `if (!emptyText) return null;` then `{emptyText}` |
+| 3   | Coverage trend section shows EmptyState when no data | VERIFIED | Ternary at line 259: `data.coverageTrend.length >= 1 ? (...) : (<EmptyState ...>)` |
+| 4   | All LineChart usages pass emptyText prop | VERIFIED | Lines 272, 454, 521 all have `emptyText={t('common.noData')}` |
+
+**Score:** 4/4 truths verified
+
+### Deferred Items
+
+None
+
+### Required Artifacts
+
+| Artifact | Expected | Status | Details |
+| -------- | -------- | ------ | ------- |
+| `charts.tsx:864` | `emptyText?: string` in LineChartProps | VERIFIED | Prop exists at correct line |
+| `charts.tsx:876` | Default value `emptyText = ''` | VERIFIED | Default empty string assigned |
+| `charts.tsx:878-885` | Conditional render using emptyText | VERIFIED | Returns null if no emptyText, renders div with {emptyText} otherwise |
+| `ThinkingModelsPage.tsx:259` | Ternary operator for coverage trend | VERIFIED | `data.coverageTrend.length >= 1 ? (...) : (<EmptyState ...>)` |
+| `ThinkingModelsPage.tsx:272` | LineChart with emptyText prop | VERIFIED | `emptyText={t('common.noData')}` |
+| `ThinkingModelsPage.tsx:454` | LineChart with emptyText prop | VERIFIED | `emptyText={t('common.noData')}` |
+| `ThinkingModelsPage.tsx:521` | LineChart with emptyText prop | VERIFIED | `emptyText={t('common.noData')}` |
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+| ---- | --- | --- | ------ | ------- |
+| LineChart | i18n system | emptyText prop | WIRED | emptyText prop accepts i18n string and renders it |
+| Coverage trend | EmptyState | ternary operator | WIRED | Ternary correctly switches between LineChart and EmptyState |
+| ThinkingModelsPage | common.noData | t() function | WIRED | All LineChart usages pass i18n key |
+| EmptyState | i18n keys | t() function | WIRED | `t('thinkingModels.emptyCoverageTrend')` and `t('thinkingModels.emptyCoverageTrendDesc')` used |
+
+### Data-Flow Trace (Level 4)
+
+| Artifact | Data Variable | Source | Produces Real Data | Status |
+| -------- | ------------- | ------ | ------------------ | ------ |
+| LineChart emptyText | emptyText prop | Parent component via t('common.noData') | N/A | STATIC — i18n key is static, not dynamic |
+
+### Behavioral Spot-Checks
+
+| Behavior | Command | Result | Status |
+| -------- | ------- | ------ | ------ |
+| emptyText in interface | `grep -n "emptyText?: string" charts.tsx` | `864:  emptyText?: string;` | PASS |
+| No hardcoded Chinese | `grep -n "暂无数据" charts.tsx` | No matches | PASS |
+| Ternary for coverage | `grep -n "coverageTrend.length.*?" ThinkingModelsPage.tsx` | `259: {data.coverageTrend.length >= 1 ?` | PASS |
+| EmptyState for coverage | `grep -n "EmptyState" ThinkingModelsPage.tsx \| head -3` | Lines 276-279 with i18n keys | PASS |
+| All LineChart have emptyText | `grep -B5 -A10 "<LineChart" ThinkingModelsPage.tsx \| grep -c "emptyText"` | 3 | PASS |
+
+### Requirements Coverage
+
+**IMPORTANT - Requirement Mismatch Found:**
+
+| Requirement | Source | Description | Status | Evidence |
+| ----------- | ------ | ----------- | ------ | -------- |
+| SDK-CORE-03 | User-provided | Implement universal PainSignal interface logic | N/A | Does not belong to 01-basic-visualization phase |
+| SDK-ADP-07 | User-provided | Implement Coding domain adapter | N/A | Does not belong to 01-basic-visualization phase |
+| SDK-ADP-08 | User-provided | Implement second domain adapter | N/A | Does not belong to 01-basic-visualization phase |
+| SDK-TEST-02 | User-provided | Implement full Adapter conformance test suite | N/A | Does not belong to 01-basic-visualization phase |
+| SDK-TEST-03 | User-provided | Execute and publish performance benchmarks | N/A | Does not belong to 01-basic-visualization phase |
+| SDK-MGMT-01 | User-provided | Package SDK as @principles/core npm package | N/A | Does not belong to 01-basic-visualization phase |
+| SDK-MGMT-02 | User-provided | Establish Semver versioning and migration guides | N/A | Does not belong to 01-basic-visualization phase |
+| VIZ-04 | GAP-CLOSURE-PLAN | Empty state optimization | VERIFIED | All 4 must_haves from GAP-CLOSURE-PLAN verified |
+
+**The 7 requirement IDs provided are SDK Core Implementation Phase 1 requirements per REQUIREMENTS.md. They do not map to the 01-basic-visualization phase. The phase's actual scope is VIZ-04 (Empty state optimization), which has been verified through must_haves.**
+
+### Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+| ---- | ---- | ------- | -------- | ------ |
+| None | - | No anti-patterns detected | - | - |
+
+### Human Verification Required
+
+None required — all truths verifiable via static analysis.
+
+### Gaps Summary
+
+**None.** All 4 must_haves verified. Phase goal achieved.
+
+**Notable finding:** The requirement IDs provided by user (SDK-CORE-03, SDK-ADP-07, SDK-ADP-08, SDK-TEST-02, SDK-TEST-03, SDK-MGMT-01, SDK-MGMT-02) are SDK Core Implementation Phase 1 requirements per REQUIREMENTS.md. This phase (01-basic-visualization) addresses VIZ-04 (Empty state optimization for visualization) - a different scope. Requirement coverage cannot be established for IDs that do not belong to this phase.
+
+---
+
+_Verified: 2026-04-17T15:30:00Z_
+_Verifier: Claude (gsd-verifier)_

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.52.0",
+  "version": "1.54.0",
   "skills": [
     "./skills"
   ],

package/package.json

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

package/src/core/bootstrap-rules.ts

@@ -13,8 +13,10 @@
  *   npm run bootstrap-rules                               (production)
  */
 
-import { loadLedger, createRule, updatePrinciple } from './principle-tree-ledger.js';
+import { loadLedger, createRule, updatePrinciple, addPrincipleToLedger } from './principle-tree-ledger.js';
+import type { LedgerPrinciple } from './principle-tree-ledger.js';
 import { loadStore } from './principle-training-state.js';
+import { CORE_THINKING_MODELS } from './init.js';
 
 export interface BootstrapResult {
   principleId: string;
@@ -77,12 +79,49 @@ export function selectPrinciplesForBootstrap(stateDir: string, limit = 3): strin
  * @throws Error if no deterministic principles found
  */
 export function bootstrapRules(stateDir: string, limit = 3): BootstrapResult[] {
+  // Migration: if T-01..T-10 exist in Training Store but not in Ledger Tree, backfill.
+  // This handles workspaces initialized before Ledger Tree was added.
+  const store = loadStore(stateDir);
+  let ledger = loadLedger(stateDir);
+  const hasTrainingT = Object.keys(store).some((id) => id.startsWith('T-'));
+  const hasAnyLedgerT = Object.keys(ledger.tree.principles).some((id) => id.startsWith('T-'));
+  if (hasTrainingT && !hasAnyLedgerT) {
+    console.warn('[bootstrap] Migrating T-01..T-10 from Training Store to Ledger Tree');
+    const now = new Date().toISOString();
+    for (const [id, entry] of Object.entries(store)) {
+      if (!id.startsWith('T-')) continue;
+      const model = CORE_THINKING_MODELS.find((m) => m.id === id);
+      if (!model) continue;
+      const lp: LedgerPrinciple = {
+        id,
+        version: 1,
+        text: model.description,
+        coreAxiomId: id,
+        triggerPattern: '',
+        action: '',
+        status: 'active',
+        priority: 'P1',
+        scope: 'general',
+        evaluability: entry.evaluability,
+        valueScore: 0,
+        adherenceRate: 0,
+        painPreventedCount: 0,
+        derivedFromPainIds: [],
+        ruleIds: [],
+        conflictsWithPrincipleIds: [],
+        createdAt: now,
+        updatedAt: now,
+        suggestedRules: [],
+      };
+      addPrincipleToLedger(stateDir, lp);
+    }
+    // Reload ledger after migration so subsequent reads see the new data.
+    ledger = loadLedger(stateDir);
+  }
+
   // Select principles for bootstrap
   const selectedPrincipleIds = selectPrinciplesForBootstrap(stateDir, limit);
 
-  // Load current ledger state
-  const ledger = loadLedger(stateDir);
-
   const results: BootstrapResult[] = [];
 
   for (const principleId of selectedPrincipleIds) {

package/src/core/evolution-hook.ts

@@ -0,0 +1,74 @@
+/**
+ * EvolutionHook interface for the Evolution SDK.
+ *
+ * Provides a callback-based interface for observing evolution lifecycle
+ * events: pain detection, principle creation, and principle promotion.
+ *
+ * Per D-03, this interface contains only the 3 core event methods.
+ * Per D-04, consumers implement the interface directly (no EventEmitter).
+ * Hooks not needed can use the provided noOpEvolutionHook and override
+ * individual methods.
+ */
+import type { PainSignal } from './pain-signal.js';
+
+// ---------------------------------------------------------------------------
+// Event Types
+// ---------------------------------------------------------------------------
+
+/** Event payload for principle creation lifecycle events. */
+export interface PrincipleCreatedEvent {
+  /** Unique principle identifier */
+  id: string;
+  /** Principle text ("When X, then Y.") */
+  text: string;
+  /** What triggered this principle's creation */
+  trigger: string;
+}
+
+/** Event payload for principle promotion lifecycle events. */
+export interface PrinciplePromotedEvent {
+  /** Unique principle identifier */
+  id: string;
+  /** Previous status tier */
+  from: string;
+  /** New status tier */
+  to: string;
+}
+
+// ---------------------------------------------------------------------------
+// EvolutionHook Interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Callback interface for observing evolution lifecycle events.
+ *
+ * Implement all 3 methods, or spread noOpEvolutionHook and override
+ * only the methods you need:
+ *
+ * @example
+ * ```ts
+ * const myHook: EvolutionHook = {
+ *   ...noOpEvolutionHook,
+ *   onPainDetected(signal) { console.log(signal); },
+ * };
+ * ```
+ */
+export interface EvolutionHook {
+  /** Called when a pain signal is detected and recorded. */
+  onPainDetected(signal: PainSignal): void;
+  /** Called when a new principle candidate is created. */
+  onPrincipleCreated(event: PrincipleCreatedEvent): void;
+  /** Called when a principle is promoted to a higher tier. */
+  onPrinciplePromoted(event: PrinciplePromotedEvent): void;
+}
+
+// ---------------------------------------------------------------------------
+// No-op Helper
+// ---------------------------------------------------------------------------
+
+/** No-op implementation -- consumers can spread and override individual methods. */
+export const noOpEvolutionHook: EvolutionHook = {
+  onPainDetected(_signal: PainSignal): void {},
+  onPrincipleCreated(_event: PrincipleCreatedEvent): void {},
+  onPrinciplePromoted(_event: PrinciplePromotedEvent): void {},
+};

package/src/core/file-storage-adapter.ts

@@ -0,0 +1,203 @@
+/**
+ * FileStorageAdapter — file-backed implementation of StorageAdapter.
+ *
+ * Wraps principle-tree-ledger functions with the async StorageAdapter
+ * contract. Uses withLockAsync for thread-safe mutateLedger with
+ * retry with exponential backoff for lock acquisition (5 retries).
+ * Write failures are logged via SystemLogger and re-thrown.
+ *
+ * Guarantees:
+ * - Atomic writes via atomicWriteFileSync (temp + rename)
+ * - Thread-safe concurrent access via file locks
+ * - Consistent read-after-write visibility
+ * - Write failures logged to SystemLogger and re-thrown
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import type { StorageAdapter } from './storage-adapter.js';
+import type { HybridLedgerStore } from './principle-tree-ledger.js';
+import { TREE_NAMESPACE } from './principle-tree-ledger.js';
+import {
+  loadLedger as loadLedgerFromFile,
+  saveLedgerAsync,
+} from './principle-tree-ledger.js';
+import { withLockAsync, type LockOptions, LockAcquisitionError } from '../utils/file-lock.js';
+import { atomicWriteFileSync } from '../utils/io.js';
+import { SystemLogger } from './system-logger.js';
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/** Maximum retries for lock acquisition in mutateLedger. */
+const MUTATE_RETRY_COUNT = 5;
+
+/** Base delay in ms for exponential backoff between retries. */
+const MUTATE_BACKOFF_BASE_MS = 50;
+
+/** Maximum backoff delay in ms. */
+const MUTATE_BACKOFF_MAX_MS = 500;
+
+const PRINCIPLE_TRAINING_FILE = 'principle_training_state.json';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Serialize the hybrid ledger store to JSON.
+ * Mirrors the unexported serializeLedger from principle-tree-ledger.ts.
+ */
+function serializeStore(store: HybridLedgerStore): string {
+  return JSON.stringify(
+    {
+      ...store.trainingStore,
+      [TREE_NAMESPACE]: {
+        ...store.tree,
+        lastUpdated: new Date().toISOString(),
+      },
+    },
+    null,
+    2,
+  );
+}
+
+/** Ensure the parent directory exists before writing. */
+function ensureParentDir(filePath: string): void {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// FileStorageAdapter
+// ---------------------------------------------------------------------------
+
+/**
+ * File-system backed storage adapter for the principle ledger.
+ *
+ * Delegates read/write operations to principle-tree-ledger while providing
+ * the async StorageAdapter interface. The mutateLedger method uses
+ * withLockAsync with exponential backoff retry for robust concurrent access.
+ */
+export class FileStorageAdapter implements StorageAdapter {
+  private readonly stateDir: string;
+  private readonly workspaceDir: string | undefined;
+
+  constructor(stateDir: string, workspaceDir?: string) {
+    this.stateDir = stateDir;
+    this.workspaceDir = workspaceDir;
+  }
+
+  /** Resolve the ledger file path for this state directory. */
+  private get filePath(): string {
+    return path.join(this.stateDir, PRINCIPLE_TRAINING_FILE);
+  }
+
+  /**
+   * Load the current ledger state from the file system.
+   *
+   * Returns an empty store if no persisted state exists (first run).
+   * Uses the synchronous loadLedger from principle-tree-ledger which
+   * handles missing/corrupted files gracefully.
+   */
+  async loadLedger(): Promise<HybridLedgerStore> {
+    return loadLedgerFromFile(this.stateDir);
+  }
+
+  /**
+   * Persist the full ledger state atomically.
+   *
+   * Delegates to principle-tree-ledger's saveLedgerAsync which uses
+   * withLockAsync internally. Logs failures via SystemLogger.
+   */
+  async saveLedger(store: HybridLedgerStore): Promise<void> {
+    try {
+      await saveLedgerAsync(this.stateDir, store);
+    } catch (err) {
+      SystemLogger.log(
+        this.workspaceDir,
+        'STORAGE_WRITE_FAILED',
+        `FileStorageAdapter.saveLedger failed: ${String(err)}`,
+      );
+      throw err;
+    }
+  }
+
+  /**
+   * Perform a read-modify-write cycle with automatic locking and retry.
+   *
+   * Uses withLockAsync to acquire a file lock, reads the current store,
+   * applies the mutate function, then writes the modified store atomically.
+   * On lock acquisition failure, retries up to MUTATE_RETRY_COUNT (5) times
+   * with exponential backoff + jitter to reduce contention.
+   *
+   * Write failures are logged to SystemLogger and re-thrown so callers
+   * can decide how to handle persistence errors.
+   */
+  async mutateLedger<T>(mutate: (store: HybridLedgerStore) => T | Promise<T>): Promise<T> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt < MUTATE_RETRY_COUNT; attempt++) {
+      try {
+        const lockOptions: LockOptions = {
+          maxRetries: 3,
+          baseRetryDelayMs: 10,
+          maxRetryDelayMs: 200,
+          lockStaleMs: 10_000,
+        };
+
+        const ledgerPath = this.filePath;
+
+        return await withLockAsync(ledgerPath, async () => {
+          const store = loadLedgerFromFile(this.stateDir);
+          const result = await mutate(store);
+
+          // Write directly — we already hold the lock, so we must NOT
+          // call saveLedger/saveLedgerAsync (they try to acquire the same lock).
+          try {
+            ensureParentDir(ledgerPath);
+            atomicWriteFileSync(ledgerPath, serializeStore(store));
+          } catch (writeErr) {
+            SystemLogger.log(
+              this.workspaceDir,
+              'STORAGE_WRITE_FAILED',
+              `FileStorageAdapter.mutateLedger write failed: ${String(writeErr)}`,
+            );
+            throw writeErr;
+          }
+
+          return result;
+        }, lockOptions);
+      } catch (err) {
+        lastError = err as Error;
+
+        // Only retry on lock acquisition errors
+        if (err instanceof LockAcquisitionError && attempt < MUTATE_RETRY_COUNT - 1) {
+          const delay = Math.min(
+            MUTATE_BACKOFF_BASE_MS * Math.pow(2, attempt),
+            MUTATE_BACKOFF_MAX_MS,
+          );
+          // Add jitter (0-20%) to avoid thundering herd
+          const jitter = delay * 0.2 * Math.random();
+          const totalDelay = Math.floor(delay + jitter);
+
+          await new Promise((resolve) => setTimeout(resolve, totalDelay));
+          continue;
+        }
+
+        // Non-retryable error or exhausted retries
+        SystemLogger.log(
+          this.workspaceDir,
+          'STORAGE_MUTATE_FAILED',
+          `FileStorageAdapter.mutateLedger failed after ${attempt + 1} attempts: ${String(err)}`,
+        );
+        throw err;
+      }
+    }
+
+    // Should not reach here, but satisfy the type checker
+    throw lastError ?? new Error('FileStorageAdapter.mutateLedger: unexpected state');
+  }
+}

package/src/core/init.ts

@@ -5,6 +5,8 @@ import type { OpenClawPluginApi, PluginLogger } from '../openclaw-sdk.js';
 import { PD_DIRS } from './paths.js';
 import { defaultContextConfig } from '../types.js';
 import { loadStore, setPrincipleState, type PrincipleTrainingState } from './principle-training-state.js';
+import { addPrincipleToLedger } from './principle-tree-ledger.js';
+import type { LedgerPrinciple } from './principle-tree-ledger.js';
 import { atomicWriteFileSync } from '../utils/io.js';
 import { createDefaultKeywordStore, saveKeywordStore } from './empathy-keyword-matcher.js';
 
@@ -150,7 +152,7 @@ function copyRecursiveSync(srcDir: string, destDir: string, api: OpenClawPluginA
  * Core thinking model definitions (T-01 through T-10).
  * These are the built-in cognitive patterns that every workspace should have.
  */
-const CORE_THINKING_MODELS: Array<{
+export const CORE_THINKING_MODELS: Array<{
   id: string;
   name: string;
   description: string;
@@ -190,7 +192,7 @@ export function ensureCorePrinciples(stateDir: string, logger: PluginLogger): bo
     for (const model of CORE_THINKING_MODELS) {
       const state: PrincipleTrainingState = {
         principleId: model.id,
-        evaluability: 'deterministic',
+        evaluability: 'manual_only',
         applicableOpportunityCount: 0,
         observedViolationCount: 0,
         complianceRate: 0,
@@ -202,6 +204,31 @@ export function ensureCorePrinciples(stateDir: string, logger: PluginLogger): bo
         internalizationStatus: 'needs_training',
       };
       setPrincipleState(stateDir, state);
+
+      // Also write to Ledger Tree so bootstrapRules() can find them
+      const now = new Date().toISOString();
+      const ledgerPrinciple: LedgerPrinciple = {
+        id: model.id,
+        version: 1,
+        text: model.description,
+        coreAxiomId: model.id,
+        triggerPattern: '',
+        action: '',
+        status: 'active',
+        priority: 'P1',
+        scope: 'general',
+        evaluability: 'manual_only',
+        valueScore: 0,
+        adherenceRate: 0,
+        painPreventedCount: 0,
+        derivedFromPainIds: [],
+        ruleIds: [],
+        conflictsWithPrincipleIds: [],
+        createdAt: now,
+        updatedAt: now,
+        suggestedRules: [],
+      };
+      addPrincipleToLedger(stateDir, ledgerPrinciple);
     }
 
     logger.info(`[PD] Initialized ${CORE_THINKING_MODELS.length} core thinking models: T-01 through T-10`);