@principles/pd-cli 1.128.1 → 1.129.0

package/tests/commands/cli-command-tree.test.ts

@@ -49,9 +49,9 @@ describe('CLI command tree structure', () => {
     expect(output).toContain('UAT');
   });
 
-  it('runtime subcommand list includes uat (pd runtime --help)', () => {
+  it('runtime subcommand list does NOT include uat (PRI-455: hidden from --help)', () => {
     const output = runPdHelp(['runtime', '--help']);
-    expect(output).toMatch(/uat\s/);
+    expect(output).not.toMatch(/uat\s/);
   });
 
   it('pruning subcommand list does NOT include uat (pd runtime pruning --help)', () => {

package/tests/commands/cli-help-snapshot.test.ts

@@ -0,0 +1,135 @@
+/**
+ * PRI-455: CLI help snapshot test — pins the visible command set.
+ *
+ * Asserts that `pd --help` shows only MVP owner-facing commands,
+ * and that operator/debug commands are hidden (de-surfaced, not deleted).
+ *
+ * Hidden commands still work when invoked explicitly — this test only
+ * checks --help visibility, not functional behavior.
+ */
+import { describe, it, expect } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import { getBuiltPdCliPath } from '../helpers/pd-cli-path.js';
+
+function runPdHelp(args: string[]): string {
+  try {
+    return execFileSync('node', [getBuiltPdCliPath(), ...args], {
+      encoding: 'utf8',
+      cwd: process.cwd(),
+    });
+  } catch (err: unknown) {
+    if (err && typeof err === 'object' && Object.hasOwn(err, 'stdout')) {
+      return String(Reflect.get(err, 'stdout'));
+    }
+    throw err;
+  }
+}
+
+describe('PRI-455: pd --help shows only MVP owner commands', () => {
+  const helpOutput = runPdHelp(['--help']);
+
+  // ── Owner-facing commands that MUST be visible ──────────────────────────
+  const OWNER_COMMANDS = [
+    'pain',          // Step 1: Capture
+    'diagnose',      // Step 2: Diagnose
+    'candidate',     // Step 3: Proposal
+    'console',       // Step 4: Review
+    'activation',    // Step 5-6: Activate & Observe (promoted)
+    'trace',         // Step 6: Observe (promoted)
+    'health',        // Global health
+    'config',        // Onboarding
+    'task',          // Async diagnosis progress
+    'runtime',       // runtime features (MVP-Core flag verification)
+  ];
+
+  for (const cmd of OWNER_COMMANDS) {
+    it(`pd --help shows owner command: ${cmd}`, () => {
+      // Anchor to line beginnings (like the hidden-command check) so the
+      // assertion matches the command list entry, not description text.
+      expect(helpOutput).toMatch(new RegExp(`^\\s+${cmd}\\b`, 'm'));
+    });
+  }
+
+  // ── Operator commands that MUST be hidden from --help ───────────────────
+  const HIDDEN_COMMANDS = [
+    'samples',
+    'evolution',
+    'central',    // MVP-Gone, deleted
+    'trajectory',
+    'history',
+    'context',
+    'legacy',
+    'artifact',
+    'demo',
+    'mvp',
+    'quality',
+    'rulecode',
+  ];
+
+  for (const cmd of HIDDEN_COMMANDS) {
+    it(`pd --help does NOT show operator command: ${cmd}`, () => {
+      expect(helpOutput).not.toMatch(new RegExp(`^\\s+${cmd}\\b`, 'm'));
+    });
+  }
+});
+
+describe('PRI-455: pd runtime --help shows only MVP owner subcommands', () => {
+  const runtimeHelp = runPdHelp(['runtime', '--help']);
+
+  // Owner-facing subcommands under runtime
+  it('runtime --help shows features', () => {
+    expect(runtimeHelp).toMatch(/\bfeatures\b/);
+  });
+
+  // Operator subcommands that should be hidden
+  const HIDDEN_RUNTIME_SUBCOMMANDS = [
+    'canary',
+    'synthetic',
+    'uat',
+    'internalization',
+    'recovery',
+    'pruning',
+    'diagnostics',
+    'probe',
+    'flow',
+  ];
+
+  for (const cmd of HIDDEN_RUNTIME_SUBCOMMANDS) {
+    it(`runtime --help does NOT show operator subcommand: ${cmd}`, () => {
+      expect(runtimeHelp).not.toMatch(new RegExp(`^\\s+${cmd}\\b`, 'm'));
+    });
+  }
+});
+
+describe('PRI-455: promoted commands work at top-level', () => {
+  it('pd trace --help shows trace subcommand', () => {
+    const output = runPdHelp(['trace', '--help']);
+    expect(output).toContain('show');
+  });
+
+  it('pd activation --help shows list and deactivate', () => {
+    const output = runPdHelp(['activation', '--help']);
+    expect(output).toContain('list');
+    expect(output).toContain('deactivate');
+  });
+});
+
+describe('PRI-455: hidden commands still function (de-surface, not delete)', () => {
+  it('pd runtime probe --help still works (hidden but callable)', () => {
+    const output = runPdHelp(['runtime', 'probe', '--help']);
+    expect(output).toContain('--workspace');
+    expect(output).toContain('--json');
+  });
+
+  it('pd runtime internalization queue --help still works', () => {
+    const output = runPdHelp(['runtime', 'internalization', 'queue', '--help']);
+    expect(output).toContain('--workspace');
+    expect(output).toContain('--json');
+  });
+
+  it('pd legacy cleanup --help still works (hidden but callable)', () => {
+    const output = runPdHelp(['legacy', 'cleanup', '--help']);
+    expect(output).toContain('--dry-run');
+    expect(output).toContain('--apply');
+  });
+});

package/tests/commands/cli-skill-contract.test.ts

@@ -0,0 +1,121 @@
+/**
+ * PRI-455: SKILL ↔ CLI contract test.
+ *
+ * Parses SKILL.md templates for `pd <command>` references and verifies
+ * that each referenced command path exists in the CLI command tree.
+ *
+ * This prevents SKILL templates from referencing deleted or renamed commands.
+ *
+ * Covers BOTH `en` and `zh` skill directories so bilingual template updates
+ * are validated. Fails explicitly (does not silently skip) when the expected
+ * skills directory is missing — a missing directory is a real contract break.
+ */
+import { describe, it, expect } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { getBuiltPdCliPath } from '../helpers/pd-cli-path.js';
+
+/**
+ * Resolve the skills directory for a given language.
+ * Tests run from packages/pd-cli, so the plugin templates live one level up.
+ */
+function resolveSkillsDir(lang: 'en' | 'zh'): string {
+  return resolve(
+    process.cwd(),
+    '..',
+    'openclaw-plugin',
+    'templates',
+    'langs',
+    lang,
+    'skills',
+  );
+}
+
+/**
+ * Extract `pd <command> [subcommand] ...` patterns from SKILL.md content.
+ * Matches lines like:
+ *   pd pain record --reason ...
+ *   pd runtime probe --json
+ *   pd candidate list --workspace ...
+ * Returns full command paths (e.g. "pain record", "runtime probe").
+ */
+function extractPdCommands(markdown: string): string[] {
+  const commands: string[] = [];
+  // Match `pd <words>` in code blocks and inline code
+  const pdPattern = /`pd\s+([\w-]+(?:\s+[\w-]+)*)/g;
+  let match: RegExpExecArray | null;
+  while ((match = pdPattern.exec(markdown)) !== null) {
+    // Take up to 3 path segments (e.g. "runtime internalization queue")
+    const parts = match[1].split(/\s+/).slice(0, 3);
+    // Filter out flags and options
+    const cleanParts = parts.filter((p) => !p.startsWith('--') && !p.startsWith('<'));
+    if (cleanParts.length > 0) {
+      commands.push(cleanParts.join(' '));
+    }
+  }
+  return [...new Set(commands)];
+}
+
+/**
+ * Check if a command path exists by running `pd <path> --help`.
+ * Returns true if the command is registered (exit code 0 or help output contains "Usage:").
+ */
+function commandExists(commandPath: string): boolean {
+  const args = commandPath.split(' ');
+  try {
+    const output = execFileSync('node', [getBuiltPdCliPath(), ...args, '--help'], {
+      encoding: 'utf8',
+      cwd: process.cwd(),
+      timeout: 10000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return output.includes('Usage:') || output.includes('Options:');
+  } catch {
+    return false;
+  }
+}
+
+// Collect (lang, skill, command) triples across both en and zh.
+// A missing skills directory is a real contract break — fail explicitly.
+const LANGS = ['en', 'zh'] as const;
+const skillCommandPairs: { lang: string; skill: string; command: string }[] = [];
+const missingLangDirs: string[] = [];
+
+for (const lang of LANGS) {
+  const skillsDir = resolveSkillsDir(lang);
+  if (!existsSync(skillsDir)) {
+    missingLangDirs.push(lang);
+    continue;
+  }
+  const skillDirs = readdirSync(skillsDir).filter((dir) =>
+    existsSync(join(skillsDir, dir, 'SKILL.md')),
+  );
+  for (const dir of skillDirs) {
+    const skillPath = join(skillsDir, dir, 'SKILL.md');
+    const content = readFileSync(skillPath, 'utf8');
+    const commands = extractPdCommands(content);
+    for (const cmd of commands) {
+      skillCommandPairs.push({ lang, skill: dir, command: cmd });
+    }
+  }
+}
+
+describe('PRI-455: SKILL ↔ CLI contract', () => {
+  it('both en and zh skills directories exist', () => {
+    // Explicit failure instead of silent skip — a missing directory means
+    // the contract is no longer being validated for that language.
+    expect(missingLangDirs, `missing skills directories: ${missingLangDirs.join(', ')}`).toEqual([]);
+  });
+
+  it('found SKILL files that reference pd commands', () => {
+    expect(skillCommandPairs.length).toBeGreaterThan(0);
+  });
+
+  // Test each SKILL-referenced command exists in the CLI
+  for (const { lang, skill, command } of skillCommandPairs) {
+    it(`[${lang}] SKILL "${skill}" references valid command: pd ${command}`, () => {
+      expect(commandExists(command)).toBe(true);
+    });
+  }
+});

package/tests/commands/run-rulehost-handler.test.ts

@@ -71,6 +71,11 @@ function parseJsonObject(text: string): Record<string, unknown> {
   return parsed;
 }
 
+/** Type guard: narrows `unknown` to `Record<string, unknown>` without `as`. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 function captureStdio(fn: () => Promise<void>): Promise<StdIoState> {
   return new Promise((resolve, reject) => {
     const origExitCode = process.exitCode;
@@ -251,3 +256,275 @@ describe('handleRunRuleHost — dry-run mode output shape (with minimal pd-confi
     }
   });
 });
+
+// ── PRI-461: readiness integration tests ──────────────────────────────────
+//
+// Verifies the handler emits the three readiness statuses (ready /
+// text_principle_only / refused) with the correct exit codes and JSON shape.
+// These tests exercise the full path: config → resolveRuleHostReadiness →
+// handler output, ensuring the readiness gate is wired into production code
+// (EP-02) and that refused statuses fail loud with reason + nextAction (EP-03).
+
+function writeFullReadyConfig(workspaceDir: string): void {
+  const configDir = path.join(workspaceDir, '.pd');
+  fs.mkdirSync(configDir, { recursive: true });
+  const cfg = {
+    version: 1,
+    features: {
+      prompt: { category: 'core', enabled: true },
+      code_tool_hook: { category: 'core', enabled: true },
+      defer_archive: { category: 'core', enabled: true },
+      code_rule_capability: { category: 'core', enabled: true },
+    },
+    workspace: { default: workspaceDir },
+    runtimeProfiles: {
+      'pi-ai.default': { type: 'pi-ai', provider: 'anthropic', model: 'claude-sonnet', apiKeyEnv: 'ANTHROPIC_API_KEY' },
+    },
+    internalAgents: {
+      defaultRuntime: 'pi-ai.default',
+      agents: {
+        dreamer: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        philosopher: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        scribe: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        artificer: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        evaluator: { enabled: true, runtimeProfile: 'pi-ai.default' },
+      },
+    },
+  };
+  fs.writeFileSync(path.join(configDir, 'config.yaml'), yaml.dump(cfg), 'utf8');
+}
+
+function writeTextPrincipleOnlyConfig(workspaceDir: string): void {
+  // code_rule_capability explicitly OFF → text_principle_only
+  const configDir = path.join(workspaceDir, '.pd');
+  fs.mkdirSync(configDir, { recursive: true });
+  const cfg = {
+    version: 1,
+    features: {
+      prompt: { category: 'core', enabled: true },
+      code_tool_hook: { category: 'core', enabled: true },
+      defer_archive: { category: 'core', enabled: true },
+      code_rule_capability: { category: 'core', enabled: false },
+    },
+    workspace: { default: workspaceDir },
+    runtimeProfiles: {
+      'pi-ai.default': { type: 'pi-ai', provider: 'anthropic', model: 'claude-sonnet', apiKeyEnv: 'ANTHROPIC_API_KEY' },
+    },
+    internalAgents: {
+      defaultRuntime: 'pi-ai.default',
+      agents: {
+        dreamer: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        philosopher: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        scribe: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        artificer: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        evaluator: { enabled: true, runtimeProfile: 'pi-ai.default' },
+      },
+    },
+  };
+  fs.writeFileSync(path.join(configDir, 'config.yaml'), yaml.dump(cfg), 'utf8');
+}
+
+function writeEvaluatorDisabledConfig(workspaceDir: string): void {
+  const configDir = path.join(workspaceDir, '.pd');
+  fs.mkdirSync(configDir, { recursive: true });
+  const cfg = {
+    version: 1,
+    features: {
+      prompt: { category: 'core', enabled: true },
+      code_tool_hook: { category: 'core', enabled: true },
+      defer_archive: { category: 'core', enabled: true },
+      code_rule_capability: { category: 'core', enabled: true },
+    },
+    workspace: { default: workspaceDir },
+    runtimeProfiles: {
+      'pi-ai.default': { type: 'pi-ai', provider: 'anthropic', model: 'claude-sonnet', apiKeyEnv: 'ANTHROPIC_API_KEY' },
+    },
+    internalAgents: {
+      defaultRuntime: 'pi-ai.default',
+      agents: {
+        dreamer: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        philosopher: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        scribe: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        artificer: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        evaluator: { enabled: false, runtimeProfile: 'pi-ai.default' },
+      },
+    },
+  };
+  fs.writeFileSync(path.join(configDir, 'config.yaml'), yaml.dump(cfg), 'utf8');
+}
+
+function writeRefusedConfig(workspaceDir: string): void {
+  // dreamer disabled → required agent missing → refused
+  const configDir = path.join(workspaceDir, '.pd');
+  fs.mkdirSync(configDir, { recursive: true });
+  const cfg = {
+    version: 1,
+    features: {
+      prompt: { category: 'core', enabled: true },
+      code_tool_hook: { category: 'core', enabled: true },
+      defer_archive: { category: 'core', enabled: true },
+      code_rule_capability: { category: 'core', enabled: true },
+    },
+    workspace: { default: workspaceDir },
+    runtimeProfiles: {
+      'pi-ai.default': { type: 'pi-ai', provider: 'anthropic', model: 'claude-sonnet', apiKeyEnv: 'ANTHROPIC_API_KEY' },
+    },
+    internalAgents: {
+      defaultRuntime: 'pi-ai.default',
+      agents: {
+        dreamer: { enabled: false, runtimeProfile: 'pi-ai.default' },
+        philosopher: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        scribe: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        artificer: { enabled: true, runtimeProfile: 'pi-ai.default' },
+        evaluator: { enabled: true, runtimeProfile: 'pi-ai.default' },
+      },
+    },
+  };
+  fs.writeFileSync(path.join(configDir, 'config.yaml'), yaml.dump(cfg), 'utf8');
+}
+
+describe('handleRunRuleHost — PRI-461 readiness integration', () => {
+  let workspaceDir: string;
+  let savedEnv: NodeJS.ProcessEnv;
+
+  beforeEach(() => {
+    workspaceDir = mkTmpDir();
+    savedEnv = { ...process.env };
+    process.env.ANTHROPIC_API_KEY = 'sk-ant-test-key';
+  });
+
+  afterEach(() => {
+    process.env = savedEnv;
+    try { fs.rmSync(workspaceDir, { recursive: true, force: true }); } catch { /* ignore */ }
+  });
+
+  // ── ready ───────────────────────────────────────────────────────────────
+
+  it('emits readiness=ready in --json dry-run when all agents and code-rule capability are ON', async () => {
+    writeFullReadyConfig(workspaceDir);
+    const { stdout, exitCode } = await captureStdio(() =>
+      handleRunRuleHost({ painId: 'pain-1', dryRun: true, json: true, workspace: workspaceDir }),
+    );
+    const payload = parseJsonObject(stdout.trim());
+    expect(payload.status).toBe('dry_run');
+    expect(payload.readinessStatus).toBe('ready');
+    const readiness = payload.readiness;
+    expect(isRecord(readiness)).toBe(true);
+    if (!isRecord(readiness)) {
+      throw new Error('readiness is not a record');
+    }
+    expect(readiness.status).toBe('ready');
+    expect(exitCode).toBeUndefined();
+  });
+
+  it('emits readiness=ready in plain-text dry-run output', async () => {
+    writeFullReadyConfig(workspaceDir);
+    const { stdout } = await captureStdio(() =>
+      handleRunRuleHost({ painId: 'pain-1', dryRun: true, workspace: workspaceDir }),
+    );
+    expect(stdout).toMatch(/readiness:\s*READY/i);
+  });
+
+  // ── text_principle_only ─────────────────────────────────────────────────
+
+  it('emits readiness=text_principle_only in --json dry-run when code_rule_capability is OFF', async () => {
+    writeTextPrincipleOnlyConfig(workspaceDir);
+    const { stdout, exitCode } = await captureStdio(() =>
+      handleRunRuleHost({ painId: 'pain-1', dryRun: true, json: true, workspace: workspaceDir }),
+    );
+    const payload = parseJsonObject(stdout.trim());
+    expect(payload.status).toBe('dry_run');
+    expect(payload.readinessStatus).toBe('text_principle_only');
+    const readiness = payload.readiness;
+    expect(isRecord(readiness)).toBe(true);
+    if (!isRecord(readiness)) {
+      throw new Error('readiness is not a record');
+    }
+    expect(readiness.status).toBe('text_principle_only');
+    expect(typeof readiness.reason).toBe('string');
+    expect(typeof readiness.nextAction).toBe('string');
+    expect(exitCode).toBeUndefined();
+  });
+
+  it('does not reclassify evaluator-disabled text_principle_only as runtime resolution failure', async () => {
+    writeEvaluatorDisabledConfig(workspaceDir);
+    const { stdout, exitCode } = await captureStdio(() =>
+      handleRunRuleHost({ painId: 'pain-1', dryRun: true, json: true, workspace: workspaceDir }),
+    );
+    const payload = parseJsonObject(stdout.trim());
+    expect(payload.status).toBe('dry_run');
+    expect(payload.readinessStatus).toBe('text_principle_only');
+    const readiness = payload.readiness;
+    expect(isRecord(readiness)).toBe(true);
+    if (!isRecord(readiness)) {
+      throw new Error('readiness is not a record');
+    }
+    expect(readiness.status).toBe('text_principle_only');
+    expect(String(readiness.reason)).toContain('evaluator');
+    expect(String(payload.capabilityStatus)).toContain('evaluator');
+    expect(exitCode).toBeUndefined();
+  });
+
+  it('emits readiness=text_principle_only in plain-text dry-run output', async () => {
+    writeTextPrincipleOnlyConfig(workspaceDir);
+    const { stdout } = await captureStdio(() =>
+      handleRunRuleHost({ painId: 'pain-1', dryRun: true, workspace: workspaceDir }),
+    );
+    expect(stdout).toMatch(/readiness:\s*TEXT_PRINCIPLE_ONLY/i);
+  });
+
+  // ── refused ─────────────────────────────────────────────────────────────
+
+  it('exits with code=1 and emits status=refused in --json when dreamer is disabled', async () => {
+    writeRefusedConfig(workspaceDir);
+    const { stdout, exitCode } = await captureStdio(() =>
+      handleRunRuleHost({ painId: 'pain-1', dryRun: true, json: true, workspace: workspaceDir }),
+    );
+    const payload = parseJsonObject(stdout.trim());
+    expect(payload.status).toBe('refused');
+    expect(typeof payload.reason).toBe('string');
+    expect(typeof payload.nextAction).toBe('string');
+    expect(exitCode).toBe(1);
+  });
+
+  it('exits with code=1 and emits REFUSED in plain-text when dreamer is disabled', async () => {
+    writeRefusedConfig(workspaceDir);
+    const { stderr, exitCode } = await captureStdio(() =>
+      handleRunRuleHost({ painId: 'pain-1', dryRun: true, workspace: workspaceDir }),
+    );
+    expect(stderr).toMatch(/REFUSED/i);
+    expect(stderr).toMatch(/dreamer/i);
+    expect(exitCode).toBe(1);
+  });
+
+  it('refused status includes the full readiness object in --json output', async () => {
+    writeRefusedConfig(workspaceDir);
+    const { stdout } = await captureStdio(() =>
+      handleRunRuleHost({ painId: 'pain-1', dryRun: true, json: true, workspace: workspaceDir }),
+    );
+    const payload = parseJsonObject(stdout.trim());
+    expect(payload.readiness).toBeDefined();
+    const readiness = payload.readiness;
+    expect(isRecord(readiness)).toBe(true);
+    if (!isRecord(readiness)) {
+      throw new Error('readiness is not a record');
+    }
+    expect(readiness.status).toBe('refused');
+    expect(readiness.agentStatuses).toBeDefined();
+  });
+
+  it('refused status does NOT attempt pipeline execution or adapter construction', async () => {
+    // If the handler tried to construct adapters with a disabled dreamer,
+    // resolveRunRuleHostRuntime would throw. The readiness gate must prevent
+    // that by exiting before resolveRunRuleHostRuntime is called.
+    writeRefusedConfig(workspaceDir);
+    const { stdout, exitCode } = await captureStdio(() =>
+      handleRunRuleHost({ painId: 'pain-1', dryRun: true, json: true, workspace: workspaceDir }),
+    );
+    const payload = parseJsonObject(stdout.trim());
+    // Must be 'refused', NOT 'failed' with 'agent_runtime_resolution_failed'
+    expect(payload.status).toBe('refused');
+    expect(payload.reason).not.toMatch(/agent_runtime_resolution_failed/);
+    expect(exitCode).toBe(1);
+  });
+});

package/tests/commands/runtime-internalization.test.ts

@@ -46,8 +46,8 @@ describe('CLI command tree: pd runtime internalization', () => {
     expect(output).toContain('--json');
   });
 
-  it('runtime subcommand list includes internalization', () => {
+  it('runtime subcommand list does NOT include internalization (PRI-455: hidden from --help)', () => {
     const output = runPdHelp(['runtime', '--help']);
-    expect(output).toMatch(/internalization\s/);
+    expect(output).not.toMatch(/internalization\s/);
   });
 });