principles-disciple 1.162.0 → 1.163.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/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/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.163.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

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