principles-disciple 1.161.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/gate.js

@@ -12,12 +12,14 @@ import { normalizePath } from '../utils/io.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 import { recordGateBlockAndReturn } from './gate-block-helper.js';
 import { RuleHost } from '../core/rule-host.js';
-import { validateCorrectionProposal, validateProposedPathBounds } from '@principles/core/runtime-v2';
+import { validateCorrectionProposal, validateProposedPathBounds, computeFeatureFlagsFromConfig, UNAVAILABLE_RULE_CONTEXT } from '@principles/core/runtime-v2';
 import { AGENT_TOOLS, BASH_TOOLS_SET, WRITE_TOOLS } from '../constants/tools.js';
 import { getSession, hasRecentThinking } from '../core/session-tracker.js';
 import { getEvolutionEngine } from '../core/evolution-engine.js';
 import { EventLogService } from '../core/event-log.js';
 import { estimateLineChanges } from '@principles/core/runtime-v2';
+import { loadPdConfigForPlugin } from '../core/pd-config-loader.js';
+import { buildProductionRuleContext } from '../core/rule-context-assembler.js';
 export function handleBeforeToolCall(event, ctx) {
     const logger = ctx.logger || console;
     // 1. Identify tool type
@@ -53,6 +55,10 @@ export function handleBeforeToolCall(event, ctx) {
     // 3. Rule Host Evaluation — sole gate
     try {
         const ruleHost = new RuleHost(wctx.stateDir, logger, { workspaceDir: ctx.workspaceDir });
+        // PRI-483 Phase 4: assemble RuleContextV2 when `rulecode_context_v2` flag is ON.
+        // flag OFF → undefined (v1 zero-change, no trajectory access).
+        // flag ON  → RuleContextV2 (available or unavailable). Never throws (ERR-024).
+        const ruleContext = _buildRuleContextIfEnabled(wctx, relPath, ctx.sessionId, logger);
         const hostInput = {
             action: {
                 toolName: event.toolName,
@@ -80,6 +86,7 @@ export function handleBeforeToolCall(event, ctx) {
                 estimatedLineChanges: estimateLineChanges({ toolName: event.toolName, params: event.params ?? {} }),
                 bashRisk: _getBashRisk(event),
             },
+            context: ruleContext,
         };
         const hostResult = ruleHost.evaluate(hostInput);
         // Always emit rulehost_evaluated
@@ -379,3 +386,53 @@ function _getBashRisk(event) {
         return 'unknown';
     }
 }
+/**
+ * PRI-483 Phase 4 — Build RuleContextV2 for RuleHost.evaluate when the
+ * `rulecode_context_v2` feature flag is ON. Returns `undefined` when the flag
+ * is OFF (v1 zero-change — does NOT touch trajectory) or when config loading
+ * fails (conservative fail-soft: can't determine flag state → v1-style).
+ *
+ * ERR-024 prevention: context assembly failures never skip RuleHost.evaluate.
+ * - loadPdConfigForPlugin throws → return undefined (v1-style)
+ * - buildProductionRuleContext throws → return UNAVAILABLE_RULE_CONTEXT
+ *   (structured unavailable so v2 rules see "context unavailable" and allow)
+ *
+ * Spec: docs/superpowers/specs/2026-06-27-rulecode-context-vision-design.md §5.3
+ */
+function _buildRuleContextIfEnabled(wctx, targetPath, sessionId, logger) {
+    // Step 1: load PD config (flag-gated). If this throws, we can't safely
+    // determine whether v2 context is required — fall back to v1 (undefined).
+    let configResult;
+    try {
+        configResult = loadPdConfigForPlugin(wctx.workspaceDir);
+    }
+    catch (err) {
+        logger?.warn?.(`[PD_GATE] RuleContext v2: config load failed, skipping context assembly: ${String(err)}`);
+        return undefined;
+    }
+    // Step 2: compute effective flags and check rulecode_context_v2.
+    // Explicit ok:false guard (rc-9-no-silent-fallback): when config is malformed,
+    // do NOT silently fall through to flag computation on defaults — log and
+    // return v1-style undefined so config issues surface to the operator.
+    if (!configResult.ok) {
+        const reasons = configResult.errors.map(e => e.reason).join('; ');
+        logger?.warn?.(`[PD_GATE] RuleContext v2: config load returned malformed result, skipping context assembly: ${reasons}`);
+        return undefined;
+    }
+    const flagsResult = computeFeatureFlagsFromConfig(configResult.effective);
+    const v2Flag = flagsResult.flags.rulecode_context_v2;
+    if (!v2Flag?.enabled) {
+        // Flag OFF → v1 zero-change. Do NOT access trajectory (spec §10.1).
+        return undefined;
+    }
+    // Step 3: flag ON → assemble context via production data source.
+    // buildProductionRuleContext is fail-soft internally (returns unavailable),
+    // but wrap in try/catch as defense-in-depth (ERR-024).
+    try {
+        return buildProductionRuleContext(sessionId, targetPath, wctx.trajectory, wctx.workspaceDir);
+    }
+    catch (err) {
+        logger?.warn?.(`[PD_GATE] RuleContext v2: buildProductionRuleContext threw unexpectedly, using unavailable context: ${String(err)}`);
+        return UNAVAILABLE_RULE_CONTEXT;
+    }
+}

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.161.0",
+  "version": "1.163.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

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