principles-disciple 1.162.0 → 1.164.0

package/dist/commands/pain.js

@@ -5,7 +5,7 @@ import { resolvePluginCommandWorkspaceDir } from '../utils/workspace-resolver.js
 import { computeHash } from '../utils/hashing.js';
 import { PainToPrincipleService, PrincipleTreeLedgerAdapter } from '@principles/core/runtime-v2';
 import { loadPdConfigForPlugin } from '../core/pd-config-loader.js';
-import { createIntentDocReader } from '../core/intent-doc-reader-adapter.js';
+import { createIntentDocReader, resolveIntentLang } from '../core/intent-doc-reader-adapter.js';
 /**
  * Creates a visual progress bar (e.g., [██████░░░░])
  */
@@ -275,7 +275,7 @@ export async function handlePainReportCommand(ctx) {
             autoIntakeEnabled: true,
             effectiveConfig: configResult.effective,
             getEnvVar: (name) => process.env[name],
-            intentDocReader: createIntentDocReader(wctx.workspaceDir),
+            intentDocReader: createIntentDocReader(wctx.workspaceDir, resolveIntentLang(wctx.workspaceDir)),
         });
         const result = await service.recordPain({
             painId: painData.painId,

package/dist/core/behavior-example-pack-assembler.d.ts

@@ -0,0 +1,43 @@
+import type { BehaviorExamplePack } from '@principles/core/runtime-v2';
+export interface BehaviorExamplePackAssemblerOptions {
+    /** Workspace directory — used to obtain the shared TrajectoryDatabase. */
+    readonly workspaceDir: string;
+    /**
+     * State directory (unused for direct DB access but required by the
+     * WorkspaceContext facade pattern; future-proofing for redaction config).
+     */
+    readonly stateDir: string;
+}
+export interface BehaviorExamplePackAssemblerInput {
+    /** Canonical pain ID (e.g. pain_<ts>_<hash>) — entry point into pain lineage. */
+    readonly sourcePainId: string;
+    /** Owner's natural-language desired outcome — must be non-empty. */
+    readonly ownerDesiredOutcome: string;
+    /**
+     * Project directory, used to detect absolute paths that should be redacted
+     * to relative/basename form in the assembled pack.
+     */
+    readonly projectDir: string;
+}
+/**
+ * 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 declare class BehaviorExamplePackAssembler {
+    private readonly db;
+    constructor(opts: BehaviorExamplePackAssemblerOptions);
+    /**
+     * 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: BehaviorExamplePackAssemblerInput): BehaviorExamplePack;
+}

package/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/dist/core/intent-doc-reader-adapter.d.ts

@@ -17,12 +17,20 @@
  * 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';
+import type { IntentDocReader, IntentLang } from '@principles/core/runtime-v2';
 /**
- * Create an IntentDocReader bound to a specific workspace.
+ * Detect which language's INTENT file exists on disk.
+ * Priority: zh-CN first, then en. Defaults to zh-CN if neither exists.
  *
- * The returned reader is stateless beyond the workspace binding — each
+ * 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.
+ * the TTL+mtime cache keyed by `${workspaceDir}:${lang}`.
  */
-export declare function createIntentDocReader(workspaceDir: string): IntentDocReader;
+export declare function createIntentDocReader(workspaceDir: string, lang: IntentLang): IntentDocReader;

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

@@ -17,18 +17,38 @@
  * 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';
 /**
- * Create an IntentDocReader bound to a specific workspace.
+ * Detect which language's INTENT file exists on disk.
+ * Priority: zh-CN first, then en. Defaults to zh-CN if neither exists.
  *
- * The returned reader is stateless beyond the workspace binding — each
+ * 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.
+ * the TTL+mtime cache keyed by `${workspaceDir}:${lang}`.
  */
-export function createIntentDocReader(workspaceDir) {
+export function createIntentDocReader(workspaceDir, lang) {
     return {
         readIntentDoc() {
-            const result = safeReadIntentDoc(workspaceDir);
+            const result = safeReadIntentDoc(workspaceDir, lang);
             if (result.ok && result.doc) {
                 const doc = result.doc;
                 const reference = {

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

@@ -21,7 +21,7 @@
  * 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';
+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). */
@@ -55,9 +55,17 @@ export interface SafeReadIntentDocResult {
 }
 /**
  * Reset the intent doc cache for test isolation.
- * Call in beforeEach() to ensure tests don't pollute each other.
+ *
+ * - 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): void;
+export declare function resetIntentDocCacheForTest(workspaceDir?: string, lang?: IntentLang): void;
 /**
  * Safely read INTENT.md for prompt injection.
  *
@@ -69,10 +77,11 @@ export declare function resetIntentDocCacheForTest(workspaceDir?: string): void;
  * 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, options?: {
+export declare function safeReadIntentDoc(workspaceDir: string, lang: IntentLang, options?: {
     logger?: {
         debug?: (msg: string) => void;
         warn?: (msg: string) => void;

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

@@ -23,29 +23,48 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { INTENT_MAX_BYTES, parseIntentDocSections, computeIntentContentHash, validateIntentDocSections, } from '@principles/core/runtime-v2';
+import { INTENT_MAX_BYTES, getIntentFilename, parseIntentDocSections, computeIntentContentHash, validateIntentDocSections, } from '@principles/core/runtime-v2';
 import { loadFeatureFlagFromConfig } from './pd-config-loader.js';
 // ── Constants ────────────────────────────────────────────────────────────────
-const INTENT_FILENAME = 'INTENT.md';
 const INTENT_DIR = '.principles';
 const INTENT_CACHE_TTL_MS = 60_000; // 1 minute (SPEC §12.1)
 // ── Module-level cache (per-workspace) ───────────────────────────────────────
 const _intentDocCache = new Map();
 /**
  * Reset the intent doc cache for test isolation.
- * Call in beforeEach() to ensure tests don't pollute each other.
+ *
+ * - 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 function resetIntentDocCacheForTest(workspaceDir) {
-    if (workspaceDir) {
-        _intentDocCache.delete(workspaceDir);
-    }
-    else {
+export function resetIntentDocCacheForTest(workspaceDir, lang) {
+    if (workspaceDir === undefined) {
         _intentDocCache.clear();
+        return;
+    }
+    if (lang !== undefined) {
+        _intentDocCache.delete(`${workspaceDir}:${lang}`);
+        return;
+    }
+    // workspaceDir only — clear all langs for this workspace by prefix.
+    const prefix = `${workspaceDir}:`;
+    for (const key of _intentDocCache.keys()) {
+        if (key.startsWith(prefix)) {
+            _intentDocCache.delete(key);
+        }
     }
 }
 // ── Helpers ──────────────────────────────────────────────────────────────────
-function getIntentFilePath(workspaceDir) {
-    return path.join(workspaceDir, INTENT_DIR, INTENT_FILENAME);
+function getIntentFilePath(workspaceDir, lang) {
+    return path.join(workspaceDir, INTENT_DIR, getIntentFilename(lang));
+}
+function getCacheKey(workspaceDir, lang) {
+    return `${workspaceDir}:${lang}`;
 }
 function buildDocFromRaw(raw, filePath, readAt) {
     const sections = parseIntentDocSections(raw);
@@ -72,10 +91,11 @@ function buildDocFromRaw(raw, filePath, readAt) {
  * 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 function safeReadIntentDoc(workspaceDir, options) {
+export function safeReadIntentDoc(workspaceDir, lang, options) {
     // SPEC §12 — Flag check FIRST. Flag off → no fs access, no cache access.
     const flagResult = loadFeatureFlagFromConfig(workspaceDir, 'intent_engineering', options?.logger);
     if (!flagResult.enabled) {
@@ -84,14 +104,15 @@ export function safeReadIntentDoc(workspaceDir, options) {
             found: false,
             flagEnabled: false,
             reason: 'flag_disabled',
-            nextAction: 'Enable the intent_engineering feature flag in .pd/config.yaml to read INTENT.md.',
+            nextAction: `Enable the intent_engineering feature flag in .pd/config.yaml to read ${getIntentFilename(lang)}.`,
             warnings: [],
         };
     }
-    const filePath = getIntentFilePath(workspaceDir);
+    const cacheKey = getCacheKey(workspaceDir, lang);
+    const filePath = getIntentFilePath(workspaceDir, lang);
     const now = Date.now();
     // Check cache freshness (TTL + mtime)
-    const cached = _intentDocCache.get(workspaceDir);
+    const cached = _intentDocCache.get(cacheKey);
     if (cached && (now - cached.loadedAt) < INTENT_CACHE_TTL_MS) {
         // Cache is within TTL. Verify mtime hasn't changed.
         try {
@@ -117,26 +138,26 @@ export function safeReadIntentDoc(workspaceDir, options) {
         // Check existence first
         if (!fs.existsSync(filePath)) {
             // Invalidate stale cache entry if any
-            _intentDocCache.delete(workspaceDir);
+            _intentDocCache.delete(cacheKey);
             return {
                 ok: false,
                 found: false,
                 flagEnabled: true,
                 reason: 'not_found',
-                nextAction: 'Create .principles/INTENT.md using "pd intent init".',
+                nextAction: `Create .principles/${getIntentFilename(lang)} using "pd intent init".`,
                 warnings: [],
             };
         }
         const stat = fs.statSync(filePath);
         // SPEC §12 — 32KB size cap
         if (stat.size > INTENT_MAX_BYTES) {
-            _intentDocCache.delete(workspaceDir);
+            _intentDocCache.delete(cacheKey);
             return {
                 ok: false,
                 found: true,
                 flagEnabled: true,
                 reason: 'oversized',
-                nextAction: `INTENT.md exceeds ${INTENT_MAX_BYTES} bytes (${stat.size} bytes). Reduce content.`,
+                nextAction: `${getIntentFilename(lang)} exceeds ${INTENT_MAX_BYTES} bytes (${stat.size} bytes). Reduce content.`,
                 warnings: [],
             };
         }
@@ -147,19 +168,19 @@ export function safeReadIntentDoc(workspaceDir, options) {
         // an oversized file would enter parse/hash/cache as ok:true.
         const actualBytes = Buffer.byteLength(raw, 'utf8');
         if (actualBytes > INTENT_MAX_BYTES) {
-            _intentDocCache.delete(workspaceDir);
+            _intentDocCache.delete(cacheKey);
             return {
                 ok: false,
                 found: true,
                 flagEnabled: true,
                 reason: 'oversized',
-                nextAction: `INTENT.md exceeds ${INTENT_MAX_BYTES} bytes (${actualBytes} bytes after read). Reduce content.`,
+                nextAction: `${getIntentFilename(lang)} exceeds ${INTENT_MAX_BYTES} bytes (${actualBytes} bytes after read). Reduce content.`,
                 warnings: [],
             };
         }
         const doc = buildDocFromRaw(raw, filePath, new Date(now).toISOString());
         // Update cache
-        _intentDocCache.set(workspaceDir, {
+        _intentDocCache.set(cacheKey, {
             doc,
             mtime: stat.mtimeMs,
             loadedAt: now,
@@ -174,15 +195,15 @@ export function safeReadIntentDoc(workspaceDir, options) {
     }
     catch (err) {
         // ERR-002 — graceful degradation with reason + nextAction
-        _intentDocCache.delete(workspaceDir);
+        _intentDocCache.delete(cacheKey);
         const message = err instanceof Error ? err.message : String(err);
-        options?.logger?.warn?.(`[PD:Intent] safeReadIntentDoc failed: workspace=${workspaceDir}, error=${message}`);
+        options?.logger?.warn?.(`[PD:Intent] safeReadIntentDoc failed: workspace=${workspaceDir}, lang=${lang}, error=${message}`);
         return {
             ok: false,
             found: false,
             flagEnabled: true,
             reason: 'read_error',
-            nextAction: 'Check filesystem permissions for .principles/INTENT.md.',
+            nextAction: `Check filesystem permissions for .principles/${getIntentFilename(lang)}.`,
             warnings: [],
         };
     }

package/dist/core/trajectory.d.ts

@@ -146,6 +146,29 @@ export declare class TrajectoryDatabase {
         confidence: number | null;
         createdAt: string;
     }[];
+    /**
+     * PRI-484 Phase 5 — Look up a single pain event by canonical_pain_id.
+     *
+     * Used by BehaviorExamplePackAssembler to anchor a pain lineage without
+     * already knowing the session_id. Returns null when not found.
+     *
+     * ERR-001 (rc-1, rc-2): row fields validated as unknown — no `as` bypass.
+     * Uses a type-guard predicate to narrow the DB row structurally.
+     */
+    getPainEventByCanonicalId(canonicalPainId: string): {
+        id: number;
+        sessionId: string;
+        source: string;
+        score: number;
+        reason: string | null;
+        severity: string | null;
+        origin: string | null;
+        confidence: number | null;
+        text: string | null;
+        canonicalPainId: string;
+        runtimeTaskId: string | null;
+        createdAt: string;
+    } | null;
     /**
      * List user turns for a session.
      * Returns sanitized/reduced fields for nocturnal use — NO raw text.

package/dist/core/trajectory.js

@@ -26,6 +26,34 @@ const SCHEMA_VERSION = 1;
 function hasNameField(row) {
     return Object.hasOwn(row, 'name');
 }
+/**
+ * Pure structural narrowing from `unknown` to `Record<string, unknown>` with
+ * no `as` cast (ERR-001 / rc-2). The returned type allows indexed access in
+ * subsequent code without further casts.
+ */
+function isStringRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isPainEventRow(value) {
+    if (!isStringRecord(value))
+        return false;
+    if (typeof value.id !== 'number')
+        return false;
+    if (typeof value.session_id !== 'string')
+        return false;
+    // The remaining fields are accessed via String()/Number() which tolerate any
+    // primitive; presence check only (rc-5: Object.hasOwn over `in`).
+    return (Object.hasOwn(value, 'source')
+        && Object.hasOwn(value, 'score')
+        && Object.hasOwn(value, 'reason')
+        && Object.hasOwn(value, 'severity')
+        && Object.hasOwn(value, 'origin')
+        && Object.hasOwn(value, 'confidence')
+        && Object.hasOwn(value, 'text')
+        && Object.hasOwn(value, 'canonical_pain_id')
+        && Object.hasOwn(value, 'runtime_task_id')
+        && Object.hasOwn(value, 'created_at'));
+}
 /**
  * Apply the full trajectory.db schema (tables + indexes + views + migrations) to an open
  * Database handle. Used by TrajectoryDatabase.initSchema() and exported via
@@ -957,6 +985,40 @@ export class TrajectoryDatabase {
             createdAt: String(row.created_at),
         }));
     }
+    /**
+     * PRI-484 Phase 5 — Look up a single pain event by canonical_pain_id.
+     *
+     * Used by BehaviorExamplePackAssembler to anchor a pain lineage without
+     * already knowing the session_id. Returns null when not found.
+     *
+     * ERR-001 (rc-1, rc-2): row fields validated as unknown — no `as` bypass.
+     * Uses a type-guard predicate to narrow the DB row structurally.
+     */
+    getPainEventByCanonicalId(canonicalPainId) {
+        const rawRow = this.db.prepare(`
+      SELECT id, session_id, source, score, reason, severity, origin, confidence,
+             text, canonical_pain_id, runtime_task_id, created_at
+      FROM pain_events
+      WHERE canonical_pain_id = ?
+      LIMIT 1
+    `).get(canonicalPainId);
+        if (!isPainEventRow(rawRow))
+            return null;
+        return {
+            id: rawRow.id,
+            sessionId: rawRow.session_id,
+            source: String(rawRow.source),
+            score: Number(rawRow.score),
+            reason: rawRow.reason ? String(rawRow.reason) : null,
+            severity: rawRow.severity ? String(rawRow.severity) : null,
+            origin: rawRow.origin ? String(rawRow.origin) : null,
+            confidence: rawRow.confidence != null ? Number(rawRow.confidence) : null,
+            text: rawRow.text ? String(rawRow.text) : null,
+            canonicalPainId: String(rawRow.canonical_pain_id),
+            runtimeTaskId: rawRow.runtime_task_id ? String(rawRow.runtime_task_id) : null,
+            createdAt: String(rawRow.created_at),
+        };
+    }
     /**
      * List user turns for a session.
      * Returns sanitized/reduced fields for nocturnal use — NO raw text.

package/dist/hooks/pain.js

@@ -25,7 +25,7 @@ import { resolveWorkspaceDirForRuntimeV2 } from '../utils/workspace-resolver.js'
 import { PainToPrincipleService, PrincipleTreeLedgerAdapter } from '@principles/core/runtime-v2';
 import { evaluatePainDiagnosticGate } from '../core/pain-diagnostic-gate.js';
 import { loadPdConfigForPlugin, loadFeatureFlagFromConfig } from '../core/pd-config-loader.js';
-import { createIntentDocReader } from '../core/intent-doc-reader-adapter.js';
+import { createIntentDocReader, resolveIntentLang } from '../core/intent-doc-reader-adapter.js';
 import { evaluateTriggerController } from '@principles/core/runtime-v2';
 import { isSharedCooldownActive, markSharedEpisodeAsDiagnosed } from './trigger-cooldown-tracker.js';
 import { buildManualPainObservation, resolveSourceKind } from './raw-observation-adapter.js';
@@ -48,7 +48,7 @@ function createPainToPrincipleService(wctx) {
         // PRI-468: wire INTENT.md reader so Stage A can produce intentTension
         // when intent_engineering flag is on. Adapter performs no I/O beyond
         // delegating to safeReadIntentDoc (which owns the flag-first check).
-        intentDocReader: createIntentDocReader(wctx.workspaceDir),
+        intentDocReader: createIntentDocReader(wctx.workspaceDir, resolveIntentLang(wctx.workspaceDir)),
     });
 }
 // buildTrajectoryEvidence is in ./trajectory-evidence.ts (re-exported above)

package/dist/hooks/prompt.js

@@ -21,6 +21,7 @@ import { buildEmpathyObservation, resolveSourceKind } from './raw-observation-ad
 import { evaluateEvidenceTriage } from './triage-adapter.js';
 import { loadFeatureFlagFromConfig } from '../core/pd-config-loader.js';
 import { safeReadIntentDoc, resetIntentDocCacheForTest } from '../core/intent-doc-reader.js';
+import { resolveIntentLang } from '../core/intent-doc-reader-adapter.js';
 import { buildIntentFrictionBlock } from '@principles/core/runtime-v2';
 import { CorrectionCueLearner } from '../core/correction-cue-learner.js';
 import { detectCorrectionCue as coreDetectCorrectionCue, escapeXml, extractMessageContent, isMinimalTrigger, } from '@principles/core/prompt-builder';
@@ -909,7 +910,7 @@ export async function handleBeforePromptBuild(event, ctx) {
     try {
         const intentFlag = loadFeatureFlagFromConfig(workspaceDir, 'intent_engineering', logger);
         if (intentFlag.enabled) {
-            const intentResult = safeReadIntentDoc(workspaceDir, { logger });
+            const intentResult = safeReadIntentDoc(workspaceDir, resolveIntentLang(workspaceDir), { logger });
             if (intentResult.ok && intentResult.doc) {
                 const block = buildIntentFrictionBlock({ rawIntentMd: intentResult.doc.raw });
                 if (block.length > 0) {

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "principles-disciple",
   "name": "Principles Disciple",
   "description": "Evolutionary programming agent framework with strategic guardrails and reflection loops.",
-  "version": "1.162.0",
+  "version": "1.164.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "1.162.0",
+  "version": "1.164.0",
   "description": "Native OpenClaw plugin for Principles Disciple",
   "type": "module",
   "main": "./dist/index.js",