principles-disciple 1.7.5 → 1.7.6

package/dist/commands/evolution-status.js

@@ -1,24 +1,6 @@
 import { EvolutionReducerImpl } from '../core/evolution-reducer.js';
 import { normalizeLanguage } from '../i18n/commands.js';
 import { RuntimeSummaryService } from '../service/runtime-summary-service.js';
-function formatAge(ageSeconds, lang) {
-    if (ageSeconds === null) {
-        return '--';
-    }
-    if (ageSeconds < 60) {
-        return lang === 'zh' ? `${ageSeconds} \u79d2` : `${ageSeconds}s`;
-    }
-    const minutes = Math.floor(ageSeconds / 60);
-    if (minutes < 60) {
-        return lang === 'zh' ? `${minutes} \u5206\u949f` : `${minutes}m`;
-    }
-    const hours = Math.floor(minutes / 60);
-    if (hours < 24) {
-        return lang === 'zh' ? `${hours} \u5c0f\u65f6` : `${hours}h`;
-    }
-    const days = Math.floor(hours / 24);
-    return lang === 'zh' ? `${days} \u5929` : `${days}d`;
-}
 function formatNumber(value) {
     if (value === null || Number.isNaN(value)) {
         return '--';
@@ -45,6 +27,7 @@ function buildEnglishOutput(workspaceDir, sessionId, warnings, stats, summary) {
         '',
         'Control Plane',
         `- Legacy Trust: ${formatNumber(summary.legacyTrust.score)}/100 (stage ${formatStage(summary.legacyTrust.stage)}, legacy/frozen, ${summary.legacyTrust.rewardPolicy})`,
+        `- Runtime Trust Truth: score ${formatNumber(summary.runtime.currentTrustScore)}, classification ${summary.runtime.workspaceState.trustClassification}, frozen ${summary.runtime.workspaceState.frozen === null ? '--' : String(summary.runtime.workspaceState.frozen)}`,
         `- Session GFI: current ${formatNumber(summary.gfi.current)}, peak ${formatNumber(summary.gfi.peak)} (${summary.gfi.dataQuality})`,
         `- GFI Sources: ${formatSources(summary.gfi.sources)}`,
         `- Pain Flag: ${summary.pain.activeFlag ? 'active' : 'inactive'}${summary.pain.activeFlagSource ? ` (${summary.pain.activeFlagSource})` : ''}`,
@@ -53,9 +36,11 @@ function buildEnglishOutput(workspaceDir, sessionId, warnings, stats, summary) {
         '',
         'Evolution',
         `- Queue: pending ${summary.evolution.queue.pending}, in_progress ${summary.evolution.queue.inProgress}, completed ${summary.evolution.queue.completed} (${summary.evolution.dataQuality})`,
-        `- Directive (derived from queue, compatibility only): ${summary.evolution.directive.exists ? 'present' : 'missing'}, active ${summary.evolution.directive.active === null ? '--' : summary.evolution.directive.active ? 'yes' : 'no'}, age ${formatAge(summary.evolution.directive.ageSeconds, 'en')}`,
-        `- Directive Task: ${summary.evolution.directive.taskPreview ?? '--'}`,
-        `- Phase 3: ready ${summary.phase3.phase3ShadowEligible ? 'yes' : 'no'}, queueTruthReady ${summary.phase3.queueTruthReady ? 'yes' : 'no'}, trustInputReady ${summary.phase3.trustInputReady ? 'yes' : 'no'}, eligible ${summary.phase3.evolutionEligible}, rejected ${summary.phase3.evolutionRejected}${summary.phase3.evolutionRejectedReasons.length > 0 ? ` (${summary.phase3.evolutionRejectedReasons.slice(0, 3).join(', ')})` : ''}${summary.phase3.trustRejectedReasons.length > 0 ? `; trust ${summary.phase3.trustRejectedReasons.slice(0, 2).join(', ')}` : ''}`,
+        `- Legacy Directive File: ${summary.phase3.legacyDirectiveFilePresent ? 'present' : 'missing'} (compatibility-only display artifact)`,
+        `- Note: Legacy directive file is NOT a truth source for Phase 3 eligibility. Queue is the only authoritative execution truth source.`,
+        `- Active Evolution Task: ${summary.evolution.directive.taskPreview ?? '--'}`,
+        `- Phase 3: ready ${summary.phase3.phase3ShadowEligible ? 'yes' : 'no'}, queueTruthReady ${summary.phase3.queueTruthReady ? 'yes' : 'no'}, trustInputReady ${summary.phase3.trustInputReady ? 'yes' : 'no'}, eligible ${summary.phase3.evolutionEligible}, reference_only ${summary.phase3.evolutionReferenceOnly}, rejected ${summary.phase3.evolutionRejected}${summary.phase3.evolutionReferenceOnlyReasons.length > 0 ? ` (reference ${summary.phase3.evolutionReferenceOnlyReasons.slice(0, 2).join(', ')})` : ''}${summary.phase3.evolutionRejectedReasons.length > 0 ? ` (${summary.phase3.evolutionRejectedReasons.slice(0, 3).join(', ')})` : ''}${summary.phase3.trustRejectedReasons.length > 0 ? `; trust ${summary.phase3.trustRejectedReasons.slice(0, 2).join(', ')}` : ''}`,
+        `- Phase 3 Legacy Directive File: ${summary.phase3.directiveStatus} (${summary.phase3.directiveIgnoredReason})`,
         '',
         'Principles',
         `- candidate principles: ${stats.candidateCount}`,
@@ -79,34 +64,37 @@ function buildEnglishOutput(workspaceDir, sessionId, warnings, stats, summary) {
 }
 function buildChineseOutput(workspaceDir, sessionId, warnings, stats, summary) {
     const lines = [
-        '\u8fdb\u5316\u72b6\u6001',
+        '进化状态',
         '================',
         '',
-        '\u63a7\u5236\u9762',
-        `- Legacy Trust: ${formatNumber(summary.legacyTrust.score)}/100\uff08\u9636\u6bb5 ${formatStage(summary.legacyTrust.stage)}\uff0clegacy/frozen\uff0c${summary.legacyTrust.rewardPolicy}\uff09`,
-        `- \u4f1a\u8bdd GFI: \u5f53\u524d ${formatNumber(summary.gfi.current)}\uff0c\u5cf0\u503c ${formatNumber(summary.gfi.peak)}\uff08${summary.gfi.dataQuality}\uff09`,
-        `- GFI \u6765\u6e90: ${formatSources(summary.gfi.sources)}`,
-        `- Pain Flag: ${summary.pain.activeFlag ? 'active' : 'inactive'}${summary.pain.activeFlagSource ? `\uff08${summary.pain.activeFlagSource}\uff09` : ''}`,
-        `- \u6700\u8fd1 Pain \u4fe1\u53f7: ${summary.pain.lastSignal ? `${summary.pain.lastSignal.source}${summary.pain.lastSignal.reason ? ` - ${summary.pain.lastSignal.reason}` : ''}` : '--'}`,
-        `- Gate \u4e8b\u4ef6: block ${formatNumber(summary.gate.recentBlocks)}\uff0cbypass ${formatNumber(summary.gate.recentBypasses)}\uff08${summary.gate.dataQuality}\uff09`,
+        '控制面',
+        `- Legacy Trust: ${formatNumber(summary.legacyTrust.score)}/100（阶段 ${formatStage(summary.legacyTrust.stage)}，legacy/frozen，${summary.legacyTrust.rewardPolicy}）`,
+        `- Runtime Trust Truth: score ${formatNumber(summary.runtime.currentTrustScore)}，classification ${summary.runtime.workspaceState.trustClassification}，frozen ${summary.runtime.workspaceState.frozen === null ? '--' : String(summary.runtime.workspaceState.frozen)}`,
+        `- 会话 GFI: 当前 ${formatNumber(summary.gfi.current)}，峰值 ${formatNumber(summary.gfi.peak)}（${summary.gfi.dataQuality}）`,
+        `- GFI 来源: ${formatSources(summary.gfi.sources)}`,
+        `- Pain Flag: ${summary.pain.activeFlag ? 'active' : 'inactive'}${summary.pain.activeFlagSource ? `（${summary.pain.activeFlagSource}）` : ''}`,
+        `- 最近 Pain 信号: ${summary.pain.lastSignal ? `${summary.pain.lastSignal.source}${summary.pain.lastSignal.reason ? ` - ${summary.pain.lastSignal.reason}` : ''}` : '--'}`,
+        `- Gate 事件: block ${formatNumber(summary.gate.recentBlocks)}，bypass ${formatNumber(summary.gate.recentBypasses)}（${summary.gate.dataQuality}）`,
         '',
-        '\u8fdb\u5316',
-        `- \u961f\u5217: pending ${summary.evolution.queue.pending}\uff0cin_progress ${summary.evolution.queue.inProgress}\uff0ccompleted ${summary.evolution.queue.completed}\uff08${summary.evolution.dataQuality}\uff09`,
-        `- Directive\uff08\u7531\u961f\u5217\u6d3e\u751f\uff0c\u517c\u5bb9\u4ec5\uff09: ${summary.evolution.directive.exists ? 'present' : 'missing'}\uff0cactive ${summary.evolution.directive.active === null ? '--' : summary.evolution.directive.active ? 'yes' : 'no'}\uff0cage ${formatAge(summary.evolution.directive.ageSeconds, 'zh')}`,
-        `- Directive \u4efb\u52a1: ${summary.evolution.directive.taskPreview ?? '--'}`,
-        `- Phase 3: ready ${summary.phase3.phase3ShadowEligible ? 'yes' : 'no'}\uff0cqueueTruthReady ${summary.phase3.queueTruthReady ? 'yes' : 'no'}\uff0ctrustInputReady ${summary.phase3.trustInputReady ? 'yes' : 'no'}\uff0celigible ${summary.phase3.evolutionEligible}\uff0crejected ${summary.phase3.evolutionRejected}${summary.phase3.evolutionRejectedReasons.length > 0 ? `\uff08${summary.phase3.evolutionRejectedReasons.slice(0, 3).join(', ')}\uff09` : ''}${summary.phase3.trustRejectedReasons.length > 0 ? `\uff1btrust ${summary.phase3.trustRejectedReasons.slice(0, 2).join(', ')}` : ''}`,
+        '进化',
+        `- 队列: pending ${summary.evolution.queue.pending}，in_progress ${summary.evolution.queue.inProgress}，completed ${summary.evolution.queue.completed}（${summary.evolution.dataQuality}）`,
+        `- Legacy Directive File: ${summary.phase3.legacyDirectiveFilePresent ? 'present' : 'missing'} （兼容仅显示产物）`,
+        `- 注：Legacy directive file 不是 Phase 3 合格性的真实源。队列是唯一权威的执行真实源。`,
+        `- Active Evolution Task: ${summary.evolution.directive.taskPreview ?? '--'}`,
+        `- Phase 3: ready ${summary.phase3.phase3ShadowEligible ? 'yes' : 'no'}，queueTruthReady ${summary.phase3.queueTruthReady ? 'yes' : 'no'}，trustInputReady ${summary.phase3.trustInputReady ? 'yes' : 'no'}，eligible ${summary.phase3.evolutionEligible}，reference_only ${summary.phase3.evolutionReferenceOnly}，rejected ${summary.phase3.evolutionRejected}${summary.phase3.evolutionReferenceOnlyReasons.length > 0 ? `（reference ${summary.phase3.evolutionReferenceOnlyReasons.slice(0, 2).join(', ')}）` : ''}${summary.phase3.evolutionRejectedReasons.length > 0 ? `（${summary.phase3.evolutionRejectedReasons.slice(0, 3).join(', ')}）` : ''}${summary.phase3.trustRejectedReasons.length > 0 ? `；trust ${summary.phase3.trustRejectedReasons.slice(0, 2).join(', ')}` : ''}`,
+        `- Phase 3 Legacy Directive File: ${summary.phase3.directiveStatus} (${summary.phase3.directiveIgnoredReason})`,
         '',
-        '\u539f\u5219\u7edf\u8ba1',
-        `- \u5019\u9009\u539f\u5219: ${stats.candidateCount}`,
-        `- \u89c2\u5bdf\u671f\u539f\u5219: ${stats.probationCount}`,
-        `- \u751f\u6548\u539f\u5219: ${stats.activeCount}`,
-        `- \u5df2\u5e9f\u5f03\u539f\u5219: ${stats.deprecatedCount}`,
-        `- \u6700\u8fd1\u664b\u5347: ${stats.lastPromotedAt ?? '\u65e0'}`,
+        '原则统计',
+        `- 候选原则: ${stats.candidateCount}`,
+        `- 观察期原则: ${stats.probationCount}`,
+        `- 生效原则: ${stats.activeCount}`,
+        `- 已废弃原则: ${stats.deprecatedCount}`,
+        `- 最近晋升: ${stats.lastPromotedAt ?? '无'}`,
         '',
-        '\u5143\u6570\u636e',
-        `- \u5de5\u4f5c\u533a: ${workspaceDir}`,
-        `- Session: ${sessionId ?? '--'}\uff08${summary.metadata.selectedSessionReason}\uff09`,
-        `- \u751f\u6210\u65f6\u95f4: ${summary.metadata.generatedAt}`,
+        '元数据',
+        `- 工作区: ${workspaceDir}`,
+        `- Session: ${sessionId ?? '--'}（${summary.metadata.selectedSessionReason}）`,
+        `- 生成时间: ${summary.metadata.generatedAt}`,
     ];
     if (warnings.length > 0) {
         lines.push('', '警告');

package/dist/config/defaults/runtime.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Centralized Runtime Defaults
+ *
+ * All runtime-related constants that were previously scattered across modules.
+ * Centralizing these makes it easier to tune behavior and understand limits.
+ */
+/**
+ * Trajectory gate block retry settings
+ * Used when trajectory recording fails and needs to retry
+ */
+export declare const TRAJECTORY_GATE_BLOCK_RETRY_DELAY_MS = 250;
+export declare const TRAJECTORY_GATE_BLOCK_MAX_RETRIES = 3;
+/**
+ * Thinking checkpoint defaults (P-10)
+ */
+export declare const THINKING_CHECKPOINT_WINDOW_MS: number;
+export declare const THINKING_CHECKPOINT_DEFAULT_HIGH_RISK_TOOLS: readonly ["run_shell_command", "delete_file", "move_file"];
+/**
+ * Large change threshold for GFI gate adjustments
+ */
+export declare const GFI_LARGE_CHANGE_LINES = 50;
+/**
+ * Agent spawn GFI threshold (critically high = no spawn)
+ */
+export declare const AGENT_SPAWN_GFI_THRESHOLD = 90;
+/**
+ * Evolution worker polling intervals
+ */
+export declare const EVOLUTION_WORKER_POLL_INTERVAL_MS: number;
+export declare const EVOLUTION_QUEUE_BATCH_SIZE = 10;
+/**
+ * Session tracker settings
+ */
+export declare const SESSION_TOKEN_WARNING_THRESHOLD = 8000;
+export declare const SESSION_MAX_IDLE_MS: number;
+/**
+ * Event log buffer settings
+ */
+export declare const EVENT_LOG_BUFFER_SIZE = 20;
+export declare const EVENT_LOG_FLUSH_INTERVAL_MS: number;

package/dist/config/defaults/runtime.js

@@ -0,0 +1,44 @@
+/**
+ * Centralized Runtime Defaults
+ *
+ * All runtime-related constants that were previously scattered across modules.
+ * Centralizing these makes it easier to tune behavior and understand limits.
+ */
+/**
+ * Trajectory gate block retry settings
+ * Used when trajectory recording fails and needs to retry
+ */
+export const TRAJECTORY_GATE_BLOCK_RETRY_DELAY_MS = 250;
+export const TRAJECTORY_GATE_BLOCK_MAX_RETRIES = 3;
+/**
+ * Thinking checkpoint defaults (P-10)
+ */
+export const THINKING_CHECKPOINT_WINDOW_MS = 5 * 60 * 1000; // 5 minutes
+export const THINKING_CHECKPOINT_DEFAULT_HIGH_RISK_TOOLS = [
+    'run_shell_command',
+    'delete_file',
+    'move_file',
+];
+/**
+ * Large change threshold for GFI gate adjustments
+ */
+export const GFI_LARGE_CHANGE_LINES = 50;
+/**
+ * Agent spawn GFI threshold (critically high = no spawn)
+ */
+export const AGENT_SPAWN_GFI_THRESHOLD = 90;
+/**
+ * Evolution worker polling intervals
+ */
+export const EVOLUTION_WORKER_POLL_INTERVAL_MS = 15 * 60 * 1000; // 15 minutes
+export const EVOLUTION_QUEUE_BATCH_SIZE = 10;
+/**
+ * Session tracker settings
+ */
+export const SESSION_TOKEN_WARNING_THRESHOLD = 8000;
+export const SESSION_MAX_IDLE_MS = 30 * 60 * 1000; // 30 minutes
+/**
+ * Event log buffer settings
+ */
+export const EVENT_LOG_BUFFER_SIZE = 20;
+export const EVENT_LOG_FLUSH_INTERVAL_MS = 30 * 1000; // 30 seconds

package/dist/config/errors.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Domain-Specific Errors for Principles Disciple
+ *
+ * These errors provide semantic meaning to failure modes,
+ * making it easier to distinguish between:
+ * - Lock contention (resource busy)
+ * - Parse/validation failures
+ * - Derived state mismatches
+ * - Configuration issues
+ */
+/**
+ * Base class for all Principles Disciple errors
+ */
+export declare class PdError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a resource lock cannot be acquired
+ * (e.g., queue, trajectory, evolution file)
+ */
+export declare class LockUnavailableError extends PdError {
+    constructor(resource: string, scope: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a path key cannot be resolved
+ */
+export declare class PathResolutionError extends PdError {
+    constructor(key: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a workspace cannot be found
+ */
+export declare class WorkspaceNotFoundError extends PdError {
+    constructor(workspace: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a required sample cannot be found
+ */
+export declare class SampleNotFoundError extends PdError {
+    constructor(sampleId: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when configuration is invalid or missing required fields
+ */
+export declare class ConfigurationError extends PdError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when prompt/logger dependencies are unavailable
+ */
+export declare class DependencyError extends PdError {
+    constructor(component: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when evolution worker encounters a processing error
+ */
+export declare class EvolutionProcessingError extends PdError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when trajectory operations fail
+ */
+export declare class TrajectoryError extends PdError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}

package/dist/config/errors.js

@@ -0,0 +1,94 @@
+/**
+ * Domain-Specific Errors for Principles Disciple
+ *
+ * These errors provide semantic meaning to failure modes,
+ * making it easier to distinguish between:
+ * - Lock contention (resource busy)
+ * - Parse/validation failures
+ * - Derived state mismatches
+ * - Configuration issues
+ */
+/**
+ * Base class for all Principles Disciple errors
+ */
+export class PdError extends Error {
+    code;
+    constructor(message, code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'PdError';
+    }
+}
+/**
+ * Thrown when a resource lock cannot be acquired
+ * (e.g., queue, trajectory, evolution file)
+ */
+export class LockUnavailableError extends PdError {
+    constructor(resource, scope, options) {
+        super(`[PD:Lock] ${scope}: queue lock unavailable for ${resource}`, 'LOCK_UNAVAILABLE', options);
+        this.name = 'LockUnavailableError';
+    }
+}
+/**
+ * Thrown when a path key cannot be resolved
+ */
+export class PathResolutionError extends PdError {
+    constructor(key, options) {
+        super(`[PD:Path] Unknown path key: ${key}`, 'PATH_RESOLUTION_ERROR', options);
+        this.name = 'PathResolutionError';
+    }
+}
+/**
+ * Thrown when a workspace cannot be found
+ */
+export class WorkspaceNotFoundError extends PdError {
+    constructor(workspace, options) {
+        super(`[PD:Workspace] Workspace not found: ${workspace}`, 'WORKSPACE_NOT_FOUND', options);
+        this.name = 'WorkspaceNotFoundError';
+    }
+}
+/**
+ * Thrown when a required sample cannot be found
+ */
+export class SampleNotFoundError extends PdError {
+    constructor(sampleId, options) {
+        super(`[PD:Sample] Correction sample not found: ${sampleId}`, 'SAMPLE_NOT_FOUND', options);
+        this.name = 'SampleNotFoundError';
+    }
+}
+/**
+ * Thrown when configuration is invalid or missing required fields
+ */
+export class ConfigurationError extends PdError {
+    constructor(message, options) {
+        super(`[PD:Config] ${message}`, 'CONFIGURATION_ERROR', options);
+        this.name = 'ConfigurationError';
+    }
+}
+/**
+ * Thrown when prompt/logger dependencies are unavailable
+ */
+export class DependencyError extends PdError {
+    constructor(component, message, options) {
+        super(`[PD:${component}] ${message}`, 'DEPENDENCY_ERROR', options);
+        this.name = 'DependencyError';
+    }
+}
+/**
+ * Thrown when evolution worker encounters a processing error
+ */
+export class EvolutionProcessingError extends PdError {
+    constructor(message, options) {
+        super(`[PD:Evolution] ${message}`, 'EVOLUTION_PROCESSING_ERROR', options);
+        this.name = 'EvolutionProcessingError';
+    }
+}
+/**
+ * Thrown when trajectory operations fail
+ */
+export class TrajectoryError extends PdError {
+    constructor(message, options) {
+        super(`[PD:Trajectory] ${message}`, 'TRAJECTORY_ERROR', options);
+        this.name = 'TrajectoryError';
+    }
+}

package/dist/config/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Configuration module for Principles Disciple
+ *
+ * Centralizes all configuration defaults, types, and domain errors.
+ */
+export * from './defaults/runtime.js';
+export * from './errors.js';

package/dist/config/index.js

@@ -0,0 +1,7 @@
+/**
+ * Configuration module for Principles Disciple
+ *
+ * Centralizes all configuration defaults, types, and domain errors.
+ */
+export * from './defaults/runtime.js';
+export * from './errors.js';

package/dist/constants/diagnostician.d.ts

@@ -10,7 +10,3 @@
  * 完整版见: templates/langs/zh/skills/pd-diagnostician/SKILL.md
  */
 export declare const DIAGNOSTICIAN_PROTOCOL_SUMMARY = "## Diagnostic Protocol (5 Whys)\n\n**Phase 1 - Evidence Gathering**:\n- Read logs: .state/logs/events.jsonl, SYSTEM.log\n- Search code for error patterns from Reason field\n- Record evidence sources\n\n**Phase 2 - Causal Chain**:\n- Each Why must have evidence support\n- Maximum 5 layers\n- Stop when reaching actionable root cause\n\n**Phase 3 - Root Cause Classification**:\nClassify into one of:\n- **People**: Human error, missing knowledge, communication gap\n- **Design**: Architecture flaw, missing validation, poor abstraction\n- **Assumption**: Invalid assumption, outdated context, edge case\n- **Tooling**: Tool limitation, environment issue, dependency problem\n\n**Phase 4 - Principle Extraction**:\nExtract protection principle with:\n- **trigger_pattern**: When this situation occurs\n- **action**: What to do differently\n\n**Output Format**:\n```json\n{\n  \"diagnosis_report\": {\n    \"task_id\": \"pain-xxx\",\n    \"summary\": \"One-line root cause\",\n    \"causal_chain\": [\n      { \"why\": 1, \"answer\": \"...\", \"evidence\": \"...\" }\n    ],\n    \"root_cause\": {\n      \"category\": \"Design|People|Assumption|Tooling\",\n      \"description\": \"...\"\n    },\n    \"principle\": {\n      \"trigger_pattern\": \"...\",\n      \"action\": \"...\"\n    }\n  }\n}\n```\n";
-/**
- * 完整诊断协议文件路径（相对于插件根目录）
- */
-export declare const DIAGNOSTICIAN_SKILL_PATH = "templates/langs/zh/skills/pd-diagnostician/SKILL.md";

package/dist/constants/diagnostician.js

@@ -54,7 +54,3 @@ Extract protection principle with:
 }
 \`\`\`
 `;
-/**
- * 完整诊断协议文件路径（相对于插件根目录）
- */
-export const DIAGNOSTICIAN_SKILL_PATH = 'templates/langs/zh/skills/pd-diagnostician/SKILL.md';

package/dist/core/control-ui-db.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Control UI database stores ANALYTICS READ MODELS.
+ *
+ * PURPOSE: Aggregated data for dashboard visualization and historical insights.
+ * USAGE: Control UI queries and dashboard displays.
+ * NOT FOR: Control decisions, Phase 3 eligibility, or real-time operations.
+ *
+ * Runtime truth comes from: queue state, workspace trust scorecard, active sessions
+ */
 export interface ThinkingModelEventInput {
     sessionId: string;
     runId: string;
@@ -59,8 +68,26 @@ export declare class ControlUiDatabase {
     constructor(opts: ControlUiDatabaseOptions);
     dispose(): void;
     recordThinkingModelEvent(input: ThinkingModelEventInput): number;
+    /**
+     * Get recent thinking context for a session.
+     *
+     * Returns: Analytics data (read model) aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     getRecentThinkingContext(sessionId: string, beforeCreatedAt: string, limit?: number): RecentThinkingContext;
+    /**
+     * Execute SQL query and return all rows.
+     *
+     * Returns: Analytics data (read model) aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     all<T>(sql: string, ...params: unknown[]): T[];
+    /**
+     * Execute SQL query and return first row.
+     *
+     * Returns: Analytics data (read model) aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     get<T>(sql: string, ...params: unknown[]): T | undefined;
     restoreRawText(inlineText?: string | null, blobRef?: string | null): string;
     private initSchema;

package/dist/core/control-ui-db.js

@@ -39,6 +39,12 @@ export class ControlUiDatabase {
             return Number(result.lastInsertRowid);
         });
     }
+    /**
+     * Get recent thinking context for a session.
+     *
+     * Returns: Analytics data (read model) aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     getRecentThinkingContext(sessionId, beforeCreatedAt, limit = 5) {
         return {
             toolCalls: this.all(`
@@ -107,9 +113,21 @@ export class ControlUiDatabase {
             })),
         };
     }
+    /**
+     * Execute SQL query and return all rows.
+     *
+     * Returns: Analytics data (read model) aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     all(sql, ...params) {
         return this.db.prepare(sql).all(...params);
     }
+    /**
+     * Execute SQL query and return first row.
+     *
+     * Returns: Analytics data (read model) aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     get(sql, ...params) {
         return this.db.prepare(sql).get(...params);
     }

package/dist/core/path-resolver.js

@@ -1,6 +1,7 @@
 import * as path from 'path';
 import * as os from 'os';
 import * as fs from 'fs';
+import { PathResolutionError } from '../config/index.js';
 const DEFAULT_WORKSPACE_SUBPATH = '.openclaw/workspace';
 export const PD_ENV_VARS = {
     WORKSPACE_DIR: 'PD_WORKSPACE_DIR',
@@ -271,7 +272,7 @@ export class PathResolver {
         const resolved = pathMap[key];
         if (!resolved) {
             this.log('warn', `Unknown path key: ${key}`);
-            throw new Error(`Unknown path key: ${key}`);
+            throw new PathResolutionError(key);
         }
         this.log('debug', `Resolved path for '${key}': ${resolved}`);
         return resolved;

package/dist/core/trajectory.d.ts

@@ -205,12 +205,36 @@ export declare class TrajectoryDatabase {
     recordEvolutionTask(input: EvolutionTaskInput): void;
     updateEvolutionTask(taskId: string, updates: Partial<Omit<EvolutionTaskInput, 'taskId' | 'traceId' | 'source'>>): void;
     recordEvolutionEvent(input: EvolutionEventInput): void;
+    /**
+     * List evolution tasks with optional filtering.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     listEvolutionTasks(filters?: EvolutionTaskFilters): EvolutionTaskRecord[];
+    /**
+     * List evolution events for a trace or globally.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     listEvolutionEvents(traceId?: string, filters?: {
         limit?: number;
         offset?: number;
     }): EvolutionEventRecord[];
+    /**
+     * Get evolution task by trace ID.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     getEvolutionTaskByTraceId(traceId: string): EvolutionTaskRecord | null;
+    /**
+     * Get evolution task statistics.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     getEvolutionStats(): {
         total: number;
         pending: number;
@@ -218,14 +242,44 @@ export declare class TrajectoryDatabase {
         completed: number;
         failed: number;
     };
+    /**
+     * List assistant turns for a session.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     listAssistantTurns(sessionId: string): AssistantTurnRecord[];
+    /**
+     * List correction samples with optional review status filter.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     listCorrectionSamples(status?: CorrectionSampleReviewStatus): CorrectionSampleRecord[];
     reviewCorrectionSample(sampleId: string, status: Exclude<CorrectionSampleReviewStatus, 'pending'>, note?: string): CorrectionSampleRecord;
+    /**
+     * Export correction samples to JSONL file.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     exportCorrections(opts: {
         mode: CorrectionExportMode;
         approvedOnly: boolean;
     }): TrajectoryExportResult;
+    /**
+     * Export analytics data to JSON file.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     exportAnalytics(): TrajectoryExportResult;
+    /**
+     * Get trajectory database statistics.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     getDataStats(): TrajectoryDataStats;
     cleanupBlobStorage(): {
         removedFiles: number;
@@ -234,6 +288,12 @@ export declare class TrajectoryDatabase {
     private initSchema;
     private importLegacyArtifacts;
     private migrateSchema;
+    /**
+     * Get daily metrics for analytics.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     private dailyMetrics;
     private importLegacySessions;
     private importLegacyEvents;