principles-disciple 1.14.0 → 1.16.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.14.0",
+  "version": "1.16.0",
   "skills": [
     "./skills"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "Native OpenClaw plugin for Principles Disciple",
   "type": "module",
   "main": "./dist/bundle.js",
@@ -32,7 +32,9 @@
     "build:production": "node esbuild.config.js --production && node scripts/build-web.mjs --production && node scripts/verify-build.mjs",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "lint": "eslint src/"
+    "lint": "eslint src/",
+    "bootstrap-rules": "node scripts/bootstrap-rules.mjs",
+    "validate-live-path": "tsx scripts/validate-live-path.ts"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.0",

package/scripts/bootstrap-rules.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+/**
+ * Minimal Rule Bootstrap CLI (Phase 17)
+ *
+ * Seeds 1-3 stub Rule entities for high-value deterministic principles.
+ * Idempotent: re-running skips already-existing rules.
+ *
+ * Usage:
+ *   npm run bootstrap-rules                        # default (3 principles)
+ *   BOOTSTRAP_LIMIT=2 npm run bootstrap-rules      # limit to 2 principles
+ *   STATE_DIR=/path/to/state npm run bootstrap-rules  # custom state dir
+ */
+
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const PROJECT_ROOT = join(__dirname, '..');
+const STATE_DIR = process.env.STATE_DIR || join(PROJECT_ROOT, '..', '.state');
+const LIMIT = parseInt(process.env.BOOTSTRAP_LIMIT || '3', 10);
+
+async function run() {
+  let BootstrapModule;
+  try {
+    BootstrapModule = await import('../dist/core/bootstrap-rules.js');
+  } catch {
+    console.error('Bootstrap module not found in dist/. Build first: node esbuild.config.js');
+    process.exit(1);
+  }
+
+  const { bootstrapRules, validateBootstrap, selectPrinciplesForBootstrap } = BootstrapModule;
+
+  console.log('Selecting principles for bootstrap...');
+  console.log(`  State dir: ${STATE_DIR}`);
+  console.log(`  Limit: ${LIMIT}`);
+
+  try {
+    const selectedIds = selectPrinciplesForBootstrap(STATE_DIR, LIMIT);
+    console.log(`  Selected ${selectedIds.length} principle(s): ${selectedIds.join(', ')}`);
+
+    console.log('\nRunning bootstrap...');
+    const results = bootstrapRules(STATE_DIR, LIMIT);
+
+    for (const r of results) {
+      console.log(`  ${r.status === 'created' ? '+' : '='} ${r.principleId} -> ${r.ruleId} (${r.status})`);
+    }
+
+    const created = results.filter((r) => r.status === 'created');
+    const skipped = results.filter((r) => r.status === 'skipped');
+    console.log(`\nDone: ${created.length} created, ${skipped.length} skipped.`);
+
+    if (created.length > 0) {
+      console.log('\nValidating...');
+      const valid = validateBootstrap(STATE_DIR, selectedIds);
+      console.log(`  Validation: ${valid ? 'PASS' : 'FAIL'}`);
+    }
+  } catch (err) {
+    console.error(`\nBootstrap failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+run();

package/scripts/validate-live-path.ts

@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+/**
+ * Validate Live Path Script (Phase 18)
+ *
+ * Validates the end-to-end nocturnal workflow path with bootstrapped principles.
+ *
+ * Purpose:
+ * - Reads bootstrapped rules from principle_training_state.json
+ * - Creates synthetic snapshot with recentPain to pass hasUsableNocturnalSnapshot() guard
+ * - Enqueues sleep_reflection task with proper file locking
+ * - Polls subagent_workflows.db directly for nocturnal workflows
+ * - Correlates workflow to queue item via taskId
+ * - Verifies state='completed' and explicit resolution (not 'expired')
+ * - Outputs summary and exits 0 on success, non-zero on failure
+ *
+ * Usage:
+ *   tsx scripts/validate-live-path.ts [--verbose]
+ *
+ * Environment:
+ *   WORKSPACE_DIR - Optional workspace directory (defaults to process.cwd())
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+// ─── Constants ───────────────────────────────────────────────────────────
+const POLL_INTERVAL_MS = 5_000;
+const POLL_TIMEOUT_MS = 5 * 60 * 1000;  // 5 minutes
+const LOCK_SUFFIX = '.lock';
+const LOCK_MAX_RETRIES = 50;
+const LOCK_RETRY_DELAY_MS = 50;
+const LOCK_STALE_MS = 30_000;
+const WORKSPACE_DIR = process.env.WORKSPACE_DIR || process.cwd();
+const STATE_DIR = path.join(WORKSPACE_DIR, '.state');
+const QUEUE_PATH = path.join(STATE_DIR, 'EVOLUTION_QUEUE');
+const QUEUE_LOCK_PATH = QUEUE_PATH + LOCK_SUFFIX;
+const LEDGER_PATH = path.join(STATE_DIR, 'principle_training_state.json');
+const DB_PATH = path.join(STATE_DIR, 'subagent_workflows.db');
+
+// ─── Types ───────────────────────────────────────────────────────────────
+interface LedgerRule {
+  id: string;
+  principleId: string;
+  action: string;
+  type: string;
+}
+
+interface HybridLedgerStore {
+  tree: {
+    rules: Record<string, LedgerRule>;
+  };
+}
+
+interface WorkflowRow {
+  workflow_id: string;
+  workflow_type: string;
+  state: string;
+  metadata_json: string;
+  created_at: number;
+}
+
+interface QueueItem {
+  id: string;
+  taskKind: string;
+  status: string;
+  resolution?: string;
+  resultRef?: string;
+}
+
+interface LockContext {
+  lockPath: string;
+  pid: number;
+  release: () => void;
+}
+
+// ─── File Lock Functions (simplified from file-lock.ts) ──────────────────
+async function acquireLockAsync(filePath: string, options: {
+  lockSuffix?: string;
+  maxRetries?: number;
+  baseRetryDelayMs?: number;
+  lockStaleMs?: number;
+} = {}): Promise<LockContext> {
+  const opts = {
+    lockSuffix: LOCK_SUFFIX,
+    maxRetries: LOCK_MAX_RETRIES,
+    baseRetryDelayMs: LOCK_RETRY_DELAY_MS,
+    lockStaleMs: LOCK_STALE_MS,
+    ...options,
+  };
+  const { pid } = process;
+  const lockPath = filePath + opts.lockSuffix;
+
+  for (let attempt = 0; attempt < opts.maxRetries!; attempt++) {
+    try {
+      // Check if lock file exists and is stale
+      if (fs.existsSync(lockPath)) {
+        const lockContent = fs.readFileSync(lockPath, 'utf8');
+        const lockPid = parseInt(lockContent, 10);
+        const lockStats = fs.statSync(lockPath);
+        const lockAge = Date.now() - lockStats.mtimeMs;
+
+        // Clean up stale lock
+        if (lockAge > opts.lockStaleMs!) {
+          fs.unlinkSync(lockPath);
+        } else if (lockPid !== pid) {
+          // Lock held by another process
+          await new Promise(resolve => setTimeout(resolve, opts.baseRetryDelayMs!));
+          continue;
+        }
+      }
+
+      // Acquire lock
+      fs.writeFileSync(lockPath, pid.toString(), { flag: 'wx' });
+      return {
+        lockPath,
+        pid,
+        release: () => {
+          try {
+            if (fs.existsSync(lockPath)) {
+              fs.unlinkSync(lockPath);
+            }
+          } catch {
+            // Ignore errors during release
+          }
+        },
+      };
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+        if (attempt < opts.maxRetries! - 1) {
+          await new Promise(resolve => setTimeout(resolve, opts.baseRetryDelayMs!));
+          continue;
+        }
+      }
+      throw new Error(`Failed to acquire lock for ${filePath}: ${String(error)}`);
+    }
+  }
+
+  throw new Error(`Failed to acquire lock for ${filePath} after ${opts.maxRetries} attempts`);
+}
+
+function releaseLock(ctx: LockContext): void {
+  ctx.release();
+}
+
+// ─── Step 1: Check bootstrapped rules ─────────────────────────────────────
+function loadBootstrappedRules(): LedgerRule[] {
+  if (!fs.existsSync(LEDGER_PATH)) {
+    throw new Error('FAIL: principle_training_state.json not found. Run Phase 17 bootstrap first: npm run bootstrap-rules');
+  }
+
+  const ledger: HybridLedgerStore = JSON.parse(fs.readFileSync(LEDGER_PATH, 'utf8'));
+  const bootstrappedRules = Object.values(ledger.tree.rules).filter(r =>
+    r.id.endsWith('_stub_bootstrap')
+  );
+
+  return bootstrappedRules;
+}
+
+// ─── Step 2: Build synthetic snapshot ──────────────────────────────────────
+function buildSyntheticSnapshot(taskId: string) {
+  return {
+    sessionId: `validation-${taskId}`,
+    startedAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    assistantTurns: [],
+    userTurns: [],
+    toolCalls: [],
+    painEvents: [],
+    gateBlocks: [],
+    stats: {
+      totalAssistantTurns: 0,
+      totalToolCalls: 0,
+      failureCount: 0,
+      totalPainEvents: 1,
+      totalGateBlocks: 0,
+    },
+    recentPain: [{
+      source: 'live-validation',
+      score: 50,
+      severity: 'moderate',
+      reason: 'Synthetic snapshot for live path validation',
+      createdAt: new Date().toISOString(),
+    }],
+    _dataSource: 'pain_context_fallback',
+  };
+}
+
+// ─── Step 3: Enqueue sleep_reflection task with proper file locking ──────────
+// Uses acquireLockAsync to prevent TOCTOU race conditions (T-18-01 mitigation)
+async function enqueueSleepReflectionTask(taskId: string): Promise<void> {
+  let lockCtx: LockContext | null = null;
+  try {
+    // Acquire lock before reading queue file (T-18-01 mitigation)
+    lockCtx = await acquireLockAsync(QUEUE_PATH, {
+      lockSuffix: LOCK_SUFFIX,
+      maxRetries: LOCK_MAX_RETRIES,
+      baseRetryDelayMs: LOCK_RETRY_DELAY_MS,
+      lockStaleMs: LOCK_STALE_MS,
+    });
+
+    let queue: QueueItem[] = [];
+    if (fs.existsSync(QUEUE_PATH)) {
+      const queueContent = fs.readFileSync(QUEUE_PATH, 'utf8');
+      queue = JSON.parse(queueContent);
+    }
+
+    queue.push({
+      id: taskId,
+      taskKind: 'sleep_reflection',
+      status: 'pending',
+    });
+
+    fs.writeFileSync(QUEUE_PATH, JSON.stringify(queue, null, 2), 'utf8');
+  } finally {
+    if (lockCtx) {
+      releaseLock(lockCtx);
+    }
+  }
+}
+
+// ─── Step 4: Poll workflow store (raw SQLite, no WorkflowStore import) ─────
+// Uses better-sqlite3 directly to avoid WorkflowStore async initialization issues in standalone script
+function listNocturnalWorkflows(): WorkflowRow[] {
+  if (!fs.existsSync(DB_PATH)) {
+    return [];
+  }
+
+  const Database = require('better-sqlite3');
+  const db = new Database(DB_PATH, { readonly: true });
+  const rows = db.prepare(`
+    SELECT workflow_id, workflow_type, state, metadata_json, created_at
+    FROM subagent_workflows
+    WHERE workflow_type = 'nocturnal'
+    ORDER BY created_at DESC
+  `).all() as WorkflowRow[];
+  db.close();
+  return rows;
+}
+
+// ─── Step 5: Correlate and verify ─────────────────────────────────────────
+function verifyWorkflowCompletion(taskId: string): {
+  workflowId: string;
+  state: string;
+  resolution: string;
+} | null {
+  const workflows = listNocturnalWorkflows();
+
+  for (const wf of workflows) {
+    const meta = JSON.parse(wf.metadata_json);
+    if (meta.taskId !== taskId) continue;
+    if (wf.state !== 'completed') continue;
+
+    // Read resolution from queue (resolution is on queue item, not on WorkflowRow)
+    let queue: QueueItem[] = [];
+    try {
+      if (fs.existsSync(QUEUE_PATH)) {
+        const queueContent = fs.readFileSync(QUEUE_PATH, 'utf8');
+        queue = JSON.parse(queueContent);
+      }
+    } catch {
+      // Queue file missing or corrupted — resolution unknown
+    }
+
+    const queueItem = queue.find(q => q.id === taskId);
+    const resolution = queueItem?.resolution;
+
+    return {
+      workflowId: wf.workflow_id,
+      state: wf.state,
+      resolution: resolution || 'MISSING',
+    };
+  }
+
+  return null;
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────
+async function main() {
+  const verbose = process.argv.includes('--verbose');
+
+  // 1. Check bootstrapped rules
+  let rules: LedgerRule[];
+  try {
+    rules = loadBootstrappedRules();
+  } catch {
+    console.error('FAIL: principle_training_state.json not found. Run Phase 17 bootstrap first: npm run bootstrap-rules');
+    process.exit(1);
+  }
+
+  if (rules.length === 0) {
+    console.error('FAIL: No _stub_bootstrap rules found. Run Phase 17 bootstrap first: npm run bootstrap-rules');
+    process.exit(1);
+  }
+
+  if (verbose) {
+    console.log(`Found ${rules.length} bootstrapped rule(s)`);
+    for (const rule of rules) {
+      console.log(`  - ${rule.id} (principleId=${rule.principleId}, action=${rule.action})`);
+    }
+  }
+
+  // 2. Generate task ID
+  const taskId = `validation-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+  // 3. Build synthetic snapshot for validation
+  const snapshot = buildSyntheticSnapshot(taskId);
+  if (verbose) {
+    console.log(`Created synthetic snapshot: sessionId=${snapshot.sessionId}`);
+  }
+
+  // 4. Enqueue task (with lock acquisition)
+  try {
+    await enqueueSleepReflectionTask(taskId);
+    if (verbose) {
+      console.log(`Enqueued sleep_reflection task: ${taskId}`);
+    }
+  } catch (error: unknown) {
+    console.error('FAIL: Failed to enqueue sleep_reflection task:', String(error));
+    process.exit(1);
+  }
+
+  // 5. Poll for completion
+  const deadline = Date.now() + POLL_TIMEOUT_MS;
+  if (verbose) {
+    console.log('Polling for workflow completion...');
+  }
+
+  while (Date.now() < deadline) {
+    await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL_MS));
+
+    const result = verifyWorkflowCompletion(taskId);
+    if (result) {
+      console.log(`RESULT: workflow=${result.workflowId} state=${result.state} resolution=${result.resolution} taskId=${taskId}`);
+
+      if (result.resolution === 'MISSING' || result.resolution === 'expired') {
+        console.error('FAIL: resolution not explicit');
+        process.exit(1);
+      }
+
+      console.log('PASS: Live path validation successful');
+      process.exit(0);
+    }
+
+    if (verbose) {
+      process.stdout.write('.');
+    }
+  }
+
+  console.error('FAIL: Poll timeout — no completed nocturnal workflow found for taskId');
+  process.exit(1);
+}
+
+main().catch(err => {
+  console.error('FAIL:', err);
+  process.exit(1);
+});

package/src/core/bootstrap-rules.ts

@@ -0,0 +1,177 @@
+/**
+ * Minimal Rule Bootstrap (Phase 17)
+ *
+ * Bootstraps 1-3 stub Rule entities for high-value deterministic principles.
+ * Selected by: observedViolationCount (descending) + evaluability=deterministic.
+ * Falls back to all deterministic principles if violation data is sparse.
+ *
+ * Rule ID format: {principleId}_stub_bootstrap
+ * Scope: BOOT-03 — bounded, no mass migration, no implementations.
+ *
+ * Usage:
+ *   npx vitest run tests/core/bootstrap-rules.test.ts   (tests)
+ *   npm run bootstrap-rules                               (production)
+ */
+
+import { loadLedger, createRule, updatePrinciple } from './principle-tree-ledger.js';
+import { loadStore } from './principle-training-state.js';
+
+export interface BootstrapResult {
+  principleId: string;
+  ruleId: string;
+  status: 'created' | 'skipped';
+}
+
+/**
+ * Select principles for bootstrap based on violation count and evaluability.
+ *
+ * @param stateDir - State directory path
+ * @param limit - Maximum number of principles to select (default: 3)
+ * @returns Array of principle IDs sorted by observedViolationCount (descending)
+ * @throws Error if no deterministic principles found
+ */
+export function selectPrinciplesForBootstrap(stateDir: string, limit: number = 3): string[] {
+  // Load training store to get evaluability and violation data
+  const store = loadStore(stateDir);
+
+  // Filter for deterministic principles only
+  const deterministicEntries = Object.values(store).filter(
+    (entry) => entry.evaluability === 'deterministic'
+  );
+
+  if (deterministicEntries.length === 0) {
+    throw new Error('No deterministic principles found in training store');
+  }
+
+  // Sort by observedViolationCount descending, then by principleId for tiebreaker
+  const sorted = deterministicEntries.sort((a, b) => {
+    const violationDiff = b.observedViolationCount - a.observedViolationCount;
+    if (violationDiff !== 0) {
+      return violationDiff;
+    }
+    // Alphabetical tiebreaker
+    return a.principleId.localeCompare(b.principleId);
+  });
+
+  // Check if we have sparse violation data (all zeros or very low)
+  const hasViolations = sorted.some((entry) => entry.observedViolationCount > 0);
+  if (!hasViolations) {
+    // Log warning and use all deterministic principles
+    console.warn('[bootstrap] No violation data found, using all deterministic principles');
+  }
+
+  // Return top N
+  return sorted.slice(0, limit).map((entry) => entry.principleId);
+}
+
+/**
+ * Bootstrap stub rules for selected principles.
+ *
+ * Creates stub Rule entities with format {principleId}_stub_bootstrap.
+ * Links rules to principles via suggestedRules array.
+ * Idempotent: skips existing rules.
+ *
+ * @param stateDir - State directory path
+ * @param limit - Maximum number of principles to bootstrap (default: 3)
+ * @returns Array of results indicating created or skipped status
+ * @throws Error if no deterministic principles found
+ */
+export function bootstrapRules(stateDir: string, limit: number = 3): BootstrapResult[] {
+  // 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) {
+    // Verify principle exists in ledger
+    const principle = ledger.tree.principles[principleId];
+    if (!principle) {
+      throw new Error(`Principle ${principleId} not found in ledger tree`);
+    }
+
+    // Compute rule ID
+    const ruleId = `${principleId}_stub_bootstrap`;
+
+    // Check if rule already exists
+    if (ledger.tree.rules[ruleId]) {
+      results.push({
+        principleId,
+        ruleId,
+        status: 'skipped',
+      });
+      continue;
+    }
+
+    // Create stub rule
+    const now = new Date().toISOString();
+    const rule = createRule(stateDir, {
+      id: ruleId,
+      version: 1,
+      name: `Stub bootstrap rule for ${principleId}`,
+      description: `Placeholder rule for principle-internalization bootstrap`,
+      type: 'hook',
+      triggerCondition: 'stub: bootstrap placeholder',
+      enforcement: 'warn',
+      action: 'allow (stub)',
+      principleId,
+      status: 'proposed',
+      coverageRate: 0,
+      falsePositiveRate: 0,
+      implementationIds: [],
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    // Link rule to principle via suggestedRules
+    const existingSuggested = principle.suggestedRules || [];
+    updatePrinciple(stateDir, principleId, {
+      suggestedRules: [...existingSuggested, ruleId],
+    });
+
+    results.push({
+      principleId,
+      ruleId,
+      status: 'created',
+    });
+  }
+
+  return results;
+}
+
+/**
+ * Validate that bootstrapped state is correct.
+ *
+ * @param stateDir - State directory path
+ * @param expectedPrincipleIds - Principle IDs that should be bootstrapped
+ * @returns true if validation passes
+ * @throws Error if validation fails
+ */
+export function validateBootstrap(stateDir: string, expectedPrincipleIds: string[]): boolean {
+  const ledger = loadLedger(stateDir);
+
+  for (const principleId of expectedPrincipleIds) {
+    // Verify principle exists
+    const principle = ledger.tree.principles[principleId];
+    if (!principle) {
+      throw new Error(`Principle ${principleId} not found in ledger tree`);
+    }
+
+    // Verify suggestedRules exists and is not empty
+    if (!principle.suggestedRules || principle.suggestedRules.length === 0) {
+      throw new Error(`Principle ${principleId} has empty or missing suggestedRules`);
+    }
+
+    // Verify each suggested rule exists in ledger
+    for (const ruleId of principle.suggestedRules) {
+      const rule = ledger.tree.rules[ruleId];
+      if (!rule) {
+        throw new Error(`Rule ${ruleId} referenced by principle ${principleId} not found in ledger`);
+      }
+    }
+  }
+
+  return true;
+}