principles-disciple 1.7.3 → 1.7.5

package/dist/core/init.js

@@ -11,6 +11,24 @@ const DEFAULT_PROFILE = {
     version: "1.0.0",
     contextInjection: defaultContextConfig
 };
+const CORE_GUIDANCE_VERSION = 'pd-core-guidance-v2';
+const CORE_GUIDANCE_FILES = new Set(['AGENTS.md', 'TOOLS.md']);
+function getCoreGuidanceVersionMarker() {
+    return `pd-core-guidance-version: ${CORE_GUIDANCE_VERSION}`;
+}
+function hasOutdatedCoreGuidance(file, content) {
+    if (!CORE_GUIDANCE_FILES.has(file))
+        return false;
+    if (content.includes(getCoreGuidanceVersionMarker()))
+        return false;
+    if (content.includes('pd_spawn_agent'))
+        return true;
+    if (!content.includes('subagents'))
+        return true;
+    if (!content.includes('sessions_spawn'))
+        return true;
+    return false;
+}
 /**
  * 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.
@@ -45,6 +63,12 @@ export function ensureWorkspaceTemplates(api, workspaceDir, language = 'en') {
                     fs.copyFileSync(srcPath, destPath);
                     api.logger.info(`[PD] Initialized core file: ${file}`);
                 }
+                else if (CORE_GUIDANCE_FILES.has(file)) {
+                    const existingContent = fs.readFileSync(destPath, 'utf8');
+                    if (hasOutdatedCoreGuidance(file, existingContent)) {
+                        api.logger.warn(`[PD] Outdated core guidance detected in ${file}. Review the latest template guidance for peer sessions, subagents, and sessions_spawn routing.`);
+                    }
+                }
             }
         }
         // 3. Copy pain memory seed files

package/dist/core/profile.js

@@ -51,7 +51,7 @@ export const PROFILE_DEFAULTS = {
     thinking_checkpoint: {
         enabled: false, // Default OFF to avoid blocking new users
         window_ms: 5 * 60 * 1000, // 5 minute window
-        high_risk_tools: ['run_shell_command', 'delete_file', 'move_file', 'pd_run_worker'],
+        high_risk_tools: ['run_shell_command', 'delete_file', 'move_file'],
     },
     custom_guards: [],
 };

package/dist/core/risk-calculator.d.ts

@@ -5,3 +5,18 @@ export interface FileModification {
 }
 export declare function estimateLineChanges(modification: FileModification): number;
 export declare function assessRiskLevel(filePath: string, modification: FileModification, riskPaths: string[]): RiskLevel;
+/**
+ * Get the total line count of a target file.
+ * @param absoluteFilePath - Absolute path to the file
+ * @returns File line count, or null if file doesn't exist or can't be read
+ */
+export declare function getTargetFileLineCount(absoluteFilePath: string): number | null;
+/**
+ * Calculate the effective line limit based on percentage of target file.
+ * @param targetLineCount - Total lines in target file
+ * @param percentage - Allowed percentage (0-100)
+ * @param minLines - Absolute minimum threshold
+ * @param maxLines - Optional upper bound to prevent misconfiguration
+ * @returns Maximum allowed lines (at least minLines, at most maxLines if provided)
+ */
+export declare function calculatePercentageThreshold(targetLineCount: number, percentage: number, minLines: number, maxLines?: number): number;

package/dist/core/risk-calculator.js

@@ -1,3 +1,4 @@
+import * as fs from 'fs';
 import { isRisky } from '../utils/io.js';
 export function estimateLineChanges(modification) {
     const { toolName, params } = modification;
@@ -37,3 +38,50 @@ export function assessRiskLevel(filePath, modification, riskPaths) {
         return 'LOW';
     }
 }
+/**
+ * Get the total line count of a target file.
+ * @param absoluteFilePath - Absolute path to the file
+ * @returns File line count, or null if file doesn't exist or can't be read
+ */
+export function getTargetFileLineCount(absoluteFilePath) {
+    try {
+        if (!fs.existsSync(absoluteFilePath)) {
+            return null; // File genuinely doesn't exist
+        }
+        const stats = fs.statSync(absoluteFilePath);
+        if (!stats.isFile()) {
+            return null; // Not a regular file (directory, device, etc.)
+        }
+        const content = fs.readFileSync(absoluteFilePath, 'utf-8');
+        return content.split('\n').length;
+    }
+    catch (e) {
+        // Log error before falling back to null - this is intentional for security gates
+        const error = e instanceof Error ? e : new Error(String(e));
+        const errorCode = e.code;
+        console.error(`[PD:RISK_CALC] Failed to read file for line count: ${absoluteFilePath}`, {
+            code: errorCode,
+            message: error.message,
+        });
+        return null;
+    }
+}
+/**
+ * Calculate the effective line limit based on percentage of target file.
+ * @param targetLineCount - Total lines in target file
+ * @param percentage - Allowed percentage (0-100)
+ * @param minLines - Absolute minimum threshold
+ * @param maxLines - Optional upper bound to prevent misconfiguration
+ * @returns Maximum allowed lines (at least minLines, at most maxLines if provided)
+ */
+export function calculatePercentageThreshold(targetLineCount, percentage, minLines, maxLines) {
+    // Clamp percentage to valid range [0, 100]
+    const clampedPercentage = Math.max(0, Math.min(100, percentage));
+    const calculated = Math.round(targetLineCount * (clampedPercentage / 100));
+    let effectiveLimit = Math.max(calculated, minLines);
+    // Apply optional upper bound
+    if (maxLines !== undefined && maxLines > 0) {
+        effectiveLimit = Math.min(effectiveLimit, maxLines);
+    }
+    return effectiveLimit;
+}

package/dist/core/trajectory.d.ts

@@ -89,6 +89,63 @@ export interface TrajectorySessionInput {
     sessionId: string;
     startedAt?: string;
 }
+export interface EvolutionTaskInput {
+    taskId: string;
+    traceId: string;
+    source: string;
+    reason?: string | null;
+    score?: number;
+    status?: string;
+    enqueuedAt?: string | null;
+    startedAt?: string | null;
+    completedAt?: string | null;
+    resolution?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface EvolutionEventInput {
+    traceId: string;
+    taskId?: string | null;
+    stage: string;
+    level?: string;
+    message: string;
+    summary?: string | null;
+    metadata?: unknown;
+    createdAt?: string;
+}
+export interface EvolutionTaskRecord {
+    id: number;
+    taskId: string;
+    traceId: string;
+    source: string;
+    reason: string | null;
+    score: number;
+    status: string;
+    enqueuedAt: string | null;
+    startedAt: string | null;
+    completedAt: string | null;
+    resolution: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface EvolutionEventRecord {
+    id: number;
+    traceId: string;
+    taskId: string | null;
+    stage: string;
+    level: string;
+    message: string;
+    summary: string | null;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+}
+export interface EvolutionTaskFilters {
+    status?: string;
+    dateFrom?: string;
+    dateTo?: string;
+    limit?: number;
+    offset?: number;
+}
 export interface AssistantTurnRecord {
     id: number;
     sessionId: string;
@@ -145,6 +202,22 @@ export declare class TrajectoryDatabase {
     recordTrustChange(input: TrajectoryTrustChangeInput): void;
     recordPrincipleEvent(input: TrajectoryPrincipleEventInput): void;
     recordTaskOutcome(input: TrajectoryTaskOutcomeInput): void;
+    recordEvolutionTask(input: EvolutionTaskInput): void;
+    updateEvolutionTask(taskId: string, updates: Partial<Omit<EvolutionTaskInput, 'taskId' | 'traceId' | 'source'>>): void;
+    recordEvolutionEvent(input: EvolutionEventInput): void;
+    listEvolutionTasks(filters?: EvolutionTaskFilters): EvolutionTaskRecord[];
+    listEvolutionEvents(traceId?: string, filters?: {
+        limit?: number;
+        offset?: number;
+    }): EvolutionEventRecord[];
+    getEvolutionTaskByTraceId(traceId: string): EvolutionTaskRecord | null;
+    getEvolutionStats(): {
+        total: number;
+        pending: number;
+        inProgress: number;
+        completed: number;
+        failed: number;
+    };
     listAssistantTurns(sessionId: string): AssistantTurnRecord[];
     listCorrectionSamples(status?: CorrectionSampleReviewStatus): CorrectionSampleRecord[];
     reviewCorrectionSample(sampleId: string, status: Exclude<CorrectionSampleReviewStatus, 'pending'>, note?: string): CorrectionSampleRecord;

package/dist/core/trajectory.js

@@ -161,6 +161,181 @@ export class TrajectoryDatabase {
       `).run(input.sessionId, input.taskId ?? null, input.outcome, input.summary ?? null, safeJson(input.principleIdsJson), input.createdAt ?? nowIso());
         });
     }
+    recordEvolutionTask(input) {
+        const now = nowIso();
+        this.withWrite(() => {
+            this.db.prepare(`
+        INSERT INTO evolution_tasks (
+          task_id, trace_id, source, reason, score, status,
+          enqueued_at, started_at, completed_at, resolution, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(task_id) DO UPDATE SET
+          status = excluded.status,
+          started_at = excluded.started_at,
+          completed_at = excluded.completed_at,
+          resolution = excluded.resolution,
+          updated_at = excluded.updated_at
+      `).run(input.taskId, input.traceId, input.source, input.reason ?? null, input.score ?? 0, input.status ?? 'pending', input.enqueuedAt ?? null, input.startedAt ?? null, input.completedAt ?? null, input.resolution ?? null, input.createdAt ?? now, input.updatedAt ?? now);
+        });
+    }
+    updateEvolutionTask(taskId, updates) {
+        const now = nowIso();
+        this.withWrite(() => {
+            const setClauses = ['updated_at = ?'];
+            const values = [now];
+            if (updates.status !== undefined) {
+                setClauses.push('status = ?');
+                values.push(updates.status);
+            }
+            if (updates.startedAt !== undefined) {
+                setClauses.push('started_at = ?');
+                values.push(updates.startedAt);
+            }
+            if (updates.completedAt !== undefined) {
+                setClauses.push('completed_at = ?');
+                values.push(updates.completedAt);
+            }
+            if (updates.resolution !== undefined) {
+                setClauses.push('resolution = ?');
+                values.push(updates.resolution);
+            }
+            if (updates.score !== undefined) {
+                setClauses.push('score = ?');
+                values.push(updates.score);
+            }
+            values.push(taskId);
+            this.db.prepare(`
+        UPDATE evolution_tasks SET ${setClauses.join(', ')} WHERE task_id = ?
+      `).run(...values);
+        });
+    }
+    recordEvolutionEvent(input) {
+        this.withWrite(() => {
+            this.db.prepare(`
+        INSERT INTO evolution_events (trace_id, task_id, stage, level, message, summary, metadata_json, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(input.traceId, input.taskId ?? null, input.stage, input.level ?? 'info', input.message, input.summary ?? null, safeJson(input.metadata), input.createdAt ?? nowIso());
+        });
+    }
+    listEvolutionTasks(filters = {}) {
+        const conditions = [];
+        const values = [];
+        if (filters.status) {
+            conditions.push('status = ?');
+            values.push(filters.status);
+        }
+        if (filters.dateFrom) {
+            conditions.push('created_at >= ?');
+            values.push(filters.dateFrom);
+        }
+        if (filters.dateTo) {
+            conditions.push('created_at <= ?');
+            values.push(filters.dateTo);
+        }
+        const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+        const limit = filters.limit ?? 50;
+        const offset = filters.offset ?? 0;
+        const rows = this.db.prepare(`
+      SELECT id, task_id, trace_id, source, reason, score, status,
+             enqueued_at, started_at, completed_at, resolution, created_at, updated_at
+      FROM evolution_tasks
+      ${whereClause}
+      ORDER BY created_at DESC
+      LIMIT ? OFFSET ?
+    `).all(...values, limit, offset);
+        return rows.map((row) => ({
+            id: Number(row.id),
+            taskId: String(row.task_id),
+            traceId: String(row.trace_id),
+            source: String(row.source),
+            reason: row.reason ? String(row.reason) : null,
+            score: Number(row.score ?? 0),
+            status: String(row.status),
+            enqueuedAt: row.enqueued_at ? String(row.enqueued_at) : null,
+            startedAt: row.started_at ? String(row.started_at) : null,
+            completedAt: row.completed_at ? String(row.completed_at) : null,
+            resolution: row.resolution ? String(row.resolution) : null,
+            createdAt: String(row.created_at),
+            updatedAt: String(row.updated_at),
+        }));
+    }
+    listEvolutionEvents(traceId, filters = {}) {
+        const limit = filters.limit ?? 100;
+        const offset = filters.offset ?? 0;
+        let rows;
+        if (traceId) {
+            rows = this.db.prepare(`
+        SELECT id, trace_id, task_id, stage, level, message, summary, metadata_json, created_at
+        FROM evolution_events
+        WHERE trace_id = ?
+        ORDER BY created_at ASC
+        LIMIT ? OFFSET ?
+      `).all(traceId, limit, offset);
+        }
+        else {
+            rows = this.db.prepare(`
+        SELECT id, trace_id, task_id, stage, level, message, summary, metadata_json, created_at
+        FROM evolution_events
+        ORDER BY created_at DESC
+        LIMIT ? OFFSET ?
+      `).all(limit, offset);
+        }
+        return rows.map((row) => ({
+            id: Number(row.id),
+            traceId: String(row.trace_id),
+            taskId: row.task_id ? String(row.task_id) : null,
+            stage: String(row.stage),
+            level: String(row.level ?? 'info'),
+            message: String(row.message),
+            summary: row.summary ? String(row.summary) : null,
+            metadata: JSON.parse(String(row.metadata_json ?? '{}')),
+            createdAt: String(row.created_at),
+        }));
+    }
+    getEvolutionTaskByTraceId(traceId) {
+        const row = this.db.prepare(`
+      SELECT id, task_id, trace_id, source, reason, score, status,
+             enqueued_at, started_at, completed_at, resolution, created_at, updated_at
+      FROM evolution_tasks
+      WHERE trace_id = ?
+      LIMIT 1
+    `).get(traceId);
+        if (!row)
+            return null;
+        return {
+            id: Number(row.id),
+            taskId: String(row.task_id),
+            traceId: String(row.trace_id),
+            source: String(row.source),
+            reason: row.reason ? String(row.reason) : null,
+            score: Number(row.score ?? 0),
+            status: String(row.status),
+            enqueuedAt: row.enqueued_at ? String(row.enqueued_at) : null,
+            startedAt: row.started_at ? String(row.started_at) : null,
+            completedAt: row.completed_at ? String(row.completed_at) : null,
+            resolution: row.resolution ? String(row.resolution) : null,
+            createdAt: String(row.created_at),
+            updatedAt: String(row.updated_at),
+        };
+    }
+    getEvolutionStats() {
+        const rows = this.db.prepare(`
+      SELECT status, COUNT(*) as count FROM evolution_tasks GROUP BY status
+    `).all();
+        const stats = { total: 0, pending: 0, inProgress: 0, completed: 0, failed: 0 };
+        for (const row of rows) {
+            stats.total += row.count;
+            if (row.status === 'pending')
+                stats.pending = row.count;
+            else if (row.status === 'in_progress')
+                stats.inProgress = row.count;
+            else if (row.status === 'completed')
+                stats.completed = row.count;
+            else if (row.status === 'failed')
+                stats.failed = row.count;
+        }
+        return stats;
+    }
     listAssistantTurns(sessionId) {
         const rows = this.db.prepare(`
       SELECT id, session_id, run_id, provider, model, raw_text, sanitized_text, blob_ref, created_at
@@ -457,6 +632,32 @@ export class TrajectoryDatabase {
         row_count INTEGER NOT NULL,
         created_at TEXT NOT NULL
       );
+      CREATE TABLE IF NOT EXISTS evolution_tasks (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        task_id TEXT UNIQUE NOT NULL,
+        trace_id TEXT NOT NULL,
+        source TEXT NOT NULL,
+        reason TEXT,
+        score INTEGER DEFAULT 0,
+        status TEXT DEFAULT 'pending',
+        enqueued_at TEXT,
+        started_at TEXT,
+        completed_at TEXT,
+        resolution TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS evolution_events (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        trace_id TEXT NOT NULL,
+        task_id TEXT,
+        stage TEXT NOT NULL,
+        level TEXT DEFAULT 'info',
+        message TEXT NOT NULL,
+        summary TEXT,
+        metadata_json TEXT,
+        created_at TEXT NOT NULL
+      );
       CREATE VIEW IF NOT EXISTS v_error_clusters AS
       SELECT tool_name, COALESCE(error_type, 'unknown') AS error_type, COUNT(*) AS occurrences
       FROM tool_calls
@@ -480,6 +681,11 @@ export class TrajectoryDatabase {
       CREATE INDEX IF NOT EXISTS idx_tool_calls_created_at ON tool_calls(created_at);
       CREATE INDEX IF NOT EXISTS idx_pain_events_session_id ON pain_events(session_id);
       CREATE INDEX IF NOT EXISTS idx_correction_samples_review_status ON correction_samples(review_status);
+      CREATE INDEX IF NOT EXISTS idx_evolution_tasks_trace_id ON evolution_tasks(trace_id);
+      CREATE INDEX IF NOT EXISTS idx_evolution_tasks_status ON evolution_tasks(status);
+      CREATE INDEX IF NOT EXISTS idx_evolution_tasks_created_at ON evolution_tasks(created_at);
+      CREATE INDEX IF NOT EXISTS idx_evolution_events_trace_id ON evolution_events(trace_id);
+      CREATE INDEX IF NOT EXISTS idx_evolution_events_created_at ON evolution_events(created_at);
     `);
         const row = this.db.prepare('SELECT version FROM schema_version LIMIT 1').get();
         this.migrateSchema(row?.version);

package/dist/hooks/gate.js

@@ -4,16 +4,18 @@ import { isRisky, normalizePath, planStatus as getPlanStatus } from '../utils/io
 import { matchesAnyPattern } from '../utils/glob-match.js';
 import { normalizeProfile } from '../core/profile.js';
 import { trackBlock, hasRecentThinking, getSession } from '../core/session-tracker.js';
-import { assessRiskLevel, estimateLineChanges } from '../core/risk-calculator.js';
+import { assessRiskLevel, estimateLineChanges, getTargetFileLineCount, calculatePercentageThreshold } from '../core/risk-calculator.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 import { checkEvolutionGate } from '../core/evolution-engine.js';
 import { EventLogService } from '../core/event-log.js';
 import { AGENT_TOOLS, BASH_TOOLS_SET, HIGH_RISK_TOOLS, LOW_RISK_WRITE_TOOLS, WRITE_TOOLS, } from '../constants/tools.js';
+const TRAJECTORY_GATE_BLOCK_RETRY_DELAY_MS = 250;
+const TRAJECTORY_GATE_BLOCK_MAX_RETRIES = 3;
 // ═══ GFI Gate Tool Tiers ═══
 // TIER 0: 只读工具 - 永不拦截
 // TIER 1: 低风险修改 - GFI >= low_risk_block 时拦截
-// 注意：pd_run_worker、sessions_spawn、task 是 Agent 派生工具，不应被 GFI Gate 拦截
-// 它们属于 AGENT_TOOLS，在早期过滤后直接放行
+// 注意：sessions_spawn、task 是 Agent 派生工具，常规阈值不拦截
+// 但极高 GFI (>=90) 时仍会拦截，防止极端情况下失控
 // TIER 2: 高风险操作 - GFI >= high_risk_block 时拦截
 // TIER 3: Bash 命令 - 根据内容判断
 /**
@@ -132,7 +134,7 @@ export function handleBeforeToolCall(event, ctx) {
         thinking_checkpoint: {
             enabled: false, // Default OFF
             window_ms: 5 * 60 * 1000,
-            high_risk_tools: ['run_shell_command', 'delete_file', 'move_file', 'pd_run_worker'],
+            high_risk_tools: ['run_shell_command', 'delete_file', 'move_file'],
         }
     };
     if (fs.existsSync(profilePath)) {
@@ -347,7 +349,13 @@ GFI: ${currentGfi}/100
         const trustScore = trustEngine.getScore();
         const stage = trustEngine.getStage();
         const trustSettings = wctx.config.get('trust') || {
-            limits: { stage_2_max_lines: 50, stage_3_max_lines: 300 }
+            limits: {
+                stage_2_max_lines: 50,
+                stage_3_max_lines: 300,
+                stage_2_max_percentage: 10,
+                stage_3_max_percentage: 15,
+                min_lines_fallback: 20,
+            }
         };
         const riskLevel = assessRiskLevel(relPath, { toolName: event.toolName, params: event.params }, profile.risk_paths);
         const lineChanges = estimateLineChanges({ toolName: event.toolName, params: event.params });
@@ -421,17 +429,34 @@ GFI: ${currentGfi}/100
             }
             if (risky || riskLevel !== 'LOW') {
                 // Block if not approved by whitelist
-                return block(relPath, `Trust score too low (${trustScore}). Stage 1 agents cannot modify risk paths or perform non-trivial edits.`, wctx, event.toolName, ctx.sessionId);
+                return block(relPath, `Trust score too low (${trustScore}). Stage 1 agents cannot modify risk paths or perform non-trivial edits.`, wctx, event.toolName, logger, ctx.sessionId);
             }
         }
         // Stage 2 (Editor): Block writes to risk paths. Block large changes.
         if (stage === 2) {
             if (risky) {
-                return block(relPath, `Stage 2 agents are not authorized to modify risk paths.`, wctx, event.toolName, ctx.sessionId);
+                return block(relPath, `Stage 2 agents are not authorized to modify risk paths.`, wctx, event.toolName, logger, ctx.sessionId);
+            }
+            // Percentage-based threshold calculation
+            const targetAbsolutePath = typeof filePath === 'string' ? path.join(ctx.workspaceDir, filePath) : null;
+            const targetLineCount = targetAbsolutePath ? getTargetFileLineCount(targetAbsolutePath) : null;
+            const minLinesFallback = trustSettings.limits?.min_lines_fallback ?? 20;
+            const stage2MaxPercentage = trustSettings.limits?.stage_2_max_percentage ?? 10;
+            const stage2FixedLimit = trustSettings.limits?.stage_2_max_lines ?? 50;
+            let effectiveLimit;
+            let limitType;
+            let actualPercentage = null;
+            if (targetLineCount !== null && targetLineCount > 0) {
+                effectiveLimit = calculatePercentageThreshold(targetLineCount, stage2MaxPercentage, minLinesFallback);
+                actualPercentage = Math.round((lineChanges / targetLineCount) * 100);
+                limitType = 'percentage';
+            }
+            else {
+                effectiveLimit = stage2FixedLimit;
+                limitType = 'fixed';
             }
-            const stage2Limit = trustSettings.limits?.stage_2_max_lines ?? 50;
-            if (lineChanges > stage2Limit) {
-                return block(relPath, `Modification too large (${lineChanges} lines) for Stage 2. Max allowed is ${stage2Limit}.`, wctx, event.toolName, ctx.sessionId);
+            if (lineChanges > effectiveLimit) {
+                return block(relPath, buildLineLimitReason(lineChanges, effectiveLimit, limitType, targetLineCount, actualPercentage, 2), wctx, event.toolName, logger, ctx.sessionId);
             }
         }
         // Stage 3 (Developer): Allow normal writes. Require READY plan for risk paths.
@@ -439,12 +464,29 @@ GFI: ${currentGfi}/100
             if (risky) {
                 const planStatus = getPlanStatus(ctx.workspaceDir);
                 if (planStatus !== 'READY') {
-                    return block(relPath, `No READY plan found. Stage 3 requires a plan for risk path modifications.`, wctx, event.toolName, ctx.sessionId);
+                    return block(relPath, `No READY plan found. Stage 3 requires a plan for risk path modifications.`, wctx, event.toolName, logger, ctx.sessionId);
                 }
             }
-            const stage3Limit = trustSettings.limits?.stage_3_max_lines ?? 300;
-            if (lineChanges > stage3Limit) {
-                return block(relPath, `Modification too large (${lineChanges} lines) for Stage 3. Max allowed is ${stage3Limit}.`, wctx, event.toolName, ctx.sessionId);
+            // Percentage-based threshold calculation
+            const targetAbsolutePath = typeof filePath === 'string' ? path.join(ctx.workspaceDir, filePath) : null;
+            const targetLineCount = targetAbsolutePath ? getTargetFileLineCount(targetAbsolutePath) : null;
+            const minLinesFallback = trustSettings.limits?.min_lines_fallback ?? 20;
+            const stage3MaxPercentage = trustSettings.limits?.stage_3_max_percentage ?? 15;
+            const stage3FixedLimit = trustSettings.limits?.stage_3_max_lines ?? 300;
+            let effectiveLimit;
+            let limitType;
+            let actualPercentage = null;
+            if (targetLineCount !== null && targetLineCount > 0) {
+                effectiveLimit = calculatePercentageThreshold(targetLineCount, stage3MaxPercentage, minLinesFallback);
+                actualPercentage = Math.round((lineChanges / targetLineCount) * 100);
+                limitType = 'percentage';
+            }
+            else {
+                effectiveLimit = stage3FixedLimit;
+                limitType = 'fixed';
+            }
+            if (lineChanges > effectiveLimit) {
+                return block(relPath, buildLineLimitReason(lineChanges, effectiveLimit, limitType, targetLineCount, actualPercentage, 3), wctx, event.toolName, logger, ctx.sessionId);
             }
         }
         // Stage 4 (Architect): Full bypass
@@ -473,7 +515,7 @@ GFI: ${currentGfi}/100
         if (risky && profile.gate?.require_plan_for_risk_paths) {
             const planStatus = getPlanStatus(ctx.workspaceDir);
             if (planStatus !== 'READY') {
-                return block(relPath, `No READY plan found in PLAN.md.`, wctx, event.toolName, ctx.sessionId);
+                return block(relPath, `No READY plan found in PLAN.md.`, wctx, event.toolName, logger, ctx.sessionId);
             }
         }
     }
@@ -494,12 +536,32 @@ GFI: ${currentGfi}/100
         }
     }
 }
-function block(filePath, reason, wctx, toolName, sessionId) {
-    const logger = console;
-    logger.error(`[PD_GATE] BLOCKED: ${filePath}. Reason: ${reason}`);
+/**
+ * Build a detailed reason message for line limit blocks.
+ */
+function buildLineLimitReason(lineChanges, effectiveLimit, limitType, targetLineCount, actualPercentage, stage) {
+    if (limitType === 'percentage' && targetLineCount !== null && actualPercentage !== null) {
+        return `Modification too large: ${lineChanges} lines (${actualPercentage}% of ${targetLineCount} lines). ` +
+            `Stage ${stage} limit is ${effectiveLimit} lines (${limitType}). ` +
+            `Threshold calculation: min(${targetLineCount} × ${actualPercentage}%, ${effectiveLimit} lines).`;
+    }
+    else {
+        return `Modification too large: ${lineChanges} lines. ` +
+            `Stage ${stage} limit is ${effectiveLimit} lines (fixed threshold). ` +
+            `Note: Could not read target file to calculate percentage-based limit. Check file permissions and encoding.`;
+    }
+}
+function block(filePath, reason, wctx, toolName, logger, sessionId) {
+    logger.error?.(`[PD_GATE] BLOCKED: ${filePath}. Reason: ${reason}`);
     if (sessionId) {
         trackBlock(sessionId);
     }
+    const trajectoryPayload = {
+        sessionId: sessionId ?? null,
+        toolName,
+        filePath,
+        reason,
+    };
     try {
         wctx.eventLog.recordGateBlock(sessionId, {
             toolName,
@@ -508,13 +570,61 @@ function block(filePath, reason, wctx, toolName, sessionId) {
         });
     }
     catch (error) {
-        logger.warn(`[PD_GATE] Failed to record gate block event: ${String(error)}`);
+        logger.warn?.(`[PD_GATE] Failed to record gate block event: ${String(error)}`);
+    }
+    try {
+        wctx.trajectory?.recordGateBlock?.(trajectoryPayload);
+    }
+    catch (error) {
+        logger.warn?.(`[PD_GATE] Failed to record trajectory gate block: ${String(error)}`);
+        scheduleTrajectoryGateBlockRetry(wctx, trajectoryPayload, 1, {
+            warn: (message) => logger.warn?.(message),
+            error: (message) => logger.error?.(message),
+        });
     }
     return {
         block: true,
-        blockReason: `[Principles Disciple] Security Gate Blocked this action.\nFile: ${filePath}\nReason: ${reason}\n\nHint: You may need a READY plan or a higher trust score to perform this action.`,
+        blockReason: `[Principles Disciple] Security Gate Blocked this action.
+File: ${filePath}
+Reason: ${reason}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📋 How to unblock this operation:
+
+1. Use the plan-script skill to create a PLAN.md:
+   → Invoke: skill:plan-script
+
+2. Fill in the plan with:
+   - Target Files: ${filePath}
+   - Steps: What you want to do (be specific)
+   - Metrics: How to verify success
+   - Active Mental Models: Select 2 relevant models from .principles/THINKING_OS.md
+   - Rollback: How to restore if it fails
+
+3. After completing the plan, set STATUS: READY in PLAN.md
+
+4. Retry the operation
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+This is a mandatory security gate. The operation was blocked because the modification exceeds the allowed threshold for your current trust stage.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`,
     };
 }
+function scheduleTrajectoryGateBlockRetry(wctx, payload, attempt, logger) {
+    if (attempt > TRAJECTORY_GATE_BLOCK_MAX_RETRIES) {
+        logger.error?.(`[PD_GATE] Failed to persist trajectory gate block after ${TRAJECTORY_GATE_BLOCK_MAX_RETRIES} retries: ${payload.toolName} ${payload.filePath}`);
+        return;
+    }
+    setTimeout(() => {
+        try {
+            wctx.trajectory?.recordGateBlock?.(payload);
+        }
+        catch (error) {
+            logger.warn(`[PD_GATE] Retrying trajectory gate block persistence: ${String(error)}`);
+            scheduleTrajectoryGateBlockRetry(wctx, payload, attempt + 1, logger);
+        }
+    }, TRAJECTORY_GATE_BLOCK_RETRY_DELAY_MS);
+}
 // ═══════════════════════════════════════════════════════════════
 // P-03: Edit Tool Force Verification
 // ═══════════════════════════════════════════════════════════════