principles-disciple 1.11.0 → 1.13.0

package/src/commands/nocturnal-review.ts

@@ -27,7 +27,6 @@ import {
   getDatasetRecord,
   updateReviewStatus,
   updateTargetModelFamily,
-  readDatasetArtifact,
   getDatasetStats,
   type NocturnalDatasetRecord,
   type NocturnalReviewStatus,
@@ -53,7 +52,7 @@ function formatRecord(record: NocturnalDatasetRecord, includeDetails = false): s
   lines.push(`  createdAt: ${new Date(record.createdAt).toLocaleString('en-US')}`);
 
   if (includeDetails) {
-    const artifactPath = record.artifactPath;
+    const {artifactPath} = record;
     if (fs.existsSync(artifactPath)) {
       try {
         const content = fs.readFileSync(artifactPath, 'utf-8');
@@ -122,7 +121,7 @@ export function handleNocturnalReviewCommand(ctx: PluginCommandContext): PluginC
     }
 
     if (action === 'show') {
-      const fingerprint = parts[1];
+      const [, fingerprint] = parts;
       if (!fingerprint) {
         return {
           text: zh
@@ -149,7 +148,7 @@ export function handleNocturnalReviewCommand(ctx: PluginCommandContext): PluginC
     }
 
     if (action === 'approve') {
-      const fingerprint = parts[1];
+      const [, fingerprint] = parts;
       const reason = parts.slice(2).join(' ') || (zh ? 'Approved by human reviewer' : 'Approved by human reviewer');
 
       if (!fingerprint) {
@@ -203,7 +202,7 @@ export function handleNocturnalReviewCommand(ctx: PluginCommandContext): PluginC
     }
 
     if (action === 'reject') {
-      const fingerprint = parts[1];
+      const [, fingerprint] = parts;
       const reason = parts.slice(2).join(' ') || (zh ? 'Rejected by human reviewer' : 'Rejected by human reviewer');
 
       if (!fingerprint) {
@@ -249,8 +248,7 @@ export function handleNocturnalReviewCommand(ctx: PluginCommandContext): PluginC
     }
 
     if (action === 'set-family') {
-      const fingerprint = parts[1];
-      const family = parts[2];
+      const [, fingerprint, family] = parts;
 
       if (!fingerprint || !family) {
         return {

package/src/commands/nocturnal-rollout.ts

@@ -24,15 +24,12 @@
  *   /nocturnal-rollout show-promotion <checkpointId>
  */
 
-import { WorkspaceContext } from '../core/workspace-context.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
-import type { TrainableWorkerProfile } from '../core/external-training-contract.js';
 import {
   evaluatePromotionGate,
   advancePromotion,
   getPromotionRecord,
   listPromotionsByState,
-  rejectCheckpoint,
   DEFAULT_BASELINE_METRICS,
   DEFAULT_MIN_DELTA,
   DEFAULT_ALLOWED_MARGIN,
@@ -44,9 +41,6 @@ import {
   disableRoutingForProfile,
   rollbackDeployment,
   getDeployment,
-  getDeploymentLineage,
-  listDeployments,
-  getFullDeploymentRegistry,
   isRoutingEnabledForProfile,
   type WorkerProfile,
 } from '../core/model-deployment-registry.js';
@@ -61,7 +55,6 @@ import {
 } from '../core/shadow-observation-registry.js';
 import {
   getCheckpoint,
-  listCheckpoints,
 } from '../core/model-training-registry.js';
 
 function isZh(ctx: PluginCommandContext): boolean {
@@ -473,10 +466,6 @@ Routing: ${deployment.routingEnabled ? 'Enabled' : 'Disabled'}`,
           ? getCheckpoint(workspaceDir, deployment.activeCheckpointId)
           : null;
 
-        const lineage = deployment.activeCheckpointId
-          ? getDeploymentLineage(workspaceDir, profile)
-          : null;
-
         return {
           text: zh
             ? `=== ${profile} 部署状态 ===
@@ -583,7 +572,7 @@ ${promotion.previousPromotionId ? `Previous Promotion: ${promotion.previousPromo
 
     // ── List by State ─────────────────────────────────────────────────────
     if (subcommand === 'list-by-state') {
-      const stateArg = parts[1];
+      const [, stateArg] = parts;
       if (!stateArg) {
         return { text: zh ? '错误: 需要状态参数' : 'Error: state argument required' };
       }

package/src/commands/nocturnal-train.ts

@@ -26,18 +26,13 @@ import * as path from 'path';
 import * as fs from 'fs';
 import { execFileSync, spawn } from 'child_process';
 import { fileURLToPath } from 'url';
-import { WorkspaceContext } from '../core/workspace-context.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
 import {
   type TrainerBackendKind,
   type HardwareTier,
-  generateExperimentId,
-  computeDatasetFingerprint,
 } from '../core/external-training-contract.js';
 import {
   TrainingProgram,
-  DEFAULT_ORPO_HYPERPARAMETERS,
-  type CreateExperimentParams,
 } from '../core/training-program.js';
 import {
   listTrainingRuns,
@@ -48,20 +43,11 @@ import {
   getTrainingRegistryStats,
 } from '../core/model-training-registry.js';
 import { getDeployment } from '../core/model-deployment-registry.js';
-import {
-  DEFAULT_MIN_DELTA,
-  DEFAULT_ALLOWED_MARGIN,
-  DEFAULT_BASELINE_METRICS,
-} from '../core/promotion-gate.js';
 
 function isZh(ctx: PluginCommandContext): boolean {
   return String(ctx.config?.language || 'en').startsWith('zh');
 }
 
-function zh(cond: string): string {
-  return cond;
-}
-
 const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(MODULE_DIR, '..', '..', '..', '..');
 const TRAINER_SCRIPTS_DIR = path.join(REPO_ROOT, 'scripts', 'nocturnal', 'trainer');
@@ -111,24 +97,6 @@ function formatTrainingRun(run: ReturnType<typeof getTrainingRun>, zh: boolean):
   return lines.join('\n  ');
 }
 
-/**
- * Format checkpoint for display.
- */
-function formatCheckpoint(cp: ReturnType<typeof getCheckpoint>, zh: boolean): string {
-  if (!cp) return zh ? '未找到' : 'Not found';
-  const lines = [
-    `ID: ${cp.checkpointId.substring(0, 8)}...`,
-    `Family: ${cp.targetModelFamily}`,
-    `Artifact: ${cp.artifactPath}`,
-    `Deployable: ${cp.deployable ? (zh ? '是' : 'Yes') : (zh ? '否' : 'No')}`,
-    `Created: ${new Date(cp.createdAt).toLocaleString()}`,
-  ];
-  if (cp.lastEvalSummaryRef) {
-    lines.push(`Eval: ${cp.lastEvalSummaryRef.substring(0, 12)}...`);
-  }
-  return lines.join('\n  ');
-}
-
 export async function handleNocturnalTrainCommand(ctx: PluginCommandContext): Promise<PluginCommandResult> {
   const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
   const zh = isZh(ctx);
@@ -261,7 +229,7 @@ Hardware tiers:
               : `Error: manifest missing datasetFingerprint: ${manifestPath}`,
           };
         }
-        datasetFingerprint = manifest.datasetFingerprint;
+        ({ datasetFingerprint } = manifest);
       }
 
       const benchmarkExportId = benchmarkExportIdArg || datasetExportId || 'benchmark-default';
@@ -284,7 +252,7 @@ Hardware tiers:
       // The trainer reads spec from scripts/nocturnal/trainer/experiment-<id>.json.
       // import-result reads spec from .state/nocturnal/checkpoints/experiment-<id>.json.
       // Both must be written so the manual create-experiment -> trainer -> import-result chain works.
-      const spec = createResult.spec;
+      const {spec} = createResult;
       const trainerSpecPath = path.join(TRAINER_SCRIPTS_DIR, `experiment-${spec.experimentId}.json`);
       const workspaceSpecPath = path.join(workspaceDir, '.state', 'nocturnal', 'checkpoints', `experiment-${spec.experimentId}.json`);
       const trainerSpecDir = path.dirname(trainerSpecPath);
@@ -302,11 +270,13 @@ Hardware tiers:
       // This closes the gap in the create-experiment -> trainer -> import-result chain.
       // NOTE: This blocks until training completes (could be minutes).
       if (runNow) {
-        const spec = createResult.spec;
+         
+        const {spec} = createResult;
         const baseDir = TRAINER_SCRIPTS_DIR;
         const scriptPath = path.join(baseDir, 'main.py');
         const specPath = path.join(baseDir, `experiment-${spec.experimentId}.json`);
-        const outputDir = spec.outputDir;
+         
+        const {outputDir} = spec;
         const resultFilePath = path.join(outputDir, `result-${spec.experimentId}.json`);
 
         // Write spec file
@@ -316,6 +286,7 @@ Hardware tiers:
         }
         fs.writeFileSync(specPath, JSON.stringify(spec, null, 2), 'utf-8');
 
+         
         let trainerResult!: import('../core/external-training-contract.js').TrainingExperimentResult;
 
         try {
@@ -423,6 +394,7 @@ Hardware tiers:
 
         // Process trainer result (register checkpoint)
         // dry_run returns null (no checkpoint); other statuses throw on error
+         
         let processed: { checkpointId: string; checkpointRef: string } | null;
         try {
           processed = program.processResult({
@@ -523,7 +495,7 @@ Next steps:
 
     // ── Show Experiment ───────────────────────────────────────────────────
     if (subcommand === 'show-experiment') {
-      const experimentId = parts[1];
+      const [, experimentId] = parts;
       if (!experimentId) {
         return { text: zh ? '错误: 需要实验 ID' : 'Error: experiment ID required' };
       }
@@ -540,7 +512,7 @@ Next steps:
 
     // ── Import Result ─────────────────────────────────────────────────────
     if (subcommand === 'import-result') {
-      const experimentId = parts[1];
+      const [, experimentId] = parts;
       if (!experimentId) {
         return { text: zh ? '错误: 需要实验 ID' : 'Error: experiment ID required' };
       }
@@ -564,6 +536,7 @@ Next steps:
         }
       }
 
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Reason: JSON.parse returns dynamic JSON - type unknown at parse time, narrowed via type narrowing below
       let result: any;
       try {
         result = JSON.parse(resultJson);
@@ -594,6 +567,7 @@ Next steps:
 
       // Process the result
       const program = new TrainingProgram(workspaceDir);
+       
       let processed: { checkpointId: string; checkpointRef: string } | null;
       try {
         processed = program.processResult({
@@ -673,11 +647,11 @@ Next steps:
       let benchmarkId = benchmarkIdArg || `bench-${Date.now()}`;
       let delta = deltaArg ? parseFloat(deltaArg) : NaN;
       let verdict: 'fail' | 'pass' | 'compare_only' = verdictArg === 'pass' || verdictArg === 'fail' || verdictArg === 'compare_only'
-        ? (verdictArg as 'fail' | 'pass' | 'compare_only')
+        ? (verdictArg)
         : 'compare_only';
       let baselineScore = baselineScoreArg ? parseFloat(baselineScoreArg) : 0.5;
       let candidateScore = candidateScoreArg ? parseFloat(candidateScoreArg) : 0.5;
-      const mode = (modeArg === 'prompt_assisted' ? 'prompt_assisted' : 'reduced_prompt') as 'prompt_assisted' | 'reduced_prompt';
+      const mode: 'prompt_assisted' | 'reduced_prompt' = (modeArg === 'prompt_assisted' ? 'prompt_assisted' : 'reduced_prompt');
 
       // --- Run benchmark mode: execute real benchmark to get scores ---
       // This closes the gap in the attach-eval command chain.
@@ -717,7 +691,7 @@ Next steps:
         if (checkpoint.trainRunId) {
           const run = getTrainingRun(workspaceDir, checkpoint.trainRunId);
           if (run?.exportId) {
-            exportId = run.exportId;
+            ({ exportId } = run);
           }
         }
         const scorerType = 'local-model'; // Use real model scorer
@@ -780,11 +754,11 @@ Next steps:
           };
         }
 
-        delta = benchmarkResult.delta.delta;
-        baselineScore = benchmarkResult.delta.baselineScore;
-        candidateScore = benchmarkResult.delta.candidateScore;
-        benchmarkId = benchmarkResult.benchmarkId;
-        verdict = benchmarkResult.verdict;
+        ({
+          delta: { delta, baselineScore, candidateScore },
+          benchmarkId,
+          verdict,
+        } = benchmarkResult);
       } else {
         // Manual mode: require explicit delta and verdict
         if (!deltaArg || !verdictArg) {
@@ -855,7 +829,7 @@ Next steps:
 
     // ── Show Lineage ─────────────────────────────────────────────────────
     if (subcommand === 'show-lineage') {
-      const checkpointId = parts[1];
+      const [, checkpointId] = parts;
       if (!checkpointId) {
         return { text: zh ? '错误: 需要 checkpointId' : 'Error: checkpointId required' };
       }

package/src/commands/pain.ts

@@ -1,4 +1,4 @@
-import { trackFriction, resetFriction, getSession } from '../core/session-tracker.js';
+import { resetFriction, getSession } from '../core/session-tracker.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
 import type { EmpathyEventStats } from '../types/event-types.js';
@@ -6,7 +6,7 @@ import type { EmpathyEventStats } from '../types/event-types.js';
 /**
  * Creates a visual progress bar (e.g., [██████░░░░])
  */
-function createProgressBar(value: number, max: number, length: number = 10): string {
+function createProgressBar(value: number, max: number, length = 10): string {
     const filledLength = Math.round((value / max) * length);
     const emptyLength = length - filledLength;
     return `[${'█'.repeat(filledLength)}${'░'.repeat(emptyLength)}]`;
@@ -15,7 +15,7 @@ function createProgressBar(value: number, max: number, length: number = 10): str
 /**
  * Creates a mini bar for daily trends
  */
-function createMiniBar(count: number, max: number, length: number = 6): string {
+function createMiniBar(count: number, max: number, length = 6): string {
     const filledLength = Math.round((count / max) * length);
     return '█'.repeat(filledLength) + '░'.repeat(length - filledLength);
 }
@@ -89,12 +89,14 @@ export function handlePainCommand(ctx: PluginCommandContext): PluginCommandResul
     const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });
     const lang = (ctx.config?.language as string) || 'en';
     const isZh = lang === 'zh';
-    const sessionId = (ctx as any).sessionId;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Reason: sessionId injected by OpenClaw plugin framework - type not available in PluginCommandContext
+    const {sessionId} = (ctx as any);
 
     const args = (ctx.args || '').trim();
 
     // Handle empathy subcommand
     if (args.startsWith('empathy')) {
+        // eslint-disable-next-line @typescript-eslint/no-use-before-define -- Reason: mutual recursion between main handler and empathy subcommand handler - reordering would break logical grouping
         return handleEmpathySubcommand(wctx, args, sessionId, isZh);
     }
 
@@ -118,12 +120,13 @@ export function handlePainCommand(ctx: PluginCommandContext): PluginCommandResul
     // Default: Show status
     const session = sessionId ? getSession(sessionId) : undefined;
     const gfi = session ? session.currentGfi : 0;
-    const dictionary = wctx.dictionary;
+    const {dictionary} = wctx;
     const stats = dictionary.getStats();
     
     const gfiBar = createProgressBar(gfi, 100, 15);
     
     // Determine Mental Mode (aligned with prompt.ts logic)
+    // eslint-disable-next-line no-useless-assignment -- Reason: initial value unused due to immediate reassignment - keeping for type inference compatibility
     let mentalMode = '';
     if (isZh) {
         if (gfi >= 70) mentalMode = '🚑 救赎模式 (HUMBLE_RECOVERY)';
@@ -136,6 +139,7 @@ export function handlePainCommand(ctx: PluginCommandContext): PluginCommandResul
     }
     
     // Determine health status based on GFI
+    // eslint-disable-next-line no-useless-assignment -- Reason: initial values unused due to immediate reassignment in all branches
     let healthLabel = 'Healthy';
     let suggestionText = '';
 
@@ -214,6 +218,7 @@ export function handlePainCommand(ctx: PluginCommandContext): PluginCommandResul
 /**
  * Handle /pd-status empathy subcommand
  */
+// eslint-disable-next-line @typescript-eslint/max-params -- Reason: empathy subcommand requires all 4 context params - refactoring would break API
 function handleEmpathySubcommand(
     wctx: WorkspaceContext,
     args: string,

package/src/commands/principle-rollback.ts

@@ -1,4 +1,4 @@
-import { EvolutionReducerImpl } from '../core/evolution-reducer.js';
+import { WorkspaceContext } from '../core/workspace-context.js';
 import type { PluginCommandContext } from '../openclaw-sdk.js';
 
 export function handlePrincipleRollbackCommand(ctx: PluginCommandContext): { text: string } {
@@ -12,7 +12,9 @@ export function handlePrincipleRollbackCommand(ctx: PluginCommandContext): { tex
     return { text: isZh ? '用法: /pd-principle-rollback <principleId> [reason]' : 'Usage: /pd-principle-rollback <principleId> [reason]' };
   }
 
-  const reducer = new EvolutionReducerImpl({ workspaceDir });
+  // #207/#210: Use WorkspaceContext to get evolutionReducer with stateDir
+  const wctx = WorkspaceContext.fromHookContext({ workspaceDir });
+  const reducer = wctx.evolutionReducer;
   const principle = reducer.getPrincipleById(principleId);
   if (!principle) {
     return { text: isZh ? `未找到原则: ${principleId}` : `Principle not found: ${principleId}` };

package/src/commands/promote-impl.ts

@@ -0,0 +1,274 @@
+/**
+ * Promote Implementation Command — CLI `/pd-promote-impl`
+ * ========================================================
+ *
+ * PURPOSE: Manually promote a candidate implementation to active status
+ * after replay evaluation review.
+ *
+ * FLOW:
+ *   1. List candidates with replay reports
+ *   2. Show replay report summary for selected candidate
+ *   3. Ask for confirmation
+ *   4. On confirm: transition candidate->active, demote previous active->disabled
+ *
+ * VALIDATION:
+ *   - Candidate must have at least one replay report with 'pass' decision
+ *   - Only candidate -> active is valid for promotion
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { ReplayEngine, formatReplayReport } from '../core/replay-engine.js';
+import { refreshPrincipleLifecycle } from '../core/principle-internalization/lifecycle-refresh.js';
+import {
+  findActiveImplementation,
+  loadLedger,
+  transitionImplementationState,
+  updateImplementation,
+} from '../core/principle-tree-ledger.js';
+import { WorkspaceContext } from '../core/workspace-context.js';
+import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
+import type { Implementation } from '../types/principle-tree-schema.js';
+import { withLock } from '../utils/file-lock.js';
+
+function getAllImplementations(stateDir: string): Implementation[] {
+  const ledger = loadLedger(stateDir);
+  return Object.values(ledger.tree.implementations);
+}
+
+function _handleListCandidates(
+  stateDir: string,
+  isZh: boolean,
+): PluginCommandResult {
+  const engine = new ReplayEngine('', stateDir);
+  const allImpls = getAllImplementations(stateDir);
+  const candidates = allImpls.filter(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Reason: lifecycleState is a dynamic property added by the system - type not in official interface
+    (impl) => (impl as any).lifecycleState === 'candidate',
+  );
+
+  if (candidates.length === 0) {
+    return {
+      text: isZh
+        ? '\nℹ️ 未找到候选实现。\n\n用法: /pd-promote-impl list'
+        : '\nℹ️ No candidate implementations found.\n\nUsage: /pd-promote-impl list',
+    };
+  }
+
+  let output = isZh ? '\n📋 候选实现列表\n' : '\n📋 Candidate Implementations\n';
+  output += `${'='.repeat(50)}\n`;
+
+  for (const impl of candidates) {
+    const hasPass = engine.hasPassingReport(impl.id);
+    const passBadge = hasPass
+      ? isZh ? '✅ 有通过报告' : '✅ Has pass report'
+      : isZh ? '❌ 无通过报告' : '❌ No pass report';
+    output += `  ${impl.id}\n`;
+    output += `    Rule: ${impl.ruleId} | Version: ${impl.version}\n`;
+    output += `    Replay: ${passBadge}\n\n`;
+  }
+
+  return { text: output };
+}
+
+function _handleShowReport(
+  stateDir: string,
+  implId: string,
+  isZh: boolean,
+): PluginCommandResult {
+  const engine = new ReplayEngine('', stateDir);
+  const report = engine.getLatestReport(implId);
+
+  if (!report) {
+    return {
+      text: isZh
+        ? `❌ 实现 ${implId} 没有回放报告。`
+        : `❌ No replay report found for implementation ${implId}.`,
+    };
+  }
+
+  return { text: formatReplayReport(report) };
+}
+
+interface RunReplayOptions {
+  workspaceDir: string;
+  stateDir: string;
+  implId: string;
+  isZh: boolean;
+}
+
+function _handleRunReplay(options: RunReplayOptions): PluginCommandResult {
+  const { workspaceDir, stateDir, implId, isZh } = options;
+  const engine = new ReplayEngine(workspaceDir, stateDir);
+
+  try {
+    const report = engine.runReplayForImplementation(implId);
+    let text = formatReplayReport(report);
+    if (report.sampleFingerprints.length === 0) {
+      text += isZh
+        ? '\n⚠️ 未找到已分类的 replay 样本。报告已生成，但当前结果只反映空样本集。\n'
+        : '\n⚠️ No classified replay samples were found. The report was generated, but it only reflects an empty sample set.\n';
+    }
+    return { text };
+  } catch (error: unknown) {
+    return {
+      text: isZh
+        ? `❌ 回放评估失败: ${String(error)}`
+        : `❌ Replay evaluation failed: ${String(error)}`,
+    };
+  }
+}
+
+interface PromoteImplOptions {
+  workspaceDir: string;
+  stateDir: string;
+  implId: string;
+  isZh: boolean;
+}
+
+function _handlePromoteImpl(options: PromoteImplOptions): PluginCommandResult {
+  const { workspaceDir, stateDir, implId, isZh } = options;
+  const engine = new ReplayEngine('', stateDir);
+  const allImpls = getAllImplementations(stateDir);
+  const candidate = allImpls.find((i) => i.id === implId);
+
+  if (!candidate) {
+    return {
+      text: isZh
+        ? `❌ 未找到实现: ${implId}`
+        : `❌ Implementation not found: ${implId}`,
+    };
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Reason: lifecycleState is a dynamic property added by the system - type not in official interface
+  const currentState = (candidate as any).lifecycleState || 'candidate';
+
+  if (currentState !== 'candidate' && currentState !== 'disabled') {
+    return {
+      text: isZh
+        ? `❌ 只能晋升 candidate 或 disabled 状态的实现。当前: ${currentState}`
+        : `❌ Can only promote 'candidate' or 'disabled' implementations. Current: ${currentState}`,
+    };
+  }
+
+  if (!engine.hasPassingReport(implId)) {
+    return {
+      text: isZh
+        ? `❌ 实现 ${implId} 没有通过的回放报告，无法晋升。\n\n请先运行回放评估。`
+        : `❌ Implementation ${implId} has no passing replay report. Promotion rejected.\n\nPlease run a replay evaluation first.`,
+    };
+  }
+
+  const report = engine.getLatestReport(implId);
+  let output = '';
+  if (report) {
+    output = `${formatReplayReport(report)}\n`;
+  }
+
+  if (currentState === 'disabled') {
+    transitionImplementationState(stateDir, implId, 'active');
+    updateImplementation(stateDir, implId, {
+      disabledAt: undefined,
+      disabledBy: undefined,
+      disabledReason: undefined,
+    });
+    refreshPrincipleLifecycle(workspaceDir, stateDir);
+
+    output += isZh
+      ? `\n✅ 实现已重新启用: ${implId}\n   状态: disabled -> active`
+      : `\n✅ Implementation re-enabled: ${implId}\n   State: disabled -> active`;
+
+    return { text: output };
+  }
+
+  const activeForRule = findActiveImplementation(stateDir, candidate.ruleId);
+
+  if (activeForRule) {
+    updateImplementation(stateDir, implId, {
+      previousActive: activeForRule.id,
+    });
+  }
+
+  transitionImplementationState(stateDir, implId, 'active');
+
+  if (activeForRule) {
+    transitionImplementationState(stateDir, activeForRule.id, 'disabled');
+
+    output += isZh
+      ? `\n上一个活跃实现已禁用: ${activeForRule.id}\n   状态: active -> disabled`
+      : `\nPrevious active implementation disabled: ${activeForRule.id}\n   State: active -> disabled`;
+  }
+
+  const eventsDir = path.join(
+    stateDir,
+    'principles',
+    'implementations',
+    implId,
+    'events',
+  );
+  if (!fs.existsSync(eventsDir)) {
+    fs.mkdirSync(eventsDir, { recursive: true });
+  }
+  const eventPath = path.join(eventsDir, 'promotion.json');
+  const promotionEvent = {
+    eventType: 'promotion',
+    implementationId: implId,
+    ruleId: candidate.ruleId,
+    fromState: 'candidate',
+    toState: 'active',
+    previousActive: activeForRule?.id ?? null,
+    replayReportId: report
+      ? report.generatedAt.replace(/[:.]/g, '-')
+      : null,
+    promotedAt: new Date().toISOString(),
+  };
+  withLock(eventPath, () => {
+    fs.writeFileSync(eventPath, JSON.stringify(promotionEvent, null, 2), 'utf-8');
+  });
+  refreshPrincipleLifecycle(workspaceDir, stateDir);
+
+  output += isZh
+    ? `\n\n✅ 实现已晋升: ${implId}\n   状态: candidate -> active`
+    : `\n\n✅ Implementation promoted: ${implId}\n   State: candidate -> active`;
+
+  return { text: output };
+}
+
+export function handlePromoteImplCommand(ctx: PluginCommandContext): PluginCommandResult {
+  const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+  const {stateDir} = WorkspaceContext.fromHookContext({ ...ctx, workspaceDir });
+  const lang = (ctx.config?.language as string) || 'en';
+  const isZh = lang === 'zh';
+
+  const args = (ctx.args || '').trim().split(/\s+/);
+  const subcommand = args[0] || '';
+  const implId = args[1] || '';
+
+  if (subcommand === 'list' || subcommand === '') {
+    return _handleListCandidates(stateDir, isZh);
+  }
+
+  if (subcommand === 'show') {
+    if (!implId) {
+      return {
+        text: isZh
+          ? '请指定要查看的实现ID: /pd-promote-impl show <implId>'
+          : 'Please specify an implementation ID: /pd-promote-impl show <implId>',
+      };
+    }
+    return _handleShowReport(stateDir, implId, isZh);
+  }
+
+  if (subcommand === 'eval') {
+    if (!implId) {
+      return {
+        text: isZh
+          ? '请指定要评估的实现ID: /pd-promote-impl eval <implId>'
+          : 'Please specify an implementation ID: /pd-promote-impl eval <implId>',
+      };
+    }
+    return _handleRunReplay({ workspaceDir, stateDir, implId, isZh });
+  }
+
+  return _handlePromoteImpl({ workspaceDir, stateDir, implId: subcommand, isZh });
+}