@principles/pd-cli 1.133.0 → 1.134.0

package/src/commands/health-codex.ts

@@ -0,0 +1,249 @@
+/**
+ * pd health --host codex command implementation.
+ *
+ * Reports Codex adapter/runtime versions, host.codex feature flag state,
+ * hook trust status, and dual global/plugin hook registration detection.
+ *
+ * CLI gate compliance:
+ * - cli-1: --json outputs exactly one parseable JSON object on stdout.
+ * - cli-2: exit paths stop execution (return after process.exit).
+ * - cli-5: failure paths do not mutate state (read-only throughout).
+ * - cli-6: every degraded/refused result includes reason + nextAction.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { createRequire } from 'module';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+import { loadPdConfigForPlugin, resolveNearestPdWorkspace } from '@principles/host-runtime';
+import { computeFeatureFlagsFromConfig, isFeatureEnabled } from '@principles/core/runtime-v2';
+
+const require = createRequire(import.meta.url);
+
+interface CodexHealthOptions {
+  workspace?: string;
+  json?: boolean;
+}
+
+interface CodexHealthReport {
+  generatedAt: string;
+  host: 'codex';
+  workspace: string;
+  adapterVersion: string;
+  runtimeVersion: string;
+  featureFlag: {
+    name: 'host.codex';
+    enabled: boolean;
+    source: 'user_config' | 'defaults' | 'malformed';
+    reason?: string;
+    nextAction?: string;
+  };
+  hooksTrust: {
+    detectable: boolean;
+    trusted?: boolean;
+    reason?: string;
+    nextAction?: string;
+  };
+  dualRegistration: {
+    detected: boolean;
+    globalHooksPath?: string;
+    pluginHooksPath?: string;
+    reason?: string;
+    nextAction?: string;
+  };
+  warnings: string[];
+}
+
+function readPackageVersion(packageName: string): string {
+  try {
+    const pkgJsonPath = require.resolve(`${packageName}/package.json`);
+    const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8')) as { version?: unknown };
+    if (typeof pkg.version === 'string') return pkg.version;
+    return 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+function detectCodexConfigDir(): string | undefined {
+  const home = os.homedir();
+  const codexDir = path.join(home, '.codex');
+  if (fs.existsSync(codexDir)) return codexDir;
+  return undefined;
+}
+
+function detectHooksTrust(codexConfigDir: string | undefined): CodexHealthReport['hooksTrust'] {
+  if (!codexConfigDir) {
+    return {
+      detectable: false,
+      reason: 'codex_config_dir_not_found',
+      nextAction: 'Install Codex CLI (>= 0.147) and run `codex` once to create ~/.codex/, then re-run `pd health --host codex` to verify hook trust state.',
+    };
+  }
+  // Codex stores hook trust in config.toml under [features] hooks = true|false.
+  // We do a best-effort text scan rather than a full TOML parse to avoid a new
+  // dependency. If the file is missing or the hook line is absent, we report
+  // undetectable with a clear next action.
+  const configTomlPath = path.join(codexConfigDir, 'config.toml');
+  if (!fs.existsSync(configTomlPath)) {
+    return {
+      detectable: false,
+      reason: 'config_toml_not_found',
+      nextAction: `Open Codex and run /hooks to trust PD hooks, then re-run \`pd health --host codex\`. Expected config at ${configTomlPath}.`,
+    };
+  }
+  try {
+    const raw = fs.readFileSync(configTomlPath, 'utf8');
+    const match = /hooks\s*=\s*(true|false)/i.exec(raw);
+    if (!match || !match[1]) {
+      return {
+        detectable: false,
+        reason: 'hooks_setting_not_found_in_config',
+        nextAction: 'Open Codex and run /hooks to trust PD hooks. Codex config.toml exists but has no `hooks` setting under [features].',
+      };
+    }
+    return { detectable: true, trusted: match[1].toLowerCase() === 'true' };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      detectable: false,
+      reason: `config_toml_read_failed: ${message.slice(0, 200)}`,
+      nextAction: `Check read permissions on ${configTomlPath} and re-run \`pd health --host codex\`.`,
+    };
+  }
+}
+
+function detectDualRegistration(codexConfigDir: string | undefined): CodexHealthReport['dualRegistration'] {
+  const globalHooksPath = codexConfigDir ? path.join(codexConfigDir, 'hooks.json') : undefined;
+  // Plugin hooks are declared in a plugin manifest; we cannot reliably detect
+  // them from outside Codex. We only flag the global-hooks path and let the
+  // operator confirm plugin registration via /hooks in Codex.
+  const globalHooksExists = globalHooksPath ? fs.existsSync(globalHooksPath) : false;
+  if (globalHooksExists) {
+    return {
+      detected: true,
+      globalHooksPath,
+      reason: 'global_hooks_json_present',
+      nextAction: 'Global ~/.codex/hooks.json is installed. If the PD Codex plugin is also installed via marketplace, this may cause double-registration. Choose ONE: keep global hooks.json (fallback path) OR uninstall it and use the plugin (recommended). To remove global PD entries, run `create-principles-disciple uninstall --host codex`.',
+    };
+  }
+  return { detected: false };
+}
+
+export async function handleHealthCodex(opts: CodexHealthOptions = {}): Promise<void> {
+  const generatedAt = new Date().toISOString();
+  const workspaceDir = opts.workspace
+    ? path.resolve(opts.workspace)
+    : resolveWorkspaceDir();
+
+  const warnings: string[] = [];
+
+  // Resolve workspace via the shared host-runtime resolver so pd-cli reports
+  // the same workspace the Codex hook would resolve.
+  const resolution = resolveNearestPdWorkspace(workspaceDir);
+  let resolvedWorkspace: string;
+  let featureFlagSource: 'user_config' | 'defaults' | 'malformed';
+  let hostCodexEnabled = false;
+
+  if (!resolution.ok) {
+    resolvedWorkspace = workspaceDir;
+    featureFlagSource = 'defaults';
+    warnings.push(`workspace_not_resolved: ${resolution.reason} — ${resolution.nextAction}`);
+  } else {
+    resolvedWorkspace = resolution.workspaceDir;
+    const configLoad = loadPdConfigForPlugin(resolvedWorkspace);
+    featureFlagSource = configLoad.source;
+    const flags = computeFeatureFlagsFromConfig(configLoad.effective);
+    hostCodexEnabled = isFeatureEnabled(flags, 'host.codex');
+    if (!configLoad.ok) {
+      for (const error of configLoad.errors) {
+        warnings.push(`config_error: ${error.reason} — ${error.nextAction}`);
+      }
+    }
+  }
+
+  const adapterVersion = readPackageVersion('@principles/codex-adapter');
+  const runtimeVersion = readPackageVersion('@principles/host-runtime');
+  const codexConfigDir = detectCodexConfigDir();
+  const hooksTrust = detectHooksTrust(codexConfigDir);
+  const dualRegistration = detectDualRegistration(codexConfigDir);
+
+  if (hooksTrust.reason) warnings.push(`hooks_trust: ${hooksTrust.reason}`);
+  if (dualRegistration.reason) warnings.push(`dual_registration: ${dualRegistration.reason}`);
+
+  const report: CodexHealthReport = {
+    generatedAt,
+    host: 'codex',
+    workspace: resolvedWorkspace,
+    adapterVersion,
+    runtimeVersion,
+    featureFlag: {
+      name: 'host.codex',
+      enabled: hostCodexEnabled,
+      source: featureFlagSource,
+      ...(hostCodexEnabled
+        ? {}
+        : {
+            reason: 'host_codex_disabled',
+            nextAction: `Enable the Codex host adapter by setting features.host.codex.enabled=true in ${resolvedWorkspace}/.pd/config.yaml, then re-run \`pd health --host codex\`.`,
+          }),
+    },
+    hooksTrust,
+    dualRegistration,
+    warnings,
+  };
+
+  if (opts.json) {
+    // cli-1: exactly one parseable JSON object on stdout.
+    console.log(JSON.stringify(report, null, 2));
+    // cli-2: exit-stops. Non-zero only when host.codex is disabled AND hooks
+    // are not trusted — the operator must act before Codex activation works.
+    if (!hostCodexEnabled && !hooksTrust.trusted) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  // Text output — still includes explicit nextAction per cli-6.
+  console.log(`generatedAt: ${report.generatedAt}`);
+  console.log(`host: ${report.host}`);
+  console.log(`workspace: ${report.workspace}`);
+  console.log(`adapterVersion: ${report.adapterVersion}`);
+  console.log(`runtimeVersion: ${report.runtimeVersion}`);
+  console.log(`featureFlag.name: ${report.featureFlag.name}`);
+  console.log(`featureFlag.enabled: ${report.featureFlag.enabled}`);
+  console.log(`featureFlag.source: ${report.featureFlag.source}`);
+  if (report.featureFlag.reason) {
+    console.log(`featureFlag.reason: ${report.featureFlag.reason}`);
+    console.log(`featureFlag.nextAction: ${report.featureFlag.nextAction ?? ''}`);
+  }
+  console.log(`hooksTrust.detectable: ${report.hooksTrust.detectable}`);
+  if (report.hooksTrust.trusted !== undefined) {
+    console.log(`hooksTrust.trusted: ${report.hooksTrust.trusted}`);
+  }
+  if (report.hooksTrust.reason) {
+    console.log(`hooksTrust.reason: ${report.hooksTrust.reason}`);
+    console.log(`hooksTrust.nextAction: ${report.hooksTrust.nextAction ?? ''}`);
+  }
+  console.log(`dualRegistration.detected: ${report.dualRegistration.detected}`);
+  if (report.dualRegistration.globalHooksPath) {
+    console.log(`dualRegistration.globalHooksPath: ${report.dualRegistration.globalHooksPath}`);
+  }
+  if (report.dualRegistration.reason) {
+    console.log(`dualRegistration.reason: ${report.dualRegistration.reason}`);
+    console.log(`dualRegistration.nextAction: ${report.dualRegistration.nextAction ?? ''}`);
+  }
+  if (report.warnings.length > 0) {
+    console.log(`warnings:`);
+    for (const w of report.warnings) console.log(`  - ${w}`);
+  }
+  console.log('');
+
+  if (!hostCodexEnabled) {
+    console.warn(`⚠️  host.codex feature flag is disabled. Enable it in ${resolvedWorkspace}/.pd/config.yaml under features.host.codex.enabled to activate Codex hooks.`);
+  }
+  if (!hooksTrust.trusted && !hooksTrust.detectable) {
+    console.warn(`⚠️  Hook trust state could not be detected. ${hooksTrust.nextAction ?? ''}`);
+    process.exitCode = 1;
+  }
+}

package/src/commands/health.ts

@@ -11,10 +11,12 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import Database from 'better-sqlite3';
+import type { Command } from 'commander';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
 import { PruningReadModel, PainChainReadModel, auditCandidateLedgerConsistency } from '@principles/core/runtime-v2';
 import type { PainChainTrace } from '@principles/core/runtime-v2';
 import { getLedgerFilePathPublic } from '@principles/core/principle-tree-ledger';
+import { handleHealthCodex } from './health-codex.js';
 
 interface LastSuccessfulChain {
   painId?: string;
@@ -188,3 +190,61 @@ export async function handleHealth(opts: HealthOptions = {}): Promise<void> {
 
   writeHealth();
 }
+
+/**
+ * Handlers backing the `pd health` command. Injected so the registration
+ * wiring test can exercise the real `registerHealthCommand` without executing
+ * real workspace/DB I/O; production uses the defaults.
+ */
+interface HealthCommandHandlers {
+  health?: typeof handleHealth;
+  healthCodex?: typeof handleHealthCodex;
+}
+
+/**
+ * Registers the `pd health` command on a Commander program.
+ *
+ * cli-7 test-wiring: this is the single registration used by both the CLI
+ * entrypoint and the wiring test, so a test exercising it covers the real
+ * production command (options + --host dispatch), not a copy.
+ *
+ * --host accepts only `openclaw` and `codex`; any other value is rejected with
+ * a structured reason/nextAction and a non-zero exit (cli-1/cli-2/cli-6). When
+ * `--json` is set, the rejection is emitted as exactly one parseable JSON
+ * object on stdout.
+ */
+export function registerHealthCommand(program: Command, handlers: HealthCommandHandlers = {}): void {
+  const healthHandler = handlers.health ?? handleHealth;
+  const codexHandler = handlers.healthCodex ?? handleHealthCodex;
+  program
+    .command('health')
+    .description('Show health diagnostics for all workspaces')
+    .option('-w, --workspace <path>', 'Workspace directory')
+    .option('--json', 'Output raw JSON')
+    .option('--host <host>', 'Host to inspect (openclaw|codex). Defaults to openclaw workspace health.')
+    .action(async (opts) => {
+      const host = opts.host ?? 'openclaw';
+      if (host !== 'codex' && host !== 'openclaw') {
+        // cli-2: exit-stops — return after setting exitCode.
+        if (opts.json) {
+          console.log(JSON.stringify({
+            ok: false,
+            reason: 'invalid_host',
+            host,
+            nextAction: `Use a supported host: openclaw or codex.`,
+          }));
+          process.exitCode = 1;
+          return;
+        }
+        console.error(`Invalid --host "${host}". Supported hosts: openclaw, codex.`);
+        console.error(`nextAction: run \`pd health --host openclaw\` or \`pd health --host codex\`.`);
+        process.exitCode = 1;
+        return;
+      }
+      if (host === 'codex') {
+        await codexHandler(opts);
+        return;
+      }
+      await healthHandler(opts);
+    });
+}

package/src/commands/intent.ts

@@ -2,14 +2,17 @@
  * pd intent — Owner-authored INTENT.md management (PRI-466).
  *
  * Subcommands:
- *   - init : create .principles/INTENT.md from the canonical template
- *   - show : display a read-only summary of INTENT.md (sections, hash, warnings)
+ *   - init : create .principles/INTENT.{lang}.md from the canonical template
+ *   - show : display a read-only summary of INTENT.{lang}.md (sections, hash, warnings)
  *
  * `init` is not gated by the intent_engineering flag — the Owner can
  * initialise the intent doc at any time. `show` IS gated: flag-off returns
  * a structured `flag_disabled` result without touching the filesystem,
  * matching the Console backend contract.
  *
+ * Bilingual: --lang zh-CN|en (default zh-CN) selects the intent doc language.
+ * File naming: INTENT.zh-CN.md / INTENT.en.md via getIntentFilename(lang).
+ *
  * JSON mode is strict: --json outputs exactly one parseable JSON object on
  * stdout (CLI Operator Gate rule 1). Failure paths include structured
  * reason + nextAction (rule 6).
@@ -27,13 +30,14 @@ import * as path from 'node:path';
 import type { Command } from 'commander';
 import {
   INTENT_MAX_BYTES,
-  INTENT_DOC_TEMPLATE,
+  getIntentFilename,
+  createIntentTemplate,
   parseIntentDocSections,
   computeIntentContentHash,
   validateIntentDocSections,
   isFeatureEnabled,
 } from '@principles/core/runtime-v2';
-import type { IntentDocSections, IntentDocWarning } from '@principles/core/runtime-v2';
+import type { IntentDocSections, IntentDocWarning, IntentLang } from '@principles/core/runtime-v2';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
 import { loadPdConfig, computeFlagsFromLoadResult } from '../services/pd-config-loader.js';
 import { emitResult } from '../services/cli-output.js';
@@ -41,7 +45,23 @@ import { emitResult } from '../services/cli-output.js';
 // ── Constants ────────────────────────────────────────────────────────────────
 
 const INTENT_DIR = '.principles';
-const INTENT_FILENAME = 'INTENT.md';
+
+/**
+ * Parse and validate the --lang option.
+ *
+ * Returns:
+ *   - 'zh-CN' | 'en' when value is undefined (default zh-CN) or a valid lang.
+ *   - null when value is a non-empty string that is neither 'zh-CN' nor 'en'.
+ *
+ * rc-9: invalid values MUST NOT silently fall back to zh-CN — that would
+ * let a typo like `--lang zh` quietly write to INTENT.zh-CN.md. Callers
+ * emit a structured `invalid_lang` error when null is returned.
+ */
+export function parseLang(value: string | undefined): IntentLang | null {
+  if (value === undefined) return 'zh-CN';
+  if (value === 'zh-CN' || value === 'en') return value;
+  return null;
+}
 
 // ── Output types ─────────────────────────────────────────────────────────────
 
@@ -54,7 +74,7 @@ export interface IntentInitOutput {
 }
 
 export interface IntentShowOutput {
-  status: 'ok' | 'flag_disabled' | 'not_found' | 'oversized' | 'read_error';
+  status: 'ok' | 'skipped' | 'flag_disabled' | 'not_found' | 'oversized' | 'read_error';
   flagEnabled: boolean;
   found: boolean;
   path?: string;
@@ -68,8 +88,8 @@ export interface IntentShowOutput {
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
-function getIntentFilePath(workspaceDir: string): string {
-  return path.join(workspaceDir, INTENT_DIR, INTENT_FILENAME);
+function getIntentFilePath(workspaceDir: string, lang: IntentLang): string {
+  return path.join(workspaceDir, INTENT_DIR, getIntentFilename(lang));
 }
 
 function sectionsToRecord(sections: IntentDocSections): Record<string, string> {
@@ -82,9 +102,9 @@ function sectionsToRecord(sections: IntentDocSections): Record<string, string> {
   return record;
 }
 
-function formatIntentShowText(o: IntentShowOutput): string {
+function formatIntentShowText(o: IntentShowOutput, filename: string): string {
   const lines: string[] = [];
-  lines.push(`INTENT.md — ${o.path}`);
+  lines.push(`${filename} — ${o.path}`);
   lines.push(`Content hash: ${o.contentHash}`);
   lines.push(`Last edited:  ${o.lastEditedAt}`);
   lines.push('');
@@ -114,9 +134,29 @@ export interface IntentInitOptions {
   json?: boolean;
   dryRun?: boolean;
   confirm?: boolean;
+  lang?: string;
 }
 
 export async function handleIntentInit(opts: IntentInitOptions): Promise<void> {
+  const lang = parseLang(opts.lang);
+
+  // rc-9: invalid --lang must not silently fall back. Emit structured error.
+  if (lang === null) {
+    const output: IntentInitOutput = {
+      status: 'skipped',
+      path: '',
+      overwritten: false,
+      reason: 'invalid_lang',
+      nextAction: `--lang must be 'zh-CN' or 'en'. Received: ${opts.lang ?? ''}`,
+    };
+    emitResult(output, {
+      json: opts.json ?? false,
+      formatText: (o) => `Error: ${o.reason}\n→ ${o.nextAction}`,
+    });
+    process.exitCode = 1;
+    return;
+  }
+
   // CLI Gate rule 4: --dry-run and --confirm must be mutually exclusive.
   if (opts.dryRun && opts.confirm) {
     const output: IntentInitOutput = {
@@ -141,7 +181,7 @@ export async function handleIntentInit(opts: IntentInitOptions): Promise<void> {
   let dir: string;
   try {
     workspaceDir = resolveWorkspaceDir(opts.workspace);
-    filePath = getIntentFilePath(workspaceDir);
+    filePath = getIntentFilePath(workspaceDir, lang);
     dir = path.dirname(filePath);
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
@@ -160,6 +200,8 @@ export async function handleIntentInit(opts: IntentInitOptions): Promise<void> {
     return;
   }
 
+  const filename = getIntentFilename(lang);
+
   // CLI Gate rule 4: state-mutating command defaults to dry-run unless --confirm.
   const isDryRun = opts.dryRun === true || opts.confirm !== true;
 
@@ -170,11 +212,11 @@ export async function handleIntentInit(opts: IntentInitOptions): Promise<void> {
         path: filePath,
         overwritten: false,
         reason: 'file_exists',
-        nextAction: `Use --force to overwrite: pd intent init --force --confirm --workspace "${workspaceDir}"`,
+        nextAction: `Use --force to overwrite: pd intent init --force --confirm --lang ${lang} --workspace "${workspaceDir}"`,
       };
       emitResult(output, {
         json: opts.json ?? false,
-        formatText: (o) => `INTENT.md already exists at ${o.path}\n→ ${o.nextAction}`,
+        formatText: (o) => `${filename} already exists at ${o.path}\n→ ${o.nextAction}`,
       });
       process.exitCode = 1;
       return;
@@ -186,17 +228,17 @@ export async function handleIntentInit(opts: IntentInitOptions): Promise<void> {
         path: filePath,
         overwritten: opts.force === true,
         reason: 'dry_run',
-        nextAction: `Confirm write: pd intent init --confirm${opts.force ? ' --force' : ''} --workspace "${workspaceDir}"`,
+        nextAction: `Confirm write: pd intent init --confirm --lang ${lang}${opts.force ? ' --force' : ''} --workspace "${workspaceDir}"`,
       };
       emitResult(output, {
         json: opts.json ?? false,
-        formatText: (o) => `[dry-run] Would create INTENT.md at ${o.path}${o.overwritten ? ' (overwritten)' : ''}\n→ ${o.nextAction}`,
+        formatText: (o) => `[dry-run] Would create ${filename} at ${o.path}${o.overwritten ? ' (overwritten)' : ''}\n→ ${o.nextAction}`,
       });
       return;
     }
 
     fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(filePath, INTENT_DOC_TEMPLATE, 'utf8');
+    fs.writeFileSync(filePath, createIntentTemplate(lang), 'utf8');
 
     const output: IntentInitOutput = {
       status: 'ok',
@@ -205,7 +247,7 @@ export async function handleIntentInit(opts: IntentInitOptions): Promise<void> {
     };
     emitResult(output, {
       json: opts.json ?? false,
-      formatText: (o) => `Created INTENT.md at ${o.path}${o.overwritten ? ' (overwritten)' : ''}\nNext: edit the file to declare your project intent, then run "pd intent show".`,
+      formatText: (o) => `Created ${filename} at ${o.path}${o.overwritten ? ' (overwritten)' : ''}\nNext: edit the file to declare your project intent, then run "pd intent show --lang ${lang}".`,
     });
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
@@ -228,9 +270,30 @@ export async function handleIntentInit(opts: IntentInitOptions): Promise<void> {
 export interface IntentShowOptions {
   workspace?: string;
   json?: boolean;
+  lang?: string;
 }
 
 export async function handleIntentShow(opts: IntentShowOptions): Promise<void> {
+  const lang = parseLang(opts.lang);
+
+  // rc-9: invalid --lang must not silently fall back. Emit structured error.
+  if (lang === null) {
+    const output: IntentShowOutput = {
+      status: 'skipped',
+      flagEnabled: false,
+      found: false,
+      warnings: [],
+      reason: 'invalid_lang',
+      nextAction: `--lang must be 'zh-CN' or 'en'. Received: ${opts.lang ?? ''}`,
+    };
+    emitResult(output, {
+      json: opts.json ?? false,
+      formatText: (o) => `Error: ${o.reason}\n→ ${o.nextAction}`,
+    });
+    process.exitCode = 1;
+    return;
+  }
+
   // CLI Gate rule 6: workspace resolution inside try/catch for structured errors.
   let workspaceDir: string;
   try {
@@ -258,6 +321,8 @@ export async function handleIntentShow(opts: IntentShowOptions): Promise<void> {
   const flagsResult = computeFlagsFromLoadResult(configResult);
   const flagEnabled = isFeatureEnabled(flagsResult, 'intent_engineering');
 
+  const filename = getIntentFilename(lang);
+
   if (!flagEnabled) {
     const output: IntentShowOutput = {
       status: 'flag_disabled',
@@ -265,7 +330,7 @@ export async function handleIntentShow(opts: IntentShowOptions): Promise<void> {
       found: false,
       warnings: [],
       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 ${filename}.`,
     };
     emitResult(output, {
       json: opts.json ?? false,
@@ -274,7 +339,7 @@ export async function handleIntentShow(opts: IntentShowOptions): Promise<void> {
     return;
   }
 
-  const filePath = getIntentFilePath(workspaceDir);
+  const filePath = getIntentFilePath(workspaceDir, lang);
 
   try {
     if (!fs.existsSync(filePath)) {
@@ -284,11 +349,11 @@ export async function handleIntentShow(opts: IntentShowOptions): Promise<void> {
         found: false,
         warnings: [],
         reason: 'not_found',
-        nextAction: `Create INTENT.md: pd intent init --workspace "${workspaceDir}"`,
+        nextAction: `Create ${filename}: pd intent init --confirm --lang ${lang} --workspace "${workspaceDir}"`,
       };
       emitResult(output, {
         json: opts.json ?? false,
-        formatText: (o) => `INTENT.md not found.\n→ ${o.nextAction}`,
+        formatText: (o) => `${filename} not found.\n→ ${o.nextAction}`,
       });
       return;
     }
@@ -301,11 +366,11 @@ export async function handleIntentShow(opts: IntentShowOptions): Promise<void> {
         found: true,
         warnings: [],
         reason: 'oversized',
-        nextAction: `INTENT.md exceeds ${INTENT_MAX_BYTES} bytes (${stat.size} bytes). Reduce content.`,
+        nextAction: `${filename} exceeds ${INTENT_MAX_BYTES} bytes (${stat.size} bytes). Reduce content.`,
       };
       emitResult(output, {
         json: opts.json ?? false,
-        formatText: (o) => `INTENT.md is too large.\n→ ${o.nextAction}`,
+        formatText: (o) => `${filename} is too large.\n→ ${o.nextAction}`,
       });
       return;
     }
@@ -327,7 +392,7 @@ export async function handleIntentShow(opts: IntentShowOptions): Promise<void> {
     };
     emitResult(output, {
       json: opts.json ?? false,
-      formatText: (o) => formatIntentShowText(o),
+      formatText: (o) => formatIntentShowText(o, filename),
     });
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
@@ -341,7 +406,7 @@ export async function handleIntentShow(opts: IntentShowOptions): Promise<void> {
     };
     emitResult(output, {
       json: opts.json ?? false,
-      formatText: (o) => `Error reading INTENT.md: ${o.reason}\n→ ${o.nextAction}`,
+      formatText: (o) => `Error reading ${filename}: ${o.reason}\n→ ${o.nextAction}`,
     });
     process.exitCode = 1;
   }
@@ -356,11 +421,12 @@ export function registerIntentCommand(parentCmd: Command): Command {
 
   intentCmd
     .command('init')
-    .description('Create .principles/INTENT.md from the canonical template')
+    .description('Create .principles/INTENT.{lang}.md from the canonical template')
     .option('-w, --workspace <path>', 'Workspace directory')
-    .option('--force', 'Overwrite existing INTENT.md')
+    .option('--force', 'Overwrite existing INTENT file')
     .option('--dry-run', 'Show what would happen without writing (default)')
-    .option('--confirm', 'Actually write the file (required to create INTENT.md)')
+    .option('--confirm', 'Actually write the file (required to create INTENT file)')
+    .option('--lang <lang>', 'Language: zh-CN or en (default: zh-CN)')
     .option('--json', 'Output raw JSON')
     .action(async (opts) => {
       await handleIntentInit({
@@ -369,18 +435,21 @@ export function registerIntentCommand(parentCmd: Command): Command {
         json: opts.json === true,
         dryRun: opts.dryRun === true,
         confirm: opts.confirm === true,
+        lang: opts.lang,
       });
     });
 
   intentCmd
     .command('show')
-    .description('Display a read-only summary of INTENT.md (sections, hash, warnings)')
+    .description('Display a read-only summary of INTENT.{lang}.md (sections, hash, warnings)')
     .option('-w, --workspace <path>', 'Workspace directory')
+    .option('--lang <lang>', 'Language: zh-CN or en (default: zh-CN)')
     .option('--json', 'Output raw JSON')
     .action(async (opts) => {
       await handleIntentShow({
         workspace: opts.workspace,
         json: opts.json === true,
+        lang: opts.lang,
       });
     });
 

package/src/commands/pain-evidence.ts

@@ -8,6 +8,12 @@
  *   pd pain evidence [--workspace <path>] [--limit N] [--json]
  *
  * Shows the most recent TRIGGER_DECISION log entries.
+ *
+ * Note: TRIGGER_DECISION entries are pain-signal admission gate decisions
+ * (Gate B / TriggerController). These are distinct from GFI (General
+ * Friction Index) friction events like GFI_SLICE_RESET, which track
+ * session-level tool-friction resets and are NOT pain signals. This command
+ * does not surface GFI events; use `pd runtime health gfi` for GFI state.
  */
 
 import * as fs from 'fs';