create-principles-disciple 1.93.0 → 1.95.0

package/plugin/dist/core/control-ui-db.js

@@ -180,9 +180,15 @@ export class ControlUiDatabase {
         ON thinking_model_events(assistant_turn_id);
       CREATE INDEX IF NOT EXISTS idx_thinking_model_events_run_id
         ON thinking_model_events(run_id);
-
-      DROP VIEW IF EXISTS v_thinking_model_usage;
-      CREATE VIEW v_thinking_model_usage AS
+    `);
+        // Views depend on tables owned by TrajectoryDatabase (assistant_turns, tool_calls,
+        // pain_events, user_turns, correction_samples). If ControlUiDatabase is constructed
+        // before TrajectoryDatabase has run initSchema (e.g. llm_output is the first hook
+        // triggered on a fresh workspace), CREATE VIEW would throw and break the hook.
+        // Wrap each view creation in try/catch so missing-dependency views are skipped with
+        // a warning rather than aborting schema initialization (rc-9: no silent fallback —
+        // failures are surfaced via console.info).
+        this.createViewSafely('v_thinking_model_usage', `
       WITH totals AS (
         SELECT COUNT(*) AS assistant_turns FROM assistant_turns
       ),
@@ -205,10 +211,9 @@ export class ControlUiDatabase {
           ELSE ROUND(CAST(usage_rows.distinct_turns AS REAL) / CAST(totals.assistant_turns AS REAL), 4)
         END AS coverage_rate
       FROM usage_rows, totals
-      ORDER BY usage_rows.hits DESC, usage_rows.model_id ASC;
-
-      DROP VIEW IF EXISTS v_thinking_model_effectiveness;
-      CREATE VIEW v_thinking_model_effectiveness AS
+      ORDER BY usage_rows.hits DESC, usage_rows.model_id ASC
+    `);
+        this.createViewSafely('v_thinking_model_effectiveness', `
       WITH event_windows AS (
         SELECT
           e.id,
@@ -274,10 +279,9 @@ export class ControlUiDatabase {
         ) THEN 1 ELSE 0 END) AS correction_sample_windows
       FROM bounded_windows b
       GROUP BY b.model_id
-      ORDER BY events DESC, model_id ASC;
-
-      DROP VIEW IF EXISTS v_thinking_model_scenarios;
-      CREATE VIEW v_thinking_model_scenarios AS
+      ORDER BY events DESC, model_id ASC
+    `);
+        this.createViewSafely('v_thinking_model_scenarios', `
       SELECT
         e.model_id AS model_id,
         CAST(j.value AS TEXT) AS scenario,
@@ -290,19 +294,39 @@ export class ControlUiDatabase {
         END
       ) AS j
       GROUP BY e.model_id, CAST(j.value AS TEXT)
-      ORDER BY hits DESC, scenario ASC;
-
-      DROP VIEW IF EXISTS v_thinking_model_daily_trend;
-      CREATE VIEW v_thinking_model_daily_trend AS
+      ORDER BY hits DESC, scenario ASC
+    `);
+        this.createViewSafely('v_thinking_model_daily_trend', `
       SELECT
         substr(created_at, 1, 10) AS day,
         model_id,
         COUNT(*) AS hits
       FROM thinking_model_events
       GROUP BY substr(created_at, 1, 10), model_id
-      ORDER BY day ASC, model_id ASC;
+      ORDER BY day ASC, model_id ASC
     `);
     }
+    /**
+     * Create or replace a view, tolerating missing dependency tables.
+     *
+     * Views in ControlUiDatabase depend on tables created by TrajectoryDatabase
+     * (assistant_turns, tool_calls, pain_events, user_turns, correction_samples).
+     * If ControlUiDatabase is constructed before TrajectoryDatabase has created
+     * those tables, CREATE VIEW would throw. We DROP+CREATE with try/catch so
+     * missing-dependency views are skipped with a warning (rc-9: surfaced via
+     * console.info) rather than aborting schema initialization.
+     */
+    createViewSafely(viewName, viewBody) {
+        try {
+            this.db.exec(`DROP VIEW IF EXISTS ${viewName};`);
+            this.db.exec(`CREATE VIEW ${viewName} AS ${viewBody};`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            // rc-9: surface the failure — do not silently swallow
+            console.info(`[PD:ControlUiDatabase] view ${viewName} creation skipped: ${message}. It will be created on next TrajectoryDatabase initSchema().`);
+        }
+    }
     withWrite(fn) {
         return withLock(this.dbPath, fn, { lockSuffix: '.trajectory.lock', lockStaleMs: 30000 });
     }

package/plugin/dist/core/detection-funnel.d.ts

@@ -1,24 +1,38 @@
+/**
+ * Detection Funnel — PRI-446 thin adapter
+ *
+ * The pure three-layer funnel logic (LRU cache, async queue, layer dispatch)
+ * now lives in principles-core
+ * (runtime-v2/detection/detection-funnel-policy.ts). This file is a thin shell
+ * that wires DetectionFunnelCore with the two environment-coupled dependencies
+ * the plugin owns:
+ *   - crypto.createHash (the L2 cache key hasher)
+ *   - PainDictionary.match (the L1 exact matcher)
+ *   - shouldIgnorePainProtocolText (the protocol-token gate)
+ *
+ * It re-exports DetectionFunnel (same class name + constructor signature) and
+ * DetectionResult so DetectionService, llm.ts, and evolution-worker keep working
+ * unchanged.
+ *
+ * ERR checklist:
+ * - ERR-011: this is a thin adapter delegating to core pure logic.
+ */
 import { type PainDictionary } from './dictionary.js';
-export interface DetectionResult {
-    detected: boolean;
-    severity?: number;
-    ruleId?: string;
-    source: 'l1_exact' | 'l2_cache' | 'l3_async_queued' | 'l3_semantic_hit';
-}
+import { type DetectionResult } from '@principles/core/runtime-v2';
+export type { DetectionResult };
 /**
  * Orchestrates the three-layer detection funnel for pain signals.
+ *
+ * Delegates to the core DetectionFunnelCore, injecting the crypto hasher,
+ * the dictionary matcher, and the protocol-token gate.
  */
 export declare class DetectionFunnel {
-    private readonly cache;
-    private asyncQueue;
-    private readonly dictionary;
+    private readonly core;
     constructor(dictionary: PainDictionary);
     /**
      * Detects pain in the given text using L1 (Exact), L2 (Cache), and L3 (Async).
      */
     detect(text: string): DetectionResult;
-    private static computeHash;
-    private enqueueAsync;
     /**
      * Internal method for the worker to update the cache after a semantic hit.
      */

package/plugin/dist/core/detection-funnel.js

@@ -1,104 +1,56 @@
-import { createHash } from 'crypto';
-import { shouldIgnorePainProtocolText } from './dictionary.js';
 /**
- * A simple LRU Cache implementation using Map.
+ * Detection Funnel — PRI-446 thin adapter
+ *
+ * The pure three-layer funnel logic (LRU cache, async queue, layer dispatch)
+ * now lives in principles-core
+ * (runtime-v2/detection/detection-funnel-policy.ts). This file is a thin shell
+ * that wires DetectionFunnelCore with the two environment-coupled dependencies
+ * the plugin owns:
+ *   - crypto.createHash (the L2 cache key hasher)
+ *   - PainDictionary.match (the L1 exact matcher)
+ *   - shouldIgnorePainProtocolText (the protocol-token gate)
+ *
+ * It re-exports DetectionFunnel (same class name + constructor signature) and
+ * DetectionResult so DetectionService, llm.ts, and evolution-worker keep working
+ * unchanged.
+ *
+ * ERR checklist:
+ * - ERR-011: this is a thin adapter delegating to core pure logic.
  */
-class SimpleLRU {
-    cache;
-    maxSize;
-    constructor(maxSize = 100) {
-        this.cache = new Map();
-        this.maxSize = maxSize;
-    }
-    get(key) {
-        const item = this.cache.get(key);
-        if (item !== undefined) {
-            // Refresh: delete and re-insert
-            this.cache.delete(key);
-            this.cache.set(key, item);
-        }
-        return item;
-    }
-    set(key, value) {
-        if (this.cache.has(key)) {
-            this.cache.delete(key);
-        }
-        else if (this.cache.size >= this.maxSize) {
-            // Remove the oldest (first) item
-            const firstKey = this.cache.keys().next().value;
-            if (firstKey !== undefined) {
-                this.cache.delete(firstKey);
-            }
-        }
-        this.cache.set(key, value);
-    }
-}
+import { createHash } from 'crypto';
+import { shouldIgnorePainProtocolText } from './dictionary.js';
+import { DetectionFunnelCore, } from '@principles/core/runtime-v2';
 /**
  * Orchestrates the three-layer detection funnel for pain signals.
+ *
+ * Delegates to the core DetectionFunnelCore, injecting the crypto hasher,
+ * the dictionary matcher, and the protocol-token gate.
  */
 export class DetectionFunnel {
-    cache = new SimpleLRU(100);
-    asyncQueue = [];
-    dictionary;
+    core;
     constructor(dictionary) {
-        this.dictionary = dictionary;
+        this.core = new DetectionFunnelCore({
+            match: (text) => dictionary.match(text),
+            hash: (text) => createHash('sha256').update(text).digest('hex'),
+            shouldIgnoreProtocol: shouldIgnorePainProtocolText,
+        });
     }
     /**
      * Detects pain in the given text using L1 (Exact), L2 (Cache), and L3 (Async).
      */
     detect(text) {
-        if (shouldIgnorePainProtocolText(text)) {
-            return { detected: false, source: 'l1_exact' };
-        }
-        // --- Layer 1: Exact Match (Sync) ---
-        const exactMatch = this.dictionary.match(text);
-        if (exactMatch) {
-            return {
-                detected: true,
-                severity: exactMatch.severity,
-                ruleId: exactMatch.ruleId,
-                source: 'l1_exact'
-            };
-        }
-        // --- Layer 2: LRU Cache (Sync) ---
-        const hash = DetectionFunnel.computeHash(text);
-        const cached = this.cache.get(hash);
-        if (cached) {
-            return {
-                detected: cached.detected,
-                severity: cached.severity,
-                source: 'l2_cache'
-            };
-        }
-        // --- Layer 3: Async Semantic Queue ---
-        this.enqueueAsync(text);
-        return {
-            detected: false,
-            source: 'l3_async_queued'
-        };
-    }
-    static computeHash(text) {
-        return createHash('sha256').update(text).digest('hex');
-    }
-    enqueueAsync(text) {
-        if (this.asyncQueue.length < 1000) {
-            this.asyncQueue.push(text);
-        }
-        // Worker will pick this up and perform semantic search via createMemorySearchTool
+        return this.core.detect(text);
     }
     /**
      * Internal method for the worker to update the cache after a semantic hit.
      */
     updateCache(text, result) {
-        const hash = DetectionFunnel.computeHash(text);
-        this.cache.set(hash, result);
+        this.core.updateCache(text, result);
     }
     /**
      * Retrieves and clears the current asynchronous queue.
      */
     flushQueue() {
-        const queue = [...this.asyncQueue];
-        this.asyncQueue = [];
-        return queue;
+        return this.core.flushQueue();
     }
 }

package/plugin/dist/core/event-log.d.ts

@@ -1,4 +1,4 @@
-import type { EventLogEntry, DailyStats, EmpathyEventStats, ToolCallEventData, PainSignalEventData, RuleMatchEventData, RulePromotionEventData, HookExecutionEventData, GateBlockEventData, GateBypassEventData, PlanApprovalEventData, EvolutionTaskEventData, EmpathyRollbackEventData, DiagnosisTaskEventData, HeartbeatDiagnosisEventData, DiagnosticianReportEventData, PrincipleCandidateEventData, RuleEnforcedEventData, RuleHostEvaluatedEventData, RuleHostBlockedEventData, RuleHostRequireApprovalEventData, RuleHostAutoCorrectProposedEventData, RuleHostAutoCorrectAppliedEventData, RuntimeV2PromptActivationsInjectedEventData, RuleHostUnhealthyEventData } from '../types/event-types.js';
+import type { EventLogEntry, DailyStats, EmpathyEventStats, ToolCallEventData, PainSignalEventData, RulePromotionEventData, HookExecutionEventData, GateBlockEventData, GateBypassEventData, PlanApprovalEventData, EvolutionTaskEventData, EmpathyRollbackEventData, DiagnosisTaskEventData, HeartbeatDiagnosisEventData, DiagnosticianReportEventData, PrincipleCandidateEventData, RuleEnforcedEventData, RuleHostEvaluatedEventData, RuleHostBlockedEventData, RuleHostRequireApprovalEventData, RuleHostAutoCorrectProposedEventData, RuleHostAutoCorrectAppliedEventData, RuntimeV2PromptActivationsInjectedEventData, RuleHostUnhealthyEventData } from '../types/event-types.js';
 import type { PluginLogger } from '../openclaw-sdk.js';
 export declare class EventLog {
     private readonly logsDir;
@@ -11,7 +11,6 @@ export declare class EventLog {
     private flushTimer?;
     private currentEventsFile;
     private currentDate;
-    private readonly painScoreSums;
     constructor(stateDir: string, logger?: PluginLogger);
     private getEventsFile;
     private getTodayStr;
@@ -19,7 +18,6 @@ export declare class EventLog {
     private cleanupOldEventFiles;
     recordToolCall(sessionId: string | undefined, data: ToolCallEventData): void;
     recordPainSignal(sessionId: string | undefined, data: PainSignalEventData): void;
-    recordRuleMatch(sessionId: string | undefined, data: RuleMatchEventData): void;
     recordRulePromotion(data: RulePromotionEventData): void;
     recordHookExecution(data: HookExecutionEventData, opts?: {
         flushImmediately?: boolean;

package/plugin/dist/core/event-log.js

@@ -15,7 +15,8 @@ export class EventLog {
     flushTimer;
     currentEventsFile;
     currentDate;
-    painScoreSums = new Map();
+    // painScoreSums map removed (PRI-451 Wave 1.5): it only fed the dead
+    // stats.pain.avgScore counter, which is also removed.
     constructor(stateDir, logger) {
         this.logsDir = path.join(stateDir, 'logs');
         if (!fs.existsSync(this.logsDir)) {
@@ -68,9 +69,6 @@ export class EventLog {
     recordPainSignal(sessionId, data) {
         this.record('pain_signal', 'detected', sessionId, data);
     }
-    recordRuleMatch(sessionId, data) {
-        this.record('rule_match', 'detected', sessionId, data);
-    }
     recordRulePromotion(data) {
         this.record('rule_promotion', 'promoted', undefined, data);
     }
@@ -293,16 +291,8 @@ export class EventLog {
         }
         else if (entry.type === 'pain_signal') {
             const data = entry.data;
-            stats.pain.signalsDetected++;
-            stats.pain.maxScore = Math.max(stats.pain.maxScore, data.score);
-            if (data.source) {
-                stats.pain.signalsBySource[data.source] = (stats.pain.signalsBySource[data.source] || 0) + 1;
-            }
-            const currentSum = this.painScoreSums.get(entry.date) ?? 0;
-            this.painScoreSums.set(entry.date, currentSum + (data.score || 0));
-            stats.pain.avgScore = stats.pain.signalsDetected > 0
-                ? Math.round((currentSum + (data.score || 0)) / stats.pain.signalsDetected)
-                : 0;
+            // stats.pain.* counters removed (PRI-451 Wave 1.5): no live reader.
+            // The user_empathy aggregation below (stats.empathy.*) is LIVE and stays.
             if (data.source === 'user_empathy') {
                 if (data.deduped) {
                     stats.empathy.dedupedCount++;
@@ -358,14 +348,8 @@ export class EventLog {
             stats.empathy.rollbackCount++;
             stats.empathy.rolledBackScore += data.originalScore || 0;
         }
-        else if (entry.type === 'rule_match') {
-            const data = entry.data;
-            if (data.ruleId) {
-                stats.pain.rulesMatched[data.ruleId] = (stats.pain.rulesMatched[data.ruleId] || 0) + 1;
-            }
-        }
         else if (entry.type === 'rule_promotion') {
-            stats.pain.candidatesPromoted++;
+            // stats.pain.candidatesPromoted removed (PRI-451 Wave 1.5): dead counter.
             stats.evolution.rulesPromoted++;
         }
         else if (entry.type === 'evolution_task') {

package/plugin/dist/core/evolution-reducer.d.ts

@@ -52,20 +52,12 @@ export declare class EvolutionReducerImpl implements EvolutionReducer {
     private readonly failureStreak;
     private lastPromotedAt;
     private isReplaying;
-    /** Registered pain_detected callbacks (e.g., PainSignalBridge). */
-    private readonly _painCallbacks;
     constructor(opts: {
         workspaceDir: string;
         stateDir?: string;
     });
     emit(event: EvolutionLoopEvent): void;
     emitSync(event: EvolutionLoopEvent): void;
-    /**
-     * Register a callback for 'pain_detected' events.
-     * The callback is invoked synchronously within emitSync() after applyEvent completes.
-     * HG-4: Callbacks are fire-and-forget from the emitSync perspective.
-     */
-    on(callback: (event: EvolutionLoopEvent) => void): void;
     getEventLog(): EvolutionLoopEvent[];
     getCandidatePrinciples(): Principle[];
     getProbationPrinciples(): Principle[];

package/plugin/dist/core/evolution-reducer.js

@@ -38,8 +38,9 @@ export class EvolutionReducerImpl {
     failureStreak = new Map();
     lastPromotedAt = null;
     isReplaying = false;
-    /** Registered pain_detected callbacks (e.g., PainSignalBridge). */
-    _painCallbacks = [];
+    // _painCallbacks pub/sub removed (PRI-451 Wave 1): no code ever registered a
+    // callback via .on(). The pain_detected → PainSignalBridge bridge happens via
+    // emitPainDetectedEvent (hooks/pain.ts), not this pub/sub layer.
     constructor(opts) {
         this.workspaceDir = opts.workspaceDir;
         this.stateDir = opts.stateDir;
@@ -77,14 +78,9 @@ export class EvolutionReducerImpl {
         }
         // Performance: sweepExpiredProbation() moved to getProbationPrinciples() for lazy cleanup
     }
-    /**
-     * Register a callback for 'pain_detected' events.
-     * The callback is invoked synchronously within emitSync() after applyEvent completes.
-     * HG-4: Callbacks are fire-and-forget from the emitSync perspective.
-     */
-    on(callback) {
-        this._painCallbacks.push(callback);
-    }
+    // on(callback) pub/sub registration removed (PRI-451 Wave 1): dead code —
+    // no caller ever registered a callback. pain_detected events still flow via
+    // emitPainDetectedEvent → PainSignalBridge, unaffected.
     getEventLog() {
         return [...this.memoryEvents];
     }
@@ -522,15 +518,9 @@ export class EvolutionReducerImpl {
                 if (!this.isReplaying) {
                     this.onPainDetected(event.data, event.ts);
                 }
-                // PainSignalBridge subscriptions: invoke registered callbacks (fire-and-forget)
-                for (const cb of this._painCallbacks) {
-                    try {
-                        cb(event);
-                    }
-                    catch {
-                        // Keep the evolution loop resilient — callback errors must not propagate
-                    }
-                }
+                // _painCallbacks dispatch removed (PRI-451 Wave 1): no callback was ever
+                // registered via .on() (also removed). The pain_detected → PainSignalBridge
+                // bridge flows through emitPainDetectedEvent (hooks/pain.ts), not here.
                 return;
             case 'candidate_created':
                 this.onCandidateCreated(event.data, event.ts);

package/plugin/dist/core/intent-doc-reader-adapter.d.ts

@@ -0,0 +1,28 @@
+/**
+ * PRI-468 — Plugin adapter implementing the core `IntentDocReader` port.
+ *
+ * Bridges the plugin-owned `safeReadIntentDoc()` I/O function to the
+ * core-owned `IntentDocReader` interface so Stage A (in core) can read
+ * INTENT.md without core performing any filesystem I/O.
+ *
+ * This adapter only MAPS types — it adds no new I/O, no new flag checks,
+ * and no new telemetry. The underlying `safeReadIntentDoc()` already
+ * performs the flag-first check (SPEC §12), TTL+mtime cache, and size cap.
+ *
+ * ERR checklist:
+ *   EP-01 / ERR-001: never `as` — field-by-field mapping with typeof checks
+ *   EP-02 / ERR-025: plugin I/O file, whitelisted in architecture-regression
+ *   EP-03 / ERR-002: every degraded path flows through with reason + nextAction
+ *
+ * Architecture: this file is I/O (delegates to fs-reading safeReadIntentDoc).
+ * It will be added to KNOWN_PLUGIN_CORE_FILES in architecture-regression.test.ts.
+ */
+import type { IntentDocReader } from '@principles/core/runtime-v2';
+/**
+ * Create an IntentDocReader bound to a specific workspace.
+ *
+ * The returned reader is stateless beyond the workspace binding — each
+ * `readIntentDoc()` call delegates to `safeReadIntentDoc()`, which owns
+ * the TTL+mtime cache.
+ */
+export declare function createIntentDocReader(workspaceDir: string): IntentDocReader;

package/plugin/dist/core/intent-doc-reader-adapter.js

@@ -0,0 +1,56 @@
+/**
+ * PRI-468 — Plugin adapter implementing the core `IntentDocReader` port.
+ *
+ * Bridges the plugin-owned `safeReadIntentDoc()` I/O function to the
+ * core-owned `IntentDocReader` interface so Stage A (in core) can read
+ * INTENT.md without core performing any filesystem I/O.
+ *
+ * This adapter only MAPS types — it adds no new I/O, no new flag checks,
+ * and no new telemetry. The underlying `safeReadIntentDoc()` already
+ * performs the flag-first check (SPEC §12), TTL+mtime cache, and size cap.
+ *
+ * ERR checklist:
+ *   EP-01 / ERR-001: never `as` — field-by-field mapping with typeof checks
+ *   EP-02 / ERR-025: plugin I/O file, whitelisted in architecture-regression
+ *   EP-03 / ERR-002: every degraded path flows through with reason + nextAction
+ *
+ * Architecture: this file is I/O (delegates to fs-reading safeReadIntentDoc).
+ * It will be added to KNOWN_PLUGIN_CORE_FILES in architecture-regression.test.ts.
+ */
+import { safeReadIntentDoc } from './intent-doc-reader.js';
+/**
+ * Create an IntentDocReader bound to a specific workspace.
+ *
+ * The returned reader is stateless beyond the workspace binding — each
+ * `readIntentDoc()` call delegates to `safeReadIntentDoc()`, which owns
+ * the TTL+mtime cache.
+ */
+export function createIntentDocReader(workspaceDir) {
+    return {
+        readIntentDoc() {
+            const result = safeReadIntentDoc(workspaceDir);
+            if (result.ok && result.doc) {
+                const doc = result.doc;
+                const reference = {
+                    raw: typeof doc.raw === 'string' ? doc.raw : '',
+                    contentHash: typeof doc.contentHash === 'string' ? doc.contentHash : '',
+                    path: typeof doc.path === 'string' ? doc.path : '',
+                };
+                return {
+                    ok: true,
+                    found: true,
+                    flagEnabled: true,
+                    doc: reference,
+                };
+            }
+            // Degraded path — preserve structured reason + nextAction (EP-03 / ERR-002)
+            return {
+                ok: false,
+                found: result.found,
+                flagEnabled: result.flagEnabled,
+                reason: result.reason,
+                nextAction: result.nextAction,
+            };
+        },
+    };
+}

package/plugin/dist/core/intent-doc-reader.d.ts

@@ -0,0 +1,80 @@
+/**
+ * PRI-467 — safeReadIntentDoc: plugin I/O wrapper for reading INTENT.md.
+ *
+ * Reads `.principles/INTENT.md` with:
+ * - Feature flag check FIRST (SPEC §12: flag off → flag_disabled without fs)
+ * - TTL + mtime cache (60s TTL, mtime check) mirroring prompt.ts cachedReadFile
+ * - 32KB size cap (INTENT_MAX_BYTES)
+ * - Never throws — all errors return structured `reason` + `nextAction`
+ *
+ * Trust boundary (SPEC §12.2):
+ * - Raw content is returned for the pure builder to escape; this reader does
+ *   NOT escape or bound the content for prompt injection. The pure builder
+ *   `buildIntentFrictionBlock` handles escaping + bounding.
+ *
+ * ERR checklist:
+ * EP-01 / ERR-001, ERR-005: raw content validated with typeof, never `as`
+ * EP-02 / ERR-025, ERR-070: production path; plugin I/O file in the whitelist
+ * EP-03 / ERR-002, ERR-014: every degraded path returns structured reason + nextAction
+ * EP-09: tests use real fs writes in temp dirs
+ *
+ * Architecture: this file is I/O (fs, path). It is whitelisted in
+ * architecture-regression.test.ts KNOWN_PLUGIN_CORE_FILES.
+ */
+import { type IntentDocSections, type IntentDocWarning } from '@principles/core/runtime-v2';
+export type SafeReadIntentDocReason = 'flag_disabled' | 'not_found' | 'oversized' | 'read_error';
+export interface IntentDoc {
+    /** Raw INTENT.md content (unescaped — caller escapes for prompt injection). */
+    raw: string;
+    /** Parsed sections from the raw content. */
+    sections: IntentDocSections;
+    /** SHA-256 content hash for deduplication and audit. */
+    contentHash: string;
+    /** Absolute path to the INTENT.md file. */
+    path: string;
+    /** ISO timestamp when the doc was read. */
+    readAt: string;
+    /** Validation warnings (missing/empty/too_vague sections). */
+    warnings: IntentDocWarning[];
+}
+export interface SafeReadIntentDocResult {
+    /** True when the doc was successfully read and parsed. */
+    ok: boolean;
+    /** True when the INTENT.md file exists on disk. */
+    found: boolean;
+    /** True when the intent_engineering flag is enabled. */
+    flagEnabled: boolean;
+    /** The parsed IntentDoc, present only when ok=true. */
+    doc?: IntentDoc;
+    /** Structured reason for a degraded path (present when ok=false). */
+    reason?: SafeReadIntentDocReason;
+    /** Next action for the operator (present when ok=false). */
+    nextAction?: string;
+    /** Validation warnings (always present, empty when no warnings). */
+    warnings: IntentDocWarning[];
+}
+/**
+ * Reset the intent doc cache for test isolation.
+ * Call in beforeEach() to ensure tests don't pollute each other.
+ */
+export declare function resetIntentDocCacheForTest(workspaceDir?: string): void;
+/**
+ * Safely read INTENT.md for prompt injection.
+ *
+ * Contract (SPEC §12):
+ * 1. Flag check FIRST via loadFeatureFlagFromConfig. Flag off → flag_disabled
+ *    WITHOUT any fs access to INTENT.md.
+ * 2. Flag on → check TTL + mtime cache. If cached and fresh → return cached.
+ * 3. Otherwise → stat the file (oversized check), read, parse, validate, cache.
+ * 4. Never throws — all errors return structured reason + nextAction.
+ *
+ * @param workspaceDir - Absolute path to the workspace root
+ * @param options - Optional logger for debug-level diagnostics
+ * @returns SafeReadIntentDocResult (never throws)
+ */
+export declare function safeReadIntentDoc(workspaceDir: string, options?: {
+    logger?: {
+        debug?: (msg: string) => void;
+        warn?: (msg: string) => void;
+    };
+}): SafeReadIntentDocResult;