principles-disciple 1.7.5 → 1.7.6

package/dist/core/trajectory.js

@@ -4,6 +4,16 @@ import path from 'path';
 import crypto from 'crypto';
 import { withLock } from '../utils/file-lock.js';
 import { resolvePdPath } from './paths.js';
+import { SampleNotFoundError } from '../config/index.js';
+/**
+ * Trajectory database stores HISTORICAL and ANALYTICS data.
+ *
+ * PURPOSE: Track task outcomes, trust changes, and evolution progress over time.
+ * USAGE: Insights, trends, and Phase 3 supporting evidence (where explicitly allowed).
+ * NOT FOR: Control decisions, Phase 3 eligibility, or real-time operations.
+ *
+ * Runtime truth comes from: queue state, workspace trust scorecard, active sessions
+ */
 const DEFAULT_INLINE_THRESHOLD = 16 * 1024;
 const DEFAULT_BUSY_TIMEOUT_MS = 5000;
 const DEFAULT_ORPHAN_BLOB_GRACE_DAYS = 7;
@@ -217,6 +227,12 @@ export class TrajectoryDatabase {
       `).run(input.traceId, input.taskId ?? null, input.stage, input.level ?? 'info', input.message, input.summary ?? null, safeJson(input.metadata), input.createdAt ?? nowIso());
         });
     }
+    /**
+     * List evolution tasks with optional filtering.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     listEvolutionTasks(filters = {}) {
         const conditions = [];
         const values = [];
@@ -259,6 +275,12 @@ export class TrajectoryDatabase {
             updatedAt: String(row.updated_at),
         }));
     }
+    /**
+     * 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, filters = {}) {
         const limit = filters.limit ?? 100;
         const offset = filters.offset ?? 0;
@@ -292,6 +314,12 @@ export class TrajectoryDatabase {
             createdAt: String(row.created_at),
         }));
     }
+    /**
+     * Get evolution task by trace ID.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     getEvolutionTaskByTraceId(traceId) {
         const row = this.db.prepare(`
       SELECT id, task_id, trace_id, source, reason, score, status,
@@ -318,6 +346,12 @@ export class TrajectoryDatabase {
             updatedAt: String(row.updated_at),
         };
     }
+    /**
+     * Get evolution task statistics.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     getEvolutionStats() {
         const rows = this.db.prepare(`
       SELECT status, COUNT(*) as count FROM evolution_tasks GROUP BY status
@@ -336,6 +370,12 @@ export class TrajectoryDatabase {
         }
         return stats;
     }
+    /**
+     * List assistant turns for a session.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     listAssistantTurns(sessionId) {
         const rows = this.db.prepare(`
       SELECT id, session_id, run_id, provider, model, raw_text, sanitized_text, blob_ref, created_at
@@ -355,6 +395,12 @@ export class TrajectoryDatabase {
             createdAt: String(row.created_at),
         }));
     }
+    /**
+     * 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 = 'pending') {
         const rows = this.db.prepare(`
       SELECT sample_id, session_id, bad_assistant_turn_id, user_correction_turn_id,
@@ -397,7 +443,7 @@ export class TrajectoryDatabase {
             return true;
         });
         if (!updated) {
-            throw new Error(`Correction sample not found: ${sampleId}`);
+            throw new SampleNotFoundError(sampleId);
         }
         const record = this.db.prepare(`
       SELECT sample_id, session_id, bad_assistant_turn_id, user_correction_turn_id,
@@ -407,7 +453,7 @@ export class TrajectoryDatabase {
       WHERE sample_id = ?
     `).get(sampleId);
         if (!record) {
-            throw new Error(`Correction sample not found after review update: ${sampleId}`);
+            throw new SampleNotFoundError(`${sampleId} (after update)`);
         }
         return {
             sampleId: String(record.sample_id),
@@ -424,6 +470,12 @@ export class TrajectoryDatabase {
             updatedAt: String(record.updated_at),
         };
     }
+    /**
+     * Export correction samples to JSONL file.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     exportCorrections(opts) {
         const rows = this.db.prepare(`
       SELECT cs.sample_id, cs.session_id, cs.recovery_tool_span_json, cs.diff_excerpt, cs.quality_score,
@@ -462,6 +514,12 @@ export class TrajectoryDatabase {
         this.recordExportAudit('corrections', opts.mode, opts.approvedOnly, exportPath, rows.length);
         return { filePath: exportPath, count: rows.length, mode: opts.mode };
     }
+    /**
+     * Export analytics data to JSON file.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     exportAnalytics() {
         const payload = {
             generatedAt: nowIso(),
@@ -476,6 +534,12 @@ export class TrajectoryDatabase {
         this.recordExportAudit('analytics', 'raw', true, exportPath, Array.isArray(payload.dailyMetrics) ? payload.dailyMetrics.length : 0);
         return { filePath: exportPath, count: Array.isArray(payload.dailyMetrics) ? payload.dailyMetrics.length : 0 };
     }
+    /**
+     * Get trajectory database statistics.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     getDataStats() {
         const getCount = (table, where) => {
             const sql = where ? `SELECT COUNT(*) as count FROM ${table} WHERE ${where}` : `SELECT COUNT(*) as count FROM ${table}`;
@@ -729,6 +793,12 @@ export class TrajectoryDatabase {
       LEFT JOIN correction_daily ON correction_daily.day = tool_daily.day;
     `);
     }
+    /**
+     * Get daily metrics for analytics.
+     *
+     * Returns: Analytics data aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
     dailyMetrics() {
         return this.db.prepare('SELECT * FROM v_daily_metrics ORDER BY day ASC').all();
     }

package/dist/hooks/bash-risk.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Bash Risk Analysis Module
+ *
+ * Analyzes bash command security risks and determines command categorization.
+ *
+ * **Responsibilities:**
+ * - De-obfuscate Unicode/Cyrillic lookalike characters (security bypass prevention)
+ * - Tokenize command chains to detect multi-command bypasses
+ * - Classify commands as: 'safe', 'dangerous', or 'normal'
+ * - Pattern matching against safe/dangerous regex patterns
+ * - Fail-closed behavior (invalid regex = dangerous)
+ *
+ * **Configuration:**
+ * - Bash safe patterns from gfi_gate.bash_safe_patterns
+ * - Bash dangerous patterns from gfi_gate.bash_dangerous_patterns
+ */
+export interface BashRiskConfig {
+    bash_safe_patterns?: string[];
+    bash_dangerous_patterns?: string[];
+}
+export type BashRiskLevel = 'safe' | 'dangerous' | 'normal';
+/**
+ * Analyzes a bash command to determine its risk level.
+ *
+ * Implements security features:
+ * - Unicode/Cyrillic de-obfuscation to detect homograph attacks
+ * - Command chain tokenization to catch multi-command bypasses
+ * - Pattern matching against safe/dangerous regex patterns
+ * - Fail-closed behavior (invalid dangerous regex = dangerous)
+ *
+ * @param command - The bash command to analyze
+ * @param safePatterns - Regex patterns that indicate safe commands
+ * @param dangerousPatterns - Regex patterns that indicate dangerous commands
+ * @param logger - Optional logger for warnings about invalid patterns
+ * @returns The risk level: 'safe', 'dangerous', or 'normal'
+ */
+export declare function analyzeBashCommand(command: string, safePatterns: string[], dangerousPatterns: string[], logger?: {
+    warn?: (message: string) => void;
+}): BashRiskLevel;
+export interface DynamicThresholdConfig {
+    large_change_lines: number;
+    trust_stage_multipliers: Record<string, number>;
+}
+/**
+ * Calculates the dynamic GFI threshold based on trust stage and line changes.
+ *
+ * The threshold is adjusted by:
+ * 1. Trust stage multiplier (higher stages get higher thresholds)
+ * 2. Large change reduction (big edits lower the threshold to catch more issues)
+ *
+ * @param baseThreshold - The base GFI threshold (typically 50 for GFI)
+ * @param trustStage - Current trust stage (1-4)
+ * @param lineChanges - Number of lines being changed
+ * @param config - Configuration with large_change_lines and trust_stage_multipliers
+ * @returns The adjusted threshold (minimum 0)
+ */
+export declare function calculateDynamicThreshold(baseThreshold: number, trustStage: number, lineChanges: number, config: DynamicThresholdConfig): number;

package/dist/hooks/bash-risk.js

@@ -0,0 +1,137 @@
+/**
+ * Bash Risk Analysis Module
+ *
+ * Analyzes bash command security risks and determines command categorization.
+ *
+ * **Responsibilities:**
+ * - De-obfuscate Unicode/Cyrillic lookalike characters (security bypass prevention)
+ * - Tokenize command chains to detect multi-command bypasses
+ * - Classify commands as: 'safe', 'dangerous', or 'normal'
+ * - Pattern matching against safe/dangerous regex patterns
+ * - Fail-closed behavior (invalid regex = dangerous)
+ *
+ * **Configuration:**
+ * - Bash safe patterns from gfi_gate.bash_safe_patterns
+ * - Bash dangerous patterns from gfi_gate.bash_dangerous_patterns
+ */
+/**
+ * Analyzes a bash command to determine its risk level.
+ *
+ * Implements security features:
+ * - Unicode/Cyrillic de-obfuscation to detect homograph attacks
+ * - Command chain tokenization to catch multi-command bypasses
+ * - Pattern matching against safe/dangerous regex patterns
+ * - Fail-closed behavior (invalid dangerous regex = dangerous)
+ *
+ * @param command - The bash command to analyze
+ * @param safePatterns - Regex patterns that indicate safe commands
+ * @param dangerousPatterns - Regex patterns that indicate dangerous commands
+ * @param logger - Optional logger for warnings about invalid patterns
+ * @returns The risk level: 'safe', 'dangerous', or 'normal'
+ */
+export function analyzeBashCommand(command, safePatterns, dangerousPatterns, logger) {
+    let normalizedCmd = command.trim().toLowerCase();
+    // Unicode de-obfuscation — convert Cyrillic/Unicode lookalikes to ASCII equivalents
+    // Common Cyrillic lookalikes that could bypass detection: аеорсух (Cyrillic) → aeopcyx (Latin)
+    const CYRILLIC_TO_LATIN = {
+        'а': 'a', 'е': 'e', 'о': 'o', 'р': 'p', 'с': 'c', 'у': 'y', 'х': 'x',
+        'А': 'a', 'Е': 'e', 'О': 'o', 'Р': 'p', 'С': 'c', 'У': 'y', 'Х': 'x',
+        // Additional confusable chars
+        'і': 'i', 'ј': 'j', 'ѕ': 's', 'ԁ': 'd', 'ɡ': 'g', 'һ': 'h', 'ⅰ': 'i',
+        'ƚ': 'l', 'м': 'm', 'п': 'n', 'ѵ': 'v', 'ѡ': 'w', 'ᴦ': 'r', 'ꜱ': 's',
+    };
+    normalizedCmd = normalizedCmd.replace(/[а-яА-Яіјѕԁɡһⅰƚмпеꜱѵѡᴦꜱ]/g, m => CYRILLIC_TO_LATIN[m] ?? m);
+    // Zero-width character detection — detect hidden characters that could bypass pattern matching
+    // Common zero-width characters used in command injection:
+    // - Zero-width space (U+200B)
+    // - Zero-width non-joiner (U+200C)
+    // - Zero-width joiner (U+200D)
+    // - Word joiner (U+2060)
+    // - Zero-width invisible separator (U+FEFF)
+    const ZERO_WIDTH_CHARS = /[\u200B\u200C\u200D\u2060\uFEFF]/g;
+    if (ZERO_WIDTH_CHARS.test(command)) {
+        logger?.warn?.(`[PD_GATE] Bash command contains zero-width characters — blocking as dangerous`);
+        return 'dangerous'; // Fail-closed: zero-width chars are suspicious
+    }
+    // Tokenize command chain before pattern matching to catch `cmd1 && cmd2` bypasses
+    // Only split on statement separators (; && ||), NOT on pipe (|) which is part of the command
+    const tokens = normalizedCmd
+        .split(/\s*(?:;|&&|\|\|)\s*/)
+        .map(t => t.trim())
+        .filter(t => t.length > 0);
+    // If no tokens (e.g., pure pipe-only), use the original
+    const segments = tokens.length > 0 ? tokens : [normalizedCmd];
+    // Also strip outer $() and backticks from each segment, but PRESERVE inner content
+    const cleanSegments = segments.map(seg => {
+        let s = seg;
+        // Extract inner content from $() or ${} or backtick-wrapped commands
+        // IMPORTANT: Preserve the inner command for analysis, don't drop it entirely
+        s = s.replace(/^\$\(([^)]+)\)$/, '$1').replace(/^\$\{([^}]+)\}$/, '$1').replace(/^`([^`]+)`$/, '$1');
+        return s.trim();
+    }).filter(s => s.length > 0);
+    // SECURITY: If original input was non-empty but we have no analyzable content, fail closed
+    if (cleanSegments.length === 0 && normalizedCmd.trim().length > 0) {
+        logger?.warn?.(`[PD_GATE] Bash command analysis produced empty segments from non-empty input, failing closed: ${normalizedCmd.substring(0, 100)}`);
+        return 'dangerous';
+    }
+    // 1. Check dangerous patterns against each segment
+    for (const seg of cleanSegments) {
+        for (const pattern of dangerousPatterns) {
+            try {
+                if (new RegExp(pattern, 'i').test(seg)) {
+                    return 'dangerous';
+                }
+            }
+            catch (error) {
+                logger?.warn?.(`[PD_GATE] Invalid dangerous bash regex "${pattern}": ${String(error)}. Failing closed.`);
+                return 'dangerous';
+                // Fail-closed: 无效的危险模式正则视为匹配危险命令
+            }
+        }
+    }
+    // 2. Check safe patterns (only if ALL segments are safe)
+    for (const seg of cleanSegments) {
+        let isSafe = false;
+        for (const pattern of safePatterns) {
+            try {
+                if (new RegExp(pattern, 'i').test(seg)) {
+                    isSafe = true;
+                    break;
+                }
+            }
+            catch (error) {
+                logger?.warn?.(`[PD_GATE] Invalid safe bash regex "${pattern}": ${String(error)}. Ignoring safe override.`);
+            }
+        }
+        if (!isSafe) {
+            // Not all segments are safe → treat as normal
+            return 'normal';
+        }
+    }
+    // All segments are safe
+    return 'safe';
+}
+/**
+ * Calculates the dynamic GFI threshold based on trust stage and line changes.
+ *
+ * The threshold is adjusted by:
+ * 1. Trust stage multiplier (higher stages get higher thresholds)
+ * 2. Large change reduction (big edits lower the threshold to catch more issues)
+ *
+ * @param baseThreshold - The base GFI threshold (typically 50 for GFI)
+ * @param trustStage - Current trust stage (1-4)
+ * @param lineChanges - Number of lines being changed
+ * @param config - Configuration with large_change_lines and trust_stage_multipliers
+ * @returns The adjusted threshold (minimum 0)
+ */
+export function calculateDynamicThreshold(baseThreshold, trustStage, lineChanges, config) {
+    // 1. Trust Stage multiplier
+    const stageMultiplier = config.trust_stage_multipliers[trustStage.toString()] || 1.0;
+    let threshold = baseThreshold * stageMultiplier;
+    // 2. Large scale modification reduces threshold
+    if (lineChanges > config.large_change_lines) {
+        const ratio = Math.min(lineChanges / 200, 0.5); // Reduce by up to 50%
+        threshold = threshold * (1 - ratio);
+    }
+    return Math.round(Math.max(threshold, 0));
+}

package/dist/hooks/edit-verification.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Edit Verification Module
+ *
+ * Enforces P-03 (precise verification principle) for edit tool operations.
+ *
+ * **Responsibilities:**
+ * - Verify oldText matches current file content before edit
+ * - Fuzzy matching for whitespace-agnostic comparison
+ * - File size limits and binary file detection
+ * - Automatic correction of whitespace mismatches
+ * - Detailed error messages with guidance for fix
+ *
+ * **Configuration:**
+ * - Edit verification settings from profile.edit_verification
+ * - Max file size threshold (default 10MB)
+ * - Fuzzy match threshold (default 0.8)
+ * - Skip action for large files (warn/block)
+ */
+import type { PluginHookBeforeToolCallEvent, PluginHookBeforeToolCallResult } from '../openclaw-sdk.js';
+import type { WorkspaceContext } from '../core/workspace-context.js';
+export interface EditVerificationConfig {
+    enabled?: boolean;
+    max_file_size_bytes?: number;
+    fuzzy_match_enabled?: boolean;
+    fuzzy_match_threshold?: number;
+    skip_large_file_action?: 'warn' | 'block';
+}
+/**
+ * Normalize a line for fuzzy matching by collapsing whitespace
+ */
+export declare function normalizeLine(line: string): string;
+/**
+ * Find fuzzy match between oldText and current file content
+ * @param lines - File content split into lines
+ * @param oldLines - oldText split into lines
+ * @param threshold - Match threshold (0-1)
+ * @returns Match index or -1 if not found
+ */
+export declare function findFuzzyMatch(lines: string[], oldLines: string[], threshold?: number): number;
+/**
+ * Try to find a fuzzy match for oldText in current content
+ * @param currentContent - Current file content
+ * @param oldText - Text to match
+ * @param threshold - Match threshold (0-1)
+ * @returns Object with found status and corrected text if found
+ */
+export declare function tryFuzzyMatch(currentContent: string, oldText: string, threshold?: number): {
+    found: boolean;
+    correctedText?: string;
+};
+/**
+ * Generate a helpful error message for edit verification failure
+ */
+export declare function generateEditError(filePath: string, oldText: string, currentContent: string): string;
+/**
+ * Handle edit tool verification before allowing operation
+ * This enforces P-03 at the tool layer
+ */
+export declare function handleEditVerification(event: PluginHookBeforeToolCallEvent, wctx: WorkspaceContext, ctx: {
+    logger?: any;
+    sessionId?: string;
+}, config?: EditVerificationConfig): PluginHookBeforeToolCallResult | void;

package/dist/hooks/edit-verification.js

@@ -0,0 +1,256 @@
+/**
+ * Edit Verification Module
+ *
+ * Enforces P-03 (precise verification principle) for edit tool operations.
+ *
+ * **Responsibilities:**
+ * - Verify oldText matches current file content before edit
+ * - Fuzzy matching for whitespace-agnostic comparison
+ * - File size limits and binary file detection
+ * - Automatic correction of whitespace mismatches
+ * - Detailed error messages with guidance for fix
+ *
+ * **Configuration:**
+ * - Edit verification settings from profile.edit_verification
+ * - Max file size threshold (default 10MB)
+ * - Fuzzy match threshold (default 0.8)
+ * - Skip action for large files (warn/block)
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Normalize a line for fuzzy matching by collapsing whitespace
+ */
+export function normalizeLine(line) {
+    return line.replace(/\s+/g, ' ').trim();
+}
+/**
+ * Find fuzzy match between oldText and current file content
+ * @param lines - File content split into lines
+ * @param oldLines - oldText split into lines
+ * @param threshold - Match threshold (0-1)
+ * @returns Match index or -1 if not found
+ */
+export function findFuzzyMatch(lines, oldLines, threshold = 0.8) {
+    if (oldLines.length === 0)
+        return -1; // P2 fix: empty array boundary check
+    const normalizedLines = lines.map(normalizeLine);
+    const normalizedOldLines = oldLines.map(normalizeLine);
+    // Try to find matching sequence
+    for (let i = 0; i <= lines.length - oldLines.length; i++) {
+        let matchCount = 0;
+        for (let j = 0; j < oldLines.length; j++) {
+            if (normalizedLines[i + j] === normalizedOldLines[j]) {
+                matchCount++;
+            }
+        }
+        // Use threshold from config
+        if (matchCount >= oldLines.length * threshold) {
+            return i;
+        }
+    }
+    return -1;
+}
+/**
+ * Try to find a fuzzy match for oldText in current content
+ * @param currentContent - Current file content
+ * @param oldText - Text to match
+ * @param threshold - Match threshold (0-1)
+ * @returns Object with found status and corrected text if found
+ */
+export function tryFuzzyMatch(currentContent, oldText, threshold = 0.8) {
+    const lines = currentContent.split('\n');
+    const oldLines = oldText.split('\n');
+    const matchIndex = findFuzzyMatch(lines, oldLines, threshold);
+    if (matchIndex !== -1) {
+        // Found fuzzy match, extract actual text from file
+        const correctedText = lines.slice(matchIndex, matchIndex + oldLines.length).join('\n');
+        return { found: true, correctedText };
+    }
+    return { found: false };
+}
+/**
+ * Generate a helpful error message for edit verification failure
+ */
+export function generateEditError(filePath, oldText, currentContent) {
+    const expectedSnippet = oldText.split('\n').slice(0, 3).join('\n').substring(0, 200);
+    const actualSnippet = currentContent.substring(0, 200);
+    return `[P-03 Violation] Edit verification failed
+
+File: ${filePath}
+
+The text you're trying to replace does not match the current file content.
+
+Expected to find:
+${expectedSnippet}${oldText.length > 200 ? '...' : ''}
+
+Actual file contains:
+${actualSnippet}${currentContent.length > 200 ? '...' : ''}
+
+Possible reasons:
+  - File has been modified by another process
+  - Whitespace characters do not match (spaces, tabs, newlines)
+  - Context compression caused outdated information
+
+Solution:
+  1. Use 'read' tool to get current file content
+  2. Update your edit command with exact text from file
+  3. Retry edit operation
+
+This is enforced by P-03 (精确匹配前验证原则).`;
+}
+/**
+ * Handle edit tool verification before allowing operation
+ * This enforces P-03 at the tool layer
+ */
+export function handleEditVerification(event, wctx, ctx, config = {}) {
+    // Skip verification if disabled - return early without any processing or logging
+    if (config.enabled === false) {
+        return;
+    }
+    const logger = ctx.logger || console;
+    const maxSizeBytes = config.max_file_size_bytes ?? 10 * 1024 * 1024; // Default 10MB
+    const fuzzyMatchEnabled = config.fuzzy_match_enabled !== false;
+    const fuzzyMatchThreshold = config.fuzzy_match_threshold ?? 0.8;
+    const skipAction = config.skip_large_file_action ?? 'warn';
+    // 1. Extract parameters (handle both parameter naming conventions)
+    const filePath = event.params.file_path || event.params.path || event.params.file;
+    const oldText = event.params.oldText || event.params.old_string;
+    if (!filePath || !oldText) {
+        // Missing required parameters, let it fail naturally
+        return;
+    }
+    // 2. Resolve and read file
+    let absolutePath;
+    try {
+        absolutePath = wctx.resolve(filePath);
+    }
+    catch (error) {
+        // Path resolution error, let it fail naturally
+        return;
+    }
+    // 2.5. Skip verification for binary files
+    const BINARY_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.svg',
+        '.pdf', '.zip', '.tar', '.gz', '.7z', '.rar',
+        '.exe', '.dll', '.so', '.dylib', '.bin',
+        '.mp3', '.mp4', '.avi', '.mov', '.wav',
+        '.ttf', '.otf', '.woff', '.woff2',
+        '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx'];
+    const ext = path.extname(absolutePath).toLowerCase();
+    if (BINARY_EXTENSIONS.includes(ext)) {
+        logger?.info?.(`[PD_GATE:EDIT_VERIFY] Skipping verification for binary file: ${path.basename(filePath)}`);
+        return;
+    }
+    try {
+        // 2.6. Check file size before reading (P-03 improvement)
+        try {
+            const stats = fs.statSync(absolutePath);
+            const fileSizeBytes = stats.size;
+            const fileSizeMB = fileSizeBytes / (1024 * 1024);
+            if (fileSizeBytes > maxSizeBytes) {
+                const message = `[PD_GATE:EDIT_VERIFY] File size check: ${path.basename(filePath)} is ${fileSizeMB.toFixed(2)}MB (threshold: ${(maxSizeBytes / (1024 * 1024)).toFixed(2)}MB)`;
+                if (skipAction === 'block') {
+                    logger?.warn?.(message + ' - BLOCKED');
+                    return {
+                        block: true,
+                        blockReason: `${message}\n\nFile is too large for edit verification. Increase max_file_size_bytes in PROFILE.json or reduce file size.`
+                    };
+                }
+                else {
+                    logger?.warn?.(message + ' - SKIPPING verification');
+                    return; // Skip verification but allow operation
+                }
+            }
+            logger?.info?.(`[PD_GATE:EDIT_VERIFY] File size check passed: ${path.basename(filePath)} (${fileSizeMB.toFixed(2)}MB)`);
+        }
+        catch (statError) {
+            // File stat error (e.g., permission denied)
+            const errStr = statError instanceof Error ? statError.message : String(statError);
+            const errCode = statError.code;
+            if (errCode === 'EACCES' || errCode === 'EPERM') {
+                logger?.error?.(`[PD_GATE:EDIT_VERIFY] Permission denied accessing file: ${path.basename(filePath)} (${errStr})`);
+                return {
+                    block: true,
+                    blockReason: `[P-03 Error] Permission denied: Cannot access file ${absolutePath}\n\nError: ${errStr}\n\nSolution: Check file permissions or run with appropriate access rights.`
+                };
+            }
+            else if (errCode === 'ENOENT') {
+                logger?.warn?.(`[PD_GATE:EDIT_VERIFY] File not found: ${path.basename(filePath)} (${errStr})`);
+                // File doesn't exist - let edit operation proceed (it will create file)
+                return;
+            }
+            else {
+                logger?.warn?.(`[PD_GATE:EDIT_VERIFY] Stat error: ${errStr}`);
+                // Let it fail naturally on read attempt
+            }
+        }
+        // 3. Read current file content with improved error handling
+        let currentContent;
+        try {
+            currentContent = fs.readFileSync(absolutePath, 'utf-8');
+        }
+        catch (readError) {
+            const errStr = readError instanceof Error ? readError.message : String(readError);
+            const errCode = readError.code;
+            if (errCode === 'EACCES' || errCode === 'EPERM') {
+                logger?.error?.(`[PD_GATE:EDIT_VERIFY] Permission denied reading file: ${path.basename(filePath)} (${errStr})`);
+                return {
+                    block: true,
+                    blockReason: `[P-03 Error] Permission denied: Cannot read file ${absolutePath}\n\nError: ${errStr}\n\nSolution: Check file permissions or run with appropriate access rights.`
+                };
+            }
+            else if (errCode === 'ENOENT') {
+                logger?.warn?.(`[PD_GATE:EDIT_VERIFY] File not found: ${path.basename(filePath)} (${errStr})`);
+                // File doesn't exist - let edit operation proceed
+                return;
+            }
+            else if (errStr.includes('UTF-8') || errStr.includes('encoding')) {
+                logger?.error?.(`[PD_GATE:EDIT_VERIFY] Encoding error reading file: ${path.basename(filePath)} (${errStr})`);
+                return {
+                    block: true,
+                    blockReason: `[P-03 Error] Encoding error: Cannot read file ${absolutePath}\n\nError: ${errStr}\n\nThe file appears to use an encoding other than UTF-8. Edit verification requires UTF-8 readable text files.\n\nSolution: Ensure file is UTF-8 encoded text, or mark binary extensions to skip verification.`
+                };
+            }
+            else {
+                logger?.warn?.(`[PD_GATE:EDIT_VERIFY] Read error: ${errStr}`);
+                // Let it fail naturally
+                return;
+            }
+        }
+        // 4. Verify oldText exists in current content
+        if (!currentContent.includes(oldText)) {
+            logger?.info?.(`[PD_GATE:EDIT_VERIFY] Exact match failed for ${path.basename(filePath)}, trying fuzzy match`);
+            // 5. Try fuzzy matching (if enabled)
+            if (fuzzyMatchEnabled) {
+                const fuzzyResult = tryFuzzyMatch(currentContent, oldText, fuzzyMatchThreshold);
+                if (fuzzyResult.found && fuzzyResult.correctedText) {
+                    logger?.info?.(`[PD_GATE:EDIT_VERIFY] Fuzzy match found for ${path.basename(filePath)}, auto-correcting oldText`);
+                    // Return corrected parameters
+                    return {
+                        params: {
+                            ...event.params,
+                            oldText: fuzzyResult.correctedText,
+                            old_string: fuzzyResult.correctedText
+                        }
+                    };
+                }
+            }
+            // 6. No match found, block operation with helpful error
+            const errorMsg = generateEditError(absolutePath, oldText, currentContent);
+            logger?.error?.(`[PD_GATE:EDIT_VERIFY] Block edit on ${path.basename(filePath)}: oldText not found`);
+            return {
+                block: true,
+                blockReason: errorMsg
+            };
+        }
+        // 7. Verification passed, allow edit to proceed
+        logger?.info?.(`[PD_GATE:EDIT_VERIFY] Verified edit on ${path.basename(filePath)}`);
+        return;
+    }
+    catch (error) {
+        // Unexpected error - let it fail naturally
+        const errorStr = error instanceof Error ? error.message : String(error);
+        logger?.warn?.(`[PD_GATE:EDIT_VERIFY] Unexpected error: ${errorStr}`);
+        return;
+    }
+}