@principles/pd-cli 1.132.0 → 1.134.0

package/scripts/migrate-illegal-expected-decision.ts

@@ -0,0 +1,252 @@
+/**
+ * 一次性数据迁移脚本：修正 pi_artifacts 中 expectedDecision = "requireApproval" 的历史坏数据。
+ *
+ * 背景：
+ *   GoldenTraceDecision 的合法值只有 "allow" | "block" | "propose_correction"
+ *   （定义在 @principles/core/runtime-v2 的 golden-trace.ts GoldenTraceDecisionSchema）。
+ *   但 PRI-427 加固前创建的 rule artifact 可能含有 "requireApproval"
+ *   （这是 RuleHostDecision 的运行时枚举值，不是测试期望值）。
+ *   这类 artifact 在 owner 批准时会失败，错误信息为
+ *   "gate_decision_not_accepted_shadow:rejected_validation_failed"，对 owner 不可操作。
+ *
+ *   根因已在 rule-host-writer.ts 的 extractGoldenTrace() 中修复（调用 validateGoldenTrace
+ *   前置 schema 校验）。本脚本用于清理已存在的坏数据。
+ *
+ * 修复策略：
+ *   - kind=negative + expectedDecision=requireApproval → 改为 "block"
+ *     （validateCaseDecision 的 'block' case 接受 requireApproval 作为合法运行时输出）
+ *   - kind=positive + expectedDecision=requireApproval → 改为 "allow"
+ *     （理论上不应出现，但兜底处理）
+ *   - 其他非法值 → 报告但不修改（需人工判断）
+ *
+ * 使用：
+ *   npx tsx scripts/migrate-illegal-expected-decision.ts <workspace-dir> [--write]
+ *
+ * 示例：
+ *   npx tsx scripts/migrate-illegal-expected-decision.ts D:/.openclaw/workspace
+ *   npx tsx scripts/migrate-illegal-expected-decision.ts D:/.openclaw/workspace --write
+ *
+ * 安全保障：
+ *   1. 默认 dry-run（只读），必须显式 --write 才会写入
+ *   2. --write 模式下自动备份 state.db 到 state.db.backup-<timestamp>
+ *   3. 只修改 artifact_kind='rule' 的记录
+ *   4. 同时修正 goldenTrace 和 goldenTraceCases 两个字段（artificer raw 输出副本）
+ *   5. --write 模式下所有 UPDATE 在单个事务内执行，保证原子性
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import Database from 'better-sqlite3';
+
+interface CliArgs {
+  workspaceDir: string;
+  dryRun: boolean;
+}
+
+function parseArgs(argv: string[]): CliArgs {
+  const positional = argv.slice(2).filter((a) => !a.startsWith('--'));
+  // Safety default: dry-run (read-only). Operator must pass --write to mutate.
+  const writeMode = argv.includes('--write');
+  if (positional.length === 0) {
+    console.error('Usage: npx tsx scripts/migrate-illegal-expected-decision.ts <workspace-dir> [--write]');
+    console.error('Example: npx tsx scripts/migrate-illegal-expected-decision.ts D:/.openclaw/workspace');
+    console.error('         npx tsx scripts/migrate-illegal-expected-decision.ts D:/.openclaw/workspace --write');
+    process.exit(1);
+  }
+  return { workspaceDir: positional[0] ?? '', dryRun: !writeMode };
+}
+
+interface FixRecord {
+  artifactId: string;
+  caseId: string;
+  kind: string;
+  from: string;
+  to: string;
+  field: 'goldenTrace' | 'goldenTraceCases';
+}
+
+function normalizeExpectedDecision(value: unknown, kind: unknown): string | null {
+  if (value !== 'requireApproval') return null;
+  // Only map explicit kinds — unknown kind must NOT be silently coerced.
+  // Unknown kinds are reported (not modified) so a human can review them.
+  if (kind === 'positive') return 'allow';
+  if (kind === 'negative') return 'block';
+  return null;
+}
+
+function fixCasesArray(
+  cases: unknown,
+  artifactId: string,
+  field: 'goldenTrace' | 'goldenTraceCases',
+  fixes: FixRecord[],
+  issues: Array<{ artifactId: string; issue: string }>,
+): boolean {
+  if (!Array.isArray(cases)) return false;
+  let modified = false;
+  for (const c of cases) {
+    if (typeof c !== 'object' || c === null) continue;
+    const rec = c as Record<string, unknown>;
+    const newVal = normalizeExpectedDecision(rec.expectedDecision, rec.kind);
+    if (newVal !== null) {
+      fixes.push({
+        artifactId,
+        caseId: typeof rec.caseId === 'string' ? rec.caseId : '<unknown>',
+        kind: typeof rec.kind === 'string' ? rec.kind : '<unknown>',
+        from: String(rec.expectedDecision),
+        to: newVal,
+        field,
+      });
+      rec.expectedDecision = newVal;
+      modified = true;
+    } else if (rec.expectedDecision === 'requireApproval') {
+      // Illegal value found but kind is not positive/negative — cannot
+      // auto-fix safely. Record for manual review instead of silently
+      // coercing to 'block' (rc-9: no silent fallback).
+      const kindStr = typeof rec.kind === 'string' ? rec.kind : '<unknown>';
+      const caseIdStr = typeof rec.caseId === 'string' ? rec.caseId : '<unknown>';
+      issues.push({
+        artifactId,
+        issue: `requireApproval with unknown kind="${kindStr}" (case=${caseIdStr}, field=${field}) — manual review required`,
+      });
+    }
+  }
+  return modified;
+}
+
+function main(): void {
+  const { workspaceDir, dryRun } = parseArgs(process.argv);
+  const dbPath = path.join(workspaceDir, '.pd', 'state.db');
+
+  if (!fs.existsSync(dbPath)) {
+    console.error(`[error] state.db not found at ${dbPath}`);
+    process.exit(1);
+  }
+
+  // 1. 备份 DB（非 dry-run 时）
+  if (!dryRun) {
+    const backupPath = `${dbPath}.backup-${Date.now()}`;
+    fs.copyFileSync(dbPath, backupPath);
+    console.log(`[backup] created ${backupPath}`);
+  } else {
+    console.log('[dry-run] no backup created');
+  }
+
+  const db = new Database(dbPath, { readonly: dryRun });
+  console.log(`\n[mode] ${dryRun ? 'DRY-RUN (read-only)' : 'WRITE'}`);
+  console.log(`[db] ${dbPath}`);
+
+  // 2. 扫描所有 rule artifact
+  const artifactsRaw = db
+    .prepare('SELECT artifact_id, content_json FROM pi_artifacts WHERE artifact_kind = ?')
+    .all('rule');
+  // Runtime guard: better-sqlite3 returns unknown[]. Validate shape before use (rc-1/rc-2).
+  const artifacts: Array<{ artifact_id: string; content_json: string }> = [];
+  if (Array.isArray(artifactsRaw)) {
+    for (const row of artifactsRaw) {
+      if (
+        typeof row === 'object' && row !== null
+        && typeof (row as Record<string, unknown>).artifact_id === 'string'
+        && typeof (row as Record<string, unknown>).content_json === 'string'
+      ) {
+        artifacts.push({
+          artifact_id: (row as Record<string, string>).artifact_id,
+          content_json: (row as Record<string, string>).content_json,
+        });
+      }
+    }
+  }
+  console.log(`[scan] found ${artifacts.length} rule artifacts`);
+
+  const fixes: FixRecord[] = [];
+  const issues: Array<{ artifactId: string; issue: string }> = [];
+
+  for (const art of artifacts) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(art.content_json);
+    } catch {
+      issues.push({ artifactId: art.artifact_id, issue: 'content_json parse failed' });
+      continue;
+    }
+    if (typeof parsed !== 'object' || parsed === null) continue;
+    const obj = parsed as Record<string, unknown>;
+
+    // 修复 goldenTrace.cases
+    if (typeof obj.goldenTrace === 'object' && obj.goldenTrace !== null) {
+      const trace = obj.goldenTrace as Record<string, unknown>;
+      fixCasesArray(trace.cases, art.artifact_id, 'goldenTrace', fixes, issues);
+    }
+
+    // 修复 goldenTraceCases（artificer raw 输出副本）
+    fixCasesArray(obj.goldenTraceCases, art.artifact_id, 'goldenTraceCases', fixes, issues);
+  }
+
+  // 3. 报告
+  if (fixes.length === 0 && issues.length === 0) {
+    console.log('\n[summary] no illegal expectedDecision values found. Nothing to fix.');
+    db.close();
+    return;
+  }
+
+  if (fixes.length > 0) {
+    console.log(`\n[fixes] ${fixes.length} case(s) ${dryRun ? 'would be ' : ''}fixed across ${new Set(fixes.map((f) => f.artifactId)).size} artifact(s):`);
+    for (const f of fixes) {
+      console.log(`  ${f.artifactId} | ${f.field} | case=${f.caseId} kind=${f.kind}: ${f.from} → ${f.to}`);
+    }
+  } else {
+    console.log('\n[fixes] 0 cases can be auto-fixed.');
+  }
+
+  if (issues.length > 0) {
+    console.log(`\n[issues] ${issues.length} artifact(s) had parse issues or require manual review:`);
+    for (const i of issues) console.log(`  ${i.artifactId}: ${i.issue}`);
+  }
+
+  if (dryRun) {
+    console.log('\n[dry-run] no changes written. Re-run with --write to apply.');
+    db.close();
+    return;
+  }
+
+  if (fixes.length === 0) {
+    // Nothing to write — only issues (manual review). Don't open a transaction.
+    db.close();
+    return;
+  }
+
+  // 4. 应用修复 — 所有 UPDATE 在单个事务内执行，保证原子性 (all-or-nothing)
+  let updatedCount = 0;
+  const artifactsToFix = new Set(fixes.map((f) => f.artifactId));
+  const applyTx = db.transaction(() => {
+    for (const art of artifacts) {
+      if (!artifactsToFix.has(art.artifact_id)) continue;
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(art.content_json);
+      } catch {
+        continue;
+      }
+      // Runtime guard (rc-1/rc-2): validate parsed shape before use.
+      if (typeof parsed !== 'object' || parsed === null) continue;
+      const parsedObj = parsed as Record<string, unknown>;
+
+      if (typeof parsedObj.goldenTrace === 'object' && parsedObj.goldenTrace !== null) {
+        const trace = parsedObj.goldenTrace as Record<string, unknown>;
+        fixCasesArray(trace.cases, art.artifact_id, 'goldenTrace', [], issues);
+      }
+      fixCasesArray(parsedObj.goldenTraceCases, art.artifact_id, 'goldenTraceCases', [], issues);
+
+      const newContentJson = JSON.stringify(parsedObj);
+      const result = db
+        .prepare('UPDATE pi_artifacts SET content_json = ?, updated_at = ? WHERE artifact_id = ?')
+        .run(newContentJson, new Date().toISOString(), art.artifact_id);
+      if (result.changes > 0) updatedCount++;
+    }
+  });
+  applyTx();
+
+  console.log(`\n[summary] ${updatedCount} artifact row(s) updated (transaction committed)`);
+
+  db.close();
+}
+
+main();

package/src/commands/__tests__/intent-flag-wiring.test.ts

@@ -8,7 +8,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { Command } from 'commander';
-import { registerIntentCommand } from '../intent.js';
+import { registerIntentCommand, parseLang } from '../intent.js';
 
 type ActionOptions = Record<string, unknown>;
 interface CapturedAction {
@@ -54,7 +54,7 @@ describe('pd intent — command registration', () => {
 });
 
 describe('pd intent init — option metadata', () => {
-  it('has --workspace (-w), --force, --dry-run, --confirm, and --json options', () => {
+  it('has --workspace (-w), --force, --dry-run, --confirm, --lang, and --json options', () => {
     const program = freshProgram();
     registerIntentCommand(program);
     const intentCmd = requireCmd(program.commands.find((c) => c.name() === 'intent'), 'intent');
@@ -65,6 +65,7 @@ describe('pd intent init — option metadata', () => {
     expect(initCmd.options.find((o) => o.long === '--force')).toBeDefined();
     expect(initCmd.options.find((o) => o.long === '--dry-run')).toBeDefined();
     expect(initCmd.options.find((o) => o.long === '--confirm')).toBeDefined();
+    expect(initCmd.options.find((o) => o.long === '--lang')).toBeDefined();
     expect(initCmd.options.find((o) => o.long === '--json')).toBeDefined();
   });
 
@@ -82,7 +83,7 @@ describe('pd intent init — option metadata', () => {
 });
 
 describe('pd intent show — option metadata', () => {
-  it('has --workspace (-w) and --json options, no --force', () => {
+  it('has --workspace (-w), --lang, and --json options, no --force', () => {
     const program = freshProgram();
     registerIntentCommand(program);
     const intentCmd = requireCmd(program.commands.find((c) => c.name() === 'intent'), 'intent');
@@ -90,6 +91,7 @@ describe('pd intent show — option metadata', () => {
 
     expect(showCmd.options.find((o) => o.long === '--workspace')).toBeDefined();
     expect(showCmd.options.find((o) => o.long === '--workspace')?.short).toBe('-w');
+    expect(showCmd.options.find((o) => o.long === '--lang')).toBeDefined();
     expect(showCmd.options.find((o) => o.long === '--json')).toBeDefined();
     expect(showCmd.options.find((o) => o.long === '--force')).toBeUndefined();
   });
@@ -195,3 +197,86 @@ describe('pd intent show — parser-level dispatch', () => {
     expect(captured.opts?.workspace).toBe('/tmp/ws');
   });
 });
+
+describe('pd intent --lang — parser-level dispatch (cli-7)', () => {
+  it('init: parses --lang zh-CN', async () => {
+    const program = freshProgram();
+    const intentCmd = registerIntentCommand(program);
+    const initCmd = requireCmd(intentCmd.commands.find((c) => c.name() === 'init'), 'init');
+    const captured: CapturedAction = { opts: null };
+    attachCapture(initCmd, captured);
+
+    await program.parseAsync(['node', 'pd', 'intent', 'init', '--lang', 'zh-CN']);
+    expect(captured.opts).not.toBeNull();
+    expect(captured.opts?.lang).toBe('zh-CN');
+  });
+
+  it('init: parses --lang en', async () => {
+    const program = freshProgram();
+    const intentCmd = registerIntentCommand(program);
+    const initCmd = requireCmd(intentCmd.commands.find((c) => c.name() === 'init'), 'init');
+    const captured: CapturedAction = { opts: null };
+    attachCapture(initCmd, captured);
+
+    await program.parseAsync(['node', 'pd', 'intent', 'init', '--lang', 'en']);
+    expect(captured.opts).not.toBeNull();
+    expect(captured.opts?.lang).toBe('en');
+  });
+
+  it('init: lang defaults to undefined when not passed', async () => {
+    const program = freshProgram();
+    const intentCmd = registerIntentCommand(program);
+    const initCmd = requireCmd(intentCmd.commands.find((c) => c.name() === 'init'), 'init');
+    const captured: CapturedAction = { opts: null };
+    attachCapture(initCmd, captured);
+
+    await program.parseAsync(['node', 'pd', 'intent', 'init']);
+    expect(captured.opts).not.toBeNull();
+    expect(captured.opts?.lang).toBeUndefined();
+  });
+
+  it('show: parses --lang en', async () => {
+    const program = freshProgram();
+    const intentCmd = registerIntentCommand(program);
+    const showCmd = requireCmd(intentCmd.commands.find((c) => c.name() === 'show'), 'show');
+    const captured: CapturedAction = { opts: null };
+    attachCapture(showCmd, captured);
+
+    await program.parseAsync(['node', 'pd', 'intent', 'show', '--lang', 'en']);
+    expect(captured.opts).not.toBeNull();
+    expect(captured.opts?.lang).toBe('en');
+  });
+
+  it('show: lang defaults to undefined when not passed', async () => {
+    const program = freshProgram();
+    const intentCmd = registerIntentCommand(program);
+    const showCmd = requireCmd(intentCmd.commands.find((c) => c.name() === 'show'), 'show');
+    const captured: CapturedAction = { opts: null };
+    attachCapture(showCmd, captured);
+
+    await program.parseAsync(['node', 'pd', 'intent', 'show']);
+    expect(captured.opts).not.toBeNull();
+    expect(captured.opts?.lang).toBeUndefined();
+  });
+});
+
+describe('parseLang — invalid value rejection (rc-9)', () => {
+  it('returns zh-CN when value is undefined (default)', () => {
+    expect(parseLang(undefined)).toBe('zh-CN');
+  });
+
+  it('returns zh-CN when value is zh-CN', () => {
+    expect(parseLang('zh-CN')).toBe('zh-CN');
+  });
+
+  it('returns en when value is en', () => {
+    expect(parseLang('en')).toBe('en');
+  });
+
+  it('returns null for invalid value (no silent fallback)', () => {
+    expect(parseLang('fr')).toBeNull();
+    expect(parseLang('zh')).toBeNull();
+    expect(parseLang('english')).toBeNull();
+    expect(parseLang('')).toBeNull();
+  });
+});

package/src/commands/__tests__/pain-retry-maxTokens-flag.test.ts

@@ -0,0 +1,73 @@
+/**
+ * CLI flag-wiring tests for `pd pain retry --maxTokens` (PRI-509 follow-up).
+ *
+ * Covers:
+ *   - `--maxTokens <n>` parses to a number and is passed to the handler
+ *   - `--maxTokens` falls back to undefined when the flag is omitted
+ *
+ * Mirrors the flag-wiring test pattern from run-rulehost-flag-wiring.test.ts.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { Command } from 'commander';
+import { registerPainRetryCommand } from '../pain-retry.js';
+
+function freshProgram(): Command {
+  return new Command();
+}
+
+function attachCapture(cmd: Command, captured: { opts: Record<string, unknown> | null }) {
+  const origAction = cmd.action.bind(cmd);
+  cmd.action = ((handler: (opts: Record<string, unknown>) => void) => {
+    return origAction((opts: Record<string, unknown>) => {
+      captured.opts = opts;
+      return handler(opts);
+    });
+  }) as typeof cmd.action;
+}
+
+function register(painCmd: Command, captured: { opts: Record<string, unknown> | null }) {
+  const cmd = registerPainRetryCommand(painCmd, async (opts) => {
+    captured.opts = opts as unknown as Record<string, unknown>;
+  });
+  attachCapture(cmd, captured);
+}
+
+describe('pd pain retry --maxTokens flag wiring', () => {
+  let captured: { opts: Record<string, unknown> | null };
+
+  beforeEach(() => {
+    captured = { opts: null };
+  });
+
+  it('parses --maxTokens to a number and passes it to the handler', async () => {
+    const program = freshProgram();
+    const painCmd = program.command('pain');
+    register(painCmd, captured);
+
+    await program.parseAsync(['node', 'pd', 'pain', 'retry', '--pain-id', 'pain-1', '--runtime', 'pi-ai', '--maxTokens', '16000']);
+
+    expect(captured.opts).not.toBeNull();
+    expect(captured.opts?.maxTokens).toBe(16000);
+    expect(typeof captured.opts?.maxTokens).toBe('number');
+  });
+
+  it('parses --maxTokens with a numeric string (parseInt path)', async () => {
+    const program = freshProgram();
+    const painCmd = program.command('pain');
+    register(painCmd, captured);
+
+    await program.parseAsync(['node', 'pd', 'pain', 'retry', '--pain-id', 'pain-1', '--runtime', 'pi-ai', '--maxTokens', '32000']);
+
+    expect(captured.opts?.maxTokens).toBe(32000);
+  });
+
+  it('keeps maxTokens undefined when flag is omitted (falls back to config)', async () => {
+    const program = freshProgram();
+    const painCmd = program.command('pain');
+    register(painCmd, captured);
+
+    await program.parseAsync(['node', 'pd', 'pain', 'retry', '--pain-id', 'pain-1', '--runtime', 'pi-ai']);
+
+    expect(captured.opts?.maxTokens).toBeUndefined();
+  });
+});

package/src/commands/__tests__/rulecode-flag-wiring.test.ts

@@ -52,6 +52,13 @@ function freshProgram(): Command {
   return program;
 }
 
+/** Find a subcommand by name, throwing if absent (replaces non-null assertions). */
+function requireSubcommand(parent: Command, name: string): Command {
+  const cmd = parent.commands.find((c) => c.name() === name);
+  if (!cmd) throw new Error(`Expected subcommand "${name}" to be registered`);
+  return cmd;
+}
+
 describe('pd rulecode — flag wiring (CLI gate rule 7)', () => {
   // ── spec subcommand ───────────────────────────────────────────────────────
 
@@ -62,10 +69,10 @@ describe('pd rulecode — flag wiring (CLI gate rule 7)', () => {
     const specCmd = rulecodeCmd.commands.find((c) => c.name() === 'spec');
     expect(specCmd).toBeDefined();
 
-    const jsonOpt = specCmd!.options.find((o) => o.long === '--json');
+    const jsonOpt = (specCmd as Command).options.find((o) => o.long === '--json');
     expect(jsonOpt).toBeDefined();
 
-    const wsOpt = specCmd!.options.find((o) => o.long === '--workspace');
+    const wsOpt = (specCmd as Command).options.find((o) => o.long === '--workspace');
     expect(wsOpt).toBeDefined();
     expect(wsOpt?.short).toBe('-w');
   });
@@ -75,7 +82,7 @@ describe('pd rulecode — flag wiring (CLI gate rule 7)', () => {
     const rulecodeCmd = registerRulecodeCommand(program);
 
     const specCmd = rulecodeCmd.commands.find((c) => c.name() === 'spec');
-    const codeOpt = specCmd!.options.find((o) => o.long === '--code');
+    const codeOpt = (specCmd as Command).options.find((o) => o.long === '--code');
     expect(codeOpt).toBeUndefined();
   });
 
@@ -88,16 +95,16 @@ describe('pd rulecode — flag wiring (CLI gate rule 7)', () => {
     const validateCmd = rulecodeCmd.commands.find((c) => c.name() === 'validate');
     expect(validateCmd).toBeDefined();
 
-    const codeOpt = validateCmd!.options.find((o) => o.long === '--code');
+    const codeOpt = (validateCmd as Command).options.find((o) => o.long === '--code');
     expect(codeOpt).toBeDefined();
 
-    const codeFileOpt = validateCmd!.options.find((o) => o.long === '--code-file');
+    const codeFileOpt = (validateCmd as Command).options.find((o) => o.long === '--code-file');
     expect(codeFileOpt).toBeDefined();
 
-    const jsonOpt = validateCmd!.options.find((o) => o.long === '--json');
+    const jsonOpt = (validateCmd as Command).options.find((o) => o.long === '--json');
     expect(jsonOpt).toBeDefined();
 
-    const wsOpt = validateCmd!.options.find((o) => o.long === '--workspace');
+    const wsOpt = (validateCmd as Command).options.find((o) => o.long === '--workspace');
     expect(wsOpt).toBeDefined();
     expect(wsOpt?.short).toBe('-w');
   });
@@ -105,7 +112,7 @@ describe('pd rulecode — flag wiring (CLI gate rule 7)', () => {
   it('validate --code is NOT required at parser level (can use --code-file instead)', async () => {
     const program = freshProgram();
     const rulecodeCmd = registerRulecodeCommand(program);
-    const validateCmd = rulecodeCmd.commands.find((c) => c.name() === 'validate')!;
+    const validateCmd = requireSubcommand(rulecodeCmd, 'validate');
     const captured: CapturedAction = { opts: null };
     attachCapture(validateCmd, captured);
 
@@ -113,7 +120,7 @@ describe('pd rulecode — flag wiring (CLI gate rule 7)', () => {
     await program.parseAsync(['node', 'pd', 'rulecode', 'validate', '--json']);
 
     expect(captured.opts).not.toBeNull();
-    expect(captured.opts!.code).toBeUndefined();
+    expect((captured.opts as ActionOptions).code).toBeUndefined();
   });
 
   // ── replay subcommand ─────────────────────────────────────────────────────
@@ -125,19 +132,19 @@ describe('pd rulecode — flag wiring (CLI gate rule 7)', () => {
     const replayCmd = rulecodeCmd.commands.find((c) => c.name() === 'replay');
     expect(replayCmd).toBeDefined();
 
-    const codeOpt = replayCmd!.options.find((o) => o.long === '--code');
+    const codeOpt = (replayCmd as Command).options.find((o) => o.long === '--code');
     expect(codeOpt).toBeDefined();
 
-    const codeFileOpt = replayCmd!.options.find((o) => o.long === '--code-file');
+    const codeFileOpt = (replayCmd as Command).options.find((o) => o.long === '--code-file');
     expect(codeFileOpt).toBeDefined();
 
-    const gtOpt = replayCmd!.options.find((o) => o.long === '--golden-trace');
+    const gtOpt = (replayCmd as Command).options.find((o) => o.long === '--golden-trace');
     expect(gtOpt).toBeDefined();
 
-    const jsonOpt = replayCmd!.options.find((o) => o.long === '--json');
+    const jsonOpt = (replayCmd as Command).options.find((o) => o.long === '--json');
     expect(jsonOpt).toBeDefined();
 
-    const wsOpt = replayCmd!.options.find((o) => o.long === '--workspace');
+    const wsOpt = (replayCmd as Command).options.find((o) => o.long === '--workspace');
     expect(wsOpt).toBeDefined();
     expect(wsOpt?.short).toBe('-w');
   });
@@ -147,7 +154,7 @@ describe('pd rulecode — flag wiring (CLI gate rule 7)', () => {
     const rulecodeCmd = registerRulecodeCommand(program);
 
     const replayCmd = rulecodeCmd.commands.find((c) => c.name() === 'replay');
-    const gtOpt = replayCmd!.options.find((o) => o.long === '--golden-trace');
+    const gtOpt = (replayCmd as Command).options.find((o) => o.long === '--golden-trace');
     expect(gtOpt?.required).toBe(true);
   });
 
@@ -168,20 +175,20 @@ describe('pd rulecode — flag wiring (CLI gate rule 7)', () => {
   it('parseAsync dispatches spec subcommand with json=true', async () => {
     const program = freshProgram();
     const rulecodeCmd = registerRulecodeCommand(program);
-    const specCmd = rulecodeCmd.commands.find((c) => c.name() === 'spec')!;
+    const specCmd = requireSubcommand(rulecodeCmd, 'spec');
     const captured: CapturedAction = { opts: null };
     attachCapture(specCmd, captured);
 
     await program.parseAsync(['node', 'pd', 'rulecode', 'spec', '--json']);
 
     expect(captured.opts).not.toBeNull();
-    expect(captured.opts!.json).toBe(true);
+    expect((captured.opts as ActionOptions).json).toBe(true);
   });
 
   it('parseAsync dispatches validate with --code', async () => {
     const program = freshProgram();
     const rulecodeCmd = registerRulecodeCommand(program);
-    const validateCmd = rulecodeCmd.commands.find((c) => c.name() === 'validate')!;
+    const validateCmd = requireSubcommand(rulecodeCmd, 'validate');
     const captured: CapturedAction = { opts: null };
     attachCapture(validateCmd, captured);
 
@@ -192,14 +199,14 @@ describe('pd rulecode — flag wiring (CLI gate rule 7)', () => {
     ]);
 
     expect(captured.opts).not.toBeNull();
-    expect(captured.opts!.code).toContain('function evaluate');
-    expect(captured.opts!.json).toBe(true);
+    expect((captured.opts as ActionOptions).code).toContain('function evaluate');
+    expect((captured.opts as ActionOptions).json).toBe(true);
   });
 
   it('parseAsync dispatches replay with --code and --golden-trace', async () => {
     const program = freshProgram();
     const rulecodeCmd = registerRulecodeCommand(program);
-    const replayCmd = rulecodeCmd.commands.find((c) => c.name() === 'replay')!;
+    const replayCmd = requireSubcommand(rulecodeCmd, 'replay');
     const captured: CapturedAction = { opts: null };
     attachCapture(replayCmd, captured);
 
@@ -211,9 +218,9 @@ describe('pd rulecode — flag wiring (CLI gate rule 7)', () => {
     ]);
 
     expect(captured.opts).not.toBeNull();
-    expect(captured.opts!.code).toContain('function evaluate');
-    expect(captured.opts!.goldenTrace).toBe('/tmp/trace.json');
-    expect(captured.opts!.json).toBe(true);
+    expect((captured.opts as ActionOptions).code).toContain('function evaluate');
+    expect((captured.opts as ActionOptions).goldenTrace).toBe('/tmp/trace.json');
+    expect((captured.opts as ActionOptions).json).toBe(true);
   });
 
   it('parseAsync rejects replay without --golden-trace (requiredOption)', async () => {

package/src/commands/__tests__/run-rulehost-flag-wiring.test.ts

@@ -88,6 +88,18 @@ describe('pd runtime internalization run-rulehost — flag wiring (CLI gate rule
     expect(opt?.long).toBe('--json');
   });
 
+  it('parses --behavior-examples as the Owner-labelled evidence file', async () => {
+    const program = freshProgram();
+    const intCmd = program.command('internalization');
+    const runCmd = registerRunRuleHostCommand(intCmd);
+    const captured: CapturedAction = { opts: null };
+    attachCapture(runCmd, captured);
+
+    await program.parseAsync(['node', 'pd', 'internalization', 'run-rulehost', '--pain-id', 'pain-1', '--behavior-examples', 'examples.json']);
+
+    expect(captured.opts?.behaviorExamples).toBe('examples.json');
+  });
+
   it('registers --pain-id as required option', () => {
     const program = freshProgram();
     const intCmd = program.command('internalization');

package/src/commands/admission-gate.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared admission gate helper for CLI commands that call intakeService.intake().
+ *
+ * PRI-442 Stage 4 / PRI-503: previously only `candidate.ts` checked the gate;
+ * `pain-retry.ts` and `diagnose.ts` bypassed it (ERR-089 sibling-branch defect).
+ * This shared helper is the single entry point so future CLI commands that
+ * call intake() can reuse it instead of re-implementing (or skipping) the check.
+ *
+ * Runtime Contract: rc-9-no-silent-fallback — refusal includes reason + nextAction
+ * (callers MUST surface these in their structured CLI output).
+ */
+import { evaluateCandidateAdmissionFromRecord, type AdmissionGateResult } from '@principles/core/runtime-v2';
+
+/**
+ * Check admission gate for a candidate. Returns null if admitted (caller may
+ * proceed); returns AdmissionGateResult with reason + nextAction if refused
+ * (caller must refuse and surface reason/nextAction in CLI output).
+ *
+ * @param candidate - Must carry recommendationKind and confidence from the candidate record
+ */
+export function checkAdmissionGate(
+  candidate: { recommendationKind: string; confidence: number | null },
+): AdmissionGateResult | null {
+  const admission = evaluateCandidateAdmissionFromRecord({
+    recommendationKind: candidate.recommendationKind as Parameters<typeof evaluateCandidateAdmissionFromRecord>[0]['recommendationKind'],
+    confidence: candidate.confidence,
+  });
+  if (admission.decision === 'admitted') return null;
+  return admission;
+}