principles-disciple 1.7.6 → 1.7.8

package/dist/core/nocturnal-compliance.js

@@ -0,0 +1,824 @@
+/**
+ * Nocturnal Compliance Engine — Opportunity-Based Principle Evaluation
+ * =====================================================================
+ *
+ * Replaces session-average compliance with opportunity-based compliance.
+ *
+ * CORE CONCEPTS:
+ *
+ * Opportunity — a session context where a principle COULD have been applied.
+ *                An opportunity exists when the agent's action (or planned action)
+ *                falls within the principle's applicability scope.
+ *
+ * Compliance   — the principle was followed in an opportunity.
+ *                Determined by absence of violation signals, not presence of
+ *                positive confirmation (avoids LLM scoring).
+ *
+ * Violation   — strong evidence the principle was NOT followed.
+ *                Detected through deterministic event signals (pain, tool failures,
+ *                gate blocks) — no LLM involved.
+ *
+ * Dilution prevention — compliance is computed ONLY over sessions where the
+ *                         principle had an opportunity. Unrelated sessions
+ *                         (where T-05's risky operations never occurred) do NOT
+ *                         dilute the compliance rate.
+ *
+ * DESIGN CONSTRAINTS (Phase 1):
+ * - T-xx principles only (deterministic / weak-heuristic evaluability)
+ * - No P_xxx automation (requires detector metadata — Task 1.3 scope)
+ * - No LLM-based scoring
+ * - No training logic
+ *
+ * FILE: No file persistence — stateless computation over event stream.
+ *       Caller is responsible for writing results to principle-training-state.ts.
+ */
+// ---------------------------------------------------------------------------
+// Risky Operation Registry
+// ---------------------------------------------------------------------------
+/**
+ * Tools and operations that constitute risky actions.
+ * Gate blocks on these map to T-05 (Safety Rails) violations.
+ */
+const RISKY_TOOLS = new Set([
+    'delete_file',
+    'move_file',
+    'rename_file',
+    'delete_directory',
+    'bash',
+    'MultiExec',
+]);
+/**
+ * Bash command patterns that constitute dangerous operations.
+ * Matched against bash command text in tool_call events.
+ */
+const DANGEROUS_BASH_PATTERNS = [
+    /rm\s+(-[a-z]*r[a-z]*f?|-rf)/i, // rm -rf / rm -r
+    /del\s+\/[s/q]/i, // Windows del /s
+    /rmdir\s+\/s/i, // rmdir /s
+    /git\s+push\s+.*--force/i, // git push --force
+    /git\s+reset\s+--hard/i, // git reset --hard
+    /git\s+clean\s+-f[dx]/i, // git clean -fd
+    /npm\s+publish/i, // npm publish
+    /pip\s+upload/i, // pip upload
+    /docker\s+push/i, // docker push
+    /curl.+\|\s*(ba)?sh/i, // curl | bash
+    /wget.+\|\s*(ba)?sh/i, // wget | bash
+    /^make\s+[^-|]+$/i, // bare make (destructive)
+];
+/**
+ * Keywords in gate block reason that indicate a dangerous/risky operation.
+ * Used as a fallback when the tool itself is risky but the reason is free text.
+ */
+const RISKY_KEYWORDS_IN_REASON = [
+    /delete|remove|destroy|drop/i,
+    /force|unsafe|dangerous/i,
+    /format|truncate|overwrite/i,
+    /exec|eval|shell|command/i,
+    /credential|secret|password|token/i,
+];
+/**
+ * Edit/write tool names.
+ */
+const EDIT_TOOLS = new Set([
+    'edit_file',
+    'edit_file_batch',
+    'write_to_file',
+    'create_file',
+    'apply_patch',
+]);
+/**
+ * Read tool names.
+ */
+const READ_TOOLS = new Set([
+    'read_file',
+    'read_multiple_files',
+    'grep',
+    'search_files',
+    'list_directory',
+    'glob',
+]);
+// ---------------------------------------------------------------------------
+// Path Normalization (cross-platform)
+// ---------------------------------------------------------------------------
+/**
+ * Normalizes a file path to POSIX forward-slash format for consistent matching.
+ * Handles Windows backslash paths on any platform.
+ */
+function normalizePath(filePath) {
+    return filePath.replace(/\\/g, '/');
+}
+/**
+ * Returns true if the file path matches any of the given patterns when normalized.
+ */
+function pathMatches(filePath, patterns) {
+    if (!filePath)
+        return false;
+    const normalized = normalizePath(filePath);
+    return patterns.some((p) => p.test(normalized));
+}
+// ---------------------------------------------------------------------------
+// Opportunity Detection
+// ---------------------------------------------------------------------------
+/**
+ * Detects whether a given session presents an APPLICABLE OPPORTUNITY
+ * for a specific T-xx principle.
+ *
+ * An opportunity exists when the session context falls within the
+ * principle's applicability scope — regardless of whether the agent
+ * followed the principle.
+ *
+ * IMPORTANT: This does NOT assess compliance. It only answers:
+ *   "Could the principle have applied here?"
+ */
+export function detectOpportunity(principleId, session) {
+    switch (principleId) {
+        case 'T-01':
+            return detectT01Opportunity(session);
+        case 'T-02':
+            return detectT02Opportunity(session);
+        case 'T-03':
+            return detectT03Opportunity(session);
+        case 'T-04':
+            return detectT04Opportunity(session);
+        case 'T-05':
+            return detectT05Opportunity(session);
+        case 'T-06':
+            return detectT06Opportunity(session);
+        case 'T-07':
+            return detectT07Opportunity(session);
+        case 'T-08':
+            return detectT08Opportunity(session);
+        case 'T-09':
+            return detectT09Opportunity(session);
+        default:
+            return { applicable: false, reason: `Unknown principle: ${principleId}` };
+    }
+}
+/**
+ * T-01 "Survey Before Acting" — Understand the structure first before making changes.
+ *
+ * APPLICABLE when: Agent performs edit/write operations.
+ * Rationale: Any edit to code is an opportunity to survey first.
+ * Excluded: Read-only sessions (no applicable opportunity).
+ */
+function detectT01Opportunity(session) {
+    const hasEdit = session.toolCalls.some((call) => EDIT_TOOLS.has(call.toolName));
+    if (hasEdit) {
+        return { applicable: true, reason: 'Edit operations present — opportunity to survey before acting' };
+    }
+    return { applicable: false, reason: 'No edit operations in session — T-01 not applicable' };
+}
+/**
+ * T-02 "Respect Constraints" — Explicitly reason about contracts, tests, schemas.
+ *
+ * APPLICABLE when: Agent interacts with type/test/schema/contract files.
+ */
+function detectT02Opportunity(session) {
+    const hasConstraintInteraction = session.toolCalls.some((call) => {
+        if (!call.filePath)
+            return false;
+        const normalized = normalizePath(call.filePath);
+        return (/\.(ts|tsx|js|jsx)$/.test(normalized) || // type-aware files
+            /\b(test|spec|contract|schema|interface|type)\b/i.test(normalized));
+    });
+    if (hasConstraintInteraction) {
+        return { applicable: true, reason: 'Type/test/contract interaction — opportunity to respect constraints' };
+    }
+    return { applicable: false, reason: 'No type/test/contract interaction — T-02 not applicable' };
+}
+/**
+ * T-03 "Evidence Over Assumption" — Use logs, code, and outputs before inferring.
+ *
+ * APPLICABLE when: Pain signals or tool failures follow an edit/write operation.
+ * Rationale: When a change causes something to go wrong, there's an opportunity
+ * to gather evidence instead of assuming. Read-only failures are less relevant.
+ * Narrowed: requires an edit/write in the session before the failure/pain signal.
+ */
+function detectT03Opportunity(session) {
+    const hasWriteBeforeFailure = session.toolCalls.some((call, i) => {
+        if (call.outcome !== 'failure')
+            return false;
+        // Check that at least one prior call was an edit/write
+        const priorCalls = session.toolCalls.slice(0, i);
+        return priorCalls.some((c) => EDIT_TOOLS.has(c.toolName));
+    });
+    if (hasWriteBeforeFailure) {
+        return { applicable: true, reason: 'Write operation followed by failure — opportunity to gather evidence before retry' };
+    }
+    // Also applicable: pain signal with severity moderate+ (indicating something went wrong after a change)
+    const hasSignificantPain = session.painSignals.some((p) => p.severity === 'moderate' || p.severity === 'severe');
+    if (hasSignificantPain) {
+        return { applicable: true, reason: 'Significant pain signal — opportunity to use evidence over assumption' };
+    }
+    return { applicable: false, reason: 'No pain or failure on write operations — T-03 not applicable' };
+}
+/**
+ * T-04 "Reversible First" — Prefer changes that are safe to roll back.
+ *
+ * APPLICABLE when: Risky or destructive operations are attempted.
+ */
+function detectT04Opportunity(session) {
+    const hasRisky = session.toolCalls.some((call) => RISKY_TOOLS.has(call.toolName) || call.toolName === 'bash');
+    if (hasRisky) {
+        return { applicable: true, reason: 'Risky/destructive operations — opportunity to prefer reversible changes' };
+    }
+    return { applicable: false, reason: 'No risky operations — T-04 not applicable' };
+}
+/**
+ * T-05 "Safety Rails" — Call out guardrails, prohibitions, failure-prevention constraints.
+ *
+ * APPLICABLE when: A gate block fires on a risky operation.
+ * Rationale: The gate block IS the safety rail being tested. An opportunity
+ * exists when the system judged an operation risky enough to block.
+ * This makes T-05 applicable ONLY when gate blocks fire — preventing dilution
+ * by unrelated sessions.
+ *
+ * IMPORTANT: T-05's compliance is tied to gate blocks specifically.
+ * A risky operation without a gate block may still be a T-05 opportunity
+ * if the reason mentions safety-relevant terms.
+ */
+function detectT05Opportunity(session) {
+    const hasGateBlock = session.gateBlocks.length > 0;
+    if (hasGateBlock) {
+        return {
+            applicable: true,
+            reason: 'Gate block present — opportunity to call out safety rails',
+        };
+    }
+    // Also applicable when a risky operation is attempted
+    // (even if not yet blocked — the agent should self-censor)
+    const hasRisky = session.toolCalls.some((call) => {
+        if (RISKY_TOOLS.has(call.toolName))
+            return true;
+        // Check bash for dangerous patterns
+        if (call.toolName === 'bash' && call.errorMessage) {
+            return DANGEROUS_BASH_PATTERNS.some((p) => p.test(call.errorMessage));
+        }
+        return false;
+    });
+    if (hasRisky) {
+        return {
+            applicable: true,
+            reason: 'Risky operation attempted — opportunity to apply safety rails',
+        };
+    }
+    return {
+        applicable: false,
+        reason: 'No gate blocks or risky operations — T-05 not applicable in this session',
+    };
+}
+/**
+ * T-06 "Simplicity First" — Prefer the smallest understandable solution.
+ *
+ * APPLICABLE when: The task involves non-trivial code creation or refactoring.
+ */
+function detectT06Opportunity(session) {
+    const hasNonTrivialWrite = session.toolCalls.some((call) => call.toolName === 'create_file' ||
+        call.toolName === 'write_to_file' ||
+        (call.toolName === 'bash' && /\b(refactor|rewrite|overhaul)\b/i.test(call.errorMessage ?? '')));
+    if (hasNonTrivialWrite) {
+        return {
+            applicable: true,
+            reason: 'Non-trivial code creation — opportunity to prefer simplicity',
+        };
+    }
+    return { applicable: false, reason: 'No non-trivial writes — T-06 not applicable' };
+}
+/**
+ * T-07 "Minimal Change Surface" — Limit the blast radius.
+ *
+ * APPLICABLE when: Multiple files are touched in a single session.
+ */
+function detectT07Opportunity(session) {
+    const filePaths = session.toolCalls
+        .filter((call) => call.filePath !== undefined)
+        .map((call) => normalizePath(call.filePath));
+    const uniqueFiles = new Set(filePaths);
+    if (uniqueFiles.size >= 3) {
+        return {
+            applicable: true,
+            reason: `Multiple files touched (${uniqueFiles.size}) — opportunity to minimize change surface`,
+        };
+    }
+    return { applicable: false, reason: 'Few files touched — T-07 not applicable' };
+}
+/**
+ * T-08 "Pain As Signal" — Treat failures and friction as clues.
+ *
+ * APPLICABLE when: Pain signals are present after a failure.
+ */
+function detectT08Opportunity(session) {
+    const hasPain = session.painSignals.length > 0;
+    const hasFailure = session.toolCalls.some((call) => call.outcome === 'failure');
+    if (hasPain && hasFailure) {
+        return {
+            applicable: true,
+            reason: 'Pain signals following failures — opportunity to treat pain as signal',
+        };
+    }
+    return { applicable: false, reason: 'No pain-after-failure — T-08 not applicable' };
+}
+/**
+ * T-09 "Divide And Conquer" — Split the task into smaller phases before execution.
+ *
+ * APPLICABLE when: Complex operations are attempted (multi-file edits, refactors,
+ * architecture changes) OR when pain events occur on complex tasks.
+ *
+ * COMPLEXITY INDICATORS:
+ * - 5+ tool calls in a session (indicates multi-step task)
+ * - Multiple file paths touched
+ * - Pain events on multi-step tasks
+ * - Explicit "complex" or "refactor" or "architecture" in operations
+ */
+function detectT09Opportunity(session) {
+    const toolCallCount = session.toolCalls.length;
+    const uniqueFiles = new Set(session.toolCalls
+        .filter((call) => call.filePath !== undefined)
+        .map((call) => normalizePath(call.filePath)));
+    const hasComplexity = toolCallCount >= 5 || uniqueFiles.size >= 3;
+    const hasPain = session.painSignals.length > 0;
+    const hasFailure = session.toolCalls.some((call) => call.outcome === 'failure');
+    if (hasComplexity) {
+        return {
+            applicable: true,
+            reason: `Complex task detected (${toolCallCount} calls, ${uniqueFiles.size} files) — opportunity to decompose`,
+        };
+    }
+    if (hasPain || hasFailure) {
+        // Pain/failure may indicate the task was too complex without decomposition
+        return {
+            applicable: true,
+            reason: 'Pain or failure present — opportunity to decompose before retry',
+        };
+    }
+    return {
+        applicable: false,
+        reason: 'No complexity indicators — T-09 not applicable in this session',
+    };
+}
+// ---------------------------------------------------------------------------
+// Violation Detection
+// ---------------------------------------------------------------------------
+/**
+ * Detects whether a principle was VIOLATED in a session where an
+ * opportunity was applicable.
+ *
+ * Returns a ViolationMatch with violated=true if violation signals are present.
+ */
+export function detectViolation(principleId, session) {
+    switch (principleId) {
+        case 'T-01':
+            return detectT01Violation(session);
+        case 'T-02':
+            return detectT02Violation(session);
+        case 'T-03':
+            return detectT03Violation(session);
+        case 'T-04':
+            return detectT04Violation(session);
+        case 'T-05':
+            return detectT05Violation(session);
+        case 'T-06':
+            return detectT06Violation(session);
+        case 'T-07':
+            return detectT07Violation(session);
+        case 'T-08':
+            return detectT08Violation(session);
+        case 'T-09':
+            return detectT09Violation(session);
+        default:
+            return { violated: false, reason: `Unknown principle: ${principleId}` };
+    }
+}
+/**
+ * T-01 violation:
+ * - Pain signal or tool failure on an edit where the file was NOT read first
+ * - Pain signal with source indicating structural misunderstanding
+ */
+function detectT01Violation(session) {
+    // Build set of files that were read (normalized for cross-platform consistency)
+    const readFiles = new Set(session.toolCalls
+        .filter((call) => READ_TOOLS.has(call.toolName) && call.filePath !== undefined)
+        .map((call) => normalizePath(call.filePath)));
+    // Find edits to files that were NOT read first
+    const unreadEdits = session.toolCalls.filter((call) => EDIT_TOOLS.has(call.toolName) &&
+        call.filePath !== undefined &&
+        !readFiles.has(normalizePath(call.filePath)));
+    // If there were edits to unread files AND pain/failure followed → T-01 likely violated
+    if (unreadEdits.length > 0) {
+        const painOnUnreadEdit = session.painSignals.some((p) => unreadEdits.some((e) => e.filePath !== undefined && p.source.includes(e.filePath)) ||
+            /structure|architecture|dependency|context|before.*edit|survey/i.test(p.reason ?? ''));
+        if (painOnUnreadEdit) {
+            return {
+                violated: true,
+                reason: `Edits to unread files (${unreadEdits.length}) followed by pain — T-01 violated: agent acted without surveying first`,
+            };
+        }
+        // If edits to unread files AND tool failures → likely violated
+        const failuresOnUnread = unreadEdits.some((e) => e.outcome === 'failure');
+        if (failuresOnUnread) {
+            return {
+                violated: true,
+                reason: `Edits to unread files (${unreadEdits.length}) followed by failures — T-01 violated: agent acted without understanding`,
+            };
+        }
+    }
+    // Also check for pain signals specifically mentioning T-01-relevant themes
+    // without any prior read
+    const hasPainTheme = /structure|architecture|context|before.*acting|didn't.*survey|didn't.*read.*first/i.test(session.painSignals.map((p) => p.reason ?? '').join(' '));
+    if (hasPainTheme && unreadEdits.length > 0) {
+        return {
+            violated: true,
+            reason: 'Pain signals mentioning structure/context themes after edits to unread files — T-01 violated',
+        };
+    }
+    return {
+        violated: false,
+        reason: 'No violation signals detected for T-01',
+    };
+}
+/**
+ * T-02 violation:
+ * - Tool failures on type/test/contract interactions without prior verification
+ */
+function detectT02Violation(session) {
+    const constraintFailures = session.toolCalls.filter((call) => call.outcome === 'failure' &&
+        call.filePath !== undefined &&
+        (/\b(test|spec|contract|schema|interface|type)\b/i.test(call.filePath) ||
+            /\b(type|test|contract)\b/i.test(call.errorMessage ?? '')));
+    if (constraintFailures.length > 0) {
+        return {
+            violated: true,
+            reason: `Tool failures on type/test/contract interactions (${constraintFailures.length}) — T-02 violated: constraints not verified`,
+        };
+    }
+    return { violated: false, reason: 'No violation signals for T-02' };
+}
+/**
+ * T-03 violation:
+ * - Tool failures without prior evidence gathering (no read calls before failure)
+ */
+function detectT03Violation(session) {
+    const failureIndices = session.toolCalls
+        .map((call, i) => (call.outcome === 'failure' ? i : -1))
+        .filter((i) => i >= 0);
+    for (const failIdx of failureIndices) {
+        const priorCalls = session.toolCalls.slice(0, failIdx);
+        const hasPriorRead = priorCalls.some((call) => READ_TOOLS.has(call.toolName) && call.filePath !== undefined);
+        if (!hasPriorRead) {
+            return {
+                violated: true,
+                reason: `Tool failure at index ${failIdx} without prior read operations — T-03 violated: assumption made without evidence`,
+            };
+        }
+    }
+    return { violated: false, reason: 'No violation signals for T-03' };
+}
+/**
+ * T-04 violation:
+ * - Pain signals following risky operations (the operation succeeded but caused issues)
+ */
+function detectT04Violation(session) {
+    const riskyIndices = session.toolCalls
+        .map((call, i) => (RISKY_TOOLS.has(call.toolName) || call.toolName === 'bash' ? i : -1))
+        .filter((i) => i >= 0);
+    if (riskyIndices.length === 0)
+        return { violated: false, reason: 'No risky operations — T-04 not violated' };
+    // If risky operations AND pain signals are present in the same session,
+    // that indicates the risky operation caused negative consequences.
+    const hasPain = session.painSignals.length > 0;
+    if (hasPain) {
+        return {
+            violated: true,
+            reason: 'Pain signals present alongside risky operations — T-04 violated: irreversible consequences',
+        };
+    }
+    return { violated: false, reason: 'No violation signals for T-04' };
+}
+/**
+ * T-05 violation:
+ * - Gate block fires → the agent tried a risky operation without first applying
+ *   safety reasoning. The gate block IS the violation signal.
+ * - Gate block on a dangerous bash command is an explicit violation.
+ */
+function detectT05Violation(session) {
+    if (session.gateBlocks.length > 0) {
+        // Check if any gate block was on a dangerous operation.
+        // A block is dangerous if:
+        // 1. The tool is in RISKY_TOOLS (delete_file, bash, MultiExec, etc.)
+        // 2. The tool is 'bash' AND the reason mentions a dangerous pattern
+        // 3. The reason contains risky keywords (delete, force, credential, exec, etc.)
+        const dangerousBlocks = session.gateBlocks.filter((block) => {
+            if (RISKY_TOOLS.has(block.toolName))
+                return true;
+            if (block.toolName === 'bash' && DANGEROUS_BASH_PATTERNS.some((p) => p.test(block.reason)))
+                return true;
+            // Fallback: scan reason for risky keywords
+            if (RISKY_KEYWORDS_IN_REASON.some((p) => p.test(block.reason)))
+                return true;
+            return false;
+        });
+        if (dangerousBlocks.length > 0) {
+            return {
+                violated: true,
+                reason: `Gate blocks on dangerous operations (${dangerousBlocks.length}) — T-05 violated: safety rail not called out`,
+            };
+        }
+        return {
+            violated: true,
+            reason: `Gate blocks present (${session.gateBlocks.length}) — T-05 violated: safety rail not respected`,
+        };
+    }
+    return { violated: false, reason: 'No gate blocks — T-05 not violated' };
+}
+/**
+ * T-06 violation:
+ * - Over-engineering signals: pain from overly complex solutions
+ */
+function detectT06Violation(session) {
+    const hasOverEngineerPain = session.painSignals.some((p) => /over.*engineer|over.*complicat|too.*complex|unnecessarily.*complex/i.test(p.reason ?? '') &&
+        p.severity === 'severe');
+    if (hasOverEngineerPain) {
+        return {
+            violated: true,
+            reason: 'Severe pain from over-engineering — T-06 violated: simplicity not preferred',
+        };
+    }
+    return { violated: false, reason: 'No over-engineering signals — T-06 not violated' };
+}
+/**
+ * T-07 violation:
+ * - Pain from wide blast radius: many files modified, cascading failures
+ */
+function detectT07Violation(session) {
+    const modifiedFiles = new Set(session.toolCalls
+        .filter((call) => EDIT_TOOLS.has(call.toolName) && call.filePath !== undefined)
+        .map((call) => normalizePath(call.filePath)));
+    const failures = session.toolCalls.filter((call) => call.outcome === 'failure');
+    if (modifiedFiles.size >= 5 && failures.length >= 2) {
+        return {
+            violated: true,
+            reason: `Wide blast radius (${modifiedFiles.size} files, ${failures.length} failures) — T-07 violated: change surface not minimized`,
+        };
+    }
+    return { violated: false, reason: 'No blast radius violations — T-07 not violated' };
+}
+/**
+ * T-08 violation:
+ * - Pain signal present but no reflection/self-correction behavior
+ * (This is harder to detect without explicit reflection events.
+ *  We use pain-without-correction as a proxy.)
+ */
+function detectT08Violation(session) {
+    const hasPain = session.painSignals.length > 0;
+    const hasFailure = session.toolCalls.some((call) => call.outcome === 'failure');
+    // If pain and failure, but the agent immediately retries without pause/reflect
+    if (hasPain && hasFailure) {
+        // Find the first failure index and check if the agent continued without reflecting
+        const failureIdx = session.toolCalls.findIndex((c) => c.outcome === 'failure');
+        if (failureIdx >= 0) {
+            const postFailure = session.toolCalls.slice(failureIdx + 1, failureIdx + 4);
+            // If the agent immediately continues without a read/reflect call, T-08 may be violated
+            const continuesImmediately = postFailure.length > 0 && !postFailure.some((c) => READ_TOOLS.has(c.toolName));
+            if (continuesImmediately) {
+                return {
+                    violated: true,
+                    reason: 'Failure followed immediately by continued operations without pause/reflect — T-08 violated: pain not treated as signal',
+                };
+            }
+        }
+    }
+    return { violated: false, reason: 'No T-08 violation signals detected' };
+}
+/**
+ * T-09 violation:
+ * - Pain or failures on complex tasks that should have been decomposed.
+ * Signal: pain/failure on multi-step task without prior planning calls.
+ */
+function detectT09Violation(session) {
+    const toolCallCount = session.toolCalls.length;
+    const uniqueFiles = new Set(session.toolCalls
+        .filter((call) => call.filePath !== undefined)
+        .map((call) => normalizePath(call.filePath)));
+    // Only applies if the session was complex
+    if (toolCallCount < 5 && uniqueFiles.size < 3) {
+        return { violated: false, reason: 'Session not complex enough for T-09 applicability' };
+    }
+    // Check: failures on complex task without prior planning
+    const hasFailures = session.toolCalls.some((call) => call.outcome === 'failure');
+    const hasPain = session.painSignals.length > 0;
+    if (hasFailures || hasPain) {
+        // Check if the agent showed decomposition/planning behavior
+        const hasPlanApproval = session.planApprovals.length > 0;
+        const hasReadFirst = session.toolCalls.some((call) => READ_TOOLS.has(call.toolName));
+        if (!hasPlanApproval && !hasReadFirst) {
+            return {
+                violated: true,
+                reason: `Complex task with failures/pain but no planning or decomposition signals — T-09 violated: task not divided`,
+            };
+        }
+    }
+    return { violated: false, reason: 'No T-09 violation signals' };
+}
+// ---------------------------------------------------------------------------
+// Compliance Computation
+// ---------------------------------------------------------------------------
+/**
+ * Computes compliance metrics for a single T-xx principle across a batch of sessions.
+ *
+ * DILUTION PREVENTION:
+ * - Sessions where the principle had NO opportunity are EXCLUDED from
+ *   applicableOpportunityCount and do not affect complianceRate.
+ * - Example: T-05 sessions with no risky operations do not dilute
+ *   the compliance rate computed from T-05 sessions with gate blocks.
+ *
+ * TREND COMPUTATION:
+ * - Sessions are ordered chronologically (most recent first).
+ * - Current window: last 3 applicable sessions.
+ * - Previous window: sessions 4-6 (if available).
+ * - If either window has < 1 applicable session, trend = 0 (insufficient data).
+ * - Otherwise: trend = prevViolationRate - currentViolationRate
+ *   (+1 = improving, 0 = stable, -1 = worsening).
+ */
+export function computeCompliance(principleId, sessions, options = {}) {
+    const windowSize = options.trendWindowSize ?? 3;
+    let applicableOpportunityCount = 0;
+    let observedViolationCount = 0;
+    const applicableSessions = [];
+    for (const session of sessions) {
+        const opp = detectOpportunity(principleId, session);
+        if (!opp.applicable) {
+            // Principle had no opportunity in this session — skip entirely.
+            // This is the key dilution-prevention mechanism.
+            continue;
+        }
+        applicableOpportunityCount++;
+        const violation = detectViolation(principleId, session);
+        if (violation.violated) {
+            observedViolationCount++;
+        }
+        applicableSessions.push({
+            session,
+            violated: violation.violated,
+            reason: violation.reason,
+        });
+    }
+    // Compute complianceRate
+    const complianceRate = applicableOpportunityCount > 0
+        ? (applicableOpportunityCount - observedViolationCount) / applicableOpportunityCount
+        : 0;
+    // Compute violationTrend using windows
+    const violationTrend = computeViolationTrend(applicableSessions, windowSize);
+    // Build explanation
+    const explanation = buildExplanation(principleId, applicableOpportunityCount, observedViolationCount, complianceRate, violationTrend, applicableSessions);
+    return {
+        principleId,
+        applicableOpportunityCount,
+        observedViolationCount,
+        complianceRate,
+        violationTrend,
+        explanation,
+    };
+}
+/**
+ * Computes violation trend across the applicable session list.
+ *
+ * Trend is positive (+1) when violations are DECREASING (improving).
+ * Trend is negative (-1) when violations are INCREASING (worsening).
+ *
+ * Sessions are ordered most-recent-first.
+ *   currentWindow = first windowSize sessions (most recent)
+ *   previousWindow = next windowSize sessions
+ */
+function computeViolationTrend(applicableSessions, windowSize) {
+    if (applicableSessions.length < 2) {
+        // Not enough data for trend
+        return 0;
+    }
+    // Sessions are ordered most-recent-first in the input array.
+    // currentWindow = most recent N sessions
+    // previousWindow = N sessions before that (older)
+    const currentWindow = applicableSessions.slice(0, windowSize);
+    const previousWindow = applicableSessions.slice(windowSize, windowSize * 2);
+    if (currentWindow.length === 0)
+        return 0;
+    const currentViolationRate = currentWindow.filter((s) => s.violated).length / currentWindow.length;
+    if (previousWindow.length === 0) {
+        // No previous window — compare to overall rate
+        const overallRate = applicableSessions.filter((s) => s.violated).length / applicableSessions.length;
+        if (currentViolationRate < overallRate - 0.1)
+            return 1; // improving
+        if (currentViolationRate > overallRate + 0.1)
+            return -1; // worsening
+        return 0;
+    }
+    const previousViolationRate = previousWindow.filter((s) => s.violated).length / previousWindow.length;
+    const delta = previousViolationRate - currentViolationRate;
+    if (delta > 0.1)
+        return 1; // violations decreasing → improving
+    if (delta < -0.1)
+        return -1; // violations increasing → worsening
+    return 0; // stable
+}
+/**
+ * Builds a human-readable explanation for the compliance result.
+ */
+function buildExplanation(principleId, applicableOpportunityCount, observedViolationCount, complianceRate, violationTrend, applicableSessions) {
+    const trendStr = violationTrend === 1
+        ? '↑ improving'
+        : violationTrend === -1
+            ? '↓ worsening'
+            : '→ stable';
+    if (applicableOpportunityCount === 0) {
+        return `${principleId}: No applicable opportunities in provided sessions — compliance cannot be assessed.`;
+    }
+    const violationExamples = applicableSessions
+        .filter((s) => s.violated)
+        .slice(0, 2)
+        .map((s) => `  • ${s.reason}`)
+        .join('\n');
+    return [
+        `${principleId}: ${applicableOpportunityCount} applicable opportunities, ${observedViolationCount} violations.`,
+        `Compliance rate: ${(complianceRate * 100).toFixed(1)}%. Trend: ${trendStr}.`,
+        violationExamples ? `Sample violation signals:\n${violationExamples}` : 'No violations detected in recent sessions.',
+    ].join('\n');
+}
+// ---------------------------------------------------------------------------
+// Batch Update Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Computes compliance results for all T-01 through T-09 principles
+ * across the provided sessions.
+ *
+ * Sessions are assumed to be ordered most-recent-first.
+ */
+export function computeAllCompliance(sessions, options = {}) {
+    const results = [];
+    for (const id of ['T-01', 'T-02', 'T-03', 'T-04', 'T-05', 'T-06', 'T-07', 'T-08', 'T-09']) {
+        results.push(computeCompliance(id, sessions, options));
+    }
+    return results;
+}
+/**
+ * Converts raw EventLogEntry[] from event-types.ts into SessionEvents.
+ *
+ * Groups events by sessionId and maps to the SessionEvents interface.
+ * Events with no sessionId are grouped under sessionId = 'unknown'.
+ */
+export function groupEventsIntoSessions(events) {
+    const sessionMap = new Map();
+    for (const event of events) {
+        const sessionId = event.sessionId ?? 'unknown';
+        if (!sessionMap.has(sessionId)) {
+            sessionMap.set(sessionId, {
+                sessionId,
+                toolCalls: [],
+                painSignals: [],
+                gateBlocks: [],
+                userCorrections: [],
+                planApprovals: [],
+            });
+        }
+        const session = sessionMap.get(sessionId);
+        switch (event.type) {
+            case 'tool_call':
+                if (event.data.toolName) {
+                    session.toolCalls.push({
+                        toolName: event.data.toolName,
+                        filePath: event.data.filePath,
+                        outcome: (event.data.error ? 'failure' : 'success'),
+                        errorType: event.data.errorType,
+                        errorMessage: event.data.error,
+                    });
+                }
+                break;
+            case 'pain_signal':
+                session.painSignals.push({
+                    source: event.data.source ?? 'unknown',
+                    score: event.data.score ?? 0,
+                    severity: event.data.severity,
+                    reason: event.data.reason,
+                });
+                break;
+            case 'gate_block':
+                session.gateBlocks.push({
+                    toolName: event.data.toolName ?? 'unknown',
+                    filePath: event.data.filePath,
+                    reason: event.data.reason ?? '',
+                });
+                break;
+            case 'empathy_rollback':
+                // User corrections are flagged via empathy rollback
+                session.userCorrections.push({
+                    correctionCue: event.data.reason,
+                });
+                break;
+            case 'plan_approval':
+                session.planApprovals.push({
+                    toolName: event.data.toolName ?? 'unknown',
+                    filePath: event.data.filePath,
+                });
+                break;
+        }
+    }
+    return sessionMap;
+}