principles-disciple 1.127.0 → 1.129.0

package/dist/config/errors.js

@@ -0,0 +1,107 @@
+/**
+ * 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
+ */
+/** Maps legacy PdError codes to canonical PDErrorCategory values. */
+const codeToCategory = {
+    LOCK_UNAVAILABLE: 'lease_conflict',
+    PATH_RESOLUTION_ERROR: 'workspace_invalid',
+    WORKSPACE_NOT_FOUND: 'workspace_invalid',
+    SAMPLE_NOT_FOUND: 'storage_unavailable',
+    CONFIGURATION_ERROR: 'input_invalid',
+    DEPENDENCY_ERROR: 'runtime_unavailable',
+    EVOLUTION_PROCESSING_ERROR: 'execution_failed',
+    TRAJECTORY_ERROR: 'storage_unavailable',
+};
+/**
+ * Base class for all Principles Disciple errors
+ */
+export class PdError extends Error {
+    code;
+    category;
+    constructor(message, code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'PdError';
+        this.category = codeToCategory[code] ?? 'execution_failed';
+    }
+}
+/**
+ * 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/{src/config/index.ts → dist/config/index.d.ts}

@@ -1,8 +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

@@ -0,0 +1,12 @@
+/**
+ * Diagnostician 协议常量
+ *
+ * 用于 Runtime V2 diagnostician prompt
+ * 与 templates/langs/zh/skills/pd-diagnostician/SKILL.md 保持一致
+ */
+/**
+ * 诊断协议摘要（用于 HEARTBEAT.md 注入）
+ *
+ * 完整版见: 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- Use the task input/context provided by Runtime V2 for pain context\n- Read .state/logs/events.jsonl recent entries\n- Search codebase for error patterns from Reason field\n- Record all evidence sources (file:line)\n\n**Phase 2 - Causal Chain (5 Whys)**:\n- Why 1: Surface symptom (what you can see)\n- Why 2: Direct cause (what triggered it)\n- Why 3: Process gap (what should have caught it)\n- Why 4: Design flaw (why the gap exists)\n- Why 5: Root cause (systemic issue to fix)\n- Each Why MUST have evidence. Stop at 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- For Design: analyze why existing hooks/rules didn't catch this\n\n**Phase 4 - Principle Extraction**:\nExtract a HIGHLY ABSTRACTED principle (not an operational rule):\n- **trigger_pattern**: regex/keywords for when this occurs\n- **action**: what to do differently\n- **abstracted_principle**: ONE sentence, max 40 chars, cross-scenario applicable\n  - \u274C Bad: \"\u5199\u5165\u524D\u68C0\u67E5\u76EE\u5F55\u662F\u5426\u5B58\u5728\" (too specific)\n  - \u2705 Good: \"\u4EFB\u4F55\u5199\u5165\u64CD\u4F5C\u5FC5\u987B\u786E\u4FDD\u76EE\u6807\u73AF\u5883\u7684\u5B8C\u6574\u6027\" (abstract, reusable)\n\n**Output Format** (single JSON object):\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\": \"file:line\" }\n    ],\n    \"root_cause\": {\n      \"category\": \"Design|People|Assumption|Tooling\",\n      \"description\": \"...\"\n    },\n    \"principle\": {\n      \"trigger_pattern\": \"...\",\n      \"action\": \"...\",\n      \"abstracted_principle\": \"\u9AD8\u5EA6\u62BD\u8C61\u7684\u4E00\u53E5\u8BDD\u539F\u5219\"\n    }\n  }\n}\n```\n";

package/{src/constants/diagnostician.ts → dist/constants/diagnostician.js}

@@ -4,7 +4,6 @@
  * 用于 Runtime V2 diagnostician prompt
  * 与 templates/langs/zh/skills/pd-diagnostician/SKILL.md 保持一致
  */
-
 /**
  * 诊断协议摘要（用于 HEARTBEAT.md 注入）
  *

package/dist/constants/tools.d.ts

@@ -0,0 +1,17 @@
+export declare const READ_ONLY_TOOL_NAMES: readonly ["read", "read_file", "read_many_files", "image_read", "search_file_content", "grep", "grep_search", "list_directory", "ls", "glob", "lsp_hover", "lsp_goto_definition", "lsp_find_references", "web_fetch", "web_search", "ref_search_documentation", "ref_read_url", "resolve-library-id", "get-library-docs", "memory_recall", "save_memory", "todo_read", "todo_write", "ask_user", "ask_user_question", "pd-status", "report"];
+export declare const LOW_RISK_WRITE_TOOL_NAMES: readonly ["write", "write_file", "edit", "edit_file", "replace", "apply_patch", "insert", "patch"];
+export declare const BASH_TOOL_NAMES: readonly ["bash", "run_shell_command", "exec", "execute", "shell", "cmd"];
+export declare const HIGH_RISK_TOOL_NAMES: readonly ["delete_file", "move_file", "bash", "run_shell_command", "exec", "execute", "shell", "cmd"];
+export declare const AGENT_TOOL_NAMES: readonly ["sessions_spawn"];
+export declare const CONTENT_LIMITED_TOOL_NAMES: readonly ["write", "write_file", "edit", "edit_file", "replace", "apply_patch", "insert", "patch"];
+export declare const CONSTRUCTIVE_TOOL_NAMES: readonly ["write", "write_file", "edit", "edit_file", "replace", "apply_patch", "insert", "patch", "delete_file", "move_file", "bash", "run_shell_command", "exec", "execute", "shell", "cmd", "sessions_spawn", "evolve-task", "init-strategy"];
+export declare const EXPLORATORY_TOOL_NAMES: readonly ["read", "read_file", "read_many_files", "image_read", "search_file_content", "grep", "grep_search", "list_directory", "ls", "glob", "lsp_hover", "lsp_goto_definition", "lsp_find_references", "web_fetch", "web_search", "ref_search_documentation", "ref_read_url", "resolve-library-id", "get-library-docs", "memory_recall", "save_memory", "todo_read", "todo_write", "ask_user", "ask_user_question", "pd-status", "report"];
+export declare const READ_ONLY_TOOLS: Set<string>;
+export declare const LOW_RISK_WRITE_TOOLS: Set<string>;
+export declare const HIGH_RISK_TOOLS: Set<string>;
+export declare const BASH_TOOLS_SET: Set<string>;
+export declare const AGENT_TOOLS: Set<string>;
+export declare const CONTENT_LIMITED_TOOLS: Set<string>;
+export declare const CONSTRUCTIVE_TOOLS: Set<string>;
+export declare const EXPLORATORY_TOOLS: Set<string>;
+export declare const WRITE_TOOLS: Set<string>;

package/dist/constants/tools.js

@@ -0,0 +1,53 @@
+export const READ_ONLY_TOOL_NAMES = [
+    'read', 'read_file', 'read_many_files', 'image_read',
+    'search_file_content', 'grep', 'grep_search', 'list_directory', 'ls', 'glob',
+    'lsp_hover', 'lsp_goto_definition', 'lsp_find_references',
+    'web_fetch', 'web_search', 'ref_search_documentation', 'ref_read_url',
+    'resolve-library-id', 'get-library-docs',
+    'memory_recall', 'save_memory', 'todo_read', 'todo_write',
+    'ask_user', 'ask_user_question',
+    'pd-status', 'report',
+];
+export const LOW_RISK_WRITE_TOOL_NAMES = [
+    'write', 'write_file',
+    'edit', 'edit_file', 'replace', 'apply_patch', 'insert', 'patch',
+];
+// BASH aliases must be defined before HIGH_RISK_TOOL_NAMES
+export const BASH_TOOL_NAMES = [
+    'bash', 'run_shell_command', 'exec', 'execute', 'shell', 'cmd',
+];
+export const HIGH_RISK_TOOL_NAMES = [
+    'delete_file', 'move_file',
+    // Include all BASH aliases for consistent high-risk classification
+    ...BASH_TOOL_NAMES,
+];
+export const AGENT_TOOL_NAMES = [
+    'sessions_spawn',
+];
+export const CONTENT_LIMITED_TOOL_NAMES = [
+    ...LOW_RISK_WRITE_TOOL_NAMES,
+];
+export const CONSTRUCTIVE_TOOL_NAMES = [
+    ...LOW_RISK_WRITE_TOOL_NAMES,
+    'delete_file', 'move_file',
+    // Include all BASH aliases for consistent constructive classification
+    ...BASH_TOOL_NAMES,
+    ...AGENT_TOOL_NAMES,
+    'evolve-task', 'init-strategy',
+];
+export const EXPLORATORY_TOOL_NAMES = [
+    ...READ_ONLY_TOOL_NAMES,
+];
+export const READ_ONLY_TOOLS = new Set(READ_ONLY_TOOL_NAMES);
+export const LOW_RISK_WRITE_TOOLS = new Set(LOW_RISK_WRITE_TOOL_NAMES);
+export const HIGH_RISK_TOOLS = new Set(HIGH_RISK_TOOL_NAMES);
+export const BASH_TOOLS_SET = new Set(BASH_TOOL_NAMES);
+export const AGENT_TOOLS = new Set(AGENT_TOOL_NAMES);
+export const CONTENT_LIMITED_TOOLS = new Set(CONTENT_LIMITED_TOOL_NAMES);
+export const CONSTRUCTIVE_TOOLS = new Set(CONSTRUCTIVE_TOOL_NAMES);
+export const EXPLORATORY_TOOLS = new Set(EXPLORATORY_TOOL_NAMES);
+export const WRITE_TOOLS = new Set([
+    ...LOW_RISK_WRITE_TOOL_NAMES,
+    'delete_file',
+    'move_file',
+]);

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

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/focus-history.test.js

@@ -0,0 +1,160 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { autoCompressFocus, cleanupStaleInfo } from '../focus-history.js';
+function makeFocusContent(artifactRows, extraLines = 0) {
+    const lines = [
+        '# CURRENT_FOCUS',
+        '',
+        '**版本**: v1',
+        '**更新**: 2026-05-09',
+        '',
+        '## 📍 状态快照',
+        '',
+        '当前聚焦于核心功能开发。',
+        '',
+        '## 🔄 当前任务',
+        '',
+        '- [ ] 实现新功能',
+        '- [ ] 修复已知问题',
+        '- [ ] 完善测试覆盖',
+        '',
+        '## ➡️ 下一步',
+        '',
+        '1. 完成 PRI-82 E2E 测试',
+        '2. 提交代码审查',
+        '',
+        '## 🧠 Working Memory',
+        '',
+        '> Last updated: 2026-05-09T12:00:00Z',
+        '',
+        '### 📁 文件输出记录',
+        '',
+        '| 文件路径 | 操作 | 描述 |',
+        '|----------|------|------|',
+    ];
+    for (const row of artifactRows) {
+        lines.push(row);
+    }
+    lines.push('');
+    lines.push('### ⚠️ 活动问题');
+    lines.push('- 测试覆盖不足 → 增加E2E测试');
+    lines.push('');
+    lines.push('### ➡️ 下一步行动');
+    lines.push('1. 完成回归测试');
+    lines.push('2. 提交PR');
+    lines.push('');
+    for (let i = 0; i < extraLines; i++) {
+        lines.push(`<!-- padding line ${i} -->`);
+    }
+    return lines.join('\n');
+}
+describe('autoCompressFocus E2E regression (PRI-82)', () => {
+    let tmpDir;
+    let workspaceDir;
+    let stateDir;
+    let focusPath;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-focus-e2e-'));
+        workspaceDir = tmpDir;
+        stateDir = path.join(tmpDir, '.state');
+        fs.mkdirSync(stateDir, { recursive: true });
+        const focusDir = path.join(tmpDir, 'okr');
+        fs.mkdirSync(focusDir, { recursive: true });
+        focusPath = path.join(focusDir, 'CURRENT_FOCUS.md');
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it('removes missing-file artifact rows via filesystem filtering before core compression', () => {
+        const existingFile = path.join(workspaceDir, 'src', 'existing-module.ts');
+        fs.mkdirSync(path.join(workspaceDir, 'src'), { recursive: true });
+        fs.writeFileSync(existingFile, 'export const x = 1;');
+        const existingRow = '| `src/existing-module.ts` | modified | 核心模块 |';
+        const missingRow = '| `src/deleted-module.ts` | modified | 已删除模块 |';
+        const content = makeFocusContent([existingRow, missingRow], 90);
+        fs.writeFileSync(focusPath, content);
+        const result = autoCompressFocus(focusPath, workspaceDir, stateDir);
+        expect(result.compressed).toBe(true);
+        expect(result.newContent).toBeDefined();
+        expect(result.newContent).not.toContain('deleted-module.ts');
+        expect(result.newLines).toBeLessThan(result.oldLines);
+        expect(result.reason).toContain('Auto-compressed');
+    });
+    it('goes through core compressFocusContent path when threshold is exceeded', () => {
+        const content = makeFocusContent([
+            '| `src/utils.ts` | created | 工具函数 |',
+        ], 90);
+        fs.writeFileSync(focusPath, content);
+        const result = autoCompressFocus(focusPath, workspaceDir, stateDir);
+        expect(result.compressed).toBe(true);
+        expect(result.reason).toContain('Auto-compressed');
+        const writtenContent = fs.readFileSync(focusPath, 'utf-8');
+        expect(writtenContent).not.toBe(content);
+        expect(writtenContent.split('\n').length).toBeLessThan(content.split('\n').length);
+    });
+    it('does not compress when below threshold', () => {
+        const content = makeFocusContent([
+            '| `src/utils.ts` | created | 工具函数 |',
+        ], 0);
+        fs.writeFileSync(focusPath, content);
+        const result = autoCompressFocus(focusPath, workspaceDir, stateDir);
+        expect(result.compressed).toBe(false);
+        expect(result.reason).toBe('Below threshold');
+    });
+    it('creates backup in history when compressing', () => {
+        const content = makeFocusContent([
+            '| `src/utils.ts` | created | 工具函数 |',
+        ], 90);
+        fs.writeFileSync(focusPath, content);
+        const result = autoCompressFocus(focusPath, workspaceDir, stateDir);
+        expect(result.compressed).toBe(true);
+        expect(result.backupPath).not.toBeNull();
+        const historyDir = path.join(path.dirname(focusPath), '.history');
+        expect(fs.existsSync(historyDir)).toBe(true);
+        const historyFiles = fs.readdirSync(historyDir).filter(f => f.startsWith('CURRENT_FOCUS.v'));
+        expect(historyFiles.length).toBeGreaterThanOrEqual(1);
+    });
+    it('handles workspace without existing files gracefully', () => {
+        const content = makeFocusContent([
+            '| `src/ghost-file.ts` | modified | 不存在的文件 |',
+        ], 90);
+        fs.writeFileSync(focusPath, content);
+        const result = autoCompressFocus(focusPath, workspaceDir, stateDir);
+        expect(result.compressed).toBe(true);
+        expect(result.newContent).not.toContain('ghost-file.ts');
+    });
+});
+describe('cleanupStaleInfo filesystem filtering (PRI-82)', () => {
+    let tmpDir;
+    let workspaceDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-cleanup-'));
+        workspaceDir = tmpDir;
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it('preserves artifact row for existing file and removes row for missing file', () => {
+        const existingFile = path.join(workspaceDir, 'src', 'real.ts');
+        fs.mkdirSync(path.join(workspaceDir, 'src'), { recursive: true });
+        fs.writeFileSync(existingFile, 'export const a = 1;');
+        const content = makeFocusContent([
+            '| `src/real.ts` | modified | 真实文件 |',
+            '| `src/phantom.ts` | modified | 幽灵文件 |',
+        ], 0);
+        const result = cleanupStaleInfo(content, workspaceDir);
+        expect(result).toContain('real.ts');
+        expect(result).not.toContain('phantom.ts');
+    });
+    it('preserves all artifact rows when no workspaceDir provided', () => {
+        const content = makeFocusContent([
+            '| `src/real.ts` | modified | 真实文件 |',
+            '| `src/phantom.ts` | modified | 幽灵文件 |',
+        ], 0);
+        const result = cleanupStaleInfo(content);
+        expect(result).toContain('real.ts');
+        expect(result).toContain('phantom.ts');
+    });
+});

package/dist/core/bootstrap-rules.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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)
+ */
+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 declare function selectPrinciplesForBootstrap(stateDir: string, limit?: number): string[];
+/**
+ * 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 declare function bootstrapRules(stateDir: string, limit?: number): BootstrapResult[];
+/**
+ * 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 declare function validateBootstrap(stateDir: string, expectedPrincipleIds: string[]): boolean;

package/dist/core/bootstrap-rules.js

@@ -0,0 +1,187 @@
+/**
+ * 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, addPrincipleToLedger } from './principle-tree-ledger.js';
+import { loadStore } from './principle-training-state.js';
+import { CORE_THINKING_MODELS } from './init.js';
+/**
+ * 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, limit = 3) {
+    // 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, limit = 3) {
+    // Migration: if T-01..T-10 exist in Training Store but not in Ledger Tree, backfill.
+    // This handles workspaces initialized before Ledger Tree was added.
+    const store = loadStore(stateDir);
+    let ledger = loadLedger(stateDir);
+    const hasTrainingT = Object.keys(store).some((id) => id.startsWith('T-'));
+    const hasAnyLedgerT = Object.keys(ledger.tree.principles).some((id) => id.startsWith('T-'));
+    if (hasTrainingT && !hasAnyLedgerT) {
+        console.warn('[bootstrap] Migrating T-01..T-10 from Training Store to Ledger Tree');
+        const now = new Date().toISOString();
+        for (const [id, entry] of Object.entries(store)) {
+            if (!id.startsWith('T-'))
+                continue;
+            const model = CORE_THINKING_MODELS.find((m) => m.id === id);
+            if (!model)
+                continue;
+            const lp = {
+                id,
+                version: 1,
+                text: model.description,
+                coreAxiomId: id,
+                triggerPattern: '',
+                action: '',
+                status: 'active',
+                priority: 'P1',
+                scope: 'general',
+                evaluability: entry.evaluability,
+                valueScore: 0,
+                adherenceRate: 0,
+                painPreventedCount: 0,
+                derivedFromPainIds: [],
+                ruleIds: [],
+                conflictsWithPrincipleIds: [],
+                createdAt: now,
+                updatedAt: now,
+                suggestedRules: [],
+            };
+            addPrincipleToLedger(stateDir, lp);
+        }
+        // Reload ledger after migration so subsequent reads see the new data.
+        ledger = loadLedger(stateDir);
+    }
+    // Select principles for bootstrap
+    const selectedPrincipleIds = selectPrinciplesForBootstrap(stateDir, limit);
+    const results = [];
+    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();
+        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, expectedPrincipleIds) {
+    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;
+}