principles-disciple 1.40.0 → 1.42.0

package/.planning/codebase/STRUCTURE.md

@@ -0,0 +1,193 @@
+# Codebase Structure
+
+**Analysis Date:** 2026-04-15
+
+## Directory Layout
+
+```
+openclaw-plugin/
+├── src/                    # Main source code
+│   ├── commands/           # Slash command implementations
+│   ├── config/            # Configuration defaults and errors
+│   ├── constants/          # Shared constants
+│   ├── core/               # Core business logic
+│   │   ├── hygiene/        # Hygiene tracking
+│   │   ├── principle-internalization/  # Principle lifecycle
+│   │   └── schema/         # Database schema and migrations
+│   ├── hooks/              # OpenClaw hook handlers
+│   ├── http/               # HTTP route handlers
+│   ├── i18n/               # Internationalization
+│   ├── service/            # Background services
+│   │   └── subagent-workflow/  # Workflow managers
+│   ├── tools/              # Plugin tools
+│   ├── types/              # TypeScript type definitions
+│   └── utils/              # Utility functions
+├── ui/                     # React UI
+│   └── src/
+│       ├── components/     # React components
+│       ├── context/        # React contexts
+│       ├── hooks/          # React hooks
+│       └── pages/          # Page components
+├── tests/                  # Test suite
+│   ├── commands/           # Command tests
+│   ├── core/               # Core module tests
+│   ├── fixtures/           # Test fixtures
+│   ├── hooks/              # Hook tests
+│   ├── integration/        # Integration tests
+│   ├── service/            # Service tests
+│   └── utils/              # Utility tests
+├── templates/               # Workspace templates
+│   ├── langs/              # Language-specific templates
+│   └── workspace/           # Workspace structure templates
+├── dist/                   # Build output
+├── scripts/                # Build scripts
+├── .state/                 # Runtime state (gitignored)
+└── .tmp/                   # Temporary files (gitignored)
+```
+
+## Directory Purposes
+
+**src/commands/:**
+- Purpose: Slash command implementations
+- Contains: 20+ command handlers (strategy, focus, pain, rollback, nocturnal-review, nocturnal-train, etc.)
+- Key files: `strategy.ts`, `focus.ts`, `nocturnal-train.ts`, `nocturnal-rollout.ts`
+
+**src/core/:**
+- Purpose: Core business logic (evolution, trajectory, pain, training, rules)
+- Contains: 70+ core modules including `evolution-engine.ts`, `trajectory.ts`, `nocturnal-trinity.ts`, `pain.ts`, `principle-tree-ledger.ts`
+- Key files: `evolution-engine.ts`, `nocturnal-trinity.ts`, `rule-host.ts`
+
+**src/hooks/:**
+- Purpose: OpenClaw hook handlers for intercepting agent behavior
+- Contains: `prompt.ts`, `gate.ts`, `pain.ts`, `llm.ts`, `lifecycle.ts`, `subagent.ts`, `trajectory-collector.ts`
+- Key files: `gate.ts` (security), `prompt.ts` (context injection)
+
+**src/service/:**
+- Purpose: Background worker services
+- Contains: `evolution-worker.ts` (main worker), `nocturnal-service.ts`, `trajectory-service.ts`, `central-database.ts`
+- Key files: `evolution-worker.ts` (144KB, main async processor)
+
+**src/service/subagent-workflow/:**
+- Purpose: Workflow orchestration for complex subagent operations
+- Contains: `nocturnal-workflow-manager.ts`, `deep-reflect-workflow-manager.ts`, `empathy-observer-workflow-manager.ts`
+- Key files: `workflow-manager-base.ts`, `dynamic-timeout.ts`
+
+**src/utils/:**
+- Purpose: Shared utility functions
+- Contains: `io.ts` (atomic writes), `plugin-logger.ts`, `retry.ts`, `hashing.ts`, `file-lock.ts`
+- Key files: `io.ts` (critical for safe file operations)
+
+**src/schema/:**
+- Purpose: SQLite database schema and migrations
+- Contains: `schema-definitions.ts`, `migration-runner.ts`, `migrations/*.ts`
+- Migrations: 4 migrations (001-004)
+
+**ui/src/:**
+- Purpose: React-based plugin UI
+- Contains: Pages (Overview, Evolution, Feedback, GateMonitor), components (Shell, ProtectedRoute)
+- Key files: `App.tsx`, `pages/EvolutionPage.tsx`, `pages/FeedbackPage.tsx`
+
+## Key File Locations
+
+**Entry Points:**
+- `src/index.ts`: Plugin entry point, registers all hooks/commands/tools
+
+**Configuration:**
+- `src/core/config.ts`: PainSettings defaults
+- `src/core/paths.ts`: Directory and file path constants (PD_DIRS, PD_FILES)
+- `openclaw.plugin.json`: Plugin manifest
+
+**Core Logic:**
+- `src/core/evolution-engine.ts`: Evolution processing (18KB)
+- `src/core/nocturnal-trinity.ts`: Nocturnal training orchestration (87KB - largest file)
+- `src/core/trajectory.ts`: Trajectory tracking (64KB)
+- `src/core/principle-tree-ledger.ts`: Principle lifecycle management (22KB)
+- `src/core/rule-host.ts`: Sandboxed rule execution (7KB)
+
+**Service Layer:**
+- `src/service/evolution-worker.ts`: Background evolution worker (144KB - largest file)
+- `src/service/nocturnal-service.ts`: Nocturnal training service (59KB)
+- `src/service/nocturnal-runtime.ts`: Runtime for nocturnal operations (24KB)
+
+**Testing:**
+- `tests/`: Test suite with unit and integration layers
+- `vitest.config.ts`: Test configuration with unit/integration project separation
+
+## Naming Conventions
+
+**Files:**
+- TypeScript: `kebab-case.ts` or `camelCase.ts` depending on module type
+- Commands: `kebab-case.ts` (e.g., `nocturnal-review.ts`)
+- Core modules: `camelCase.ts` (e.g., `evolutionEngine.ts`)
+- React components: `PascalCase.tsx`
+
+**Directories:**
+- kebab-case: `subagent-workflow`, `principle-internalization`
+
+**Types:**
+- Interfaces: `PascalCase` (e.g., `PainSettings`, `EvolutionContext`)
+- Type aliases: `PascalCase`
+- Enums: `PascalCase`
+
+## Where to Add New Code
+
+**New Command:**
+- Primary code: `src/commands/<name>.ts`
+- Handler registration: `src/index.ts` in `registerCommandWithAlias()` or `api.registerCommand()`
+- Tests: `tests/commands/<name>.test.ts`
+
+**New Hook Handler:**
+- Implementation: `src/hooks/<name>.ts`
+- Registration: `src/index.ts` in `api.on('<hook_name>', ...)` call
+- Tests: `tests/hooks/<name>.test.ts`
+
+**New Core Service:**
+- Implementation: `src/core/<name>.ts` or `src/service/<name>.ts`
+- Registration: `src/index.ts` in `api.registerService()`
+- Tests: `tests/core/<name>.test.ts` or `tests/service/<name>.test.ts`
+
+**New Workflow Manager:**
+- Implementation: `src/service/subagent-workflow/<name>-workflow-manager.ts`
+- Base class: `src/service/subagent-workflow/workflow-manager-base.ts`
+- Tests: `tests/service/subagent-workflow/<name>.test.ts`
+
+**New Database Migration:**
+- Implementation: `src/core/schema/migrations/<number>-<description>.ts`
+- Registration: `src/core/schema/migrations/index.ts`
+- Tests: Integration test in `tests/core/control-ui-db.test.ts`
+
+**New Utility:**
+- Shared: `src/utils/<name>.ts`
+- Tests: `tests/utils/<name>.test.ts`
+
+## Special Directories
+
+**.state/:**
+- Purpose: Runtime state (per workspace)
+- Generated: Yes (created at runtime)
+- Committed: No (gitignored)
+
+**.tmp/:**
+- Purpose: Temporary files during build/dev
+- Generated: Yes
+- Committed: No (gitignored)
+
+**dist/:**
+- Purpose: Build output
+- Generated: Yes (by `npm run build`)
+- Committed: Yes (in some branches)
+
+**templates/:**
+- Purpose: Workspace template files copied on init
+- Generated: No
+- Committed: Yes
+- Contains: Language-specific templates (en, zh), workspace structure
+
+**node_modules/:**
+- Purpose: Dependencies
+- Generated: Yes (by pnpm install)
+- Committed: No
+
+---
+
+*Structure analysis: 2026-04-15*

package/.planning/codebase/TESTING.md

@@ -0,0 +1,243 @@
+# Testing Patterns
+
+**Analysis Date:** 2026-04-15
+
+## Test Framework
+
+**Runner:** Vitest 4.1.0
+- Config: `vitest.config.ts`
+- Environment: `node`
+- Pool: `threads` (required for `better-sqlite3` native handle cleanup)
+
+**Assertion Library:** Vitest built-in (`expect`)
+
+**Coverage:** `@vitest/coverage-v8`
+- Thresholds: lines 70%, functions 70%, branches 60%, statements 70%
+- Excludes: `tests/**`
+
+**Run Commands:**
+```bash
+npm test              # Run unit tests (fast, parallel)
+npm run test:unit     # Alias for above
+npm run test:integration  # Run integration tests only
+npm run test:coverage # Run with coverage report
+npm run test:all      # Run all tests (unit + integration)
+```
+
+## Test File Organization
+
+**Location:**
+- Tests co-located in `tests/` directory, mirroring `src/` structure
+- `tests/core/`, `tests/commands/`, `tests/hooks/`, `tests/service/`, `tests/utils/`
+- Integration tests in `tests/integration/`
+
+**Naming:**
+- `*.test.ts` suffix for all test files
+- Example: `tests/core/detection-service.test.ts`
+
+**Structure:**
+```
+tests/
+├── commands/     # Command handlers
+├── core/         # Core services and logic
+├── fixtures/     # Shared fixtures
+├── hooks/        # Hook handlers
+├── integration/  # End-to-end tests
+├── scripts/      # Script tests
+└── service/      # Service layer
+```
+
+## Test Structure
+
+**Suite Organization:**
+```typescript
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+describe('DetectionService', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        // Reset state between tests
+        DetectionService.reset();
+    });
+
+    it('should create a new instance on first get', () => {
+        // Test implementation
+    });
+});
+```
+
+**Patterns:**
+- `beforeEach` for setup, `afterEach` for teardown
+- `vi.clearAllMocks()` between tests (not `vi.resetAllMocks()`)
+- `vi.useFakeTimers()` / `vi.useRealTimers()` for time-sensitive tests
+
+## Mocking
+
+**Framework:** Vitest's `vi.fn()` and `vi.mock()`
+
+**Module Mocking:**
+```typescript
+vi.mock('../../src/core/dictionary-service.js');
+vi.mock('../../src/core/detection-funnel.js');
+
+// Then configure mock implementations
+vi.mocked(DictionaryService.get).mockReturnValue(mockDict as any);
+```
+
+**Built-in Module Mocking:**
+```typescript
+vi.mock('fs');
+vi.mocked(fs.existsSync).mockReturnValue(true);
+vi.mocked(fs.readFileSync).mockImplementation((p) => {
+    if (p.toString() === configPath) return JSON.stringify(mockConfig);
+    return '';
+});
+```
+
+**Mock Reset:**
+- `vi.clearAllMocks()` clears call history but keeps implementations
+- `vi.resetAllMocks()` clears both (use with caution)
+- Reset singleton state: `DetectionService.reset()`, `WorkspaceContext.clearCache()`
+
+**Partial Mocks:**
+```typescript
+vi.mocked(fs.existsSync).mockImplementation((p) => p.toString() === configPath);
+```
+
+## Fixtures and Factories
+
+**Temp Directory Pattern (integration tests):**
+```typescript
+const tempDirs: string[] = [];
+
+function makeWorkspace(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-runtime-summary-'));
+  tempDirs.push(dir);
+  fs.mkdirSync(path.join(dir, '.state', 'sessions'), { recursive: true });
+  return dir;
+}
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+```
+
+**JSON Fixture Writing:**
+```typescript
+function writeJson(filePath: string, value: unknown): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(value, null, 2), 'utf8');
+}
+```
+
+**Session File Helper:**
+```typescript
+function writeSession(workspace: string, sessionId: string, payload: Record<string, unknown>): void {
+  writeJson(path.join(workspace, '.state', 'sessions', `${sessionId}.json`), {
+    sessionId,
+    ...payload,
+  });
+}
+```
+
+## Integration Tests
+
+**Requirements:**
+- Real SQLite database via `better-sqlite3`
+- Thread pool required (not `vm` pool) due to native handle cleanup issues
+- Explicit file list in `vitest.config.ts` integration array
+
+**Integration Test Files:**
+```typescript
+const integrationTests = [
+  'tests/core/control-ui-db.test.ts',
+  'tests/core/evolution-logger.test.ts',
+  'tests/core/nocturnal-e2e.test.ts',
+  // ...
+];
+```
+
+## Common Patterns
+
+**Async Testing with Fake Timers:**
+```typescript
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+it('should retry on retryable error', async () => {
+  const fn = vi.fn()
+    .mockRejectedValueOnce(new Error('ETIMEDOUT'))
+    .mockResolvedValue('success');
+
+  const resultPromise = retryAsync(fn, { initialDelayMs: 100 });
+  await vi.advanceTimersByTimeAsync(100);
+  const result = await resultPromise;
+  expect(result).toBe('success');
+});
+```
+
+**Error Testing:**
+```typescript
+it('should throw after max retries exceeded', async () => {
+  vi.useRealTimers();
+  const fn = vi.fn().mockRejectedValue(new Error('ETIMEDOUT'));
+
+  await expect(retryAsync(fn, { maxRetries: 1, initialDelayMs: 1, logger: { warn: vi.fn() } }))
+    .rejects.toThrow('ETIMEDOUT');
+});
+```
+
+**Singleton Reset Pattern:**
+```typescript
+// Many services use singleton pattern requiring reset between tests
+DetectionService.reset();
+WorkspaceContext.clearCache();
+clearSession('live-session');
+```
+
+## Test Naming and Documentation
+
+**Descriptive Test Names:**
+```typescript
+it('should block risk path writes at Seed tier (EP system)', () => { ... });
+it('should return default values if file does not exist', () => { ... });
+```
+
+**Test Comments for Context:**
+```typescript
+// Task 4: Default Values Consistency Tests
+describe('Gate Default Values Consistency', () => {
+  /**
+   * PURPOSE: Prove that gate.ts inline defaults match PROFILE_DEFAULTS.
+   * If gate.ts has inline defaults that differ from normalizeProfile(),
+   * this is a bug - the defaults should come from a single source of truth.
+   */
+});
+```
+
+## Test Isolation
+
+**Environment Variable Injection:**
+```typescript
+// Set env before module load
+process.env.PD_TEST_AGENTS_DIR = TEST_AGENTS_DIR;
+```
+
+**Path Traversal Protection Tests:**
+```typescript
+it('rejects path traversal session IDs', async () => {
+  const result = await extractRecentConversation('../../etc/passwd', 'main');
+  expect(result).toBe('');
+});
+```
+
+---
+
+*Testing analysis: 2026-04-15*

package/esbuild.config.js

@@ -25,6 +25,7 @@ function copyRecursive(src, dest) {
 
 async function bundlePlugin() {
   try {
+    // 1. Build the main bundle for OpenClaw
     await build({
       entryPoints: ['src/index.ts'],
       outfile: 'dist/bundle.js',
@@ -44,7 +45,35 @@ async function bundlePlugin() {
       metafile: true,
     });
 
-    console.log('Bundle created: dist/bundle.js');
+    console.log('Main bundle created: dist/bundle.js');
+
+    // 2. Build core tools for CLI usage (bootstrap-rules, etc)
+    // We keep these separate and un-minified for easier debugging and CLI importing
+    await build({
+      entryPoints: {
+        'core/bootstrap-rules': 'src/core/bootstrap-rules.ts',
+        'core/principle-tree-ledger': 'src/core/principle-tree-ledger.ts',
+        'core/principle-training-state': 'src/core/principle-training-state.ts',
+        'core/principle-compiler/index': 'src/core/principle-compiler/index.ts',
+        'core/trajectory/index': 'src/core/trajectory.ts',
+      },
+      outdir: 'dist',
+      bundle: true,
+      platform: 'node',
+      target: 'node20',
+      format: 'esm',
+      outbase: 'src',
+      external: [
+        'openclaw',
+        '@openclaw/sdk',
+        '@openclaw/plugin-kit',
+        'better-sqlite3',
+      ],
+      sourcemap: false,
+      minify: false,
+    });
+
+    console.log('Core CLI tools built in dist/core/');
 
     const staticFiles = ['templates', 'openclaw.plugin.json'];
     const distDir = 'dist';
@@ -65,9 +94,9 @@ async function bundlePlugin() {
       console.log(`Copied: ${file} -> dist/${file}`);
     }
 
-    console.log('\nPlugin bundle ready for distribution.');
+    console.log('\nPlugin build ready for distribution.');
   } catch (error) {
-    console.error('Bundle failed:', error);
+    console.error('Build failed:', error);
     process.exit(1);
   }
 }

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "1.40.0",
+  "version": "1.42.0",
   "description": "Native OpenClaw plugin for Principles Disciple",
   "type": "module",
   "main": "./dist/bundle.js",
@@ -37,6 +37,7 @@
     "test:all": "vitest run",
     "lint": "eslint src/",
     "bootstrap-rules": "node scripts/bootstrap-rules.mjs",
+    "compile-principles": "node scripts/compile-principles.mjs",
     "validate-live-path": "tsx scripts/validate-live-path.ts"
   },
   "devDependencies": {

package/scripts/compile-principles.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+/**
+ * Principle Compiler CLI
+ *
+ * Compiles eligible principles (those derived from pain events) into
+ * auto-generated rules via the PrincipleCompiler pipeline.
+ *
+ * Usage:
+ *   npm run compile-principles
+ *   WORKSPACE_DIR=/path/to/workspace npm run compile-principles
+ *   node scripts/compile-principles.mjs /path/to/workspace
+ */
+
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Resolve workspace directory: CLI arg > env var > default
+const WORKSPACE_DIR = process.argv[2]
+  || process.env.WORKSPACE_DIR
+  || join(process.env.HOME, '.openclaw', 'workspace-main');
+
+const STATE_DIR = join(WORKSPACE_DIR, '.state');
+
+async function run() {
+  console.log('Principle Compiler CLI');
+  console.log(`  Workspace: ${WORKSPACE_DIR}`);
+  console.log(`  State dir: ${STATE_DIR}`);
+
+  let compilerModule, trajectoryModule;
+
+  try {
+    compilerModule = await import('../dist/core/principle-compiler/index.js');
+  } catch {
+    console.error('PrincipleCompiler module not found in dist/. Build first: node esbuild.config.js');
+    process.exit(1);
+  }
+
+  try {
+    trajectoryModule = await import('../dist/core/trajectory/index.js');
+  } catch {
+    console.error('TrajectoryDatabase module not found in dist/. Build first: node esbuild.config.js');
+    process.exit(1);
+  }
+
+  const { PrincipleCompiler } = compilerModule;
+  const { TrajectoryDatabase } = trajectoryModule;
+
+  let trajectory;
+  try {
+    trajectory = new TrajectoryDatabase({ workspaceDir: WORKSPACE_DIR });
+  } catch (err) {
+    console.error(`Failed to open trajectory database: ${err.message}`);
+    process.exit(1);
+  }
+
+  try {
+    const compiler = new PrincipleCompiler(STATE_DIR, trajectory);
+
+    console.log('\nCompiling eligible principles...');
+    const results = compiler.compileAll();
+
+    const succeeded = results.filter(r => r.success);
+    const failed = results.filter(r => !r.success);
+
+    console.log(`\nResults: ${succeeded.length} succeeded, ${failed.length} failed`);
+
+    for (const r of succeeded) {
+      console.log(`  + ${r.principleId} -> rule ${r.ruleId} (impl: ${r.implementationId})`);
+    }
+
+    for (const r of failed) {
+      console.log(`  x ${r.principleId}: ${r.reason}`);
+    }
+
+    if (results.length === 0) {
+      console.log('  No eligible principles found for compilation.');
+    }
+
+    if (failed.length > 0) {
+      process.exitCode = 1;
+    }
+  } finally {
+    trajectory.dispose();
+  }
+}
+
+run().catch((err) => {
+  console.error(`Fatal: ${err.message}`);
+  process.exit(1);
+});