@principles/pd-cli 1.73.0

package/src/commands/runtime-internalization-wake-once.ts

@@ -0,0 +1,87 @@
+/**
+ * pd runtime internalization wake-once command handler.
+ *
+ * Usage:
+ *   pd runtime internalization wake-once --workspace <path> --dry-run --json
+ *
+ * This command ONLY supports --dry-run mode. Non-dry-run invocations are rejected
+ * before any state interaction (no lease acquisition, no mutation).
+ *
+ * PRI-73 scope: dry-run inspection only; real lease acquisition is future scope.
+ */
+import * as path from 'path';
+import { RuntimeStateManager, InternalizationOrchestrator } from '@principles/core/runtime-v2';
+import type { WakeOnceResult } from '@principles/core/runtime-v2';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+
+interface WakeOnceOptions {
+  workspace?: string;
+  dryRun?: boolean;
+  json?: boolean;
+}
+
+const OWNER = 'pd-cli-internalization-wake-once';
+const RUNTIME_KIND = 'local-worker';
+
+function formatTextOutput(result: WakeOnceResult): string {
+  switch (result.decision) {
+    case 'would_lease':
+      return `would_lease: ${result.taskId} (${result.taskKind})`;
+    case 'no_ready_tasks':
+      return `no_ready_tasks: ${result.reason} (inspected: ${result.inspectedCount})`;
+    case 'blocked':
+      return `blocked: ${result.taskId} (${result.taskKind}) by [${result.blockedBy.join(', ')}]`;
+    case 'dependency_failed':
+      return `dependency_failed: ${result.taskId} (${result.taskKind}) failed deps: [${result.failedDependencies.join(', ')}]`;
+    case 'lease_conflict':
+      return `lease_conflict: ${result.taskId} — ${result.conflictReason}`;
+    case 'invalid_task_metadata':
+      return `invalid_task_metadata: ${result.taskId} (${result.taskKind})`;
+    case 'leased':
+      return `leased: ${result.taskId} (${result.taskKind}) attempt ${result.attemptCount}`;
+  }
+}
+
+export async function handleRuntimeInternalizationWakeOnce(opts: WakeOnceOptions): Promise<void> {
+  // REJECT non-dry-run — only dry-run mode is implemented in this issue
+  if (!opts.dryRun) {
+    console.error('Error: wake-once without --dry-run is not implemented.');
+    console.error('Only --dry-run mode is available for operator inspection.');
+    process.exit(1);
+    return;
+  }
+
+  const workspaceDir = opts.workspace ? path.resolve(opts.workspace) : resolveWorkspaceDir();
+
+  const stateManager = new RuntimeStateManager({ workspaceDir });
+  await stateManager.initialize();
+
+  try {
+    const orchestrator = new InternalizationOrchestrator(
+      { stateManager },
+      { owner: OWNER, runtimeKind: RUNTIME_KIND, dryRun: true },
+    );
+
+    let result: WakeOnceResult = { decision: 'no_ready_tasks', reason: 'no_candidates', inspectedCount: 0 };
+    try {
+      result = await orchestrator.wakeOnce();
+    } catch (err) {
+      console.error('Error: wake-once failed:', err);
+      process.exitCode = 1;
+      return;
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatTextOutput(result));
+    }
+
+    // Exit code 1 when no task could be leased (operator alert condition)
+    if (result.decision === 'no_ready_tasks' || result.decision === 'lease_conflict') {
+      process.exitCode = 1;
+    }
+  } finally {
+    await stateManager.close();
+  }
+}

package/src/commands/runtime-pain-flood-simulation.ts

@@ -0,0 +1,121 @@
+import * as path from 'path';
+import * as os from 'os';
+import * as fs from 'fs';
+import { runPainFloodSimulation } from '../services/pain-flood-simulation-runner.js';
+import type { PainFloodSimulationSummary } from '@principles/core/runtime-v2';
+
+interface CliPainFloodOptions {
+  workspace?: string;
+  json?: boolean;
+  identicalCount?: number;
+  similarCount?: number;
+  stressCount?: number;
+}
+
+function formatTextOutput(summary: PainFloodSimulationSummary): string {
+  const lines: string[] = [];
+  const icon = summary.status === 'healthy' ? '✓' : summary.status === 'degraded' ? '⚠' : '✗';
+
+  lines.push('PD Pain Flood Simulation');
+  lines.push(`generatedAt: ${summary.generatedAt}`);
+  lines.push(`workspaceMode: ${summary.workspaceMode}`);
+  lines.push(`OVERALL: ${icon} ${summary.status.toUpperCase()}`);
+  lines.push('');
+  lines.push(`  inputPainCount: ${summary.inputPainCount}`);
+  lines.push(`  acceptedPainCount: ${summary.acceptedPainCount}`);
+  lines.push(`  skippedDuplicateCount: ${summary.skippedDuplicateCount}`);
+  lines.push(`  failedCount: ${summary.failedCount}`);
+  lines.push(`  candidateCount: ${summary.candidateCount}`);
+  lines.push(`  taskCount: ${summary.taskCount}`);
+  lines.push(`  maxEvidencePreviewLength: ${summary.maxEvidencePreviewLength}`);
+  lines.push(`  contextBudgetSummary: ${summary.contextBudgetSummary}`);
+  lines.push('');
+
+  for (const stage of summary.stages) {
+    const stageIcon = stage.status === 'passed' ? '✓' : stage.status === 'skipped' ? '○' : '✗';
+    lines.push(`  ${stageIcon} ${stage.scenarioName}: ${stage.status}`);
+    lines.push(`      input=${stage.inputCount} accepted=${stage.acceptedCount} skipped=${stage.skippedCount} failed=${stage.failedCount} tasks=${stage.taskCount} candidates=${stage.candidateCount}`);
+    if (stage.reason) {
+      lines.push(`      reason: ${stage.reason}`);
+    }
+  }
+
+  if (summary.recommendedNextIssue) {
+    lines.push('');
+    lines.push(`Recommended next issue: ${summary.recommendedNextIssue}`);
+  }
+
+  if (summary.reason) {
+    lines.push(`reason: ${summary.reason}`);
+  }
+
+  if (summary.nextAction) {
+    lines.push(`nextAction: ${summary.nextAction}`);
+  }
+
+  return lines.join('\n');
+}
+
+export async function handleRuntimePainFlood(opts: CliPainFloodOptions): Promise<void> {
+  if (opts.workspace) {
+    if (opts.json) {
+      console.log(JSON.stringify({ status: 'error', reason: 'Explicit workspace is not allowed for pain flood simulation — this command mutates state and must run in an auto-created temp workspace only.', nextAction: 'Remove --workspace flag and re-run to use a temp workspace.' }));
+    } else {
+      console.error('Error: --workspace is not allowed for pain flood simulation. This command mutates state and must run in an auto-created temp workspace only.');
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  const countFields: { name: 'identicalCount' | 'similarCount' | 'stressCount'; value: number | undefined; min: number }[] = [
+    { name: 'identicalCount', value: opts.identicalCount, min: 1 },
+    { name: 'similarCount', value: opts.similarCount, min: 1 },
+    { name: 'stressCount', value: opts.stressCount, min: 1 },
+  ];
+
+  for (const field of countFields) {
+    if (field.value !== undefined) {
+      if (!Number.isFinite(field.value) || !Number.isInteger(field.value) || field.value < field.min) {
+        const reason = `--${field.name === 'identicalCount' ? 'identical-count' : field.name === 'similarCount' ? 'similar-count' : 'stress-count'} must be a finite integer >= ${field.min}, got ${field.value}`;
+        if (opts.json) {
+          console.log(JSON.stringify({ status: 'error', reason, nextAction: `Provide a valid --${field.name === 'identicalCount' ? 'identical-count' : field.name === 'similarCount' ? 'similar-count' : 'stress-count'} value` }));
+        } else {
+          console.error(`Error: ${reason}`);
+        }
+        process.exitCode = 1;
+        return;
+      }
+    }
+  }
+
+  const workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-pain-flood-'));
+  const workspaceMode = 'temp' as const;
+
+  try {
+    const summary = await runPainFloodSimulation({
+      workspaceDir,
+      workspaceMode,
+      identicalCount: opts.identicalCount,
+      similarCount: opts.similarCount,
+      stressCount: opts.stressCount,
+    });
+
+    if (opts.json) {
+      console.log(JSON.stringify(summary, null, 2));
+    } else {
+      console.log(formatTextOutput(summary));
+    }
+
+    if (summary.status !== 'healthy') {
+      console.error('');
+      console.error(`FAIL: status=${summary.status}`);
+      process.exitCode = 1;
+    }
+  } finally {
+    try {
+      fs.rmSync(workspaceDir, { recursive: true, force: true });
+    } catch {
+      // ignore cleanup errors on Windows
+    }
+  }
+}

package/src/commands/runtime-pruning.ts

@@ -0,0 +1,438 @@
+/**
+ * pd runtime pruning report command — non-destructive pruning metrics.
+ *
+ * Usage: pd runtime pruning report [--workspace <path>] [--json]
+ *
+ * Delegates to PruningReadModel (core).
+ */
+
+import * as path from 'path';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+import { PruningReadModel, appendPruningReview, listPruningReviews, buildMaskedPrincipleSet, removeOrphanReferencesFromLedger } from '@principles/core/runtime-v2';
+import type { PruningReviewDecision, OrphanDerivedCandidate, OrphanDetectionResult } from '@principles/core/runtime-v2';
+import { createRemediationResult, remediationAction } from './remediation-output.js';
+import type { RemediationResult } from './remediation-output.js';
+
+interface PruningReportOptions {
+  workspace?: string;
+  json?: boolean;
+}
+
+function outputText(
+  summary: ReturnType<PruningReadModel['getHealthSummary']>,
+  signals: ReturnType<PruningReadModel['getPrincipleSignals']>,
+  workspaceDir: string,
+): void {
+  console.log(`generatedAt: ${summary.generatedAt}`);
+  console.log(`workspace: ${workspaceDir}`);
+  console.log(`totalPrinciples: ${summary.totalPrinciples}`);
+  console.log(`byStatus: ${JSON.stringify(summary.byStatus)}`);
+  console.log(`orphanDerivedCandidateCount: ${summary.orphanDerivedCandidateCount}`);
+  console.log(`averageAgeDays: ${summary.averageAgeDays}`);
+  console.log('');
+  console.log(`watchCount: ${summary.watchCount}`);
+  console.log(`reviewCount: ${summary.reviewCount}`);
+
+  if (summary.watchCount > 0) {
+    console.log('');
+    console.log('── Principles flagged WATCH ──');
+    for (const s of signals) {
+      if (s.riskLevel === 'watch') {
+        console.log(`  [${s.status}] ${s.principleId} (age: ${s.ageDays}d, derivedPainCount: ${s.derivedPainCount})`);
+        for (const r of s.reasons) {
+          console.log(`    ↳ ${r}`);
+        }
+      }
+    }
+  }
+
+  if (summary.reviewCount > 0) {
+    console.log('');
+    console.log('── Principles flagged REVIEW ──');
+    for (const s of signals) {
+      if (s.riskLevel === 'review') {
+        console.log(`  [${s.status}] ${s.principleId} (age: ${s.ageDays}d, derivedPainCount: ${s.derivedPainCount})`);
+        for (const r of s.reasons) {
+          console.log(`    ↳ ${r}`);
+        }
+      }
+    }
+  }
+
+  if (summary.watchCount === 0 && summary.reviewCount === 0) {
+    console.log('');
+    console.log('No watch or review signals. System is healthy.');
+  }
+
+  console.log('');
+  console.log('NOTE: This report is read-only. No principles are modified or deleted.');
+}
+
+export function handlePruningReport(opts: PruningReportOptions): void {
+  const workspaceDir = opts.workspace
+    ? path.resolve(opts.workspace)
+    : resolveWorkspaceDir();
+
+  const model = new PruningReadModel({ workspaceDir });
+  const signals = model.getPrincipleSignals();
+  const summary = model.getHealthSummary();
+
+  if (opts.json) {
+    console.log(JSON.stringify({ generatedAt: summary.generatedAt, workspace: workspaceDir, summary, signals }, null, 2));
+    return;
+  }
+
+  outputText(summary, signals, workspaceDir);
+}
+
+// ── Pruning explain ────────────────────────────────────────────────────────────
+
+export interface PruningExplainOptions {
+  principleId: string;
+  workspace?: string;
+  json?: boolean;
+}
+
+export interface PruningReviewOptions {
+  principleId: string;
+  decision: PruningReviewDecision;
+  note?: string;
+  reviewer?: string;
+  workspace?: string;
+  json?: boolean;
+}
+
+export function handlePruningReview(opts: PruningReviewOptions): void {
+  const workspaceDir = opts.workspace
+    ? path.resolve(opts.workspace)
+    : resolveWorkspaceDir();
+
+  const model = new PruningReadModel({ workspaceDir });
+  const signals = model.getPrincipleSignals();
+
+  const signal = signals.find((s) => s.principleId === opts.principleId);
+
+  if (!signal) {
+    if (opts.json) {
+      console.log(JSON.stringify({ error: `Principle not found: '${opts.principleId}'` }));
+    } else {
+      console.error(`Error: Principle not found: '${opts.principleId}'`);
+    }
+    process.exit(1);
+    return; // satisfies TypeScript control flow (process.exit is [noreturn] in tests)
+  }
+
+  if (opts.decision !== 'keep' && opts.decision !== 'defer' && opts.decision !== 'archive-candidate') {
+    if (opts.json) {
+      console.log(JSON.stringify({ error: `Invalid decision: '${opts.decision}'. Must be one of: keep, defer, archive-candidate` }));
+    } else {
+      console.error(`Error: Invalid decision: '${opts.decision}'. Must be one of: keep, defer, archive-candidate`);
+    }
+    process.exit(1);
+    return;
+  }
+
+  if (opts.decision === 'archive-candidate' && !opts.note) {
+    if (opts.json) {
+      console.log(JSON.stringify({ error: 'archive-candidate decision requires --note' }));
+    } else {
+      console.error('Error: archive-candidate decision requires --note');
+    }
+    process.exit(1);
+    return;
+  }
+
+  const record = appendPruningReview(workspaceDir, {
+    principleId: signal.principleId,
+    decision: opts.decision,
+    note: opts.note ?? '',
+    reviewer: opts.reviewer,
+    signalSnapshot: signal,
+  });
+
+  if (opts.json) {
+    console.log(JSON.stringify({
+      reviewId: record.reviewId,
+      principleId: record.principleId,
+      decision: record.decision,
+      reviewer: record.reviewer,
+      reviewedAt: record.reviewedAt,
+    }));
+    return;
+  }
+
+  console.log(`reviewId: ${record.reviewId}`);
+  console.log(`principleId: ${record.principleId}`);
+  console.log(`decision: ${record.decision}`);
+  console.log(`reviewer: ${record.reviewer}`);
+  console.log(`reviewedAt: ${record.reviewedAt}`);
+  console.log('');
+  console.log('NOTE: This audit record does not modify the principle.');
+}
+
+export function handlePruningExplain(opts: PruningExplainOptions): void {
+  const workspaceDir = opts.workspace
+    ? path.resolve(opts.workspace)
+    : resolveWorkspaceDir();
+
+  const model = new PruningReadModel({ workspaceDir });
+  const signals = model.getPrincipleSignals();
+  const now = new Date().toISOString();
+
+  const signal = signals.find((s) => s.principleId === opts.principleId);
+
+  if (!signal) {
+    if (opts.json) {
+      console.log(JSON.stringify({ error: `Principle not found: '${opts.principleId}'`, workspace: workspaceDir, generatedAt: now }, null, 2));
+    } else {
+      console.error(`Error: Principle not found: '${opts.principleId}'`);
+    }
+    process.exit(1);
+    return; // unreachable but satisfies TypeScript
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify({ workspace: workspaceDir, principleId: signal.principleId, signal, generatedAt: now }, null, 2));
+    return;
+  }
+
+  console.log(`principleId: ${signal.principleId}`);
+  console.log(`status: ${signal.status}`);
+  console.log(`riskLevel: ${signal.riskLevel}`);
+  console.log(`ageDays: ${signal.ageDays}`);
+  console.log(`derivedPainCount: ${signal.derivedPainCount}`);
+  console.log(`matchedCandidateCount: ${signal.matchedCandidateCount}`);
+  console.log(`orphanCandidateCount: ${signal.orphanCandidateCount}`);
+  console.log(`reasons:`);
+  for (const r of signal.reasons) {
+    console.log(`  ${r}`);
+  }
+  console.log('');
+  console.log('NOTE: This report is read-only. No principles are modified or deleted.');
+}
+
+// ── Pruning rollback ──────────────────────────────────────────────────────────
+
+export interface PruningRollbackOptions {
+  principleId: string;
+  note?: string;
+  reviewer?: string;
+  workspace?: string;
+  json?: boolean;
+}
+
+export function handlePruningRollback(opts: PruningRollbackOptions): void {
+  const workspaceDir = opts.workspace
+    ? path.resolve(opts.workspace)
+    : resolveWorkspaceDir();
+
+  const reviews = listPruningReviews(workspaceDir, { principleId: opts.principleId });
+  if (reviews.length === 0) {
+    if (opts.json) {
+      console.log(JSON.stringify({ error: `No reviews found for principle: '${opts.principleId}'` }));
+    } else {
+      console.error(`Error: No reviews found for principle: '${opts.principleId}'`);
+    }
+    process.exit(1);
+    return;
+  }
+
+  const maskedIds = buildMaskedPrincipleSet(reviews);
+  if (!maskedIds.has(opts.principleId)) {
+    if (opts.json) {
+      console.log(JSON.stringify({ error: `Principle '${opts.principleId}' is not currently masked (latest decision is not archive-candidate)` }));
+    } else {
+      console.error(`Error: Principle '${opts.principleId}' is not currently masked (latest decision is not archive-candidate)`);
+    }
+    process.exit(1);
+    return;
+  }
+
+  const model = new PruningReadModel({ workspaceDir });
+  const signals = model.getPrincipleSignals();
+  const signal = signals.find((s) => s.principleId === opts.principleId) ?? undefined;
+
+  const record = appendPruningReview(workspaceDir, {
+    principleId: opts.principleId,
+    decision: 'keep',
+    note: opts.note ?? 'Rollback: restore principle injection',
+    reviewer: opts.reviewer,
+    signalSnapshot: signal,
+  });
+
+  if (opts.json) {
+    console.log(JSON.stringify({
+      reviewId: record.reviewId,
+      principleId: record.principleId,
+      decision: record.decision,
+      reviewer: record.reviewer,
+      reviewedAt: record.reviewedAt,
+    }));
+    return;
+  }
+
+  console.log(`reviewId: ${record.reviewId}`);
+  console.log(`principleId: ${record.principleId}`);
+  console.log(`decision: ${record.decision}`);
+  console.log(`reviewer: ${record.reviewer}`);
+  console.log(`reviewedAt: ${record.reviewedAt}`);
+  console.log('');
+  console.log('Principle has been restored to injection.');
+}
+
+// ── Pruning orphans ───────────────────────────────────────────────────────────
+
+export interface PruningOrphansOptions {
+  workspace?: string;
+  dryRun?: boolean;
+  confirm?: boolean;
+  json?: boolean;
+}
+
+function orphanActions(orphans: OrphanDerivedCandidate[]) {
+  return orphans.map((orphan) => remediationAction({
+    action: 'remove_orphan_reference',
+    targetId: orphan.candidateId,
+    previousState: orphan.status ?? 'unknown',
+    nextState: 'removed_from_ledger_reference',
+    reason: `${orphan.reason} (principle: ${orphan.principleId})`,
+  }));
+}
+
+export function handlePruningOrphans(opts: PruningOrphansOptions): void {
+  if (opts.dryRun && opts.confirm) {
+    console.error('Error: --dry-run and --confirm are mutually exclusive');
+    process.exit(1);
+  }
+
+  const workspaceDir = opts.workspace
+    ? path.resolve(opts.workspace)
+    : resolveWorkspaceDir();
+
+  const model = new PruningReadModel({ workspaceDir });
+  const detection: OrphanDetectionResult = model.getOrphanDerivedCandidates();
+  const orphans = detection.candidates;
+  const isDryRun = !opts.confirm;
+
+  if (isDryRun) {
+    const result: RemediationResult = createRemediationResult({
+      mode: 'dry_run',
+      repairedCount: 0,
+      skippedCount: 0,
+      actions: orphanActions(orphans),
+      warnings: detection.dbReadable ? [] : ['state.db is unreadable; --confirm will be refused until DB access is restored.'],
+      safeToConfirm: detection.dbReadable && orphans.length > 0,
+      includeLegacyDryRun: true,
+    });
+
+    if (opts.json) {
+      console.log(JSON.stringify({
+        ...result,
+        orphanDerivedCandidateCount: orphans.length,
+        candidates: orphans,
+        dbReadable: detection.dbReadable,
+      }, null, 2));
+      return;
+    }
+
+    console.log(`orphanDerivedCandidateCount: ${orphans.length}`);
+    console.log(`dryRun: true`);
+    console.log(`dbReadable: ${detection.dbReadable}`);
+    console.log('');
+    if (!detection.dbReadable) {
+      console.log('⚠️  state.db is unreadable — orphan list may include valid candidates.');
+      console.log('   --confirm will be refused until the DB is accessible.');
+      console.log('');
+    }
+    if (orphans.length === 0) {
+      console.log('No orphan derived candidates found.');
+    } else {
+      console.log('── Orphan derived candidates ──');
+      for (const o of orphans) {
+        console.log(`  [${o.status ?? 'unknown'}] ${o.candidateId} → principle: ${o.principleId}`);
+        console.log(`    ↳ ${o.reason}`);
+      }
+      console.log('');
+      console.log('NOTE: This is a dry-run. No data was modified. Use --confirm to remove orphan references.');
+    }
+    return;
+  }
+
+  if (!detection.dbReadable) {
+    const result: RemediationResult = createRemediationResult({
+      mode: 'confirm',
+      status: 'refused',
+      safeToConfirm: false,
+      repairedCount: 0,
+      skippedCount: orphans.length,
+      actions: orphanActions(orphans),
+      warnings: ['state.db is unreadable; refusing orphan cleanup because candidates cannot be verified.'],
+      includeLegacyDryRun: true,
+    });
+
+    if (opts.json) {
+      console.log(JSON.stringify({
+        ...result,
+        orphanDerivedCandidateCount: orphans.length,
+        candidates: orphans,
+        dbReadable: false,
+      }, null, 2));
+    } else {
+      console.error('❌ REFUSED: state.db is unreadable — cannot safely confirm orphan cleanup.');
+      console.error('   All derivedFromPainIds would appear as orphans when the DB is inaccessible.');
+      console.error('   Fix the DB access issue and re-run.');
+    }
+    process.exit(1);
+    return;
+  }
+
+  const orphanIdsByPrinciple = new Map<string, Set<string>>();
+  for (const o of orphans) {
+    if (!orphanIdsByPrinciple.has(o.principleId)) {
+      orphanIdsByPrinciple.set(o.principleId, new Set());
+    }
+    orphanIdsByPrinciple.get(o.principleId)?.add(o.candidateId);
+  }
+
+  const stateDir = path.join(workspaceDir, '.state');
+  const removedFromPrinciples = (() => {
+    try {
+      return removeOrphanReferencesFromLedger(stateDir, orphanIdsByPrinciple);
+    } catch (err) {
+      console.error(`❌ Failed to save ledger: ${err instanceof Error ? err.message : String(err)}`);
+      process.exit(1);
+      return [] as { principleId: string; removedIds: string[] }[];
+    }
+  })();
+
+  const removedCount = removedFromPrinciples.reduce((sum, item) => sum + item.removedIds.length, 0);
+  const result: RemediationResult = createRemediationResult({
+    mode: 'confirm',
+    repairedCount: removedCount,
+    skippedCount: Math.max(0, orphans.length - removedCount),
+    actions: orphanActions(orphans),
+    warnings: [],
+    includeLegacyDryRun: true,
+  });
+
+  if (opts.json) {
+    console.log(JSON.stringify({
+      ...result,
+      orphanDerivedCandidateCount: orphans.length,
+      candidates: orphans,
+      dbReadable: true,
+      removedFromPrinciples,
+    }, null, 2));
+    return;
+  }
+
+  console.log(`orphanDerivedCandidateCount: ${orphans.length}`);
+  console.log(`dryRun: false`);
+  console.log('');
+  for (const r of removedFromPrinciples) {
+    console.log(`principle: ${r.principleId}`);
+    console.log(`  removed: ${r.removedIds.join(', ')}`);
+  }
+  console.log('');
+  console.log(`${removedFromPrinciples.length} principles updated. ${orphans.length} orphan references removed.`);
+}