principles-disciple 1.201.0 → 1.202.0

package/dist/core/evolution-logger.d.ts

@@ -0,0 +1,137 @@
+/**
+ * EvolutionLogger - 进化流程日志服务
+ *
+ * 提供两层日志：
+ * - 技术层：结构化 JSON，包含 trace_id、stage、metadata
+ * - 用户层：中文摘要，便于小白用户理解
+ *
+ * 日志写入两个地方：
+ * 1. SYSTEM_LOG (system.jsonl) - 技术细节
+ * 2. evolution_events 表 (SQLite) - 结构化查询
+ */
+import type { TrajectoryDatabase } from './trajectory.js';
+export type EvolutionStage = 'pain_detected' | 'queued' | 'started' | 'analyzing' | 'principle_generated' | 'completed' | 'failed';
+export type EvolutionLogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface EvolutionLogEntry {
+    traceId: string;
+    stage: EvolutionStage;
+    level: EvolutionLogLevel;
+    message: string;
+    summary: string;
+    timestamp: string;
+    metadata?: Record<string, unknown>;
+    taskId?: string;
+    sessionId?: string;
+}
+export interface EvolutionLogInput {
+    traceId: string;
+    stage: EvolutionStage;
+    level?: EvolutionLogLevel;
+    message: string;
+    summary: string;
+    metadata?: Record<string, unknown>;
+    taskId?: string;
+    sessionId?: string;
+}
+export declare const STAGE_LABELS: Record<EvolutionStage, string>;
+export declare const STAGE_COLORS: Record<EvolutionStage, string>;
+/**
+ * 创建新的 trace_id
+ * 格式: ev_{timestamp}_{random}
+ * 使用 crypto.randomBytes 确保不可预测性
+ */
+export declare function createTraceId(): string;
+/**
+ * EvolutionLogger 类
+ * 管理进化流程的日志记录
+ */
+export declare class EvolutionLogger {
+    private readonly workspaceDir;
+    private readonly trajectory;
+    constructor(workspaceDir: string, trajectory?: TrajectoryDatabase);
+    /**
+     * 记录进化事件
+     * 同时写入 SYSTEM_LOG 和 evolution_events 表
+     */
+    log(input: EvolutionLogInput): void;
+    /**
+     * 记录 pain_detected 事件
+     */
+    logPainDetected(params: {
+        traceId: string;
+        source: string;
+        reason: string;
+        score: number;
+        toolName?: string;
+        filePath?: string;
+        sessionId?: string;
+    }): void;
+    /**
+     * 记录 queued 事件
+     */
+    logQueued(params: {
+        traceId: string;
+        taskId: string;
+        score: number;
+        source: string;
+        reason: string;
+    }): void;
+    /**
+     * 记录 started 事件
+     */
+    logStarted(params: {
+        traceId: string;
+        taskId: string;
+    }): void;
+    /**
+     * 记录 analyzing 事件
+     */
+    logAnalyzing(params: {
+        traceId: string;
+        taskId: string;
+        analysisType?: string;
+    }): void;
+    /**
+     * 记录 principle_generated 事件
+     */
+    logPrincipleGenerated(params: {
+        traceId: string;
+        taskId: string;
+        principleId: string;
+        principleText: string;
+    }): void;
+    /**
+     * 记录 completed 事件
+     */
+    logCompleted(params: {
+        traceId: string;
+        taskId: string;
+        resolution: 'marker_detected' | 'auto_completed_timeout' | 'manual' | 'late_marker_principle_created' | 'late_marker_no_principle' | 'diagnostician_timeout' | 'noise_classified' | 'duplicate' | 'serverDuplicate';
+        durationMs?: number;
+        principlesGenerated?: number;
+    }): void;
+    /**
+     * 记录 failed 事件
+     */
+    logFailed(params: {
+        traceId: string;
+        taskId: string;
+        error: string;
+        stack?: string;
+    }): void;
+}
+/**
+ * 获取 EvolutionLogger 实例（单例）
+ *
+ * 注意：带 trajectory 和不带 trajectory 的请求会返回不同的实例，
+ * 因为 trajectory 影响事件持久化行为。
+ */
+export declare function getEvolutionLogger(workspaceDir: string, trajectory?: TrajectoryDatabase): EvolutionLogger;
+/**
+ * 清理指定 workspace 的 logger 缓存
+ */
+export declare function disposeEvolutionLogger(workspaceDir: string): boolean;
+/**
+ * 清理所有 logger 缓存（用于测试或进程退出）
+ */
+export declare function disposeAllEvolutionLoggers(): void;

package/dist/core/evolution-reducer.d.ts

@@ -0,0 +1,116 @@
+import type { EvolutionLoopEvent, Principle, PrincipleDetectorSpec, PrincipleEvaluatorLevel, PrincipleSuggestedRule } from './evolution-types.js';
+export interface EvolutionReducer {
+    emit(_event: EvolutionLoopEvent): void;
+    emitSync(_event: EvolutionLoopEvent): void;
+    getEventLog(): EvolutionLoopEvent[];
+    getCandidatePrinciples(): Principle[];
+    getProbationPrinciples(): Principle[];
+    getActivePrinciples(): Principle[];
+    getPrincipleById(_id: string): Principle | null;
+    promote(_principleId: string, _reason?: string): void;
+    deprecate(_principleId: string, _reason: string): void;
+    rollbackPrinciple(_principleId: string, _reason: string): void;
+    recordProbationFeedback(_principleId: string, _success: boolean): void;
+    /**
+     * Creates a new principle with generalized trigger/action from diagnostician.
+     * Called after diagnostician analysis to create principle directly.
+     */
+    createPrincipleFromDiagnosis(params: {
+        painId: string;
+        painType: 'tool_failure' | 'subagent_error' | 'user_frustration';
+        triggerPattern: string;
+        action: string;
+        source: string;
+        evaluability?: PrincipleEvaluatorLevel;
+        detectorMetadata?: PrincipleDetectorSpec;
+        /** Highly abstracted principle text — if absent, falls back to action-based title */
+        abstractedPrinciple?: string;
+        /** Associated core axiom (e.g., "T-01") */
+        coreAxiomId?: string;
+        priority?: 'P0' | 'P1' | 'P2';
+        scope?: 'general' | 'domain';
+        domain?: string;
+        suggestedRules?: PrincipleSuggestedRule[];
+    }): string | null;
+    getStats(): {
+        candidateCount: number;
+        probationCount: number;
+        activeCount: number;
+        deprecatedCount: number;
+        lastPromotedAt: string | null;
+    };
+}
+export declare class EvolutionReducerImpl implements EvolutionReducer {
+    private readonly streamPath;
+    private readonly lockTargetPath;
+    private readonly blacklistPath;
+    private readonly principlesPath;
+    private readonly workspaceDir;
+    private readonly stateDir;
+    private readonly memoryEvents;
+    private readonly principles;
+    private readonly failureStreak;
+    private lastPromotedAt;
+    private isReplaying;
+    constructor(opts: {
+        workspaceDir: string;
+        stateDir?: string;
+    });
+    emit(event: EvolutionLoopEvent): void;
+    emitSync(event: EvolutionLoopEvent): void;
+    getEventLog(): EvolutionLoopEvent[];
+    getCandidatePrinciples(): Principle[];
+    getProbationPrinciples(): Principle[];
+    getActivePrinciples(): Principle[];
+    getPrincipleById(id: string): Principle | null;
+    promote(principleId: string, reason?: string): void;
+    deprecate(principleId: string, reason: string): void;
+    rollbackPrinciple(principleId: string, reason: string): void;
+    recordProbationFeedback(principleId: string, success: boolean): void;
+    /**
+     * Creates a new principle with generalized trigger/action from diagnostician.
+     * Called after diagnostician analysis to create principle directly (no intermediate overfitted principle).
+     * @returns the new principle ID, or null if creation failed
+     */
+    createPrincipleFromDiagnosis(params: {
+        painId: string;
+        painType: 'tool_failure' | 'subagent_error' | 'user_frustration';
+        triggerPattern: string;
+        action: string;
+        source: string;
+        evaluability?: PrincipleEvaluatorLevel;
+        detectorMetadata?: PrincipleDetectorSpec;
+        abstractedPrinciple?: string;
+        coreAxiomId?: string;
+        priority?: 'P0' | 'P1' | 'P2';
+        scope?: 'general' | 'domain';
+        domain?: string;
+        suggestedRules?: PrincipleSuggestedRule[];
+    }): string | null;
+    private syncPrincipleToFile;
+    private static detectPrincipleLanguage;
+    private static formatPrincipleForFile;
+    getStats(): {
+        candidateCount: number;
+        probationCount: number;
+        activeCount: number;
+        deprecatedCount: number;
+        lastPromotedAt: string | null;
+    };
+    private ensureDirs;
+    private loadFromStream;
+    private applyEvent;
+    private onCandidateCreated;
+    private onPrinciplePromoted;
+    private onPrincipleDeprecated;
+    private onPrincipleRolledBack;
+    private onPainDetected;
+    private updateFailureStreakFromPain;
+    private nextPrincipleId;
+    private getByStatus;
+    private sweepExpiredProbation;
+    private persistBlacklist;
+    private loadBlacklist;
+    private isBlacklisted;
+}
+export declare function stableContentHash(input: string): string;

package/dist/core/evolution-types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Evolution Points System V2.0 - MVP
+ *
+ * Canonical definitions moved to @principles/core/runtime-v2/evolution/
+ * This file re-exports everything for backward compatibility.
+ *
+ * NOTE: Principle → EvolutionPrinciple, PrincipleStatus → EvolutionPrincipleStatus
+ *       to avoid collision with runtime-v2/types/principle-schema.ts Principle.
+ *       Backward-compatible aliases are provided below.
+ */
+import type { TaskKind, TaskPriority } from './trajectory-types.js';
+import type { EvolutionPrinciple as EvolutionPrincipleType, EvolutionPrincipleStatus as EvolutionPrincipleStatusType, EvolutionPrincipleSuggestedRule as EvolutionPrincipleSuggestedRuleType, EvolutionPrincipleValueMetricsSnapshot as EvolutionPrincipleValueMetricsSnapshotType, EvolutionPainDetectedData as EvolutionPainDetectedDataType } from '@principles/core/runtime-v2';
+export { EvolutionTier, TIER_DEFINITIONS, getTierDefinition, getTierByPoints, TASK_DIFFICULTY_CONFIG, DEFAULT_EVOLUTION_CONFIG, isCompleteDetectorMetadata, } from '@principles/core/runtime-v2';
+export type { TierPermissions, TierDefinition, TaskDifficulty, TaskDifficultyConfig, EvolutionEventType, EvolutionEvent, EvolutionScorecard, EvolutionStats, EvolutionStorage, EvolutionConfig, ArchivedEventStats, GateDecision, ToolCallContext, TierPromotionEvent, EvolutionPrincipleStatus, PrincipleEvaluatorLevel, Evaluability, PrincipleDetectorSpec, EvolutionPrinciple, EvolutionPrincipleSuggestedRule, EvolutionPrincipleValueMetricsSnapshot, EvolutionLoopEventType, EvolutionPainDetectedData, CandidateCreatedData, PrinciplePromotedData, PrincipleDeprecatedData, PrincipleRolledBackData, CircuitBreakerOpenedData, LegacyImportData, EvolutionLoopEvent, } from '@principles/core/runtime-v2';
+/** @deprecated Use EvolutionPrinciple instead. Alias for backward compatibility. */
+export type Principle = EvolutionPrincipleType;
+/** @deprecated Use EvolutionPrincipleStatus instead. Alias for backward compatibility. */
+export type PrincipleStatus = EvolutionPrincipleStatusType;
+/** @deprecated Use EvolutionPrincipleSuggestedRule instead. Alias for backward compatibility. */
+export type PrincipleSuggestedRule = EvolutionPrincipleSuggestedRuleType;
+/** @deprecated Use EvolutionPrincipleValueMetricsSnapshot instead. Alias for backward compatibility. */
+export type PrincipleValueMetricsSnapshot = EvolutionPrincipleValueMetricsSnapshotType;
+/** @deprecated Use EvolutionPainDetectedData instead. Alias for backward compatibility. */
+export type PainDetectedData = EvolutionPainDetectedDataType;
+export type QueueStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'canceled';
+export type TaskResolution = 'marker_detected' | 'auto_completed_timeout' | 'failed_max_retries' | 'runtime_unavailable' | 'canceled' | 'late_marker_principle_created' | 'late_marker_no_principle' | 'stub_fallback' | 'skipped_thin_violation' | 'success' | 'failure' | 'skipped' | 'noise_classified' | 'retired';
+export interface EvolutionQueueItem {
+    id: string;
+    taskKind: TaskKind;
+    priority: TaskPriority;
+    source: string;
+    traceId?: string;
+    task?: string;
+    score: number;
+    reason: string;
+    timestamp: string;
+    enqueued_at?: string;
+    started_at?: string;
+    completed_at?: string;
+    assigned_session_key?: string;
+    trigger_text_preview?: string;
+    status: QueueStatus;
+    resolution?: TaskResolution;
+    session_id?: string;
+    agent_id?: string;
+    retryCount: number;
+    maxRetries: number;
+    lastError?: string;
+    resultRef?: string;
+}

package/dist/core/file-store.d.ts

@@ -0,0 +1,41 @@
+/**
+ * FileStore — generic interface for atomic JSON file persistence.
+ *
+ * Encapsulates the common "read JSON → modify → atomic write" pattern
+ * used throughout core modules. Implementations handle:
+ * - Missing file → default data
+ * - Malformed file → default data (graceful degradation)
+ * - Atomic writes via temp + rename
+ */
+export interface FileStore<T> {
+    /** Load data from file, returning defaults if missing or corrupt. */
+    load(): T;
+    /** Atomically write data to file. */
+    save(data: T): void;
+    /**
+     * Read-modify-write cycle.
+     * The mutate function receives current data and may modify it in place.
+     * The modified data is saved automatically after fn completes.
+     * If fn throws, the write is aborted and the file is unchanged.
+     *
+     * Returns the value returned by fn (useful for extracting computed results).
+     *
+     * NOTE: This method is NOT thread-safe. Caller must ensure no concurrent
+     * writes to the same file — use withLock() or equivalent to serialize access.
+     */
+    mutate<R>(fn: (data: T) => R): R;
+}
+/**
+ * JSON-backed FileStore implementation.
+ *
+ * Uses atomicWriteFileSync for crash-safe writes.
+ * Handles missing/corrupt files by returning the provided default factory result.
+ */
+export declare class JsonFileStore<T extends object> implements FileStore<T> {
+    private readonly filePath;
+    private readonly defaultFactory;
+    constructor(filePath: string, defaultFactory: () => T);
+    load(): T;
+    save(data: T): void;
+    mutate<R>(fn: (data: T) => R): R;
+}

package/dist/core/focus-history.d.ts

@@ -0,0 +1,50 @@
+import type { WorkingMemorySnapshot } from '@principles/core/prompt-builder';
+export { extractVersion, extractDate, extractSummary, parseWorkingMemorySection, workingMemoryToInjection, extractMilestones, validateCurrentFocus, mergeWorkingMemory, compressFocusContent, } from '@principles/core/prompt-builder';
+export type { FileArtifact, WorkingMemorySnapshot, } from '@principles/core/prompt-builder';
+interface CompressionConfig {
+    lineThreshold: number;
+    sizeThreshold: number;
+    intervalMs: number;
+    keepCompletedTasks: number;
+    maxWorkingMemoryArtifacts: number;
+}
+export declare function getHistoryDir(focusPath: string): string;
+export declare function backupToHistory(focusPath: string, content: string): string | null;
+export declare function cleanupHistory(focusPath: string, maxFiles?: number): void;
+export declare function getHistoryVersions(focusPath: string, count?: number): Promise<string[]>;
+export declare function compressFocus(focusPath: string, newContent: string): {
+    backupPath: string | null;
+    cleanedCount: number;
+};
+export declare function extractWorkingMemory(messages: {
+    role?: string;
+    content?: string | unknown[];
+}[], workspaceDir?: string): WorkingMemorySnapshot;
+export declare function cleanupStaleInfo(content: string, workspaceDir?: string, config?: CompressionConfig): string;
+export declare function autoCompressFocus(focusPath: string, workspaceDir?: string, stateDir?: string): {
+    compressed: boolean;
+    oldLines: number;
+    newLines: number;
+    milestonesArchived: boolean;
+    backupPath: string | null;
+    reason: string;
+    newContent?: string;
+};
+export declare function needsAutoCompression(focusPath: string, stateDir?: string): boolean;
+export declare function archiveMilestonesToDaily(workspaceDir: string, milestones: {
+    completedTasks: string[];
+    fileArtifacts: string[];
+}, version: string): string | null;
+export declare function recoverFromTemplate(focusPath: string, extensionRoot: string): {
+    success: boolean;
+    error?: string;
+    templatePath?: string;
+};
+export declare function safeReadCurrentFocus(focusPath: string, extensionRoot: string, logger?: {
+    warn?: (msg: string) => void;
+    info?: (msg: string) => void;
+}): {
+    content: string;
+    recovered: boolean;
+    validationErrors: string[];
+};

package/dist/core/hygiene/tracker.d.ts

@@ -0,0 +1,22 @@
+import type { HygieneStats, PersistenceAction } from '../../types/hygiene-types.js';
+import type { PluginLogger } from '../../openclaw-sdk.js';
+/**
+ * HygieneTracker - Tracks agent behavior regarding workspace organization and persistence.
+ */
+export declare class HygieneTracker {
+    private readonly statsFile;
+    private currentStats;
+    private readonly logger?;
+    constructor(stateDir: string, logger?: PluginLogger);
+    private loadStats;
+    private saveStats;
+    /**
+     * Records a persistence action (writing to memory or plan).
+     */
+    recordPersistence(action: PersistenceAction): void;
+    /**
+     * Records a grooming action (cleaning up the workspace).
+     */
+    recordGrooming(): void;
+    getStats(): HygieneStats;
+}

package/dist/core/init.d.ts

@@ -0,0 +1,30 @@
+import type { OpenClawPluginApi, PluginLogger } from '../openclaw-sdk.js';
+/**
+ * Ensures that the workspace has the necessary template files for Principles Disciple.
+ * This function flattens 'core' templates to the root so OpenClaw can find them.
+ */
+export declare function ensureWorkspaceTemplates(api: OpenClawPluginApi, workspaceDir: string, language?: string): void;
+/**
+ * Core thinking model definitions (T-01 through T-10).
+ * Derived from the Core Principle Registry — the single source of truth.
+ */
+export declare const CORE_THINKING_MODELS: Array<{
+    id: string;
+    name: string;
+    description: string;
+}>;
+/**
+ * Initialize core thinking models into the training store if it's empty.
+ * This ensures every workspace has evaluable principles for nocturnal reflection.
+ *
+ * @param stateDir - State directory path
+ * @param logger - Plugin logger
+ * @returns true if initialization was performed, false if already had principles
+ */
+export declare function ensureCorePrinciples(stateDir: string, logger: PluginLogger): boolean;
+/**
+ * Ensures that the state directory has the necessary files (like pain_dictionary.json).
+ */
+export declare function ensureStateTemplates(ctx: {
+    logger: PluginLogger;
+}, stateDir: string, language?: string): void;

package/dist/core/intent-doc-reader-adapter.d.ts

@@ -0,0 +1,36 @@
+/**
+ * PRI-468 — Plugin adapter implementing the core `IntentDocReader` port.
+ *
+ * Bridges the plugin-owned `safeReadIntentDoc()` I/O function to the
+ * core-owned `IntentDocReader` interface so Stage A (in core) can read
+ * INTENT.md without core performing any filesystem I/O.
+ *
+ * This adapter only MAPS types — it adds no new I/O, no new flag checks,
+ * and no new telemetry. The underlying `safeReadIntentDoc()` already
+ * performs the flag-first check (SPEC §12), TTL+mtime cache, and size cap.
+ *
+ * ERR checklist:
+ *   EP-01 / ERR-001: never `as` — field-by-field mapping with typeof checks
+ *   EP-02 / ERR-025: plugin I/O file, whitelisted in architecture-regression
+ *   EP-03 / ERR-002: every degraded path flows through with reason + nextAction
+ *
+ * Architecture: this file is I/O (delegates to fs-reading safeReadIntentDoc).
+ * It will be added to KNOWN_PLUGIN_CORE_FILES in architecture-regression.test.ts.
+ */
+import type { IntentDocReader, IntentLang } from '@principles/core/runtime-v2';
+/**
+ * Detect which language's INTENT file exists on disk.
+ * Priority: zh-CN first, then en. Defaults to zh-CN if neither exists.
+ *
+ * This lets hooks avoid hardcoding a single language — the Owner may have
+ * created either INTENT.zh-CN.md or INTENT.en.md.
+ */
+export declare function resolveIntentLang(workspaceDir: string): IntentLang;
+/**
+ * Create an IntentDocReader bound to a specific workspace and language.
+ *
+ * The returned reader is stateless beyond the (workspace, lang) binding — each
+ * `readIntentDoc()` call delegates to `safeReadIntentDoc()`, which owns
+ * the TTL+mtime cache keyed by `${workspaceDir}:${lang}`.
+ */
+export declare function createIntentDocReader(workspaceDir: string, lang: IntentLang): IntentDocReader;

package/dist/core/intent-doc-reader.d.ts

@@ -0,0 +1,89 @@
+/**
+ * PRI-467 — safeReadIntentDoc: plugin I/O wrapper for reading INTENT.md.
+ *
+ * Reads `.principles/INTENT.md` with:
+ * - Feature flag check FIRST (SPEC §12: flag off → flag_disabled without fs)
+ * - TTL + mtime cache (60s TTL, mtime check) mirroring prompt.ts cachedReadFile
+ * - 32KB size cap (INTENT_MAX_BYTES)
+ * - Never throws — all errors return structured `reason` + `nextAction`
+ *
+ * Trust boundary (SPEC §12.2):
+ * - Raw content is returned for the pure builder to escape; this reader does
+ *   NOT escape or bound the content for prompt injection. The pure builder
+ *   `buildIntentFrictionBlock` handles escaping + bounding.
+ *
+ * ERR checklist:
+ * EP-01 / ERR-001, ERR-005: raw content validated with typeof, never `as`
+ * EP-02 / ERR-025, ERR-070: production path; plugin I/O file in the whitelist
+ * EP-03 / ERR-002, ERR-014: every degraded path returns structured reason + nextAction
+ * EP-09: tests use real fs writes in temp dirs
+ *
+ * Architecture: this file is I/O (fs, path). It is whitelisted in
+ * architecture-regression.test.ts KNOWN_PLUGIN_CORE_FILES.
+ */
+import { type IntentDocSections, type IntentDocWarning, type IntentLang } from '@principles/core/runtime-v2';
+export type SafeReadIntentDocReason = 'flag_disabled' | 'not_found' | 'oversized' | 'read_error';
+export interface IntentDoc {
+    /** Raw INTENT.md content (unescaped — caller escapes for prompt injection). */
+    raw: string;
+    /** Parsed sections from the raw content. */
+    sections: IntentDocSections;
+    /** SHA-256 content hash for deduplication and audit. */
+    contentHash: string;
+    /** Absolute path to the INTENT.md file. */
+    path: string;
+    /** ISO timestamp when the doc was read. */
+    readAt: string;
+    /** Validation warnings (missing/empty/too_vague sections). */
+    warnings: IntentDocWarning[];
+}
+export interface SafeReadIntentDocResult {
+    /** True when the doc was successfully read and parsed. */
+    ok: boolean;
+    /** True when the INTENT.md file exists on disk. */
+    found: boolean;
+    /** True when the intent_engineering flag is enabled. */
+    flagEnabled: boolean;
+    /** The parsed IntentDoc, present only when ok=true. */
+    doc?: IntentDoc;
+    /** Structured reason for a degraded path (present when ok=false). */
+    reason?: SafeReadIntentDocReason;
+    /** Next action for the operator (present when ok=false). */
+    nextAction?: string;
+    /** Validation warnings (always present, empty when no warnings). */
+    warnings: IntentDocWarning[];
+}
+/**
+ * Reset the intent doc cache for test isolation.
+ *
+ * - No args: clear the whole cache.
+ * - workspaceDir only: delete all entries for that workspace (any lang).
+ *   Keys are formatted as `${workspaceDir}:${lang}`, so we match by prefix.
+ * - workspaceDir + lang: delete the single `${workspaceDir}:${lang}` entry.
+ *
+ * Note: prompt.ts resetPromptStateForTest passes workspaceDir only — the
+ * previous signature treated it as a literal cache key, which never matched
+ * the `${workspaceDir}:${lang}` format and silently left entries behind.
+ */
+export declare function resetIntentDocCacheForTest(workspaceDir?: string, lang?: IntentLang): void;
+/**
+ * Safely read INTENT.md for prompt injection.
+ *
+ * Contract (SPEC §12):
+ * 1. Flag check FIRST via loadFeatureFlagFromConfig. Flag off → flag_disabled
+ *    WITHOUT any fs access to INTENT.md.
+ * 2. Flag on → check TTL + mtime cache. If cached and fresh → return cached.
+ * 3. Otherwise → stat the file (oversized check), read, parse, validate, cache.
+ * 4. Never throws — all errors return structured reason + nextAction.
+ *
+ * @param workspaceDir - Absolute path to the workspace root
+ * @param lang - Mandatory language code ('zh-CN' | 'en'); selects INTENT.${lang}.md
+ * @param options - Optional logger for debug-level diagnostics
+ * @returns SafeReadIntentDocResult (never throws)
+ */
+export declare function safeReadIntentDoc(workspaceDir: string, lang: IntentLang, options?: {
+    logger?: {
+        debug?: (msg: string) => void;
+        warn?: (msg: string) => void;
+    };
+}): SafeReadIntentDocResult;

package/dist/core/migration.d.ts

@@ -0,0 +1,6 @@
+import type { OpenClawPluginApi } from '../openclaw-sdk.js';
+/**
+ * Handles migration of Principles Disciple files from legacy directories
+ * (docs/ and memory/.state/) to the new hidden directory structure (.principles/ and .state/).
+ */
+export declare function migrateDirectoryStructure(api: OpenClawPluginApi, workspaceDir: string): void;

package/dist/core/pain-diagnostic-gate.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Pain Diagnostic Gate — PRI-446 thin adapter
+ *
+ * @deprecated PRI-454 — Gate A (PainDiagnosticGate) is superseded by Gate B
+ * (TriggerController + EvidenceTriage). This module remains as the rollback
+ * path when `painEvidenceAdmission` or `painEvidenceAdmissionDefault` flags
+ * are OFF. Do not add new callers. New admission logic must use
+ * `evaluateTriggerController` from runtime-v2/evidence-triage.
+ *
+ * Disposition: Archive (do not delete) per PRI-454 plan step 6.
+ * Removal conditions: Both flags confirmed ON in production for 30 days,
+ * and all 5 MVP paths verified on Gate B. See
+ * docs/plans/2026-06-pain-evidence-admission-track.md.
+ *
+ * The pure decision logic (threshold tree, cooldown comparison, episode-key
+ * construction) now lives in principles-core
+ * (runtime-v2/pain-gate/pain-diagnostic-gate-policy.ts). This file is the
+ * stateful adapter that owns:
+ *   - the cooldown Map (lastDiagnosedAtByEpisode)
+ *   - Date.now() injection
+ *   - SystemLogger for unknown-source telemetry
+ *
+ * It preserves the original export names (evaluatePainDiagnosticGate,
+ * isCooldownActiveForEpisode, resetPainDiagnosticGateForTest) so all 5 callers
+ * (gate-block-helper, llm, pain, prompt x2) and the characterization test keep
+ * working unchanged.
+ *
+ * ERR checklist:
+ * - ERR-011: this is a stateful adapter delegating to core pure logic.
+ */
+import { type PainDiagnosticSource, type PainDiagnosticGateReason, type PainDiagnosticGateInput, type PainDiagnosticGateDecision } from '@principles/core/runtime-v2';
+export type { PainDiagnosticSource, PainDiagnosticGateReason, PainDiagnosticGateInput, PainDiagnosticGateDecision, };
+export declare function resetPainDiagnosticGateForTest(): void;
+/**
+ * Check whether cooldown is currently active for a given episode.
+ * Used by the trigger controller (PEAT-B2) to align its cooldown decision
+ * with the PainDiagnosticGate's cooldown state.
+ */
+export declare function isCooldownActiveForEpisode(source: string, sessionId: string | undefined, errorHash: string | undefined, cooldownMs?: number): boolean;
+/**
+ * Evaluate the pain diagnostic gate. Delegates the pure decision to core and,
+ * when the decision is to diagnose, records the current time against the
+ * episode so subsequent calls within the cooldown window are suppressed.
+ */
+export declare function evaluatePainDiagnosticGate(input: PainDiagnosticGateInput): PainDiagnosticGateDecision;

package/dist/core/pain.d.ts

@@ -0,0 +1,24 @@
+export declare function computePainScore(rc: number, isSpiral: boolean, missingTestCommand: boolean, softScore: number, projectDir?: string): number;
+/**
+ * Track principle value metrics when a pain signal is written.
+ * This is observation-only — it does NOT affect the pain flag write flow.
+ * If any principle matches the pain signal, its painPreventedCount is incremented.
+ * Errors are silently ignored to avoid disrupting the pain pipeline.
+ */
+export declare function trackPrincipleValue(workspaceDir: string, painData: {
+    reason?: string;
+    source?: string;
+    score?: string;
+}, getActivePrinciples: () => {
+    id: string;
+    trigger: string;
+    valueMetrics?: {
+        painPreventedCount: number;
+        lastPainPreventedAt?: string;
+        calculatedAt: string;
+    };
+}[], updatePrincipleMetrics: (_id: string, _metrics: {
+    painPreventedCount: number;
+    lastPainPreventedAt: string;
+    calculatedAt: string;
+}) => void): void;