@principles/pd-cli 1.133.0 → 1.134.0

package/src/commands/runtime-internalization-run-rulehost.ts

@@ -24,6 +24,7 @@
  *   - --dry-run and --confirm are mutually exclusive
  */
 import * as path from 'path';
+import * as fs from 'node:fs';
 import type { Command } from 'commander';
 import { runRuleHostPipeline } from '../services/rulehost-pipeline-runner.js';
 import type { RuleHostPipelineResult, CodeRuleCapability, RuleHostAgentAdapters } from '../services/rulehost-pipeline-runner.js';
@@ -37,6 +38,7 @@ import {
   isFeatureEnabled,
 } from '@principles/core/runtime-v2';
 import type { EffectivePdConfig, InternalAgentName, PDRuntimeAdapter } from '@principles/core/runtime-v2';
+import type { BehaviorExamplePack } from '@principles/core/runtime-v2';
 import { resolveRuntimeFromPdConfig } from '../services/resolve-runtime-from-pd-config.js';
 import { resolveRuleHostReadiness } from '../services/rulehost-readiness.js';
 import type { RuleHostReadinessResult } from '../services/rulehost-readiness.js';
@@ -47,6 +49,7 @@ export interface RunRuleHostOptions {
   channel?: string;
   maxRounds?: number;
   timeoutMs?: number;
+  behaviorExamples?: string;
   json?: boolean;
   /** Dry-run mode (default). Validates inputs + config, reports capability status, does NOT run the pipeline. */
   dryRun?: boolean;
@@ -68,6 +71,49 @@ interface ResolvedRunRuleHostRuntime {
   readonly agentRuntimeProfiles: Partial<Record<InternalAgentName, string>>;
   readonly capability: CodeRuleCapability;
   readonly capabilityStatus: string;
+  readonly contextV2Enabled: boolean;
+}
+
+interface OwnerBehaviorExamplesInput {
+  readonly ownerDesiredOutcome: string;
+  readonly sourceNegativeToolCallId: number;
+  readonly positiveToolCallIds: readonly number[];
+}
+
+type OwnerBehaviorExamplesResult =
+  | { readonly ok: true; readonly value: OwnerBehaviorExamplesInput }
+  | { readonly ok: false; readonly reason: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function readOwnerBehaviorExamples(filePath: string): OwnerBehaviorExamplesResult {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    return { ok: false, reason: `behavior_examples_unreadable: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  if (!isRecord(parsed)) return { ok: false, reason: 'behavior_examples_invalid: root must be an object' };
+  if (typeof parsed.ownerDesiredOutcome !== 'string' || parsed.ownerDesiredOutcome.trim() === '') {
+    return { ok: false, reason: 'behavior_examples_invalid: ownerDesiredOutcome must be a non-empty string' };
+  }
+  if (!Number.isSafeInteger(parsed.sourceNegativeToolCallId) || Number(parsed.sourceNegativeToolCallId) <= 0) {
+    return { ok: false, reason: 'behavior_examples_invalid: sourceNegativeToolCallId must be a positive integer' };
+  }
+  if (!Array.isArray(parsed.positiveToolCallIds) || parsed.positiveToolCallIds.length === 0 || parsed.positiveToolCallIds.length > 3
+    || parsed.positiveToolCallIds.some((id) => !Number.isSafeInteger(id) || Number(id) <= 0)) {
+    return { ok: false, reason: 'behavior_examples_invalid: positiveToolCallIds must contain 1 to 3 positive integers' };
+  }
+  return {
+    ok: true,
+    value: {
+      ownerDesiredOutcome: parsed.ownerDesiredOutcome,
+      sourceNegativeToolCallId: Number(parsed.sourceNegativeToolCallId),
+      positiveToolCallIds: parsed.positiveToolCallIds.map((id) => Number(id)),
+    },
+  };
 }
 
 function resolvePiAiAgentAdapter(
@@ -120,6 +166,8 @@ function resolveRunRuleHostRuntime(
   }
 
   const { effective } = configLoadResult;
+  const featureFlags = computeFeatureFlagsFromConfig(effective);
+  const contextV2Enabled = isFeatureEnabled(featureFlags, 'rulecode_context_v2');
   const adapterOptions = { workspaceDir, timeoutMs };
   const dreamer = resolvePiAiAgentAdapter(effective, 'dreamer', adapterOptions);
   const philosopher = resolvePiAiAgentAdapter(effective, 'philosopher', adapterOptions);
@@ -135,15 +183,16 @@ function resolveRunRuleHostRuntime(
       agentRuntimeProfiles,
       capability: { enabled: false, disabledReason: readiness.reason },
       capabilityStatus: `code_rule_capability: OFF (${readiness.reason})`,
+      contextV2Enabled,
     };
   }
-  const featureFlags = computeFeatureFlagsFromConfig(effective);
   if (!isFeatureEnabled(featureFlags, 'code_rule_capability')) {
     return {
       agentAdapters: { dreamer: dreamer.adapter, philosopher: philosopher.adapter, scribe: scribe.adapter, evaluator: scribe.adapter },
       agentRuntimeProfiles,
       capability: { enabled: false, disabledReason: 'code_rule_capability feature flag is disabled' },
       capabilityStatus: 'code_rule_capability: OFF (feature flag disabled)',
+      contextV2Enabled,
     };
   }
 
@@ -157,6 +206,7 @@ function resolveRunRuleHostRuntime(
       agentRuntimeProfiles,
       capability: { enabled: false, disabledReason: `artificer agent disabled: ${artificerBinding.reason}` },
       capabilityStatus: `code_rule_capability: OFF (artificer disabled — ${artificerBinding.reason})`,
+      contextV2Enabled,
     };
   }
   if (!evaluatorBinding.ok) {
@@ -165,6 +215,7 @@ function resolveRunRuleHostRuntime(
       agentRuntimeProfiles,
       capability: { enabled: false, disabledReason: `evaluator agent disabled: ${evaluatorBinding.reason}` },
       capabilityStatus: `code_rule_capability: OFF (evaluator disabled — ${evaluatorBinding.reason})`,
+      contextV2Enabled,
     };
   }
 
@@ -177,6 +228,7 @@ function resolveRunRuleHostRuntime(
       agentRuntimeProfiles,
       capability: { enabled: false, disabledReason: `artificer runtime profile is not pi-ai (got '${artificerProfile.type}')` },
       capabilityStatus: `code_rule_capability: OFF (artificer profile type='${artificerProfile.type}', expected pi-ai)`,
+      contextV2Enabled,
     };
   }
 
@@ -187,6 +239,7 @@ function resolveRunRuleHostRuntime(
       agentRuntimeProfiles,
       capability: { enabled: false, disabledReason: `artificer apiKeyEnv '${artificerProfile.apiKeyEnv}' is not set in environment` },
       capabilityStatus: `code_rule_capability: OFF (artificer apiKeyEnv '${artificerProfile.apiKeyEnv}' not set)`,
+      contextV2Enabled,
     };
   }
 
@@ -209,6 +262,7 @@ function resolveRunRuleHostRuntime(
     agentRuntimeProfiles,
     capability: { enabled: true, artificerAdapter },
     capabilityStatus: `code_rule_capability: ON (artificer profile='${artificerBinding.profileId}', evaluator profile='${evaluatorBinding.profileId}')`,
+    contextV2Enabled,
   };
 }
 
@@ -374,6 +428,91 @@ export async function handleRunRuleHost(opts: RunRuleHostOptions): Promise<void>
     return;
   }
 
+  let effectiveCapability = resolvedRuntime.capability;
+  let contextMode: 'v1' | 'v2' = 'v1';
+  let behaviorExamplePack: BehaviorExamplePack | undefined;
+  let behaviorExamplesReason: string | undefined;
+  const behaviorExamplesPath = opts.behaviorExamples
+    ? path.resolve(workspaceDir, opts.behaviorExamples)
+    : undefined;
+
+  if (!resolvedRuntime.contextV2Enabled && behaviorExamplesPath) {
+    const reason = 'behavior_examples_not_allowed: rulecode_context_v2 is disabled';
+    if (opts.json) {
+      process.stdout.write(JSON.stringify({ status: 'failed', reason, nextAction: 'enable rulecode_context_v2 or remove --behavior-examples' }) + '\n');
+    } else {
+      console.error(`Error: ${reason}. Enable rulecode_context_v2 or remove --behavior-examples.`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (resolvedRuntime.contextV2Enabled) {
+    contextMode = 'v2';
+    if (!behaviorExamplesPath) {
+      behaviorExamplesReason = 'behavior_examples_missing';
+    } else {
+      const examplesResult = readOwnerBehaviorExamples(behaviorExamplesPath);
+      if (!examplesResult.ok) {
+        // P1 fix (CodeRabbit PR2 Comment 1): fail fast on parse failure instead
+        // of silently degrading to text_principle_only (rc-9-no-silent-fallback).
+        // examplesResult.reason already carries a stable prefix
+        // (behavior_examples_unreadable: | behavior_examples_invalid:).
+        const { reason } = examplesResult;
+        if (opts.json) {
+          process.stdout.write(JSON.stringify({
+            status: 'failed',
+            reason,
+            nextAction: 'fix the --behavior-examples JSON payload and retry',
+          }) + '\n');
+        } else {
+          console.error(`Error: ${reason}. Fix the --behavior-examples JSON payload and retry.`);
+        }
+        process.exitCode = 1;
+        return;
+      }
+      if (opts.confirm) {
+        // Lazy import: avoids loading `principles-disciple` at module init time.
+        // `pd --version` (and the create-principles-disciple smoke test) loads
+        // this file statically via index.ts. If we used a static import, the
+        // module would fail with MODULE_NOT_FOUND in bundled environments where
+        // `principles-disciple` is not resolvable from pd-cli's node_modules.
+        // The import only executes when `--confirm` is actually used.
+        const { BehaviorExamplePackAssembler, RuleHostEvidenceRegistry } = await import('principles-disciple/rulehost-evidence');
+        try {
+          const assembler = new BehaviorExamplePackAssembler({ workspaceDir, stateDir: path.join(workspaceDir, '.state') });
+          behaviorExamplePack = assembler.assemble({
+            sourcePainId: opts.painId,
+            ownerDesiredOutcome: examplesResult.value.ownerDesiredOutcome,
+            sourceNegativeToolCallId: examplesResult.value.sourceNegativeToolCallId,
+            positiveToolCallIds: examplesResult.value.positiveToolCallIds,
+            projectDir: workspaceDir,
+          });
+        } catch (error) {
+          // P1 fix (CodeRabbit PR2 Comment 1): fail fast on assembly failure
+          // instead of silently degrading to text_principle_only.
+          const reason = `behavior_examples_unreliable: ${error instanceof Error ? error.message : String(error)}`;
+          if (opts.json) {
+            process.stdout.write(JSON.stringify({
+              status: 'failed',
+              reason,
+              nextAction: 'verify pain lineage and tool call IDs reference existing trajectory rows; rerun pd pain record if needed',
+            }) + '\n');
+          } else {
+            console.error(`Error: ${reason}. Verify pain lineage and tool call IDs reference existing trajectory rows; rerun pd pain record if needed.`);
+          }
+          process.exitCode = 1;
+          return;
+        } finally {
+          RuleHostEvidenceRegistry.dispose(workspaceDir);
+        }
+      }
+    }
+    if (behaviorExamplesReason) {
+      effectiveCapability = { enabled: false, disabledReason: `${behaviorExamplesReason}; nextAction: provide reliable Owner-labelled tool call IDs with --behavior-examples` };
+    }
+  }
+
   // ── Dry-run mode: report what would happen, don't run the pipeline ──
   // Default is dry-run (CLI gate rule 4: mutating commands default to dry-run).
   const isDryRun = opts.dryRun || !opts.confirm;
@@ -386,9 +525,15 @@ export async function handleRunRuleHost(opts: RunRuleHostOptions): Promise<void>
         channel,
         readiness,
         readinessStatus: readiness.status,
-        capabilityStatus: resolvedRuntime.capabilityStatus,
+        capabilityStatus: behaviorExamplesReason
+          ? `code_rule_capability: OFF (${behaviorExamplesReason})`
+          : resolvedRuntime.capabilityStatus,
         agentRuntimeProfiles: resolvedRuntime.agentRuntimeProfiles,
-        codeRuleCapability: { enabled: resolvedRuntime.capability.enabled, disabledReason: resolvedRuntime.capability.disabledReason },
+        codeRuleCapability: { enabled: effectiveCapability.enabled, disabledReason: effectiveCapability.disabledReason },
+        contextMode,
+        behaviorExamples: behaviorExamplesPath
+          ? { path: behaviorExamplesPath, status: behaviorExamplesReason ? 'unreliable' : 'provided' }
+          : { status: resolvedRuntime.contextV2Enabled ? 'missing' : 'not_required' },
         nextAction: readiness.status === 'ready'
           ? 'pass --confirm to run the full pipeline'
           : readiness.status === 'text_principle_only'
@@ -396,7 +541,12 @@ export async function handleRunRuleHost(opts: RunRuleHostOptions): Promise<void>
             : 'fix the readiness issues above before running the pipeline',
       }) + '\n');
     } else {
-      process.stdout.write(formatDryRunOutput({ opts, capabilityStatus: resolvedRuntime.capabilityStatus, workspaceDir, readiness }) + '\n');
+      // P2 fix (CodeRabbit PR2 Comment 2): text branch must use the same v2-aware
+      // capabilityStatus source as the JSON branch (behaviorExamplesReason-aware).
+      const effectiveCapabilityStatus = behaviorExamplesReason
+        ? `code_rule_capability: OFF (${behaviorExamplesReason})`
+        : resolvedRuntime.capabilityStatus;
+      process.stdout.write(formatDryRunOutput({ opts, capabilityStatus: effectiveCapabilityStatus, workspaceDir, readiness }) + '\n');
     }
     return;
   }
@@ -409,7 +559,9 @@ export async function handleRunRuleHost(opts: RunRuleHostOptions): Promise<void>
       painId: opts.painId,
       runtimeAdapter: resolvedRuntime.agentAdapters.dreamer,
       agentAdapters: resolvedRuntime.agentAdapters,
-      codeRuleCapability: resolvedRuntime.capability,
+      codeRuleCapability: effectiveCapability,
+      contextMode,
+      behaviorExamplePack,
       channel: channel as RuleHostChannel,
       maxRounds: opts.maxRounds,
       timeoutMs: opts.timeoutMs,
@@ -465,10 +617,11 @@ export function registerRunRuleHostCommand(internalizationCmd: Command): Command
     .option('--channel <channel>', 'Activation channel: code_tool_hook, prompt, defer_archive (default: code_tool_hook)', 'code_tool_hook')
     .option('--max-rounds <n>', 'Max adversarial rounds (PRD cap = 2)', parseInt)
     .option('--timeout-ms <ms>', 'Per-LLM-call timeout in milliseconds (default: 300000)', parseInt)
+    .option('--behavior-examples <json>', 'Owner-labelled negative/positive tool call IDs for RuleContext v2')
     .option('--dry-run', 'Validate inputs + config, report capability status, do NOT run the pipeline (default)')
     .option('--confirm', 'Actually run the pipeline (mutually exclusive with --dry-run)')
     .option('--json', 'Output raw JSON')
     .action(async (opts) => {
-      await handleRunRuleHost({ workspace: opts.workspace, painId: opts.painId, channel: opts.channel, maxRounds: opts.maxRounds, timeoutMs: opts.timeoutMs, dryRun: opts.dryRun, confirm: opts.confirm, json: opts.json });
+      await handleRunRuleHost({ workspace: opts.workspace, painId: opts.painId, channel: opts.channel, maxRounds: opts.maxRounds, timeoutMs: opts.timeoutMs, behaviorExamples: opts.behaviorExamples, dryRun: opts.dryRun, confirm: opts.confirm, json: opts.json });
     });
 }

package/src/commands/runtime-uat.guard.test.ts

@@ -18,6 +18,11 @@ vi.mock('child_process', () => ({
 const { handleRuntimeUat } = await import('./runtime-uat.js');
 const { guardUatWorkspace } = await import('../utils/production-workspace-guard.js');
 
+// ─── Cross-platform production workspace path ─────────────────────────────────
+// Mirrors the default in production-workspace-guard.ts: ~/.openclaw/workspace.
+// Using this instead of hardcoded "D:\..." paths ensures tests work on Linux/macOS CI.
+const PROD_WORKSPACE = path.join(os.homedir(), '.openclaw', 'workspace');
+
 // ─── Test Setup ─────────────────────────────────────────────────────────────
 const capturedStderr: string[] = [];
 const capturedStdout: string[] = [];
@@ -53,23 +58,16 @@ beforeEach(() => {
 
 // ─── Tests ──────────────────────────────────────────────────────────────────
 describe('PRI-334: production workspace refusal', () => {
-  it('refuses D: workspace with exit code 1', async () => {
-    mockExecFileSync.mockClear();
-    await handleRuntimeUat({ workspace: 'D:\\.openclaw\\workspace', count: 1 });
-    expect(capturedExitCode).toBe(1);
-    expect(mockExecFileSync).not.toHaveBeenCalled();
-  });
-
-  it('refuses C: workspace with exit code 1', async () => {
+  it('refuses default production workspace with exit code 1', async () => {
     mockExecFileSync.mockClear();
-    await handleRuntimeUat({ workspace: 'C:\\.openclaw\\workspace', count: 1 });
+    await handleRuntimeUat({ workspace: PROD_WORKSPACE, count: 1 });
     expect(capturedExitCode).toBe(1);
     expect(mockExecFileSync).not.toHaveBeenCalled();
   });
 
-  it('refuses production workspace subdirectory', async () => {
+  it('refuses production workspace subdirectory with exit code 1', async () => {
     mockExecFileSync.mockClear();
-    await handleRuntimeUat({ workspace: 'D:\\.openclaw\\workspace\\sub\\path', count: 1 });
+    await handleRuntimeUat({ workspace: path.join(PROD_WORKSPACE, 'sub', 'path'), count: 1 });
     expect(capturedExitCode).toBe(1);
     expect(mockExecFileSync).not.toHaveBeenCalled();
   });
@@ -82,11 +80,11 @@ describe('PRI-334: allowed paths (guard level)', () => {
   });
 
   it('allows workspace-test sibling (ERR-030)', () => {
-    expect(guardUatWorkspace('D:\\.openclaw\\workspace-test', 'test').refused).toBe(false);
+    expect(guardUatWorkspace(path.join(os.homedir(), '.openclaw', 'workspace-test'), 'test').refused).toBe(false);
   });
 
   it('allows workspace-backup sibling (ERR-030)', () => {
-    expect(guardUatWorkspace('D:\\.openclaw\\workspace-backup', 'test').refused).toBe(false);
+    expect(guardUatWorkspace(path.join(os.homedir(), '.openclaw', 'workspace-backup'), 'test').refused).toBe(false);
   });
 });
 
@@ -94,7 +92,7 @@ describe('PRI-334: JSON output (EP-04)', () => {
   it('outputs single JSON object with reason and nextAction', async () => {
     mockExecFileSync.mockClear();
     capturedStdout.length = 0;
-    await handleRuntimeUat({ workspace: 'D:\\.openclaw\\workspace', count: 1, json: true });
+    await handleRuntimeUat({ workspace: PROD_WORKSPACE, count: 1, json: true });
     expect(capturedExitCode).toBe(1);
     expect(mockExecFileSync).not.toHaveBeenCalled();
 
@@ -115,7 +113,7 @@ describe('PRI-334: escape hatch', () => {
     capturedStderr.length = 0;
     capturedExitCode = null;
 
-    await handleRuntimeUat({ workspace: 'D:\\.openclaw\\workspace', count: 1, allowProductionWorkspaceForUat: true });
+    await handleRuntimeUat({ workspace: PROD_WORKSPACE, count: 1, allowProductionWorkspaceForUat: true });
     const stderrText = capturedStderr.join('\n');
     expect(stderrText).toContain('WARNING');
     expect(stderrText).toContain('--allow-production-workspace-for-uat');
@@ -125,7 +123,7 @@ describe('PRI-334: escape hatch', () => {
 describe('PRI-334: mutation prevention', () => {
   it('does not call execFileSync after guard refusal', async () => {
     mockExecFileSync.mockClear();
-    await handleRuntimeUat({ workspace: 'D:\\.openclaw\\workspace', count: 1 });
+    await handleRuntimeUat({ workspace: PROD_WORKSPACE, count: 1 });
     expect(mockExecFileSync).not.toHaveBeenCalled();
   });
 });

package/src/commands/runtime-uat.ts

@@ -144,11 +144,12 @@ function pd(args: string[], workspace: string, timeoutMs = 300_000): string {
       stdio: ['pipe', 'pipe', 'pipe'],
     });
   } catch (err: unknown) {
-    if (err instanceof Error && 'code' in err && (err as { code: string }).code === 'ENOENT') {
+    if (err instanceof Error && // eslint-disable-next-line no-restricted-syntax -- 'in' required for Error subtype narrowing (err.code access)
+    'code' in err && (err as { code: string }).code === 'ENOENT') {
       throw new Error(`pd CLI not found at ${cliPath} — run: npm run build --workspace=@principles/pd-cli`, { cause: err });
     }
-    if (err && typeof err === 'object' && 'stdout' in err) {
-      return String((err).stdout);
+    if (err && typeof err === 'object' && Object.hasOwn(err, 'stdout')) {
+      return String((err as { stdout: unknown }).stdout);
     }
     throw err;
   }

package/src/config-reader.ts

@@ -13,7 +13,7 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 import { resolveOutputLanguage, DEFAULT_OUTPUT_LANGUAGE } from '@principles/core/runtime-v2';
 import type { ResolvedOutputLanguage } from '@principles/core/runtime-v2';
 

package/src/index.ts

@@ -8,13 +8,13 @@
 
 import { Command } from 'commander';
 import { handlePainRecord } from './commands/pain-record.js';
-import { handlePainRetry } from './commands/pain-retry.js';
+import { registerPainRetryCommand } from './commands/pain-retry.js';
 import { handlePainEvidence } from './commands/pain-evidence.js';
 import { handleSamplesList } from './commands/samples-list.js';
 import { handleSamplesReview } from './commands/samples-review.js';
 import { handleEvolutionTasksList } from './commands/evolution-tasks-list.js';
 import { handleEvolutionTasksShow } from './commands/evolution-tasks-show.js';
-import { handleHealth } from './commands/health.js';
+import { registerHealthCommand } from './commands/health.js';
 import { handleTaskShow, registerTaskListCommand } from './commands/task.js';
 import { handleRunList, handleRunShow } from './commands/run.js';
 import { handleTrajectoryLocate } from './commands/trajectory.js';
@@ -42,11 +42,20 @@ import { handleRuntimePainFlood } from './commands/runtime-pain-flood-simulation
 import { handleRuntimeInternalizationIntegrity } from './commands/runtime-internalization-integrity.js';
 import { handleRuntimeInternalizationIntegrityRepair } from './commands/runtime-internalization-integrity-repair.js';
 import { handleRuntimeInternalizationEnqueueSuccessors } from './commands/runtime-internalization-enqueue-successors.js';
+import { handleRuntimeInternalizationContextTrace } from './commands/runtime-internalization-context-trace.js';
 import { handleRuntimeDiagnosticsExport } from './commands/runtime-diagnostics-export.js';
 import { handleRuntimeRecoverySweep } from './commands/runtime-recovery.js';
 import { handleRuntimeRecoveryFailedTasks } from './commands/runtime-recovery-failed-tasks.js';
-import { handleRuntimeActivationDispatch } from './commands/runtime-activation.js';
-import { handleRuntimeActivationDeactivate, handleRuntimeActivationList, handleRuntimeActivationEdit } from './commands/runtime-activation.js';
+import {
+  handleRuntimeActivationDeactivate,
+  handleRuntimeActivationList,
+  handleRuntimeActivationEdit,
+  registerRuntimeActivationPromoteCommand,
+  registerRuntimeActivationDeactivateCommand,
+  registerRuntimeActivationListCommand,
+  registerRuntimeActivationDispatchCommand,
+  registerRuntimeActivationApproveCommand,
+} from './commands/runtime-activation.js';
 import { handleProvenChannelBaseline } from './commands/proven-channel-baseline.js';
 import { handleDemoStoryA } from './commands/demo-story-a.js';
 import { handleRuntimeFeaturesStatus } from './commands/runtime-features.js';
@@ -54,6 +63,7 @@ import { handleConfigDoctor } from './commands/config-doctor.js';
 import { registerMvpCommands } from './commands/mvp-smoke.js';
 import { registerRulecodeCommand } from './commands/rulecode.js';
 import { registerIntentCommand } from './commands/intent.js';
+import { registerErrorsListCommand } from './commands/errors-list.js';
 
 import { createRequire } from 'module';
 const require = createRequire(import.meta.url);
@@ -85,30 +95,11 @@ painCmd
     await handlePainRecord(opts);
   });
 
-painCmd
-  .command('retry')
-  .description('Retry a failed diagnosis by pain ID')
-  .requiredOption('-p, --pain-id <painId>', 'Pain ID to retry diagnosis for')
-  .option('-w, --workspace <path>', 'Workspace directory')
-  .option('-r, --runtime <kind>', "Runtime kind: 'openclaw-cli', 'test-double', 'pi-ai'")
-  .option('--openclaw-local', 'Use local OpenClaw (mutually exclusive with --openclaw-gateway)')
-  .option('--openclaw-gateway', 'Use gateway OpenClaw (mutually exclusive with --openclaw-local)')
-  .option('-a, --agent <agentId>', 'Agent ID to invoke')
-  .option('--provider <name>', 'LLM provider (e.g., openrouter) — for pi-ai, falls back to policy')
-  .option('--model <id>', 'Model ID (e.g., anthropic/claude-sonnet-4) — for pi-ai, falls back to policy')
-  .option('--apiKeyEnv <name>', 'Env var name for API key — for pi-ai, falls back to policy')
-  .option('--baseUrl <url>', 'Custom base URL — for pi-ai, falls back to policy')
-  .option('--maxRetries <n>', 'Max retry attempts for LLM failures — for pi-ai, falls back to policy', parseInt)
-  .option('--timeoutMs <ms>', 'Timeout in milliseconds — for pi-ai, falls back to policy', parseInt)
-  .option('--force', 'Allow retry of already-succeeded tasks')
-  .option('--json', 'Output raw JSON')
-  .action(async (opts) => {
-    await handlePainRetry(opts);
-  });
+registerPainRetryCommand(painCmd);
 
 painCmd
   .command('evidence')
-  .description('Show recent pain admission/trigger decisions (PEAT-B2)')
+  .description('Show recent TRIGGER_DECISION log entries — pain admission gate decisions only (PEAT-B2)')
   .option('-w, --workspace <path>', 'Workspace directory')
   .option('-l, --limit <number>', 'Max entries to show (default: 20)', parseInt)
   .option('--json', 'Output raw JSON')
@@ -169,14 +160,7 @@ tasksCmd
     await handleEvolutionTasksShow({ id });
   });
 
-program
-  .command('health')
-  .description('Show health diagnostics for all workspaces')
-  .option('-w, --workspace <path>', 'Workspace directory')
-  .option('--json', 'Output raw JSON')
-  .action(async (opts) => {
-    await handleHealth(opts);
-  });
+registerHealthCommand(program);
 
 // ── Runtime v2 task/run commands ──────────────────────────────────────────────鈹€鈹€鈹€鈹€鈹€鈹€
 
@@ -303,7 +287,7 @@ diagnoseCmd
   .description('Execute diagnostician runner for a task')
   .requiredOption('-t, --task-id <taskId>', 'Task ID to execute')
   .option('-w, --workspace <path>', 'Workspace directory')
-  .option('-r, --runtime <kind>', "Runtime kind: 'openclaw-cli', 'test-double', 'pi-ai'")
+  .option('-r, --runtime <kind>', "Runtime kind: 'openclaw-cli', 'test-double', 'pi-ai'. If omitted, resolved from .pd/config.yaml; refuses if no binding (no test-double default).")
   .option('--openclaw-local', 'Use local OpenClaw (mutually exclusive with --openclaw-gateway)')
   .option('--openclaw-gateway', 'Use gateway OpenClaw (mutually exclusive with --openclaw-local)')
   .option('-a, --agent <agentId>', 'Agent ID to invoke')
@@ -334,6 +318,28 @@ runtimeCmd
     await handleRuntimeCanary({ workspace: opts.workspace, json: opts.json });
   });
 
+// pd runtime init — Initialize all PD SQLite databases for a workspace.
+// Lazy import: avoids loading `principles-disciple` at module init time, which
+// would crash `pd --version` in packaged installs where the plugin's transitive
+// deps are not resolvable from pd-cli's node_modules. The import only executes
+// when `pd runtime init` is actually invoked.
+runtimeCmd
+  .command('init')
+  .description('Initialize all PD SQLite databases (state.db, trajectory.db, subagent_workflows.db)')
+  .option('-w, --workspace <path>', 'Workspace directory')
+  .option('--dry-run', 'Show what would be initialized without writing (default)')
+  .option('--confirm', 'Actually initialize the databases (required to write)')
+  .option('--json', 'Output raw JSON')
+  .action(async (opts) => {
+    const { handleRuntimeInit } = await import('./commands/runtime-init.js');
+    await handleRuntimeInit({
+      workspace: opts.workspace,
+      dryRun: opts.dryRun === true,
+      confirm: opts.confirm === true,
+      json: opts.json === true,
+    });
+  });
+
 const synthCmd = runtimeCmd
   .command('synthetic', { hidden: true })
   .description('Synthetic workload baseline commands');
@@ -414,31 +420,15 @@ const activationTopCmd = program
   .command('activation')
   .description('Activation management — list active activations, deactivate (Story A\' Steps 5-6)');
 
-activationTopCmd
-  .command('list')
-  .description('List all activations for a workspace')
-  .option('-w, --workspace <path>', 'Workspace directory')
-  .option('-c, --channel <channel>', 'Filter by channel (prompt|code_tool_hook)')
-  .option('--include-deactivated', 'Include deactivated records in output')
-  .option('--json', 'Output raw JSON')
-  .action(async (opts) => {
-    await handleRuntimeActivationList({
-      workspace: opts.workspace,
-      channel: opts.channel,
-      includeDeactivated: opts.includeDeactivated,
-      json: opts.json,
-    });
-  });
+registerRuntimeActivationListCommand(activationTopCmd);
 
-activationTopCmd
-  .command('deactivate')
-  .description('Deactivate an activation by activation ID')
-  .requiredOption('--activation-id <id>', 'Activation ID to deactivate')
-  .option('-w, --workspace <path>', 'Workspace directory')
-  .option('--json', 'Output raw JSON')
-  .action(async (opts) => {
-    await handleRuntimeActivationDeactivate({ activationId: opts.activationId, workspace: opts.workspace, json: opts.json });
-  });
+registerRuntimeActivationDeactivateCommand(activationTopCmd);
+
+// Bug-M fix: CLI closed loop — approve a pending approval and dispatch its activation.
+// Reuses the same ApprovalQueue + ApprovalCompletionService as the Console model.
+registerRuntimeActivationApproveCommand(activationTopCmd);
+
+registerRuntimeActivationPromoteCommand(activationTopCmd);
 
 const configCmd = program
   .command('config')
@@ -459,6 +449,7 @@ const demoCmd = program
 
 demoCmd
   .command('story-a')
+  .alias('first-principle')
   .description('Run Story A\'s proven-channel demo (PRI-246) — full evidence→proposal→approval→activation→observation chain')
   .option('-w, --workspace <path>', 'Workspace directory (default: temp workspace)')
   .option('--json', 'Output raw JSON')
@@ -541,7 +532,7 @@ runtimeHealthCmd
   });
 
 const internalizationCmd = runtimeCmd
-  .command('internalization', { hidden: true })
+  .command('internalization')
   .description('Internalization Engine operator visibility');
 
 internalizationCmd
@@ -610,29 +601,23 @@ internalizationCmd
     await handleRuntimeInternalizationEnqueueSuccessors({ workspace: opts.workspace, dryRun: opts.dryRun, confirm: opts.confirm, json: opts.json });
   });
 
+// Layer 3 (design §6.7, PR 5): read-only context-trace command.
+internalizationCmd
+  .command('context-trace')
+  .description('Trace the internalization context chain: summaries, three-segment diagnosis, truncations, degradations')
+  .requiredOption('-t, --task <taskId>', 'Task ID to trace')
+  .option('-a, --artifact <artifactId>', 'Specific artifact ID to start from')
+  .option('-w, --workspace <path>', 'Workspace directory')
+  .option('--json', 'Output raw JSON (default)')
+  .action(async (opts) => {
+    await handleRuntimeInternalizationContextTrace({ workspace: opts.workspace, task: opts.task, artifact: opts.artifact, json: opts.json });
+  });
+
 const activationCmd = runtimeCmd
   .command('activation', { hidden: true })
   .description('Activation dispatch operations (hidden — use pd activation for list/deactivate)');
 
-activationCmd
-  .command('dispatch')
-  .description('Dispatch an activation for a rollout-reviewed artifact')
-  .option('-a, --artifact-id <id>', 'PIArtifact ID to activate')
-  .option('-w, --workspace <path>', 'Workspace directory')
-  .option('-c, --channel <channel>', 'Activation channel (prompt|defer_archive)', 'prompt')
-  .option('--dry-run', 'Dry-run mode (default, no writes)')
-  .option('--confirm', 'Confirm and write activation record')
-  .option('--json', 'Output raw JSON')
-  .action(async (opts) => {
-    await handleRuntimeActivationDispatch({
-      workspace: opts.workspace,
-      artifactId: opts.artifactId,
-      channel: opts.channel,
-      dryRun: opts.dryRun,
-      confirm: opts.confirm,
-      json: opts.json,
-    });
-  });
+registerRuntimeActivationDispatchCommand(activationCmd);
 
 // PRI-408 Contract E: Owner-initiated rollback/deactivate of an activation.
 // Idempotent — calling twice on the same ID is safe and returns ok=false with reason.
@@ -977,6 +962,12 @@ registerRulecodeCommand(program);
 
 registerIntentCommand(program);
 
+// ─── Errors List (Task 14: Feedback Pipeline Observability) ────────────────
+// Operator diagnostic: aggregates SQLite failed/needs_human_review tasks +
+// worker-status.json errors array. Read-only.
+
+registerErrorsListCommand(program);
+
 const consoleCmd = program
   .command('console')
   .description('Start the pd-console web UI for principle review (default: fallback launcher)')