@principles/pd-cli 1.142.2 → 1.142.4

package/src/commands/runtime-activation.ts

@@ -23,7 +23,9 @@ import {
   SqliteActivationSafetyStore,
   collectOpenClawPromotionChecks,
   summarizeRuleCodeShadowEvents,
+  buildPromotionEvidenceSnapshot,
 } from '@principles/core/runtime-v2';
+import { resolveOwnerIdentity, defaultOwnerIdentityHomeDir } from '@principles/core/runtime-v2';
 import type {
   ActivationDecision,
   PIArtifactSnapshot,
@@ -53,11 +55,65 @@ function unavailableShadowSummary(): PromotionEvidenceSnapshot['shadowSummary']
   };
 }
 
-function readShadowSummary(workspaceDir: string, activationId: string): PromotionEvidenceSnapshot['shadowSummary'] {
-  const logsDir = path.join(workspaceDir, '.pd', 'logs'); if (!fs.existsSync(logsDir)) return unavailableShadowSummary();
+/**
+ * PRI-577: RuleCode event telemetry candidate directories, in priority order.
+ *
+ * Runtime V2 convention is `.pd/logs`, but the v1 EventLog writer
+ * (openclaw-plugin `src/core/event-log.ts`) still emits `events_*.jsonl` under
+ * `.state/logs`. No production code ever created `.pd/logs`, so scanning only
+ * that path made every shadow metric report "unavailable" while 2500+ real
+ * evaluations sat unread in `.state/logs`. Readers scan both candidates until
+ * the writer migrates (ERR-031: both readers derive from this same list).
+ */
+export const RULECODE_EVENT_LOG_CANDIDATE_DIRS: readonly string[] = ['.pd/logs', '.state/logs'];
+
+export interface CollectedRuleCodeEventEntries {
+  entries: unknown[];
+  /** Number of candidate directories that actually exist on disk. */
+  sourceDirsFound: number;
+}
+
+/**
+ * Collect rulehost telemetry entries from all candidate log directories.
+ * Malformed lines are excluded individually. A directory counts as a source
+ * only after it can be enumerated, so an unreadable path cannot be mistaken
+ * for a healthy channel with zero events (ERR-002).
+ *
+ * Exact lines copied between candidate directories are deduplicated by
+ * priority. Different events in same-named daily files are retained.
+ */
+export function collectRuleCodeEventEntries(workspaceDir: string): CollectedRuleCodeEventEntries {
   const entries: unknown[] = [];
-  try { for (const file of fs.readdirSync(logsDir).filter(name => /^events_.*\.jsonl$/.test(name)).sort().slice(-7)) for (const line of fs.readFileSync(path.join(logsDir, file), 'utf8').split('\n').filter(Boolean)) { try { entries.push(JSON.parse(line) as unknown); } catch { /* exclude malformed telemetry */ } } }
-  catch { return unavailableShadowSummary(); }
+  let sourceDirsFound = 0;
+  const higherPriorityLines = new Set<string>();
+  for (const candidate of RULECODE_EVENT_LOG_CANDIDATE_DIRS) {
+    const logsDir = path.join(workspaceDir, ...candidate.split('/'));
+    if (!fs.existsSync(logsDir)) continue;
+    try {
+      const files = fs.readdirSync(logsDir)
+        .filter(name => /^events_.*\.jsonl$/.test(name))
+        .sort()
+        .slice(-7);
+      sourceDirsFound += 1;
+      const currentSourceLines: string[] = [];
+      for (const file of files) {
+        const lines = fs.readFileSync(path.join(logsDir, file), 'utf8').split('\n').filter(Boolean);
+        for (const line of lines) {
+          currentSourceLines.push(line);
+          if (higherPriorityLines.has(line)) continue;
+          try { entries.push(JSON.parse(line) as unknown); } catch { /* exclude malformed telemetry */ }
+        }
+      }
+      for (const line of currentSourceLines) higherPriorityLines.add(line);
+    } catch { /* unreadable directory contributes no entries */ }
+  }
+  return { entries, sourceDirsFound };
+}
+
+/** Exported for PRI-577 regression tests and reuse by promote evidence assembly. */
+export function readShadowSummaryForActivation(workspaceDir: string, activationId: string): PromotionEvidenceSnapshot['shadowSummary'] {
+  const { entries, sourceDirsFound } = collectRuleCodeEventEntries(workspaceDir);
+  if (sourceDirsFound === 0) return unavailableShadowSummary();
   return summarizeRuleCodeShadowEvents(entries, activationId);
 }
 
@@ -445,8 +501,9 @@ export async function handleRuntimeActivationPromote(opts: ActivationPromoteOpti
   try {
     const workspaceDir = opts.workspace ? path.resolve(opts.workspace) : resolveWorkspaceDir();
     const flags = computeFlagsFromLoadResult(loadPdConfig(workspaceDir));
-    const ownerId = process.env.PD_OWNER_ID?.trim();
-    const credentialId = process.env.PD_OWNER_CREDENTIAL_ID?.trim();
+    // ADR-0022 (PRI-578): single resolver — env > ~/.pd/owner.json > none
+    const identity = resolveOwnerIdentity(process.env, defaultOwnerIdentityHomeDir());
+    const { ownerId, credentialId } = identity;
     const consoleToken = process.env.PD_CONSOLE_TOKEN?.trim();
     const operatorId = process.env.USERNAME?.trim() || process.env.USER?.trim();
     const actor = ownerId && credentialId && consoleToken
@@ -498,22 +555,17 @@ export async function handleRuntimeActivationPromote(opts: ActivationPromoteOpti
               validateProductionArtifact: value => writer.canActivate(value),
             });
           },
-          buildEvidenceSnapshot: (checks, artifact) => {
-            const createdAt = new Date().toISOString();
-            const artifactDigest = artifact
-              ? `sha256:${createHash('sha256').update(JSON.stringify(artifact), 'utf8').digest('hex')}`
-              : request.expectedArtifactDigest;
-            const snapshotBody = JSON.stringify({ artifactDigest, checks, createdAt });
-            return {
-              snapshotId: `snapshot-${randomUUID()}`,
-              snapshotDigest: `sha256:${createHash('sha256').update(snapshotBody, 'utf8').digest('hex')}`,
-              artifactDigest,
-              lineageRefs: artifact ? [artifact.sourceTaskId, ...artifact.lineageArtifactIds] : [],
-              hostRuntimeVersion: 'openclaw-legacy@1', safetyGateResults: checks,
-              shadowSummary: readShadowSummary(workspaceDir, activationId),
-              configurationVersion: 'pd-config-current',
-              redaction: { version: 'v1', rawParametersStored: false }, createdAt,
-            };
+          buildEvidenceSnapshot: (checks, artifact, evaluationId) => {
+            return buildPromotionEvidenceSnapshot({
+              activationId,
+              evaluationId,
+              checks,
+              artifact,
+              expectedArtifactDigest: request.expectedArtifactDigest,
+              ownerIdentity: actor,
+              hostRuntimeVersion: 'openclaw-legacy@1',
+              shadowSummary: readShadowSummaryForActivation(workspaceDir, activationId),
+            });
           },
           newEvaluationId: () => `readiness-${randomUUID()}`,
         });

package/src/commands/runtime-internalization-enqueue-successors.ts

@@ -4,8 +4,9 @@ import {
   InternalizationOrchestrator,
   isPeerRunnerKind,
   hydratePITaskRecord,
+  PD_TASK_STATUSES,
 } from '@principles/core/runtime-v2';
-import type { CommitNextTaskResult } from '@principles/core/runtime-v2';
+import type { CommitNextTaskResult, PDTaskStatus } from '@principles/core/runtime-v2';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
 
 interface EnqueueSuccessorsOptions {
@@ -236,7 +237,7 @@ interface SuccessorIndexEntry {
 async function buildSuccessorIndex(
   stateManager: RuntimeStateManager,
 ): Promise<Map<string, SuccessorIndexEntry>> {
-  const allStatuses: ('pending' | 'retry_wait' | 'succeeded' | 'leased' | 'failed' | 'needs_human_review')[] = ['pending', 'retry_wait', 'succeeded', 'leased', 'failed', 'needs_human_review'];
+  const allStatuses: PDTaskStatus[] = [...PD_TASK_STATUSES];
   const index = new Map<string, SuccessorIndexEntry>();
   const results = await Promise.all(
     allStatuses.map(status => stateManager.listTasks({ status })),

package/src/commands/telemetry.ts

@@ -0,0 +1,349 @@
+/**
+ * pd telemetry — Anonymous Product Telemetry v1 control plane
+ * (PRI-597, SPEC §40-§43).
+ *
+ * Consent lives at the machine level (~/.pd/product-telemetry.json via
+ * host-runtime); measurement (daily ID, dedup, retry, lock) is
+ * workspace-scoped. The release feature flag (anonymous_product_telemetry)
+ * is an INDEPENDENT gate read from the resolved workspace's .pd/config.yaml.
+ *
+ * Commands:
+ *   pd telemetry status   — gates, consent, eligibility, bounded export status
+ *   pd telemetry enable   — explicit consent (default dry-run; --confirm to write)
+ *   pd telemetry disable  — deny consent + delete local identity (default dry-run)
+ *   pd telemetry reset    — rotate/delete identity (default dry-run)
+ *   pd telemetry preview  — exact outbound payload; never sends
+ *
+ * --json outputs exactly one parseable object; failures carry reason +
+ * nextAction; the telemetry secret is never printed.
+ */
+
+import * as path from 'path';
+import type { Command } from 'commander';
+import {
+  createProductTelemetryService,
+  PREVIEW_BANNER,
+  type ProductTelemetryStatusView,
+} from '@principles/host-runtime';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+import { emitError, emitFlagConflict, emitResult } from '../services/cli-output.js';
+
+// ── Output types ─────────────────────────────────────────────────────────────
+
+export interface TelemetryStatusOutput {
+  status: 'ok' | 'degraded' | 'failed';
+  command: 'telemetry:status';
+  consent: string;
+  consentVersion: string;
+  hasSecret: boolean;
+  flagEnabled: boolean | null;
+  flagSource: string | null;
+  environmentSuppressed: boolean;
+  suppressionReasons: string[];
+  canExport: boolean;
+  blockers: string[];
+  lastAttemptedAt?: string;
+  lastSucceededAt?: string;
+  lastFailureCode?: string;
+  nextRetryAt?: string;
+  endpoint: string;
+  workspaceDir?: string;
+  nextAction?: string;
+  reason?: string;
+}
+
+export interface TelemetryMutationOutput {
+  status: 'ok' | 'failed';
+  command: 'telemetry:enable' | 'telemetry:disable' | 'telemetry:reset';
+  dryRun: boolean;
+  applied: boolean;
+  consent?: string;
+  /** What the applied/dry-run mutation changes, in plain terms. */
+  effect: string;
+  reason?: string;
+  nextAction?: string;
+}
+
+export interface TelemetryPreviewOutput {
+  status: 'ok';
+  command: 'telemetry:preview';
+  banner: string;
+  snapshot: Record<string, unknown>;
+  gates: {
+    flagEnabled: boolean | null;
+    consent: string;
+    environmentSuppressed: boolean;
+    suppressionReasons: string[];
+    canExport: boolean;
+    blockers: string[];
+  };
+  notes: string[];
+  secretEphemeral: boolean;
+  nextAction?: string;
+}
+
+// ── Text formatting ──────────────────────────────────────────────────────────
+
+function formatStatusText(output: TelemetryStatusOutput): string {
+  const lines: string[] = [];
+  lines.push('PD Anonymous Product Telemetry');
+  lines.push(`consent: ${output.consent} (v${output.consentVersion})`);
+  lines.push(`feature flag: ${output.flagEnabled === null ? 'unknown (no workspace)' : output.flagEnabled ? 'on' : 'off'}${output.flagSource ? ` (${output.flagSource})` : ''}`);
+  lines.push(`environment: ${output.environmentSuppressed ? `suppressed (${output.suppressionReasons.join(', ')})` : 'eligible'}`);
+  lines.push(`can export: ${output.canExport ? 'yes' : `no (${output.blockers.join(', ')})`}`);
+  lines.push(`local secret: ${output.hasSecret ? 'present' : 'absent'}`);
+  if (output.lastAttemptedAt) lines.push(`last attempted: ${output.lastAttemptedAt}`);
+  if (output.lastSucceededAt) lines.push(`last succeeded: ${output.lastSucceededAt}`);
+  if (output.lastFailureCode) lines.push(`last failure: ${output.lastFailureCode}`);
+  if (output.nextRetryAt) lines.push(`next retry: ${output.nextRetryAt}`);
+  lines.push(`collector: ${output.endpoint}`);
+  lines.push('');
+  lines.push('Collects: PD version, anonymous tri-state milestones (true/false/unavailable), coarse reliability.');
+  lines.push('Never collects: conversations, code/files, Principle content, Pain content.');
+  if (output.nextAction) lines.push(`Next action: ${output.nextAction}`);
+  return lines.join('\n');
+}
+
+function formatMutationText(output: TelemetryMutationOutput): string {
+  const lines: string[] = [];
+  lines.push(`PD telemetry ${output.command.split(':')[1]} ${output.applied ? 'applied' : '(dry-run — not applied)'}`);
+  lines.push(output.effect);
+  if (!output.applied) lines.push('Re-run with --confirm to apply.');
+  if (output.nextAction) lines.push(`Next action: ${output.nextAction}`);
+  return lines.join('\n');
+}
+
+function formatPreviewText(output: TelemetryPreviewOutput): string {
+  const lines: string[] = [];
+  lines.push(output.secretEphemeral
+    ? 'PD Telemetry Preview — exact payload shape (dailyTelemetryId is provisional until enabled)'
+    : 'PD Telemetry Preview — exact outbound payload');
+  lines.push('');
+  lines.push(JSON.stringify(output.snapshot, null, 2));
+  lines.push('');
+    lines.push(`Collected: PD version, anonymous tri-state milestones (true/false/unavailable), coarse reliability.`);
+  lines.push(`Never collected: conversations, code/files, Principle content, Pain content.`);
+  lines.push(`Gates: flag=${output.gates.flagEnabled ?? 'unresolved'} consent=${output.gates.consent} environment=${output.gates.environmentSuppressed ? 'suppressed' : 'eligible'} → wouldExport=${output.gates.canExport}`);
+  if (output.notes.length > 0) {
+    lines.push('Notes:');
+    for (const note of output.notes) lines.push(`  [!] ${note}`);
+  }
+  lines.push('');
+  lines.push(`>>> ${PREVIEW_BANNER}`);
+  return lines.join('\n');
+}
+
+// ── Shared helpers ───────────────────────────────────────────────────────────
+
+interface TelemetryOptions {
+  workspace?: string;
+  json?: boolean;
+  confirm?: boolean;
+  dryRun?: boolean;
+}
+
+function resolveWorkspaceOrNull(opts: TelemetryOptions): string | undefined {
+  if (opts.workspace) return path.resolve(opts.workspace);
+  try {
+    return resolveWorkspaceDir();
+  } catch {
+    // Consent/identity commands are machine-scope; a workspace is only needed
+    // to report the workspace-scope flag gate. Absent workspace = flag unknown.
+    return undefined;
+  }
+}
+
+function makeService() {
+  return createProductTelemetryService({});
+}
+
+function checkDryRunConfirmMutex(opts: TelemetryOptions, json: boolean): boolean {
+  if (opts.dryRun === true && opts.confirm === true) {
+    process.exitCode = emitFlagConflict({ json });
+    return false;
+  }
+  return true;
+}
+
+// ── Handlers ─────────────────────────────────────────────────────────────────
+
+export async function handleTelemetryStatus(opts: TelemetryOptions): Promise<void> {
+  const service = makeService();
+  const workspaceDir = resolveWorkspaceOrNull(opts);
+  const result = service.getStatus(workspaceDir);
+  if (!result.ok) {
+    process.exitCode = emitError(new Error(result.reason), { json: opts.json ?? false, nextAction: result.nextAction });
+    return;
+  }
+  const view: ProductTelemetryStatusView = result.view;
+  const output: TelemetryStatusOutput = {
+    status: 'ok',
+    command: 'telemetry:status',
+    consent: view.consent,
+    consentVersion: view.consentVersion,
+    hasSecret: view.hasSecret,
+    flagEnabled: view.flagEnabled,
+    flagSource: view.flagSource,
+    environmentSuppressed: view.environmentSuppressed,
+    suppressionReasons: view.suppressionReasons,
+    canExport: view.canExport,
+    blockers: view.blockers,
+    ...(view.lastAttemptedAt !== undefined ? { lastAttemptedAt: view.lastAttemptedAt } : {}),
+    ...(view.lastSucceededAt !== undefined ? { lastSucceededAt: view.lastSucceededAt } : {}),
+    ...(view.lastFailureCode !== undefined ? { lastFailureCode: view.lastFailureCode } : {}),
+    ...(view.nextRetryAt !== undefined ? { nextRetryAt: view.nextRetryAt } : {}),
+    endpoint: view.endpoint,
+    ...(workspaceDir !== undefined ? { workspaceDir } : {}),
+    ...(view.nextAction !== undefined ? { nextAction: view.nextAction } : {}),
+  };
+  emitResult(output, { json: opts.json ?? false, formatText: formatStatusText });
+}
+
+type MutationKind = 'enable' | 'disable' | 'reset';
+
+const MUTATION_EFFECTS: Record<MutationKind, string> = {
+  enable: 'Records explicit telemetry consent (granted) and creates a local random secret for daily unlinkable IDs. Nothing is exported unless the feature flag and environment eligibility also allow it.',
+  disable: 'Records consent denied and deletes the local telemetry secret and export status. Future telemetry export requests: 0.',
+  reset: 'Deletes the local telemetry secret and export status. If consent remains granted, a fresh secret is generated — future daily IDs are unrelated to previous ones.',
+};
+
+const MUTATION_NEXT_ACTIONS: Record<MutationKind, string> = {
+  enable: 'Run "pd telemetry preview" to inspect the exact outbound payload.',
+  disable: 'Telemetry is fully off. Re-enable anytime with "pd telemetry enable --confirm".',
+  reset: 'Previous daily IDs can no longer be derived. See "pd telemetry status".',
+};
+
+export async function handleTelemetryMutation(kind: MutationKind, opts: TelemetryOptions): Promise<void> {
+  const json = opts.json ?? false;
+  if (!checkDryRunConfirmMutex(opts, json)) return;
+  const applied = opts.confirm === true;
+  const service = makeService();
+
+  if (!applied) {
+    const output: TelemetryMutationOutput = {
+      status: 'ok',
+      command: `telemetry:${kind}`,
+      dryRun: true,
+      applied: false,
+      effect: MUTATION_EFFECTS[kind],
+      nextAction: 'Re-run with --confirm to apply.',
+    };
+    emitResult(output, { json, formatText: formatMutationText });
+    return;
+  }
+
+  const result =
+    kind === 'enable' ? service.enable() : kind === 'disable' ? service.disable() : service.reset();
+  if (!result.ok) {
+    process.exitCode = emitError(new Error(result.reason), { json, nextAction: result.nextAction });
+    return;
+  }
+  const output: TelemetryMutationOutput = {
+    status: 'ok',
+    command: `telemetry:${kind}`,
+    dryRun: false,
+    applied: true,
+    consent: result.consent,
+    effect: MUTATION_EFFECTS[kind],
+    nextAction: MUTATION_NEXT_ACTIONS[kind],
+  };
+  emitResult(output, { json, formatText: formatMutationText });
+}
+
+export async function handleTelemetryPreview(opts: TelemetryOptions): Promise<void> {
+  let workspaceDir: string;
+  if (opts.workspace) {
+    workspaceDir = path.resolve(opts.workspace);
+  } else {
+    try {
+      workspaceDir = resolveWorkspaceDir();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      process.exitCode = emitError(new Error(`workspace_unresolvable: ${message}`), {
+        json: opts.json ?? false,
+        nextAction: 'Pass --workspace <path> or run from a PD workspace',
+      });
+      return;
+    }
+  }
+  const service = makeService();
+  const preview = service.preview(workspaceDir);
+  const output: TelemetryPreviewOutput = {
+    status: 'ok',
+    command: 'telemetry:preview',
+    banner: PREVIEW_BANNER,
+    snapshot: preview.snapshot,
+    gates: {
+      flagEnabled: preview.gates.flagEnabled,
+      consent: preview.gates.consent,
+      environmentSuppressed: preview.gates.environmentSuppressed,
+      suppressionReasons: preview.gates.suppressionReasons,
+      canExport: preview.gates.canExport,
+      blockers: preview.gates.blockers,
+    },
+    notes: preview.notes,
+    secretEphemeral: preview.secretEphemeral,
+  };
+  emitResult(output, { json: opts.json ?? false, formatText: formatPreviewText });
+}
+
+// ── Registration (used by index.ts and wiring tests) ─────────────────────────
+
+export function registerTelemetryCommand(parent: Command): Command {
+  const telemetry = parent
+    .command('telemetry')
+    .description('Anonymous product telemetry control (opt-in, privacy-preserving)');
+
+  telemetry
+    .command('status')
+    .description('Show telemetry consent, gates, eligibility, and bounded export status')
+    .option('-w, --workspace <path>', 'Workspace directory (for the feature-flag gate)')
+    .option('--json', 'Output raw JSON')
+    .action(async (opts) => {
+      await handleTelemetryStatus({ workspace: opts.workspace, json: opts.json });
+    });
+
+  telemetry
+    .command('enable')
+    .description('Grant explicit telemetry consent (default OFF until enabled)')
+    .option('--dry-run', 'Show the effect without writing (default)')
+    .option('--confirm', 'Apply the consent change (required to write)')
+    .option('-w, --workspace <path>', 'Workspace directory (reporting only)')
+    .option('--json', 'Output raw JSON')
+    .action(async (opts) => {
+      await handleTelemetryMutation('enable', { workspace: opts.workspace, json: opts.json, confirm: opts.confirm, dryRun: opts.dryRun });
+    });
+
+  telemetry
+    .command('disable')
+    .description('Deny consent and delete the local telemetry identity (zero future exports)')
+    .option('--dry-run', 'Show the effect without writing (default)')
+    .option('--confirm', 'Apply the change (required to write)')
+    .option('-w, --workspace <path>', 'Workspace directory (reporting only)')
+    .option('--json', 'Output raw JSON')
+    .action(async (opts) => {
+      await handleTelemetryMutation('disable', { workspace: opts.workspace, json: opts.json, confirm: opts.confirm, dryRun: opts.dryRun });
+    });
+
+  telemetry
+    .command('reset')
+    .description('Delete and rotate the local telemetry identity (unlink from previous daily IDs)')
+    .option('--dry-run', 'Show the effect without writing (default)')
+    .option('--confirm', 'Apply the change (required to write)')
+    .option('-w, --workspace <path>', 'Workspace directory (reporting only)')
+    .option('--json', 'Output raw JSON')
+    .action(async (opts) => {
+      await handleTelemetryMutation('reset', { workspace: opts.workspace, json: opts.json, confirm: opts.confirm, dryRun: opts.dryRun });
+    });
+
+  telemetry
+    .command('preview')
+    .description('Show the exact outbound telemetry payload (nothing is sent)')
+    .option('-w, --workspace <path>', 'Workspace directory')
+    .option('--json', 'Output raw JSON')
+    .action(async (opts) => {
+      await handleTelemetryPreview({ workspace: opts.workspace, json: opts.json });
+    });
+
+  return telemetry;
+}

package/src/commands/version.ts

@@ -0,0 +1,49 @@
+/**
+ * pd version command (SPEC §12).
+ *
+ * Human output prints the short stable version text; `--json` emits exactly
+ * one parseable JSON object with the full canonical report (productVersion,
+ * releaseId, components, bootstrapVersion, channel, source, generation,
+ * health, lastTransaction).
+ */
+
+import type { Command } from 'commander';
+import { buildVersionReport, formatShortVersion, VersionReportError } from '../services/version-report.js';
+
+async function runVersion(json: boolean): Promise<void> {
+  try {
+    const report = buildVersionReport();
+    if (json) {
+      console.log(JSON.stringify(report, null, 2));
+      return;
+    }
+    console.log(formatShortVersion(report));
+  } catch (error) {
+    if (error instanceof VersionReportError) {
+      if (json) {
+        console.log(JSON.stringify({
+          ok: false,
+          reason: error.reason,
+          message: error.message,
+          nextAction: error.nextAction,
+        }, null, 2));
+      } else {
+        console.error(error.message);
+        console.error(`Next: ${error.nextAction}`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+    throw error;
+  }
+}
+
+export function registerVersionCommand(program: Command): void {
+  program
+    .command('version')
+    .description('Show the canonical PD product version and installation state')
+    .option('--json', 'Emit the full canonical version report as one JSON object', false)
+    .action(async (opts: Record<string, unknown>) => {
+      await runVersion(opts.json === true);
+    });
+}

package/src/index.ts

@@ -15,6 +15,8 @@ import { handleSamplesReview } from './commands/samples-review.js';
 import { handleEvolutionTasksList } from './commands/evolution-tasks-list.js';
 import { handleEvolutionTasksShow } from './commands/evolution-tasks-show.js';
 import { registerHealthCommand } from './commands/health.js';
+import { registerVersionCommand } from './commands/version.js';
+import { buildVersionReport, formatShortVersion, VersionReportError } from './services/version-report.js';
 import { handleTaskShow, registerTaskListCommand } from './commands/task.js';
 import { handleRunList, handleRunShow } from './commands/run.js';
 import { handleTrajectoryLocate } from './commands/trajectory.js';
@@ -68,6 +70,7 @@ import { registerRulecodeCommand } from './commands/rulecode.js';
 import { registerIntentCommand } from './commands/intent.js';
 import { registerErrorsListCommand } from './commands/errors-list.js';
 import { registerPrinciplesCommand } from './commands/principles-stats.js';
+import { registerTelemetryCommand } from './commands/telemetry.js';
 
 import { createRequire } from 'module';
 const require = createRequire(import.meta.url);
@@ -75,12 +78,38 @@ const pkg = require('../package.json') as { version: string };
 
 const program = new Command();
 
+// SPEC §12: `pd --version` prints the canonical product version when a
+// supported installation exists; a development checkout falls back to the
+// CLI package version with an explicit marker instead of impersonating an
+// installed release.
+function handleVersionFlag(args: readonly string[]): boolean {
+  if (!args.includes('--version') && !args.includes('-V')) return false;
+  try {
+    console.log(formatShortVersion(buildVersionReport()));
+    return true;
+  } catch (error) {
+    if (error instanceof VersionReportError && error.reason === 'not_installed') {
+      console.log(`Principles Disciple ${pkg.version} (development-checkout)`);
+      return true;
+    }
+    if (error instanceof VersionReportError) {
+      console.error(error.message);
+      console.error(`Next: ${error.nextAction}`);
+      process.exitCode = 1;
+      return true;
+    }
+    throw error;
+  }
+}
+
 program
   .name('pd')
   .description('PD CLI — Pain recording, sample management, and evolution tasks')
-  .version(pkg.version)
+  .option('-V, --version', 'output the canonical PD product version')
   .enablePositionalOptions();
 
+registerVersionCommand(program);
+
 const painCmd = program
   .command('pain')
   .description('Pain signal management');
@@ -166,6 +195,10 @@ tasksCmd
 
 registerHealthCommand(program);
 
+// ── Anonymous Product Telemetry v1 control plane (PRI-595~603) ────────────────
+
+registerTelemetryCommand(program);
+
 // ── Runtime v2 task/run commands ──────────────────────────────────────────────鈹€鈹€鈹€鈹€鈹€鈹€
 
 const rtTaskCmd = program
@@ -1098,4 +1131,6 @@ qualityCmd
     await handleQualityScorecard(opts);
   });
 
-program.parse();
+if (!handleVersionFlag(process.argv.slice(2))) {
+  program.parse();
+}