create-principles-disciple 1.94.0 → 1.96.0

package/plugin/dist/core/behavior-example-pack-assembler.js

@@ -0,0 +1,247 @@
+/**
+ * PRI-484 — Phase 5 Task 28 — BehaviorExamplePackAssembler (plugin I/O)
+ *
+ * Reads pain lineage + trajectory rows from TrajectoryDatabase and assembles
+ * a validated BehaviorExamplePack for the Artificer. Fail loud on any gap
+ * (missing pain, empty trajectory, invalid pack) — no silent fallback.
+ *
+ * Err-prevention:
+ *   - ERR-001: every DB row field validated as `unknown` (no `as` bypass on
+ *     parsed params_json or row casts).
+ *   - ERR-069: Artificer shared schema — invalid pack must fail loud.
+ *   - ERR-026: reuses production TrajectoryDatabase (no hand-written DDL).
+ *   - rc-2: structural type guards, no `as T` on parsed input.
+ *   - rc-5: Object.hasOwn over `in`.
+ *   - rc-9: every failure path throws a structured Error with a clear reason.
+ *
+ * Spec: docs/superpowers/specs/2026-06-27-rulecode-context-vision-design.md §7.2
+ *
+ * Boundary: this module is I/O. Pure logic (type + validator) lives in
+ * `@principles/core/runtime-v2` → `behavior-example-pack.ts`.
+ */
+import { validateBehaviorExamplePack, } from '@principles/core/runtime-v2';
+import { TrajectoryRegistry } from './trajectory.js';
+// ── internal constants ─────────────────────────────────────────────────────
+const MAX_POSITIVES = 3;
+const MAX_EVIDENCE_REFS = 5;
+const HISTORY_LIMIT = 100;
+const PROTO_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+// ── type guards (rc-2: no `as` bypass) ─────────────────────────────────────
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasNoProtoKeys(value) {
+    for (const key of Object.keys(value)) {
+        if (PROTO_KEYS.has(key))
+            return false;
+    }
+    return true;
+}
+// ── BehaviorExamplePackAssembler ───────────────────────────────────────────
+/**
+ * Plugin I/O assembler: pain lineage + trajectory → validated BehaviorExamplePack.
+ *
+ * Lifecycle: cheap to construct; obtains TrajectoryDatabase via the registry.
+ * Dispose is the registry's responsibility (singleton per workspace).
+ */
+export class BehaviorExamplePackAssembler {
+    db;
+    constructor(opts) {
+        // TrajectoryRegistry.get returns the workspace-wide singleton; do NOT
+        // dispose it here. The caller (typically a workspace lifecycle hook)
+        // owns dispose.
+        this.db = TrajectoryRegistry.get(opts.workspaceDir);
+    }
+    /**
+     * Assemble a BehaviorExamplePack from the pain lineage anchored at
+     * `input.sourcePainId`.
+     *
+     * Fail-loud contract (spec §7.2, ERR-069):
+     *   - pain event not found → throws
+     *   - empty trajectory → throws
+     *   - no failing tool call to anchor sourceNegativeCase → throws
+     *   - no successful tool call for positiveCounterexamples → throws
+     *   - assembled pack fails validateBehaviorExamplePack → throws
+     */
+    assemble(input) {
+        // ── 1. Look up the anchoring pain event ──
+        const pain = this.db.getPainEventByCanonicalId(input.sourcePainId);
+        if (!pain) {
+            throw new Error(`[BehaviorExamplePackAssembler] pain event not found for canonical_pain_id="${input.sourcePainId}" (ERR-069 fail loud)`);
+        }
+        // ── 2. Pull the recent trajectory for the pain's session ──
+        // getRuleHostContextRows returns rows WITH params_json (which
+        // listToolCallsForSession does not), so we use it here.
+        const ctxResult = this.db.getRuleHostContextRows(pain.sessionId, HISTORY_LIMIT);
+        const rows = ctxResult.rows;
+        if (rows.length === 0) {
+            throw new Error(`[BehaviorExamplePackAssembler] empty trajectory (no tool calls) for sessionId="${pain.sessionId}" (pain=${input.sourcePainId}, ERR-069 fail loud)`);
+        }
+        // ── 3. Partition into failures (negative candidates) and successes (positives) ──
+        const failures = [];
+        const successes = [];
+        for (const row of rows) {
+            if (row.outcome === 'failure') {
+                failures.push(row);
+            }
+            else if (row.outcome === 'success') {
+                successes.push(row);
+            }
+            // 'blocked' rows are not used as either positive or negative cases.
+        }
+        if (failures.length === 0) {
+            throw new Error(`[BehaviorExamplePackAssembler] no failing tool call in sessionId="${pain.sessionId}" — cannot build sourceNegativeCase (pain=${input.sourcePainId}, ERR-069 fail loud)`);
+        }
+        if (successes.length === 0) {
+            throw new Error(`[BehaviorExamplePackAssembler] no successful tool call in sessionId="${pain.sessionId}" — cannot build positiveCounterexamples (pain=${input.sourcePainId}, ERR-069 fail loud)`);
+        }
+        // ── 4. Build sourceNegativeCase from the most recent failure ──
+        const sourceFailure = failures[failures.length - 1];
+        if (!sourceFailure) {
+            // Defensive: should be unreachable due to the failures.length === 0 check
+            // above, but noUncheckedIndexedAccess requires the guard.
+            throw new Error(`[BehaviorExamplePackAssembler] internal error: sourceFailure undefined (pain=${input.sourcePainId})`);
+        }
+        const sourceNegativeCase = buildCaseFromRow(sourceFailure, 'negative', 'block', input.projectDir);
+        // ── 5. Build positiveCounterexamples from successes (≤3, most recent first) ──
+        const positiveRows = successes.slice(-MAX_POSITIVES); // most recent ≤3
+        const positiveCounterexamples = [];
+        for (const row of positiveRows) {
+            positiveCounterexamples.push(buildCaseFromRow(row, 'positive', 'allow', input.projectDir));
+        }
+        // ── 6. Build evidenceRefs from pain events + gate blocks (≤5) ──
+        const evidenceRefs = [];
+        const sessionPainEvents = this.db.listPainEventsForSession(pain.sessionId);
+        for (const p of sessionPainEvents) {
+            if (evidenceRefs.length >= MAX_EVIDENCE_REFS)
+                break;
+            evidenceRefs.push(`pain:${p.id}`);
+        }
+        const gateBlocks = this.db.listGateBlocksForSession(pain.sessionId);
+        for (const g of gateBlocks) {
+            if (evidenceRefs.length >= MAX_EVIDENCE_REFS)
+                break;
+            evidenceRefs.push(`gate:${g.id}`);
+        }
+        if (evidenceRefs.length === 0) {
+            // The anchor pain event itself always provides at least one evidenceRef.
+            evidenceRefs.push(`pain:${pain.id}`);
+        }
+        // ── 7. Apply redaction (spec §7.2: "经过脱敏") ──
+        const redactionResult = redactParams(sourceNegativeCase.params, input.projectDir);
+        const redactedNegativeCase = {
+            ...sourceNegativeCase,
+            params: redactionResult.redacted,
+        };
+        const redactedPositives = positiveCounterexamples.map((c) => {
+            const r = redactParams(c.params, input.projectDir);
+            return { ...c, params: r.redacted };
+        });
+        const redactionNotes = [...redactionResult.notes];
+        // ── 8. Assemble the pack ──
+        const pack = {
+            sourceNegativeCase: redactedNegativeCase,
+            ownerDesiredOutcome: input.ownerDesiredOutcome,
+            positiveCounterexamples: redactedPositives,
+            evidenceRefs,
+            redactionNotes,
+        };
+        // ── 9. Validate — fail loud (ERR-069) ──
+        const validation = validateBehaviorExamplePack(pack);
+        if (!validation.valid) {
+            throw new Error(`[BehaviorExamplePackAssembler] assembled pack failed validateBehaviorExamplePack: ${validation.errors.join('; ')} (ERR-069 fail loud)`);
+        }
+        return pack;
+    }
+}
+// ── internal: case builder ─────────────────────────────────────────────────
+/**
+ * Build a GoldenTraceCaseInput from a trajectory tool_call row.
+ *
+ * ERR-001: parses params_json as unknown and structurally validates (must be
+ * a plain object without proto-pollution keys). Throws on malformed input
+ * (rc-9: no silent fallback).
+ */
+function buildCaseFromRow(row, kind, expectedDecision, _projectDir) {
+    if (typeof row.toolName !== 'string' || row.toolName.length === 0) {
+        throw new Error(`[BehaviorExamplePackAssembler] row id=${row.id}: toolName must be a non-empty string (rc-9 fail loud)`);
+    }
+    if (typeof row.paramsJson !== 'string') {
+        throw new Error(`[BehaviorExamplePackAssembler] row id=${row.id}: paramsJson must be a string (rc-9 fail loud)`);
+    }
+    let parsedParams;
+    try {
+        parsedParams = JSON.parse(row.paramsJson);
+    }
+    catch {
+        throw new Error(`[BehaviorExamplePackAssembler] row id=${row.id}: paramsJson is not valid JSON (rc-9 fail loud)`);
+    }
+    if (!isPlainObject(parsedParams)) {
+        throw new Error(`[BehaviorExamplePackAssembler] row id=${row.id}: paramsJson must parse to a non-array object (rc-9 fail loud)`);
+    }
+    if (!hasNoProtoKeys(parsedParams)) {
+        throw new Error(`[BehaviorExamplePackAssembler] row id=${row.id}: paramsJson must not carry prototype-pollution keys (ERR-076, rc-9 fail loud)`);
+    }
+    return {
+        caseId: `case-${kind}-${row.id}`,
+        kind,
+        toolName: row.toolName,
+        params: parsedParams,
+        expectedDecision,
+    };
+}
+/**
+ * Redact sensitive fields from tool call params before they enter the pack.
+ *
+ * First-version policy:
+ *   - Absolute paths outside the project tree → replaced with `<redacted:absolute-path>`
+ *   - String values that look like secrets (long base64 / AKIA-style keys / etc.)
+ *     → replaced with `<redacted:secret>`
+ *
+ * Records each redaction in `notes` so the Artificer and the owner can see
+ * what was stripped (spec §7.2: redactionNotes is part of the pack contract).
+ */
+function redactParams(params, projectDir) {
+    const notes = [];
+    const redacted = {};
+    for (const key of Object.keys(params)) {
+        if (PROTO_KEYS.has(key))
+            continue; // defense in depth (ERR-076)
+        const value = params[key];
+        if (typeof value !== 'string') {
+            redacted[key] = value;
+            continue;
+        }
+        // Path-like values
+        if (looksLikeAbsolutePath(value) && !value.startsWith(projectDir)) {
+            redacted[key] = '<redacted:absolute-path>';
+            notes.push(`redacted absolute path in field "${key}" (outside project tree)`);
+            continue;
+        }
+        // Secret-like values (AWS keys, long base64 tokens, etc.)
+        if (looksLikeSecret(value)) {
+            redacted[key] = '<redacted:secret>';
+            notes.push(`redacted possible secret in field "${key}"`);
+            continue;
+        }
+        redacted[key] = value;
+    }
+    return { redacted, notes };
+}
+function looksLikeAbsolutePath(value) {
+    // POSIX absolute path or Windows drive path
+    return value.startsWith('/') || /^[A-Za-z]:[\\/]/.test(value);
+}
+const SECRET_PATTERNS = [
+    /AKIA[0-9A-Z]{16}/, // AWS access key ID
+    /[A-Za-z0-9+/]{40,}/, // long base64-ish token (≥40 chars, no spaces)
+];
+function looksLikeSecret(value) {
+    if (value.length < 20)
+        return false; // too short to be a real secret
+    for (const pattern of SECRET_PATTERNS) {
+        if (pattern.test(value))
+            return true;
+    }
+    return false;
+}

package/plugin/dist/core/control-ui-db.d.ts

@@ -102,5 +102,16 @@ export declare class ControlUiDatabase {
     run(sql: string, ...params: unknown[]): void;
     restoreRawText(inlineText?: string | null, blobRef?: string | null): string;
     private initSchema;
+    /**
+     * 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.
+     */
+    private createViewSafely;
     private withWrite;
 }

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/event-log.js

@@ -69,8 +69,6 @@ export class EventLog {
     recordPainSignal(sessionId, data) {
         this.record('pain_signal', 'detected', sessionId, data);
     }
-    // recordRuleMatch removed (PRI-451 Wave 1): dead code. Its only effect was
-    // incrementing stats.pain.rulesMatched (also dead, removed in Wave 1.5).
     recordRulePromotion(data) {
         this.record('rule_promotion', 'promoted', undefined, data);
     }
@@ -350,9 +348,6 @@ export class EventLog {
             stats.empathy.rollbackCount++;
             stats.empathy.rolledBackScore += data.originalScore || 0;
         }
-        // rule_match handler removed (PRI-451 Wave 1.5): recordRuleMatch is gone
-        // (Wave 1.1), so no rule_match events are emitted; stats.pain.rulesMatched
-        // was its only consumer and is also removed.
         else if (entry.type === 'rule_promotion') {
             // stats.pain.candidatesPromoted removed (PRI-451 Wave 1.5): dead counter.
             stats.evolution.rulesPromoted++;

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

@@ -0,0 +1,36 @@
+/**
+ * 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, IntentLang } from '@principles/core/runtime-v2';
+/**
+ * Detect which language's INTENT file exists on disk.
+ * Priority: zh-CN first, then en. Defaults to zh-CN if neither exists.
+ *
+ * This lets hooks avoid hardcoding a single language — the Owner may have
+ * created either INTENT.zh-CN.md or INTENT.en.md.
+ */
+export declare function resolveIntentLang(workspaceDir: string): IntentLang;
+/**
+ * Create an IntentDocReader bound to a specific workspace and language.
+ *
+ * The returned reader is stateless beyond the (workspace, lang) binding — each
+ * `readIntentDoc()` call delegates to `safeReadIntentDoc()`, which owns
+ * the TTL+mtime cache keyed by `${workspaceDir}:${lang}`.
+ */
+export declare function createIntentDocReader(workspaceDir: string, lang: IntentLang): IntentDocReader;

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

@@ -0,0 +1,76 @@
+/**
+ * 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 * as fs from 'node:fs';
+import * as path from 'node:path';
+import { safeReadIntentDoc } from './intent-doc-reader.js';
+import { getIntentFilename, } from '@principles/core/runtime-v2';
+const INTENT_DIR = '.principles';
+/**
+ * Detect which language's INTENT file exists on disk.
+ * Priority: zh-CN first, then en. Defaults to zh-CN if neither exists.
+ *
+ * This lets hooks avoid hardcoding a single language — the Owner may have
+ * created either INTENT.zh-CN.md or INTENT.en.md.
+ */
+export function resolveIntentLang(workspaceDir) {
+    const zhPath = path.join(workspaceDir, INTENT_DIR, getIntentFilename('zh-CN'));
+    if (fs.existsSync(zhPath))
+        return 'zh-CN';
+    const enPath = path.join(workspaceDir, INTENT_DIR, getIntentFilename('en'));
+    if (fs.existsSync(enPath))
+        return 'en';
+    return 'zh-CN';
+}
+/**
+ * Create an IntentDocReader bound to a specific workspace and language.
+ *
+ * The returned reader is stateless beyond the (workspace, lang) binding — each
+ * `readIntentDoc()` call delegates to `safeReadIntentDoc()`, which owns
+ * the TTL+mtime cache keyed by `${workspaceDir}:${lang}`.
+ */
+export function createIntentDocReader(workspaceDir, lang) {
+    return {
+        readIntentDoc() {
+            const result = safeReadIntentDoc(workspaceDir, lang);
+            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,89 @@
+/**
+ * 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, type IntentLang } 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.
+ *
+ * - No args: clear the whole cache.
+ * - workspaceDir only: delete all entries for that workspace (any lang).
+ *   Keys are formatted as `${workspaceDir}:${lang}`, so we match by prefix.
+ * - workspaceDir + lang: delete the single `${workspaceDir}:${lang}` entry.
+ *
+ * Note: prompt.ts resetPromptStateForTest passes workspaceDir only — the
+ * previous signature treated it as a literal cache key, which never matched
+ * the `${workspaceDir}:${lang}` format and silently left entries behind.
+ */
+export declare function resetIntentDocCacheForTest(workspaceDir?: string, lang?: IntentLang): 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 lang - Mandatory language code ('zh-CN' | 'en'); selects INTENT.${lang}.md
+ * @param options - Optional logger for debug-level diagnostics
+ * @returns SafeReadIntentDocResult (never throws)
+ */
+export declare function safeReadIntentDoc(workspaceDir: string, lang: IntentLang, options?: {
+    logger?: {
+        debug?: (msg: string) => void;
+        warn?: (msg: string) => void;
+    };
+}): SafeReadIntentDocResult;