@principles/pd-cli 1.128.1 → 1.129.0

package/src/commands/mvp-smoke.ts

@@ -144,7 +144,7 @@ export async function handleMvpSmoke(opts: MvpSmokeOptions): Promise<void> {
  */
 export function registerMvpCommands(program: Command): Command {
   const mvpCmd = program
-    .command('mvp')
+    .command('mvp', { hidden: true })
     .description('MVP readiness commands');
 
   withWorkspaceAndJson(

package/src/commands/rulecode.ts

@@ -381,7 +381,7 @@ export async function handleRulecodeReplay(opts: ReplayOptions): Promise<void> {
  */
 export function registerRulecodeCommand(parentCmd: Command): Command {
   const rulecodeCmd = parentCmd
-    .command('rulecode')
+    .command('rulecode', { hidden: true })
     .description('RuleCode dialect spec, static validation, and sandbox replay (read-only)');
 
   // spec — no code input needed

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

@@ -38,6 +38,8 @@ import {
 } from '@principles/core/runtime-v2';
 import type { EffectivePdConfig, InternalAgentName, PDRuntimeAdapter } 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';
 
 export interface RunRuleHostOptions {
   workspace?: string;
@@ -109,6 +111,7 @@ function resolvePiAiAgentAdapter(
 function resolveRunRuleHostRuntime(
   workspaceDir: string,
   timeoutMs: number | undefined,
+  readiness: RuleHostReadinessResult,
 ): ResolvedRunRuleHostRuntime {
   const { configLoadResult } = resolveRuntimeFromPdConfig(workspaceDir);
 
@@ -126,6 +129,14 @@ function resolveRunRuleHostRuntime(
     philosopher: philosopher.profileId,
     scribe: scribe.profileId,
   };
+  if (readiness.status === 'text_principle_only') {
+    return {
+      agentAdapters: { dreamer: dreamer.adapter, philosopher: philosopher.adapter, scribe: scribe.adapter, evaluator: scribe.adapter },
+      agentRuntimeProfiles,
+      capability: { enabled: false, disabledReason: readiness.reason },
+      capabilityStatus: `code_rule_capability: OFF (${readiness.reason})`,
+    };
+  }
   const featureFlags = computeFeatureFlagsFromConfig(effective);
   if (!isFeatureEnabled(featureFlags, 'code_rule_capability')) {
     return {
@@ -234,16 +245,35 @@ function formatTextOutput(result: RuleHostPipelineResult): string {
   return lines.join('\n');
 }
 
-function formatDryRunOutput(opts: RunRuleHostOptions, capabilityStatus: string, workspaceDir: string): string {
+interface DryRunFormatInput {
+  readonly opts: RunRuleHostOptions;
+  readonly capabilityStatus: string;
+  readonly workspaceDir: string;
+  readonly readiness: RuleHostReadinessResult;
+}
+
+function formatDryRunOutput(input: DryRunFormatInput): string {
+  const { opts, capabilityStatus, workspaceDir, readiness } = input;
   const lines: string[] = [];
   lines.push('RuleHost Pipeline (PRI-429) — DRY RUN');
   lines.push(`pain: ${opts.painId}`);
   lines.push(`workspace: ${workspaceDir}`);
   lines.push(`channel: ${opts.channel ?? 'code_tool_hook'}`);
+  lines.push(`readiness: ${readiness.status.toUpperCase()}`);
+  if (readiness.status !== 'ready') {
+    lines.push(`  reason: ${readiness.reason}`);
+    lines.push(`  nextAction: ${readiness.nextAction}`);
+  }
   lines.push(capabilityStatus);
   lines.push('');
   lines.push('No tasks created, no LLM calls made, no artifacts written.');
-  lines.push('Next: pass --confirm to actually run the pipeline.');
+  if (readiness.status === 'ready') {
+    lines.push('Next: pass --confirm to actually run the pipeline.');
+  } else if (readiness.status === 'text_principle_only') {
+    lines.push('Next: pass --confirm to run in text-principle-only mode, or fix the issues above to enable full pipeline.');
+  } else {
+    lines.push('Next: fix the readiness issues above before running the pipeline.');
+  }
   return lines.join('\n');
 }
 
@@ -303,14 +333,40 @@ export async function handleRunRuleHost(opts: RunRuleHostOptions): Promise<void>
 
   const workspaceDir = resolveWorkspace(opts);
 
+  // ── Readiness check (PRI-461) ──
+  // Check all preconditions BEFORE constructing adapters. This produces a
+  // structured ready/text_principle_only/refused status instead of an opaque
+  // agent_runtime_resolution_failed error.
+  const readiness = resolveRuleHostReadiness(workspaceDir);
+
+  // If refused, emit structured error and exit (CLI gate rule 2 + rule 5).
+  // Refused means the pipeline cannot run at all — do NOT attempt adapter
+  // construction or pipeline execution.
+  if (readiness.status === 'refused') {
+    if (opts.json) {
+      process.stdout.write(JSON.stringify({
+        status: 'refused',
+        reason: readiness.reason,
+        nextAction: readiness.nextAction,
+        readiness,
+      }) + '\n');
+    } else {
+      console.error(`RuleHost readiness: REFUSED`);
+      console.error(`  reason: ${readiness.reason}`);
+      console.error(`  nextAction: ${readiness.nextAction}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
   // ── Resolve each executed agent from canonical config ──
   let resolvedRuntime: ResolvedRunRuleHostRuntime;
   try {
-    resolvedRuntime = resolveRunRuleHostRuntime(workspaceDir, opts.timeoutMs);
+    resolvedRuntime = resolveRunRuleHostRuntime(workspaceDir, opts.timeoutMs, readiness);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     if (opts.json) {
-      process.stdout.write(JSON.stringify({ status: 'failed', reason: 'agent_runtime_resolution_failed', message, nextAction: 'check internalAgents and runtimeProfiles in .pd/config.yaml; run pd config doctor' }) + '\n');
+      process.stdout.write(JSON.stringify({ status: 'failed', reason: 'agent_runtime_resolution_failed', message, nextAction: 'check internalAgents and runtimeProfiles in .pd/config.yaml; run pd config doctor', readiness }) + '\n');
     } else {
       console.error(`Error: ${message}`);
     }
@@ -328,13 +384,19 @@ export async function handleRunRuleHost(opts: RunRuleHostOptions): Promise<void>
         painId: opts.painId,
         workspace: workspaceDir,
         channel,
+        readiness,
+        readinessStatus: readiness.status,
         capabilityStatus: resolvedRuntime.capabilityStatus,
         agentRuntimeProfiles: resolvedRuntime.agentRuntimeProfiles,
         codeRuleCapability: { enabled: resolvedRuntime.capability.enabled, disabledReason: resolvedRuntime.capability.disabledReason },
-        nextAction: 'pass --confirm to actually run the pipeline',
+        nextAction: readiness.status === 'ready'
+          ? 'pass --confirm to run the full pipeline'
+          : readiness.status === 'text_principle_only'
+            ? 'pass --confirm to run in text-principle-only mode (code-rule capability OFF), or fix the issues above to enable full pipeline'
+            : 'fix the readiness issues above before running the pipeline',
       }) + '\n');
     } else {
-      process.stdout.write(formatDryRunOutput(opts, resolvedRuntime.capabilityStatus, workspaceDir) + '\n');
+      process.stdout.write(formatDryRunOutput({ opts, capabilityStatus: resolvedRuntime.capabilityStatus, workspaceDir, readiness }) + '\n');
     }
     return;
   }

package/src/commands/runtime.ts

@@ -453,7 +453,7 @@ export async function handleRuntimeProbe(opts: RuntimeProbeOptions): Promise<voi
  */
 export function registerRuntimeProbeCommand(runtimeCmd: Command): Command {
   return runtimeCmd
-    .command('probe')
+    .command('probe', { hidden: true })
     .description('Probe runtime health and capabilities (HG-01 HARD GATE)')
     .requiredOption('-r, --runtime <kind>', "Runtime kind: 'openclaw-cli', 'pi-ai', or 'config'")
     .option('--openclaw-local', 'Use local OpenClaw (mutually exclusive with --openclaw-gateway)')

package/src/index.ts

@@ -15,7 +15,6 @@ 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 { handleCentralSync } from './commands/central-sync.js';
 import { handleTaskShow, registerTaskListCommand } from './commands/task.js';
 import { handleRunList, handleRunShow } from './commands/run.js';
 import { handleTrajectoryLocate } from './commands/trajectory.js';
@@ -117,7 +116,7 @@ painCmd
   });
 
 const samplesCmd = program
-  .command('samples')
+  .command('samples', { hidden: true })
   .description('Correction sample management');
 
 samplesCmd
@@ -143,7 +142,7 @@ samplesCmd
   });
 
 const evolutionCmd = program
-  .command('evolution')
+  .command('evolution', { hidden: true })
   .description('Evolution task management');
 
 const tasksCmd = evolutionCmd
@@ -178,17 +177,6 @@ program
     await handleHealth(opts);
   });
 
-const centralCmd = program
-  .command('central')
-  .description('Central server management');
-
-centralCmd
-  .command('sync')
-  .description('Trigger a sync cycle and report results')
-  .action(async () => {
-    await handleCentralSync();
-  });
-
 // ── Runtime v2 task/run commands ──────────────────────────────────────────────鈹€鈹€鈹€鈹€鈹€鈹€
 
 const rtTaskCmd = program
@@ -207,7 +195,7 @@ rtTaskCmd
   });
 
 const rtRunCmd = program
-  .command('run')
+  .command('run', { hidden: true })
   .description('Runtime v2 run inspection');
 
 rtRunCmd
@@ -227,7 +215,7 @@ rtRunCmd
 // ── Runtime v2 trajectory/history/context commands ────────────────────────────鈹€鈹€
 
 const trajectoryCmd = program
-  .command('trajectory')
+  .command('trajectory', { hidden: true })
   .description('Runtime v2 trajectory location');
 
 trajectoryCmd
@@ -244,7 +232,7 @@ trajectoryCmd
   });
 
 const historyCmd = program
-  .command('history')
+  .command('history', { hidden: true })
   .description('Runtime v2 history query');
 
 historyCmd
@@ -261,7 +249,7 @@ historyCmd
   });
 
 const contextCmd = program
-  .command('context')
+  .command('context', { hidden: true })
   .description('Runtime v2 context assembly');
 
 contextCmd
@@ -276,7 +264,7 @@ contextCmd
 // ── Legacy import command ──────────────────────────────────────────────────────鈹€鈹€鈹€鈹€鈹€鈹€鈹€
 
 const legacyCmd = program
-  .command('legacy')
+  .command('legacy', { hidden: true })
   .description('Legacy data management (import and cleanup)');
 
 const importCmd = legacyCmd.command('import');
@@ -337,7 +325,7 @@ const runtimeCmd = program
   .description('Runtime inspection and health checks');
 
 runtimeCmd
-  .command('canary')
+  .command('canary', { hidden: true })
   .description('One-shot control plane health canary')
   .option('-w, --workspace <path>', 'Workspace directory')
   .option('--json', 'Output raw JSON')
@@ -346,7 +334,7 @@ runtimeCmd
   });
 
 const synthCmd = runtimeCmd
-  .command('synthetic')
+  .command('synthetic', { hidden: true })
   .description('Synthetic workload baseline commands');
 
 synthCmd
@@ -402,6 +390,55 @@ runtimeCmd
     });
   });
 
+// ── PRI-455: Promoted owner commands (trace + activation) ────────────────────
+// These are promoted from runtime subcommands to top-level for discoverability.
+// The old paths (pd runtime trace show, pd runtime activation list) remain as
+// hidden aliases — they still work but are not shown in --help.
+
+const traceTopCmd = program
+  .command('trace')
+  .description('Trace full pain-to-ledger chain (Story A\' Step 6: Observe)');
+
+traceTopCmd
+  .command('show')
+  .description('Show full trace for a pain ID')
+  .requiredOption('--pain-id <id>', 'Pain ID to trace')
+  .option('-w, --workspace <path>', 'Workspace directory')
+  .option('--json', 'Output raw JSON')
+  .action(async (opts) => {
+    await handleTraceShow({ painId: opts.painId, workspace: opts.workspace, json: opts.json });
+  });
+
+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,
+    });
+  });
+
+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 });
+  });
+
 const configCmd = program
   .command('config')
   .description('PD configuration discovery and diagnosis');
@@ -416,7 +453,7 @@ configCmd
   });
 
 const demoCmd = program
-  .command('demo')
+  .command('demo', { hidden: true })
   .description('Demo scenarios for MVP validation');
 
 demoCmd
@@ -436,7 +473,7 @@ demoCmd
 registerRuntimeProbeCommand(runtimeCmd);
 
 const flowCmd = runtimeCmd
-  .command('flow')
+  .command('flow', { hidden: true })
   .description('Workflow funnel inspection');
 
 flowCmd
@@ -449,8 +486,8 @@ flowCmd
   });
 
 const traceCmd = runtimeCmd
-  .command('trace')
-  .description('Trace full pain-to-ledger chain');
+  .command('trace', { hidden: true })
+  .description('Trace full pain-to-ledger chain (hidden alias — use pd trace show)');
 
 traceCmd
   .command('show')
@@ -463,7 +500,7 @@ traceCmd
   });
 
 runtimeCmd
-  .command('uat')
+  .command('uat', { hidden: true })
   .description('Runtime V2 chain UAT baseline runner')
   .option('-w, --workspace <path>', 'Workspace directory')
   .option('--count <n>', 'Number of iterations (default: 5, max: 50)', parseInt)
@@ -481,7 +518,7 @@ runtimeCmd
   });
 
 const runtimeHealthCmd = runtimeCmd
-  .command('health')
+  .command('health', { hidden: true })
   .description('Runtime V2 health inspection');
 
 runtimeHealthCmd
@@ -503,7 +540,7 @@ runtimeHealthCmd
   });
 
 const internalizationCmd = runtimeCmd
-  .command('internalization')
+  .command('internalization', { hidden: true })
   .description('Internalization Engine operator visibility');
 
 internalizationCmd
@@ -573,8 +610,8 @@ internalizationCmd
   });
 
 const activationCmd = runtimeCmd
-  .command('activation')
-  .description('Activation dispatch operations');
+  .command('activation', { hidden: true })
+  .description('Activation dispatch operations (hidden — use pd activation for list/deactivate)');
 
 activationCmd
   .command('dispatch')
@@ -652,11 +689,11 @@ activationCmd
   });
 
 const diagnosticsCmd = runtimeCmd
-  .command('diagnostics')
+  .command('diagnostics', { hidden: true })
   .description('Control plane diagnostic bundle operations');
 
 const recoveryCmd = runtimeCmd
-  .command('recovery')
+  .command('recovery', { hidden: true })
   .description('Runtime V2 lease recovery operations');
 
 recoveryCmd
@@ -699,7 +736,7 @@ diagnosticsCmd
   });
 
 const pruningCmd = runtimeCmd
-  .command('pruning')
+  .command('pruning', { hidden: true })
   .description('Non-destructive pruning metrics and health signals');
 
 pruningCmd
@@ -882,7 +919,7 @@ candidateInternalizationCmd
 // ── Artifact inspection commands ──────────────────────────────────────────────
 
 const artifactCmd = program
-  .command('artifact')
+  .command('artifact', { hidden: true })
   .description('Artifact registry inspection');
 
 artifactCmd
@@ -936,7 +973,7 @@ registerRulecodeCommand(program);
 
 const consoleCmd = program
   .command('console')
-  .description('Start the pd-console web UI for principle review (default: legacy launcher)')
+  .description('Start the pd-console web UI for principle review (default: fallback launcher)')
   .passThroughOptions()
   .option('-w, --workspace <path>', 'Workspace directory')
   .option('-p, --port <port>', 'Port to listen on', '3100')
@@ -998,7 +1035,7 @@ consoleCmd.action(async (opts) => {
 // ─── Quality Scorecard (PRI-361) ──────────────────────────────────
 
 const qualityCmd = program
-  .command('quality')
+  .command('quality', { hidden: true })
   .description('Quality scoring and evaluation');
 
 qualityCmd