principles-disciple 1.5.4 → 1.7.0

package/dist/core/evolution-reducer.js

@@ -0,0 +1,369 @@
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { withLock } from '../utils/file-lock.js';
+import { PathResolver } from './path-resolver.js';
+import { SystemLogger } from './system-logger.js';
+import { shouldIgnorePainProtocolText } from './dictionary.js';
+import { TrajectoryRegistry } from './trajectory.js';
+const PROBATION_SUCCESS_THRESHOLD = 3;
+const CIRCUIT_BREAKER_THRESHOLD = 3;
+const PROBATION_MAX_AGE_DAYS = 30;
+export class EvolutionReducerImpl {
+    streamPath;
+    lockTargetPath;
+    blacklistPath;
+    workspaceDir;
+    memoryEvents = [];
+    principles = new Map();
+    failureStreak = new Map();
+    lastPromotedAt = null;
+    isReplaying = false;
+    constructor(opts) {
+        this.workspaceDir = opts.workspaceDir;
+        const resolver = new PathResolver({ workspaceDir: opts.workspaceDir });
+        this.streamPath = resolver.resolve('EVOLUTION_STREAM');
+        this.lockTargetPath = resolver.resolve('EVOLUTION_LOCK');
+        this.blacklistPath = resolver.resolve('PRINCIPLE_BLACKLIST');
+        this.ensureDirs();
+        this.loadFromStream();
+        this.sweepExpiredProbation();
+    }
+    emit(event) {
+        this.emitSync(event);
+    }
+    emitSync(event) {
+        withLock(this.lockTargetPath, () => {
+            fs.appendFileSync(this.streamPath, `${JSON.stringify(event)}\n`, 'utf8');
+        }, { lockStaleMs: 15000 });
+        this.applyEvent(event);
+        if (event.type !== 'pain_detected') {
+            try {
+                TrajectoryRegistry.use(this.workspaceDir, (trajectory) => {
+                    trajectory.recordPrincipleEvent({
+                        principleId: 'principleId' in event.data && typeof event.data.principleId === 'string' ? event.data.principleId : null,
+                        eventType: event.type,
+                        payload: event.data,
+                        createdAt: event.ts,
+                    });
+                });
+            }
+            catch {
+                // Keep evolution loop resilient if trajectory storage is unavailable.
+            }
+        }
+        // Performance: sweepExpiredProbation() moved to getProbationPrinciples() for lazy cleanup
+    }
+    getEventLog() {
+        return [...this.memoryEvents];
+    }
+    getCandidatePrinciples() {
+        return this.getByStatus('candidate');
+    }
+    getProbationPrinciples() {
+        // Lazy cleanup: sweep expired probation principles on access
+        this.sweepExpiredProbation();
+        return this.getByStatus('probation');
+    }
+    getActivePrinciples() {
+        return this.getByStatus('active');
+    }
+    getPrincipleById(id) {
+        return this.principles.get(id) ?? null;
+    }
+    promote(principleId, reason = 'manual') {
+        const p = this.principles.get(principleId);
+        if (!p || p.status === 'active' || p.status === 'deprecated')
+            return;
+        const nextStatus = p.status === 'candidate' ? 'probation' : 'active';
+        const event = {
+            ts: new Date().toISOString(),
+            type: 'principle_promoted',
+            data: {
+                principleId,
+                from: p.status,
+                to: nextStatus,
+                reason,
+                successCount: p.validation.successCount,
+            },
+        };
+        this.emitSync(event);
+    }
+    deprecate(principleId, reason) {
+        const p = this.principles.get(principleId);
+        if (!p || p.status === 'deprecated')
+            return;
+        this.emitSync({
+            ts: new Date().toISOString(),
+            type: 'principle_deprecated',
+            data: {
+                principleId,
+                reason,
+                triggeredBy: 'manual',
+            },
+        });
+    }
+    rollbackPrinciple(principleId, reason) {
+        const p = this.principles.get(principleId);
+        if (!p)
+            return;
+        this.emitSync({
+            ts: new Date().toISOString(),
+            type: 'principle_rolled_back',
+            data: {
+                principleId,
+                reason,
+                triggeredBy: 'user_command',
+                blacklistPattern: p.trigger,
+                relatedPainId: p.source.painId,
+            },
+        });
+    }
+    recordProbationFeedback(principleId, success) {
+        const p = this.principles.get(principleId);
+        if (!p || p.status !== 'probation')
+            return;
+        if (success) {
+            p.validation.successCount += 1;
+            p.feedbackScore += 10;
+            if (p.validation.successCount >= PROBATION_SUCCESS_THRESHOLD) {
+                this.promote(principleId, 'auto_threshold');
+            }
+            return;
+        }
+        p.validation.conflictCount += 1;
+        if (p.validation.conflictCount >= 1) {
+            this.deprecate(principleId, 'conflict_detected');
+        }
+    }
+    getStats() {
+        return {
+            candidateCount: this.getCandidatePrinciples().length,
+            probationCount: this.getProbationPrinciples().length,
+            activeCount: this.getActivePrinciples().length,
+            deprecatedCount: this.getByStatus('deprecated').length,
+            lastPromotedAt: this.lastPromotedAt,
+        };
+    }
+    ensureDirs() {
+        fs.mkdirSync(path.dirname(this.streamPath), { recursive: true });
+        fs.mkdirSync(path.dirname(this.lockTargetPath), { recursive: true });
+        fs.mkdirSync(path.dirname(this.blacklistPath), { recursive: true });
+    }
+    loadFromStream() {
+        if (!fs.existsSync(this.streamPath))
+            return;
+        const raw = fs.readFileSync(this.streamPath, 'utf8').trim();
+        if (!raw)
+            return;
+        this.isReplaying = true;
+        for (const line of raw.split('\n')) {
+            try {
+                const event = JSON.parse(line);
+                this.applyEvent(event);
+            }
+            catch (e) {
+                SystemLogger.log(this.workspaceDir, 'EVOLUTION_WARN', `skip malformed event line: ${String(e)}`);
+            }
+        }
+        this.isReplaying = false;
+    }
+    applyEvent(event) {
+        this.memoryEvents.push(event);
+        switch (event.type) {
+            case 'pain_detected':
+                this.updateFailureStreakFromPain(event.data);
+                if (!this.isReplaying) {
+                    this.onPainDetected(event.data, event.ts);
+                }
+                return;
+            case 'candidate_created':
+                this.onCandidateCreated(event.data, event.ts);
+                return;
+            case 'principle_promoted':
+                this.onPrinciplePromoted(event.data, event.ts);
+                return;
+            case 'principle_deprecated':
+                this.onPrincipleDeprecated(event.data, event.ts);
+                return;
+            case 'principle_rolled_back':
+                this.onPrincipleRolledBack(event.data, event.ts);
+                return;
+            case 'circuit_breaker_opened':
+            case 'legacy_import':
+                return;
+            default:
+                return;
+        }
+    }
+    onCandidateCreated(data, ts) {
+        const existing = this.principles.get(data.principleId);
+        if (existing) {
+            existing.status = 'candidate';
+            return;
+        }
+        const principle = {
+            id: data.principleId,
+            version: 1,
+            text: `When ${data.trigger}, then ${data.action}.`,
+            source: {
+                painId: data.painId,
+                painType: 'tool_failure',
+                timestamp: ts,
+            },
+            trigger: data.trigger,
+            action: data.action,
+            contextTags: [],
+            validation: { successCount: 0, conflictCount: 0 },
+            status: 'candidate',
+            feedbackScore: 0,
+            usageCount: 0,
+            createdAt: ts,
+        };
+        this.principles.set(principle.id, principle);
+    }
+    onPrinciplePromoted(data, ts) {
+        const p = this.principles.get(data.principleId);
+        if (!p)
+            return;
+        p.status = data.to;
+        if (data.to === 'active') {
+            p.activatedAt = ts;
+        }
+        this.lastPromotedAt = ts;
+    }
+    onPrincipleDeprecated(data, ts) {
+        const p = this.principles.get(data.principleId);
+        if (!p)
+            return;
+        p.status = 'deprecated';
+        p.deprecatedAt = ts;
+    }
+    onPrincipleRolledBack(data, ts) {
+        const p = this.principles.get(data.principleId);
+        if (p) {
+            p.status = 'deprecated';
+            p.deprecatedAt = ts;
+        }
+        this.persistBlacklist({
+            painId: data.relatedPainId,
+            pattern: data.blacklistPattern,
+            reason: data.reason,
+            rolledBackAt: ts,
+        });
+    }
+    onPainDetected(data, eventTs) {
+        const trigger = String(data.reason ?? data.source ?? 'unknown trigger');
+        const action = `Prevent recurrence for: ${String(data.source ?? 'unknown')}`;
+        // Defense in depth: protocol/system tokens must never become principles,
+        // even if a pain_detected event is emitted from a new callsite in the future.
+        if (shouldIgnorePainProtocolText(trigger)) {
+            return;
+        }
+        if (this.isBlacklisted(data.painId, trigger)) {
+            return;
+        }
+        const principleId = this.nextPrincipleId();
+        const principle = {
+            id: principleId,
+            version: 1,
+            text: `When ${trigger}, then ${action}.`,
+            source: {
+                painId: data.painId,
+                painType: data.painType,
+                timestamp: eventTs,
+            },
+            trigger,
+            action,
+            contextTags: [data.source],
+            validation: { successCount: 0, conflictCount: 0 },
+            status: 'candidate',
+            feedbackScore: 0,
+            usageCount: 0,
+            createdAt: eventTs,
+        };
+        this.principles.set(principleId, principle);
+        this.emitSync({
+            ts: new Date().toISOString(),
+            type: 'candidate_created',
+            data: {
+                painId: principle.source.painId,
+                principleId,
+                trigger,
+                action,
+                status: 'candidate',
+            },
+        });
+        this.promote(principleId, 'auto_from_pain');
+        if (data.painType === 'subagent_error') {
+            const key = String(data.taskId ?? data.source ?? 'subagent');
+            const next = this.failureStreak.get(key) ?? 0;
+            if (next >= CIRCUIT_BREAKER_THRESHOLD) {
+                const nextRetryAt = new Date(Date.now() + 15 * 60 * 1000).toISOString();
+                this.emitSync({
+                    ts: new Date().toISOString(),
+                    type: 'circuit_breaker_opened',
+                    data: {
+                        taskId: key,
+                        painId: principle.source.painId,
+                        failCount: next,
+                        reason: 'Max retries exceeded',
+                        requireHuman: true,
+                        nextRetryAt,
+                    },
+                });
+            }
+        }
+    }
+    updateFailureStreakFromPain(data) {
+        if (data.painType !== 'subagent_error')
+            return;
+        const key = String(data.taskId ?? data.source ?? 'subagent');
+        const next = (this.failureStreak.get(key) ?? 0) + 1;
+        this.failureStreak.set(key, next);
+    }
+    nextPrincipleId() {
+        const ids = [...this.principles.keys()]
+            .map((id) => Number(id.replace(/^P_/, '')))
+            .filter((n) => Number.isFinite(n));
+        const next = (ids.length ? Math.max(...ids) : 0) + 1;
+        return `P_${String(next).padStart(3, '0')}`;
+    }
+    getByStatus(status) {
+        return [...this.principles.values()].filter((p) => p.status === status);
+    }
+    sweepExpiredProbation() {
+        const now = Date.now();
+        const maxAgeMs = PROBATION_MAX_AGE_DAYS * 24 * 60 * 60 * 1000;
+        // Use getByStatus directly to avoid infinite recursion with getProbationPrinciples()
+        for (const p of this.getByStatus('probation')) {
+            const age = now - new Date(p.createdAt).getTime();
+            if (age > maxAgeMs) {
+                this.deprecate(p.id, 'probation_expired');
+            }
+        }
+    }
+    persistBlacklist(entry) {
+        const list = this.loadBlacklist();
+        list.push(entry);
+        fs.writeFileSync(this.blacklistPath, JSON.stringify(list, null, 2), 'utf8');
+    }
+    loadBlacklist() {
+        if (!fs.existsSync(this.blacklistPath))
+            return [];
+        try {
+            return JSON.parse(fs.readFileSync(this.blacklistPath, 'utf8'));
+        }
+        catch (e) {
+            SystemLogger.log(this.workspaceDir, 'EVOLUTION_WARN', `failed to parse blacklist: ${String(e)}`);
+            return [];
+        }
+    }
+    isBlacklisted(painId, trigger) {
+        return this.loadBlacklist().some((entry) => (entry.painId && entry.painId === painId) ||
+            (entry.pattern && trigger.includes(entry.pattern)));
+    }
+}
+export function stableContentHash(input) {
+    return crypto.createHash('sha1').update(input).digest('hex');
+}

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

@@ -124,3 +124,106 @@ export interface TierPromotionEvent {
     timestamp: string;
     newPermissions: TierPermissions;
 }
+export type PrincipleStatus = 'candidate' | 'probation' | 'active' | 'deprecated';
+export interface Principle {
+    id: string;
+    version: number;
+    text: string;
+    source: {
+        painId: string;
+        painType: 'tool_failure' | 'subagent_error' | 'user_frustration';
+        timestamp: string;
+    };
+    trigger: string;
+    action: string;
+    guardrails?: string[];
+    contextTags: string[];
+    validation: {
+        successCount: number;
+        conflictCount: number;
+    };
+    status: PrincipleStatus;
+    feedbackScore: number;
+    usageCount: number;
+    createdAt: string;
+    activatedAt?: string;
+    deprecatedAt?: string;
+}
+export type EvolutionLoopEventType = 'pain_detected' | 'candidate_created' | 'principle_promoted' | 'principle_deprecated' | 'principle_rolled_back' | 'circuit_breaker_opened' | 'legacy_import';
+export interface PainDetectedData {
+    painId: string;
+    painType: 'tool_failure' | 'subagent_error' | 'user_frustration';
+    source: string;
+    reason: string;
+    score?: number;
+    sessionId?: string;
+    taskId?: string;
+}
+export interface CandidateCreatedData {
+    painId: string;
+    principleId: string;
+    trigger: string;
+    action: string;
+    status: 'candidate';
+}
+export interface PrinciplePromotedData {
+    principleId: string;
+    from: 'candidate' | 'probation';
+    to: 'probation' | 'active';
+    reason: string;
+    successCount?: number;
+}
+export interface PrincipleDeprecatedData {
+    principleId: string;
+    reason: string;
+    triggeredBy: 'auto' | 'manual';
+}
+export interface PrincipleRolledBackData {
+    principleId: string;
+    reason: string;
+    triggeredBy: 'user_command' | 'auto_conflict';
+    blacklistPattern?: string;
+    relatedPainId?: string;
+}
+export interface CircuitBreakerOpenedData {
+    taskId: string;
+    painId: string;
+    failCount: number;
+    reason: string;
+    requireHuman: boolean;
+    nextRetryAt?: string;
+}
+export interface LegacyImportData {
+    sourceFile: string;
+    content: string;
+    contentHash?: string;
+}
+export type EvolutionLoopEvent = {
+    ts: string;
+    type: 'pain_detected';
+    data: PainDetectedData;
+} | {
+    ts: string;
+    type: 'candidate_created';
+    data: CandidateCreatedData;
+} | {
+    ts: string;
+    type: 'principle_promoted';
+    data: PrinciplePromotedData;
+} | {
+    ts: string;
+    type: 'principle_deprecated';
+    data: PrincipleDeprecatedData;
+} | {
+    ts: string;
+    type: 'principle_rolled_back';
+    data: PrincipleRolledBackData;
+} | {
+    ts: string;
+    type: 'circuit_breaker_opened';
+    data: CircuitBreakerOpenedData;
+} | {
+    ts: string;
+    type: 'legacy_import';
+    data: LegacyImportData;
+};

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

@@ -0,0 +1,65 @@
+/**
+ * CURRENT_FOCUS 历史版本管理
+ *
+ * 功能：
+ * - 压缩时备份当前版本到历史目录
+ * - 清理过期历史版本
+ * - 读取历史版本（用于 full 模式）
+ */
+/**
+ * 获取历史目录路径
+ */
+export declare function getHistoryDir(focusPath: string): string;
+/**
+ * 从 CURRENT_FOCUS.md 提取版本号
+ * 支持整数和小数版本（如 v1, v1.1, v1.2）
+ */
+export declare function extractVersion(content: string): string;
+/**
+ * 从 CURRENT_FOCUS.md 提取更新日期
+ */
+export declare function extractDate(content: string): string;
+/**
+ * 备份当前版本到历史目录
+ *
+ * @param focusPath CURRENT_FOCUS.md 的完整路径
+ * @param content 当前内容
+ * @returns 备份文件路径，失败返回 null
+ */
+export declare function backupToHistory(focusPath: string, content: string): string | null;
+/**
+ * 清理过期历史版本
+ *
+ * @param focusPath CURRENT_FOCUS.md 的完整路径
+ * @param maxFiles 最大保留数量
+ */
+export declare function cleanupHistory(focusPath: string, maxFiles?: number): void;
+/**
+ * 获取历史版本列表
+ *
+ * @param focusPath CURRENT_FOCUS.md 的完整路径
+ * @param count 获取数量
+ * @returns 历史版本内容数组（按时间倒序）
+ */
+export declare function getHistoryVersions(focusPath: string, count?: number): string[];
+/**
+ * 压缩 CURRENT_FOCUS.md
+ *
+ * @param focusPath CURRENT_FOCUS.md 的完整路径
+ * @param newContent 新内容
+ * @returns 压缩后的信息
+ */
+export declare function compressFocus(focusPath: string, newContent: string): {
+    backupPath: string | null;
+    cleanedCount: number;
+};
+/**
+ * 智能摘要提取
+ *
+ * 优先提取关键章节，确保不丢失重要信息
+ * 对于非结构化内容，回退到简单的行截取
+ *
+ * @param content CURRENT_FOCUS.md 内容
+ * @param maxLines 最大行数
+ */
+export declare function extractSummary(content: string, maxLines?: number): string;