principles-disciple 1.72.0 → 1.74.0

package/src/types/principle-tree-schema.ts

@@ -22,233 +22,31 @@
  *   - Track principle value ranking (pain prevented, adherence rate)
  */
 
-import type { PrincipleStatus } from '../core/evolution-types.js';
+import type { Principle as CorePrinciple } from '@principles/core/runtime-v2';
 import type { PrincipleDetectorSpec } from '../core/evolution-types.js';
 
+// Re-exported from core (PRI-51) for plugin consumers
+export type {
+  PrinciplePriority,
+  PrincipleScope,
+  PrincipleEvaluability,
+  RuleStatus,
+  RuleType,
+  ImplementationLifecycleState,
+  ImplementationType,
+  Rule,
+  Implementation,
+  PrincipleDependency,
+  PrincipleValueMetrics,
+  PrincipleEventType,
+  PrincipleLifecycleEvent,
+  PrincipleTreeStore,
+} from '@principles/core/runtime-v2';
+
 // =========================================================================
 // 1. PRINCIPLE (Tree Root) — Highly abstract, cross-scenario, value-driven
 // =========================================================================
 
-export type PrinciplePriority = 'P0' | 'P1' | 'P2';
-
-export type PrincipleScope = 'general' | 'domain';
-
-export type PrincipleEvaluability =
-  | 'manual_only'        // Cannot be automatically evaluated
-  | 'deterministic'      // Clear yes/no evaluation criteria
-  | 'weak_heuristic';    // Fuzzy evaluation with confidence score
-
-export interface Principle {
-  // Identity
-  id: string;                     // e.g., "P_060"
-  version: number;                // Incremented on each update
-
-  // Core content
-  text: string;                   // One-line abstract principle statement
-  coreAxiomId?: string;           // Associated core axiom (e.g., "T-01")
-  triggerPattern: string;         // Regex/keywords for auto-matching pain signals
-  action: string;                 // What to do when triggered
-
-  // Status and lifecycle
-  status: PrincipleStatus;
-  priority: PrinciplePriority;
-  scope: PrincipleScope;
-  domain?: string;                // Required when scope === 'domain', e.g., "file_operations"
-  evaluability: PrincipleEvaluability;
-
-  // Value metrics (auto-calculated)
-  valueScore: number;             // pain_prevented_count × avg_pain_severity
-  adherenceRate: number;          // 0-100, percentage of times followed
-  painPreventedCount: number;     // Number of pain signals prevented by this principle
-  lastPainPreventedAt?: string;   // ISO timestamp of most recent prevention
-
-  // Relationships
-  derivedFromPainIds: string[];   // Source pain signal IDs
-  ruleIds: string[];              // Associated rule IDs (trunk connections)
-  conflictsWithPrincipleIds: string[];  // Conflicting principles
-  supersedesPrincipleId?: string; // If this replaces a deprecated principle
-
-  // Metadata
-  createdAt: string;              // ISO timestamp
-  updatedAt: string;              // ISO timestamp
-  deprecatedAt?: string;          // Set when status changes to 'deprecated'
-  deprecatedReason?: string;      // Why it was deprecated (e.g., "solidified into hook at src/hooks/file-safety.ts")
-
-  // Detector metadata (for auto-training eligibility)
+export interface Principle extends CorePrinciple {
   detectorMetadata?: PrincipleDetectorSpec;
-
-  // Compilation retry tracking (for runtime auto-trigger)
-  // undefined = not yet attempted or succeeded; 0 = queued; n >= 1 = retry attempt n
-  compilationRetryCount?: number;
-}
-
-// =========================================================================
-// 2. RULE (Tree Trunk) — Verifiable, actionable, principle-specific
-// =========================================================================
-
-export type RuleStatus =
-  | 'proposed'     // Suggested but not implemented
-  | 'implemented'  // Code/skill exists but not fully tested
-  | 'enforced'     // Actively enforced with monitoring
-  | 'retired';     // No longer needed (principle deprecated)
-
-export type RuleType =
-  | 'hook'         // Code hook (before/after tool call)
-  | 'gate'         // Pre-execution gate (block/warn)
-  | 'skill'        // LLM skill/instruction
-  | 'lora'         // Fine-tuned model weight
-  | 'test'         // Automated test case
-  | 'prompt'       // System prompt injection;
-
-export interface Rule {
-  // Identity
-  id: string;                     // e.g., "R_060_01"
-  version: number;
-
-  // Core content
-  name: string;                   // Short descriptive name
-  description: string;            // What this rule does
-  type: RuleType;
-
-  // Trigger and enforcement
-  triggerCondition: string;       // When this rule activates (regex, tool name, context)
-  enforcement: 'block' | 'warn' | 'log';  // What happens when violated
-  action: string;                 // Concrete action to take
-
-  // Association
-  principleId: string;            // Parent principle ID
-  parentRuleId?: string;          // If this is a sub-rule
-
-  // Status and metrics
-  status: RuleStatus;
-  coverageRate: number;           // 0-100, how often this rule catches violations
-  falsePositiveRate: number;      // 0-100, how often this rule fires incorrectly
-
-  // Implementation reference
-  implementationPath?: string;    // File path, skill name, or LoRA model path
-  testPath?: string;              // Test file path
-
-  // Metadata
-  createdAt: string;
-  updatedAt: string;
-}
-
-// =========================================================================
-// 3. IMPLEMENTATION (Tree Leaf) — Concrete, executable
-// =========================================================================
-
-export type ImplementationLifecycleState =
-  | 'candidate'    // Newly created, awaiting replay evaluation
-  | 'active'       // Currently active for this rule
-  | 'disabled'     // Manually disabled (e.g., regression)
-  | 'archived';    // Permanently archived
-
-export type ImplementationType = 'code' | 'skill' | 'lora' | 'test' | 'prompt';
-
-export interface Implementation {
-  // Identity
-  id: string;                     // e.g., "IMPL_060_01_hook"
-  ruleId: string;                 // Parent rule ID
-
-  // Type and location
-  type: ImplementationType;
-  path: string;                   // File path, skill ID, or model path
-  version: string;                // Code commit hash, skill version, or LoRA version
-
-  // Coverage
-  coversCondition: string;        // What condition this implementation covers
-  coveragePercentage: number;     // 0-100, how much of the rule this covers
-
-  // Lifecycle state
-  lifecycleState: ImplementationLifecycleState;
-
-  // Rollback support: tracks which implementation was active before this one
-  previousActive?: string;        // Implementation ID that was active before promotion
-
-  // Disable metadata
-  disabledAt?: string;            // ISO timestamp of disable
-  disabledBy?: string;            // Who disabled (session/user)
-  disabledReason?: string;        // Human-readable reason
-
-  // Archive metadata
-  archivedAt?: string;            // ISO timestamp of archive
-
-  // Metadata
-  createdAt: string;
-  updatedAt: string;
-}
-
-// =========================================================================
-// 4. PRINCIPLE-RELATIONSHIP GRAPH
-// =========================================================================
-
-export interface PrincipleDependency {
-  principleId: string;
-  dependsOn: string[];            // Principle IDs this depends on
-  conflictedWith: string[];       // Principle IDs this conflicts with
-  supersedes: string[];           // Principle IDs this replaces
-}
-
-// =========================================================================
-// 5. VALUE METRICS (Auto-calculated)
-// =========================================================================
-
-export interface PrincipleValueMetrics {
-  principleId: string;
-  
-  // Pain prevention
-  painPreventedCount: number;     // Total pain signals prevented
-  avgPainSeverityPrevented: number;  // Average severity of prevented pain
-  lastPainPreventedAt?: string;
-  
-  // Adherence tracking
-  totalOpportunities: number;     // Times the principle could have applied
-  adheredCount: number;           // Times the principle was followed
-  violatedCount: number;          // Times the principle was violated
-  
-  // Cost-benefit
-  implementationCost: number;     // Dev hours to implement
-  benefitScore: number;           // pain_prevented × severity × adherence_rate
-  
-  // Timestamps
-  calculatedAt: string;
-}
-
-// =========================================================================
-// 6. LIFECYCLE EVENTS (Event stream format for evolution.jsonl)
-// =========================================================================
-
-export type PrincipleEventType =
-  | 'principle_created'
-  | 'principle_updated'
-  | 'principle_promoted'
-  | 'principle_deprecated'
-  | 'rule_created'
-  | 'rule_enforced'
-  | 'rule_retired'
-  | 'implementation_added'
-  | 'value_metrics_updated';
-
-export interface PrincipleLifecycleEvent {
-  ts: string;                     // ISO timestamp
-  type: PrincipleEventType;
-  data: {
-    principleId?: string;
-    ruleId?: string;
-    implementationId?: string;
-    reason: string;
-    metrics?: Partial<PrincipleValueMetrics>;
-  };
-}
-
-// =========================================================================
-// 8. STORE SCHEMA (principle_training_state.json extension)
-// =========================================================================
-
-export interface PrincipleTreeStore {
-  principles: Record<string, Principle>;
-  rules: Record<string, Rule>;
-  implementations: Record<string, Implementation>;
-  metrics: Record<string, PrincipleValueMetrics>;
-  lastUpdated: string;
 }

package/src/types/queue.ts

@@ -1,70 +1,15 @@
-/**
- * Branded types for queue and workflow domain identifiers.
- * These prevent accidental interchange of plain strings with domain-specific IDs.
- */
-
-/**
- * Brand type constructor using intersection type pattern.
- * @example type UserId = Brand<string, 'UserId'>;
- */
-export type Brand<T, B> = T & { readonly _brand: B };
-
-/**
- * Queue item identifier — not interchangeable with plain string.
- */
-export type QueueItemId = Brand<string, 'QueueItemId'>;
-
-/**
- * Workflow identifier — not interchangeable with plain string.
- */
-export type WorkflowId = Brand<string, 'WorkflowId'>;
-
-/**
- * Session key — not interchangeable with plain string.
- */
-export type SessionKey = Brand<string, 'SessionKey'>;
-
-/**
- * Constructor for QueueItemId.
- * @param id - raw string ID from queue operations
- */
-export function toQueueItemId(id: string): QueueItemId {
-  return id as QueueItemId;
-}
-
-/**
- * Constructor for WorkflowId.
- * @param id - raw string ID from workflow operations
- */
-export function toWorkflowId(id: string): WorkflowId {
-  return id as WorkflowId;
-}
-
-/**
- * Constructor for SessionKey.
- * @param key - raw string key from session operations
- */
-export function toSessionKey(key: string): SessionKey {
-  return key as SessionKey;
-}
-
-/**
- * Type predicate: true if value is a QueueItemId.
- */
-export function isQueueItemId(value: unknown): value is QueueItemId {
-  return typeof value === 'string';
-}
-
-/**
- * Type predicate: true if value is a WorkflowId.
- */
-export function isWorkflowId(value: unknown): value is WorkflowId {
-  return typeof value === 'string';
-}
-
-/**
- * Type predicate: true if value is a SessionKey.
- */
-export function isSessionKey(value: unknown): value is SessionKey {
-  return typeof value === 'string';
-}
+export type {
+  Brand,
+  QueueItemId,
+  WorkflowId,
+  SessionKey,
+} from '@principles/core/runtime-v2';
+
+export {
+  toQueueItemId,
+  toWorkflowId,
+  toSessionKey,
+  isQueueItemId,
+  isWorkflowId,
+  isSessionKey,
+} from '@principles/core/runtime-v2';

package/src/types/runtime-summary.ts

@@ -1,49 +1,5 @@
-/**
- * Runtime truth represents the current state of the system.
- * Used for control decisions, Phase 3 eligibility, and real-time operations.
- * Sources: queue state, active session registry
- */
-export interface RuntimeTruth {
-  queueState: {
-    total: number;
-    pending: number;
-    inProgress: number;
-    completed: number;
-    lastUpdated: string;
-  };
-  activeSessions: string[];
-}
-
-/**
- * Analytics truth represents historical data and aggregated metrics.
- * Used for insights, trends, and supporting evidence (where explicitly allowed).
- * NOT used for control decisions or Phase 3 eligibility.
- * Sources: trajectory.db, daily-stats.json, control-ui DB
- */
-export interface AnalyticsTruth {
-  trajectoryData: {
-    totalTasks: number;
-    successRate: number;
-    timeoutRate: number;
-    lastUpdated: string;
-  };
-  dailyStats: {
-    toolCalls: number;
-    painSignals: number;
-    evolutionTasks: number;
-    lastUpdated: string;
-  };
-  trends: {
-    sevenDay: TrendMetrics;
-    thirtyDay: TrendMetrics;
-  };
-}
-
-/**
- * Trend metrics for analytics aggregation.
- */
-export interface TrendMetrics {
-  successRateChange: number;
-  toolCallVolumeChange: number;
-  painSignalRateChange: number;
-}
+export type {
+  RuntimeTruth,
+  AnalyticsTruth,
+  TrendMetrics,
+} from '@principles/core/runtime-v2';

package/src/utils/io.ts

@@ -1,6 +1,5 @@
 import * as path from 'path';
 import * as fs from 'fs';
-import { resolvePdPath } from '../core/paths.js';
 
 /**
  * Atomic file write — write to temp then rename to prevent partial writes on crash.
@@ -148,23 +147,12 @@ export function serializeKvLines(data: Record<string, any>): string {
   return lines.join('\n');
 }
 
-export function planStatus(projectDir: string): string {
-  const planPath = resolvePdPath(projectDir, 'PLAN');
-  try {
-    if (!fs.existsSync(planPath)) return '';
-    const content = fs.readFileSync(planPath, 'utf8');
-    const lines = content.split('\n');
-    for (const line of lines) {
-      if (line.startsWith('STATUS:')) {
-        const parts = line.split(':');
-        if (parts.length > 1) {
-           return parts[1].trim().split(/\s+/)[0] || '';
-        }
-      }
-    }
-  /* eslint-disable @typescript-eslint/no-unused-vars -- Reason: Error is intentionally ignored for graceful degradation */
-  } catch (_e) {
-    // Ignore read errors
-  }
-  return '';
+/**
+ * Normalize command arguments from PluginCommandContext.args.
+ * Handles string | string[] | undefined union by joining arrays with spaces.
+ */
+export function normalizeCommandArgs(args: string | string[] | undefined): string {
+  if (args === undefined || args === null) return '';
+  if (Array.isArray(args)) return args.join(' ');
+  return args;
 }

package/src/utils/retry.ts

@@ -307,7 +307,7 @@ export async function retryNetworkRequest<T>(
 }
 
 // =========================================================================
-// Dynamic Timeout Support (from dynamic-timeout.ts)
+// Dynamic Timeout Support
 // =========================================================================
 
 /** Minimum samples needed before trusting learned timeout values */

package/src/utils/shadow-fingerprint.ts

@@ -35,8 +35,8 @@ export function computeRuntimeShadowTaskFingerprint(
     label: event.label ?? '',
     mode: event.mode,
     threadRequested: event.threadRequested,
-    requesterChannel: event.requester?.channel ?? '',
-    requesterThreadId: event.requester?.threadId ?? '',
+    requesterChannel: (event.requester as { channel?: string })?.channel ?? '',
+    requesterThreadId: (event.requester as { threadId?: string })?.threadId ?? '',
   };
   return crypto.createHash('sha256').update(JSON.stringify(payload)).digest('hex').slice(0, RUNTIME_SHADOW_FINGERPRINT_HEX_LENGTH);
 }

package/src/utils/workspace-resolver.ts

@@ -8,6 +8,7 @@ import type { OpenClawPluginApi, PluginCommandContext } from '../openclaw-sdk.js
 import { validateWorkspaceDir, type WorkspaceResolutionContext } from '../core/workspace-dir-validation.js';
 import { resolveWorkspaceDir } from '../core/workspace-dir-service.js';
 import { resolveWorkspaceDirFromApi } from '../core/path-resolver.js';
+import * as path from 'path';
 
 /**
  * Resolve workspace directory for command execution.
@@ -93,3 +94,52 @@ export function resolveToolHookWorkspaceDirSafe(
 ): string | undefined {
   return resolveWorkspaceDir(api, ctx, { source });
 }
+
+export class WorkspaceResolutionError extends Error {
+  readonly reason: string;
+  readonly nextAction: string;
+
+  constructor(message: string, reason: string, nextAction: string) {
+    super(message);
+    this.name = 'WorkspaceResolutionError';
+    this.reason = reason;
+    this.nextAction = nextAction;
+  }
+
+  toJSON() {
+    return {
+      ok: false as const,
+      reason: this.reason,
+      message: this.message,
+      nextAction: this.nextAction,
+    };
+  }
+}
+
+export function resolveWorkspaceDirForRuntimeV2(
+  ctx: { workspaceDir?: string },
+  api: OpenClawPluginApi | undefined,
+  source: string,
+): string {
+  const explicit = ctx.workspaceDir;
+  if (!explicit || !explicit.trim()) {
+    throw new WorkspaceResolutionError(
+      `No explicit workspace directory for Runtime V2 entrypoint (${source}). ` +
+      'Provide workspaceDir in context. Runtime V2 does not use legacy discovery fallback.',
+      'workspace_dir_missing',
+      'Ensure the OpenClaw hook context includes workspaceDir, or set PD_WORKSPACE_DIR environment variable.',
+    );
+  }
+
+  const normalized = path.resolve(explicit.trim());
+  const validation = validateWorkspaceDir(normalized);
+  if (validation) {
+    throw new WorkspaceResolutionError(
+      `workspaceDir validation failed for ${source}: ${validation}`,
+      'workspace_dir_invalid',
+      'Provide a valid workspaceDir that is not the home directory, root, or empty.',
+    );
+  }
+
+  return normalized;
+}

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

@@ -17,8 +17,7 @@ As Principles Disciple, you must distinguish between two physical spaces:
 Make decisions based on relative paths in the **Project Battlefield**:
 
 - **Strategic Focus**: `./memory/STRATEGY.md`
-- **Physical Plan**: `./PLAN.md`
-- **Pain Signal**: `./.state/.pain_flag`
+- **Pain Signal**: Runtime V2 `PainSignalBridge` (`pd pain record` for manual trigger; `.state/.pain_flag` is legacy compatibility only)
 - **System Capabilities**: `./.state/SYSTEM_CAPABILITIES.json`
 
 ---
@@ -72,7 +71,7 @@ When you receive a heartbeat poll, don't just reply `HEARTBEAT_OK` every time. U
 
 ### What to Check (rotate through these):
 
-- **Pain & Evolution**: Check `.pain_flag`, `EVOLUTION_QUEUE.json`
+- **Pain & Evolution**: Check Runtime V2 diagnostics (`pd pain record`, candidates, ledger) and `EVOLUTION_QUEUE.json`; `.pain_flag` is legacy compatibility only
 - **Strategic Alignment**: Compare against `CURRENT_FOCUS.md`
 - **Environment Health**: Tool chain status, project root cleanliness
 
@@ -166,12 +165,13 @@ On platforms that support reactions (Discord, Slack), use emoji reactions natura
 You default to architect mode.
 
 - **L1 (Direct Execution)**: Single-file tweaks, doc maintenance → do it directly
-- **L2 (Delegation Protocol)**: Major changes → **MUST** update `./PLAN.md` and use `pd_spawn_agent` tool
+- **L2 (Delegation Protocol)**: Major changes → recommended to describe the plan and get owner confirmation before executing
 
-### State Machine Gating
+### Planning Guidance
 
-- **Single source of truth**: `./PLAN.md`
-- **Physical interception**: Plugin activated. If `PLAN.md` is not `READY` and you attempt to modify risk paths, calls will be blocked
+- For complex tasks, consider drafting a plan document and getting owner approval before making large changes
+- This is a behavioral suggestion, not a built-in gate — PD does not enforce plan-before-action by default
+- If an owner-approved RuleHost rule enforces planning behavior, that rule takes effect automatically
 - **Prevent pollution**: Never write execution details back to strategic documents
 
 ---

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

@@ -16,7 +16,7 @@ Short, explicit instructions for what OpenClaw should do on startup. If the task
 2. **Confirm workspace**: Check current working directory is correct
 3. **Read identity files**: `SOUL.md`, `USER.md`, `IDENTITY.md`
 4. **Check memory state**: Read today's and yesterday's `memory/YYYY-MM-DD.md`
-5. **Check pain signals**: See if `.state/.pain_flag` exists
+5. **Check Runtime V2 pain diagnostics**: use `pd candidate list` / ledger state; `.state/.pain_flag` is legacy compatibility only
 
 ---
 

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

@@ -8,7 +8,7 @@ On each heartbeat, run these core checks. **Don't just reply `HEARTBEAT_OK` ever
 
 ## 🩹 Pain & Evolution Check
 
-- [ ] **`.state/.pain_flag`** — Any unprocessed pain signals?
+- [ ] **Runtime V2 pain** — Check `pd candidate list` / ledger if a recent `pd pain record` or tool failure occurred. `.state/.pain_flag` is legacy compatibility only.
 - [ ] **`.state/evolution_queue.json`** — Any pending evolution tasks?
 - [ ] **`memory/logs/SYSTEM.log`** — Any unresolved high-priority issues?
 
@@ -71,4 +71,4 @@ On each heartbeat, run these core checks. **Don't just reply `HEARTBEAT_OK` ever
 
 ---
 
-*If no issues and no action needed, reply `HEARTBEAT_OK` to save tokens.*
+*If no issues and no action needed, reply `HEARTBEAT_OK` to save tokens.*

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

@@ -39,8 +39,9 @@ LLMs are highly sensitive to XML tags; this structure is designed to boost instr
   <!-- 执行与物理限制 (Execution & Physical Constraints) -->
   <directive id="T-05" name="PHYSICAL_DEFENSE_AND_ORCHESTRATION">
     <trigger>When asked to perform a major refactoring, multi-file change (>2 files), or an architectural shift.</trigger>
-    <must>Limit your blast radius. You MUST draft a `PLAN.md` (status: READY). After any code change, you MUST run canary tests (e.g., `npm test`, linters) to verify integrity.</must>
-    <forbidden>Executing large-scale unstructured changes directly without a plan, or skipping post-modification validation.</forbidden>
+    <should>For complex changes, describe your plan and get owner confirmation before executing.</should>
+    <must>Limit your blast radius. After any code change, you MUST run canary tests (e.g., `npm test`, linters) to verify integrity.</must>
+    <forbidden>Executing large-scale unstructured changes directly, or skipping post-modification validation.</forbidden>
   </directive>
 
   <directive id="T-06" name="OCCAMS_RAZOR_MVC">