create-principles-disciple 1.144.11 → 1.144.13

package/pd-cli/dist/commands/candidate.js

@@ -1,19 +1,27 @@
 /**
- * pd candidate commands — Principle candidate inspection, intake, audit, repair.
+ * pd candidate commands — Principle candidate inspection, intake, audit, repair, reuse review.
  *
  * Usage:
  *   pd candidate list --task-id <taskId> --workspace <path> [--json]
  *   pd candidate show <candidateId> --workspace <path> [--json]
  *   pd candidate intake --candidate-id <id> [--workspace <path>] [--json] [--dry-run]
+ *   pd candidate review --candidate-id <id> [--workspace <path>] [--json]
+ *   pd candidate review --candidate-id <id> --decide reuse --principle-id <id> --reason "..." [--json]
+ *   pd candidate review --candidate-id <id> --decide create --reason "..." [--json]
  *   pd candidate audit --workspace <path> [--json]
  *   pd candidate repair --candidate-id <id> --workspace <path> [--json]
  *   pd candidate route --candidate-id <id> --workspace <path> [--json]
  */
 import { randomUUID } from 'crypto';
 import * as path from 'path';
-import { RuntimeStateManager, SqliteConnection, candidateList, candidateShow, CandidateIntakeService, CandidateIntakeError, INTAKE_ERROR_CODES, decideInternalizationRoute, buildDreamerSeedFromCandidate, findExistingDreamerTask, parseSeedSourcePainId, PrincipleTreeLedgerAdapter, } from '@principles/core/runtime-v2';
+import { RuntimeStateManager, SqliteConnection, candidateList, candidateShow, CandidateIntakeService, CandidateIntakeError, INTAKE_ERROR_CODES, decideInternalizationRoute, buildDreamerSeedFromCandidate, findExistingDreamerTask, parseSeedSourcePainId, PrincipleTreeLedgerAdapter, 
+// PRI-917 PR3A: the review surface consumes the SAME proposal/semantics
+// machinery as the intake gate (audit C4 — one implementation, no drift).
+buildReuseProposal, buildReuseShortlist, extractIntakeRecommendation, isPrincipleLedgerEligibleKind, resolveOwnerIdentity, defaultOwnerIdentityHomeDir, ReuseEvaluationRunner, ReuseEvaluationError, storeEmitter, } from '@principles/core/runtime-v2';
 import { loadLedger, getLedgerFilePathPublic } from '@principles/core/principle-tree-ledger';
 import { resolveWorkspaceDir } from '../resolve-workspace.js';
+import { loadPdConfig } from '../services/pd-config-loader.js';
+import { resolveRuntimeAdapterFromConfig } from '../services/runtime-adapter-resolver.js';
 import { resolvePromptFullPipelineSeedMode } from '../services/pd-config-loader.js';
 import { createRemediationResult, remediationAction } from './remediation-output.js';
 import { checkAdmissionGate } from './admission-gate.js';
@@ -380,6 +388,243 @@ export async function handleCandidateShow(opts) {
     }
 }
 // ── Intake ───────────────────────────────────────────────────────────────────
+// ── Shared intake/decision finalizers (PRI-917 PR3A) ─────────────────────────
+/**
+ * PRI-917 PR3A (surface audit C2): unify the candidate terminal state after a
+ * successful ledger write OR a recorded reuse resolution — always through the
+ * guarded {@link updateCandidateStatus} (optimistic pending→consumed +
+ * consumed_at), never bypassing the existing mechanism (SPEC §13: the
+ * candidate still reaches `consumed`).
+ *
+ * Returns 'already_consumed' when the candidate was consumed before this call
+ * (e.g. an INV-R07 replay). Exits non-zero on a guarded-transition failure —
+ * the ledger/LEDGER fact is already durable, so the inconsistency must be
+ * loud (same posture as the pre-PR3A intake path).
+ */
+async function markCandidateConsumed(stateManager, candidateId, ledgerFact) {
+    const candidate = await stateManager.getCandidate(candidateId);
+    if (candidate?.status === 'consumed') {
+        return 'already_consumed';
+    }
+    try {
+        await updateCandidateStatus({ stateManager, candidateId, targetStatus: 'consumed', expectedCurrentStatus: 'pending' });
+    }
+    catch (err) {
+        const msg = `The ledger fact is durable (${ledgerFact}) but the candidate status update failed: ${err instanceof Error ? err.message : String(err)}. ` +
+            `Candidate ${candidateId} may be in inconsistent state.`;
+        console.error(`ERROR: ${msg}`);
+        process.exit(1);
+    }
+    return 'consumed';
+}
+/**
+ * PRI-917 PR3A (surface audit C1/C2): report a `reuse_selected` intake result
+ * as the SUCCESS it is — resolution + selected Principle + evidence, exit 0 —
+ * and unify the candidate terminal state (C2). Used by BOTH `pd candidate
+ * intake` (replay path) and `pd candidate review --decide reuse` (fresh
+ * decision). The CLI prints the durable fact; it does not create one.
+ */
+async function reportReuseResolution(opts) {
+    const { stateManager, candidateId, result, json } = opts;
+    if (!result.selectedPrincipleId || !result.reuseEvidence) {
+        // Adapter/service contract violation — never print a hollow resolution.
+        throw new CandidateIntakeError(INTAKE_ERROR_CODES.INPUT_INVALID, `reuse_selected result for candidate ${candidateId} is missing selectedPrincipleId/reuseEvidence (contract violation)`, { candidateId, reason: 'reuse_resolution_contract_violation' });
+    }
+    const consumedState = await markCandidateConsumed(stateManager, candidateId, `reuse evidence on ${result.selectedPrincipleId}`);
+    const replayed = result.reuseProposal === undefined;
+    const resolution = {
+        candidateId,
+        status: 'reused',
+        selectedPrincipleId: result.selectedPrincipleId,
+        reuseEvidence: result.reuseEvidence,
+        replayed,
+        candidateStatus: consumedState,
+        message: result.message,
+    };
+    if (json) {
+        console.log(JSON.stringify(resolution, null, 2));
+        return;
+    }
+    console.log(`\nPrinciple Candidate Reuse: ${candidateId}\n`);
+    console.log(`  Candidate:         ${candidateId}`);
+    console.log(`  Reused Principle:  ${result.selectedPrincipleId}`);
+    console.log(`  Pain:              ${result.reuseEvidence.painId}`);
+    console.log(`  Decided By:        ${result.reuseEvidence.actor.kind} ${result.reuseEvidence.actor.id}`);
+    console.log(`  Decided At:        ${result.reuseEvidence.decidedAt}`);
+    console.log(`  Reason:            ${result.reuseEvidence.reason}`);
+    console.log(`  Candidate Status:  ${consumedState === 'already_consumed' ? 'already consumed (INV-R07 replay)' : 'consumed'}`);
+    console.log('  Evidence:          recorded on the Principle\'s reuseEvidence (append-only)\n');
+}
+async function evaluateReuseProposal(workspaceDir, claim, entries) {
+    const configLoad = loadPdConfig(workspaceDir);
+    const effective = configLoad.ok ? configLoad.effective : configLoad.defaults;
+    const capability = effective.config.reuseEvaluation;
+    if (!capability?.enabled) {
+        return null;
+    }
+    if (entries.length === 0) {
+        // Case A (SPEC §6): nothing credible was found — there is nothing to
+        // evaluate, and intake proceeds to create without an Owner decision.
+        return null;
+    }
+    // PRI-917 review (P2): timeout precedence — capability.timeoutMs wins,
+    // otherwise the resolved PROFILE's own timeout (its documented default),
+    // otherwise the runner's built-in default.
+    const capabilityProfile = effective.config.runtimeProfiles[capability.runtimeProfile ?? ''];
+    const profileTimeoutMs = capabilityProfile?.type === 'pi-ai' ? capabilityProfile.timeoutMs : undefined;
+    try {
+        const adapter = resolveRuntimeAdapterFromConfig({
+            runtimeKind: 'config',
+            workspaceDir,
+            runtimeProfileId: capability.runtimeProfile,
+        });
+        const runner = new ReuseEvaluationRunner({ runtimeAdapter: adapter }, { ...(capability.timeoutMs !== undefined ? { timeoutMs: capability.timeoutMs } : { ...(profileTimeoutMs !== undefined ? { timeoutMs: profileTimeoutMs } : {}) }) });
+        const output = await runner.recommend({
+            candidate: claim,
+            candidates: entries.map((entry) => ({
+                principleId: entry.principleId,
+                text: entry.existingPrinciple.text,
+                triggerPattern: entry.existingPrinciple.triggerPattern,
+                action: entry.existingPrinciple.action,
+            })),
+        });
+        // PRI-917 review (P2): the validator deliberately does NOT check id
+        // existence (INV-R08 lives one layer up, against the REAL shortlist).
+        // This is that layer: a hallucinated/foreign id must not reach the Owner
+        // as an executable-looking recommendation.
+        if (output.recommendation === 'reuse') {
+            const inShortlist = entries.some((entry) => entry.principleId === output.selectedPrincipleId);
+            if (!inShortlist) {
+                return {
+                    status: 'unavailable',
+                    reason: `selected_principle_not_in_shortlist:${output.selectedPrincipleId ?? '(absent)'}`,
+                };
+            }
+        }
+        return {
+            status: 'recommended',
+            recommendation: output.recommendation,
+            ...(output.selectedPrincipleId !== undefined ? { selectedPrincipleId: output.selectedPrincipleId } : {}),
+            rationale: output.rationale,
+            confidence: output.confidence,
+        };
+    }
+    catch (err) {
+        const reason = err instanceof ReuseEvaluationError
+            ? `${err.reason}: ${err.detail ?? err.message}`
+            : err instanceof Error
+                ? err.message
+                : String(err);
+        return { status: 'unavailable', reason };
+    }
+}
+/**
+ * Decision mode of {@link handleCandidateReview}: validate the CLI contract
+ * (rc-3), resolve the Owner identity (fail-closed), then run the EXISTING
+ * intake chain with the §11 verdict injected. No CLI-side persistence.
+ */
+async function executeOwnerDecision(deps) {
+    const { opts, stateManager, ledgerAdapter, stateDir } = deps;
+    const failCli = (message, nextAction) => {
+        if (opts.json) {
+            console.log(JSON.stringify({ candidateId: opts.candidateId, status: 'refused', decision: opts.decide, error: message, nextAction }, null, 2));
+        }
+        else {
+            console.error(`ERROR: ${message}`);
+            console.error(`  Next Action: ${nextAction}`);
+        }
+        process.exit(1);
+    };
+    if (typeof opts.reason !== 'string' || opts.reason.trim() === '') {
+        failCli('--reason is required with --decide (the evidence entry must record why the Owner resolved this candidate)', 'Re-run with --reason "..." (non-empty).');
+    }
+    if (opts.decide === 'reuse' && (typeof opts.principleId !== 'string' || opts.principleId.trim() === '')) {
+        failCli('--principle-id is required with --decide reuse', 'Re-run with --principle-id <id from the review proposal>.');
+    }
+    // Owner identity: env > ~/.pd/owner.json > none (ADR-0022 resolver).
+    const identity = resolveOwnerIdentity(process.env, defaultOwnerIdentityHomeDir());
+    if ((identity.source !== 'env' && identity.source !== 'file') || !identity.ownerId) {
+        failCli(`Owner identity is required to record a ${opts.decide} decision (identity source: ${identity.source})${identity.error ? `: ${identity.error}` : ''}`, 'Register the Owner identity file (~/.pd/owner.json) or set PD_OWNER_ID and PD_OWNER_CREDENTIAL_ID together, then retry.');
+    }
+    const decision = opts.decide === 'reuse'
+        ? {
+            decision: 'reuse',
+            selectedPrincipleId: opts.principleId,
+            actor: { kind: 'owner', id: identity.ownerId },
+            reason: opts.reason,
+            decidedAt: new Date().toISOString(),
+        }
+        : { decision: 'create' };
+    // INV-R08: verify the selected principle is in the current proposal.
+    // This prevents a stale or empty proposal from silently degrading reuse
+    // into create.
+    if (opts.decide === 'reuse') {
+        const candidate = await stateManager.getCandidate(opts.candidateId);
+        const artifact = candidate ? await stateManager.getArtifact(candidate.artifactId) : null;
+        const extracted = candidate ? extractIntakeRecommendation(candidate, artifact) : null;
+        if (!candidate || !extracted || !extracted.ok) {
+            failCli('Cannot build the reuse proposal for this candidate', 'Run `pd candidate review --candidate-id <id>` first.');
+            return;
+        }
+        const proposal = buildReuseProposal(opts.candidateId, buildReuseShortlist({
+            text: extracted.recommendation.text || candidate.description || '',
+            triggerPattern: extracted.recommendation.triggerPattern ?? '',
+            action: extracted.recommendation.action ?? '',
+        }, stateDir, { recommendationKind: candidate.rawRecommendationKind }));
+        if (!proposal.candidates.some((c) => c.principleId === opts.principleId)) {
+            failCli(`Principle ${opts.principleId} is not in the current reuse proposal`, 'Re-run `pd candidate review` to see the current proposal.');
+        }
+    }
+    const service = new CandidateIntakeService({
+        stateManager,
+        ledgerAdapter,
+        // The verdict is fixed by the CLI invocation; the intake gate still
+        // validates it (rc-1/rc-2/rc-3) and checks the selection against the
+        // proposal (INV-R08) — the CLI cannot smuggle a decision past the gate.
+        reuseDecision: () => decision,
+        reuseStateDir: stateDir,
+    });
+    const intakeResult = await service.intake(opts.candidateId);
+    if (intakeResult.outcome === 'refused' && intakeResult.reason === 'reuse_selected') {
+        await reportReuseResolution({ stateManager, candidateId: opts.candidateId, result: intakeResult, json: opts.json === true });
+        return;
+    }
+    if (intakeResult.outcome === 'refused') {
+        // A non-principle kind or unknown kind cannot carry a reuse decision.
+        throw new CandidateIntakeError(INTAKE_ERROR_CODES.INPUT_INVALID, `Principle Ledger write refused: ${intakeResult.message}`, { candidateId: opts.candidateId, reason: intakeResult.reason });
+    }
+    // create verdict (or gate absent shapes) — same durable outcome as intake.
+    const { entry } = intakeResult;
+    const consumedState = await markCandidateConsumed(stateManager, opts.candidateId, entry.id);
+    if (consumedState === 'already_consumed') {
+        // Consumed before this call — the ledger entry is identical by intake
+        // idempotency; report it like `pd candidate intake` does.
+        const infoMessage = `Candidate ${opts.candidateId} was already consumed. Ledger entry: ${entry.id}`;
+        if (opts.json) {
+            console.log(JSON.stringify({ candidateId: opts.candidateId, ledgerEntryId: entry.id, status: 'already_consumed', message: infoMessage }, null, 2));
+        }
+        else {
+            console.log(infoMessage);
+        }
+        return;
+    }
+    const result = {
+        candidateId: opts.candidateId,
+        decision: opts.decide,
+        ledgerEntryId: entry.id,
+        status: 'consumed',
+    };
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(`\nPrinciple Candidate Decision: ${opts.candidateId}\n`);
+    console.log(`  Decision:     ${opts.decide}`);
+    console.log(`  Candidate:    ${opts.candidateId}`);
+    console.log(`  Ledger Entry: ${entry.id}`);
+    console.log(`  Status:       consumed\n`);
+    console.log('Decision complete.\n');
+}
 /**
  * pd candidate intake --candidate-id <id> [--workspace <path>] [--json] [--dry-run]
  *
@@ -465,12 +710,22 @@ export async function handleCandidateIntake(opts) {
         // candidate id, so a Principle Ledger write boundary refusal is surfaced
         // loudly (never silently swallowed) instead of being treated as success.
         const intakeResult = await service.intake(opts.candidateId);
+        if (intakeResult.outcome === 'refused' && intakeResult.reason === 'reuse_selected') {
+            // PRI-917 PR3A (surface audit C1/C2): a recorded reuse resolution is a
+            // SUCCESS, not a failure — the evidence is already durable on the
+            // selected Principle (fresh decision) or was recorded earlier (INV-R07
+            // replay via intake step 2b, which is how this branch is reachable from
+            // the gate-less intake command). Report the resolution, unify the
+            // candidate terminal state with the automatic paths (SPEC §13), exit 0.
+            await reportReuseResolution({ stateManager, candidateId: opts.candidateId, result: intakeResult, json: opts.json === true });
+            return;
+        }
         if (intakeResult.outcome === 'refused') {
             throw new CandidateIntakeError(INTAKE_ERROR_CODES.INPUT_INVALID, `Principle Ledger write refused: ${intakeResult.message}`, { candidateId: opts.candidateId, reason: intakeResult.reason });
         }
         const { entry } = intakeResult;
-        // Check if already consumed before this call
-        if (candidate?.status === 'consumed') {
+        const consumedState = await markCandidateConsumed(stateManager, opts.candidateId, entry.id);
+        if (consumedState === 'already_consumed') {
             const infoMessage = `Candidate ${opts.candidateId} was already consumed. Ledger entry: ${entry.id}`;
             if (opts.json) {
                 console.log(JSON.stringify({
@@ -485,16 +740,6 @@ export async function handleCandidateIntake(opts) {
             }
             return;
         }
-        // Update DB status — this must succeed; if it fails, exit non-zero
-        try {
-            await updateCandidateStatus({ stateManager, candidateId: opts.candidateId, targetStatus: 'consumed', expectedCurrentStatus: 'pending' });
-        }
-        catch (err) {
-            const msg = `Ledger write succeeded (entry ${entry.id}) but DB status update failed: ${err instanceof Error ? err.message : String(err)}. ` +
-                `Candidate ${opts.candidateId} may be in inconsistent state.`;
-            console.error(`ERROR: ${msg}`);
-            process.exit(1);
-        }
         const result = {
             candidateId: opts.candidateId,
             ledgerEntryId: entry.id,
@@ -526,6 +771,255 @@ export async function handleCandidateIntake(opts) {
         await stateManager.close();
     }
 }
+/**
+ * pd candidate review — PRI-917 PR3A Owner decision surface (SPEC §18).
+ *
+ * Phase 1 (read-only): shows the candidate and the deterministic Top-K reuse
+ * proposal (score, reasons/shared terms, and the existing Principle's text /
+ * triggerPattern / action / status) so the Owner can decide with the same
+ * information the gate will consume.
+ *
+ * Phase 2 (`--decide`): constructs the SPEC §11 verdict (actor from
+ * resolveOwnerIdentity — fail-closed when unresolvable) and injects it into
+ * CandidateIntakeService, which runs the EXISTING gate → appendReuseEvidence
+ * chain. The CLI is an interaction layer only: it never writes reuseEvidence,
+ * decision files, or any other state (SPEC §18 — the only durable authority
+ * is `Principle.reuseEvidence[]`).
+ */
+export async function handleCandidateReview(opts) {
+    const workspaceDir = resolveWorkspaceDir(opts.workspace);
+    const stateManager = new RuntimeStateManager({ workspaceDir });
+    try {
+        await stateManager.initialize();
+        const stateDir = path.join(workspaceDir, '.state');
+        const ledgerAdapter = new PrincipleTreeLedgerAdapter({ stateDir });
+        const candidate = await stateManager.getCandidate(opts.candidateId);
+        if (!candidate) {
+            console.error(`Candidate not found: ${opts.candidateId}`);
+            process.exit(1);
+            return;
+        }
+        if (opts.decide === 'reuse' || opts.decide === 'create') {
+            // PRI-442 Stage 4: admission gate check — same as handleCandidateIntake.
+            // Prevents CLI from bypassing the production admission gate.
+            //
+            // PRI-917 v0.3.3 (R5 F4 two-heads-block fix): the pre-check does NOT
+            // apply to a `reuse` verdict. Admission confidence protects the LEDGER
+            // from low-quality NEW principles; a reuse decision creates nothing — it
+            // appends one auditable evidence entry to an EXISTING principle whose
+            // recurrence is itself the proof of value. Blocking it here left every
+            // low-confidence historical candidate permanently undecidable while the
+            // auto path consumed high-confidence ones before any Owner could ask.
+            // `create` keeps the pre-check: a low-confidence candidate still cannot
+            // become a new Principle via the CLI.
+            if (opts.decide === 'create') {
+                const admissionBlock = checkAdmissionGate(candidate);
+                if (admissionBlock) {
+                    const payload = {
+                        candidateId: opts.candidateId,
+                        status: 'refused',
+                        admissionDecision: admissionBlock.decision,
+                        reason: admissionBlock.reason,
+                        nextAction: admissionBlock.nextAction,
+                    };
+                    if (opts.json) {
+                        console.log(JSON.stringify(payload, null, 2));
+                    }
+                    else {
+                        console.error(`Admission gate refused candidate ${opts.candidateId}: ${admissionBlock.decision}`);
+                        console.error(`  Reason:      ${admissionBlock.reason}`);
+                        console.error(`  Next Action: ${admissionBlock.nextAction}`);
+                    }
+                    process.exit(1);
+                    return;
+                }
+            }
+            // opts.decide is narrowed here — no cast needed to build the decision-mode shape.
+            await executeOwnerDecision({ opts: { ...opts, decide: opts.decide }, stateManager, ledgerAdapter, stateDir });
+            return;
+        }
+        // ── Read-only proposal view ──
+        const rawKindEligible = isPrincipleLedgerEligibleKind(candidate.rawRecommendationKind);
+        if (!rawKindEligible) {
+            // Fail closed like the intake boundary: a non-principle candidate never
+            // reaches the reuse gate, so reviewing a proposal for it would lie.
+            const rawKind = typeof candidate.rawRecommendationKind === 'string' ? candidate.rawRecommendationKind : null;
+            const payload = {
+                candidateId: opts.candidateId,
+                recommendationKindEligible: false,
+                rawRecommendationKind: rawKind,
+                message: `Candidate ${opts.candidateId} has recommendation_kind '${rawKind ?? 'absent'}' which does not target the Principle Ledger; there is no reuse proposal to review.`,
+                nextAction: 'Run `pd candidate route --candidate-id <id>` for this candidate\'s internalization route instead.',
+            };
+            if (opts.json) {
+                console.log(JSON.stringify(payload, null, 2));
+                return;
+            }
+            console.log(`\nPrinciple Candidate Review: ${opts.candidateId}\n`);
+            console.log(`  Kind:         ${rawKind ?? 'absent'} (not Principle-Ledger eligible)`);
+            console.log(`  ${payload.message}`);
+            console.log(`  Next Action:  ${payload.nextAction}\n`);
+            return;
+        }
+        const artifact = await stateManager.getArtifact(candidate.artifactId);
+        if (!artifact) {
+            console.error(`Artifact not found for candidate: ${opts.candidateId} (artifact ${candidate.artifactId})`);
+            process.exit(1);
+            return;
+        }
+        // C4: the SAME extraction intake uses (4b/4c) — never a second parser.
+        const extracted = extractIntakeRecommendation(candidate, artifact);
+        if (!extracted.ok) {
+            throw extracted.error;
+        }
+        const { recommendation } = extracted;
+        const shortlist = buildReuseShortlist({
+            text: recommendation.text || candidate.description || '',
+            triggerPattern: recommendation.triggerPattern ?? '',
+            action: recommendation.action ?? '',
+        }, stateDir, { recommendationKind: candidate.rawRecommendationKind });
+        const proposal = buildReuseProposal(opts.candidateId, shortlist);
+        // Enrich each entry with the existing Principle's durable content.
+        const ledger = loadLedger(stateDir);
+        const entries = proposal.candidates.map((entry) => {
+            const principle = ledger.tree.principles[entry.principleId];
+            return {
+                principleId: entry.principleId,
+                score: entry.score,
+                reasons: entry.reasons,
+                existingPrinciple: principle
+                    ? { text: principle.text, triggerPattern: principle.triggerPattern, action: principle.action, status: principle.status }
+                    : { text: '', triggerPattern: '', action: '', status: 'missing' },
+            };
+        });
+        // PRI-917 v0.3.2 (Phase 3C-4): run the Semantic Reuse Evaluation
+        // Capability as a DISPLAY enhancement on the read-only review path. Its
+        // output is a RECOMMENDATION for the Owner — it never decides, never
+        // writes, and its failure degrades observably to lexical-only (SPEC §9).
+        const evaluation = await evaluateReuseProposal(workspaceDir, {
+            text: recommendation.text || candidate.description || '',
+            triggerPattern: recommendation.triggerPattern ?? '',
+            action: recommendation.action ?? '',
+        }, entries);
+        // PRI-917 v0.3.2 §11: the events are OBSERVATION ONLY. They record what
+        // the capability recommended; they are never decision storage (the
+        // Owner's verdict lives exclusively in Principle.reuseEvidence[]) and
+        // no intake outcome reads them. Emitted only when the capability
+        // actually ran (disabled or nothing-to-evaluate emits nothing).
+        if (evaluation !== null) {
+            const timestamp = new Date().toISOString();
+            if (evaluation.status === 'recommended') {
+                storeEmitter.emitTelemetry({
+                    eventType: 'reuse_evaluation_recommended',
+                    traceId: opts.candidateId,
+                    timestamp,
+                    sessionId: 'pd-cli-review',
+                    agentId: 'reuse-evaluation',
+                    payload: {
+                        candidateId: opts.candidateId,
+                        recommendation: evaluation.recommendation,
+                        ...(evaluation.selectedPrincipleId !== undefined ? { selectedPrincipleId: evaluation.selectedPrincipleId } : {}),
+                        confidence: evaluation.confidence,
+                    },
+                });
+            }
+            else {
+                storeEmitter.emitTelemetry({
+                    eventType: 'reuse_evaluation_unavailable',
+                    traceId: opts.candidateId,
+                    timestamp,
+                    sessionId: 'pd-cli-review',
+                    agentId: 'reuse-evaluation',
+                    payload: {
+                        candidateId: opts.candidateId,
+                        reason: evaluation.reason.slice(0, 200),
+                    },
+                });
+            }
+        }
+        const nextAction = entries.length > 0
+            ? `pd candidate review --candidate-id ${opts.candidateId} --decide reuse --principle-id <id> --reason "..." (or --decide create --reason "...")`
+            : `No credible reuse proposal — intake will create a new Principle: pd candidate intake --candidate-id ${opts.candidateId} --workspace "${workspaceDir}"`;
+        if (opts.json) {
+            console.log(JSON.stringify({
+                candidateId: opts.candidateId,
+                title: candidate.title,
+                description: candidate.description,
+                status: candidate.status,
+                taskId: candidate.taskId,
+                recommendationKindEligible: true,
+                claim: { text: recommendation.text || candidate.description || '', triggerPattern: recommendation.triggerPattern ?? '', action: recommendation.action ?? '' },
+                proposal: {
+                    status: proposal.status,
+                    eligibleCount: proposal.eligibleCount,
+                    candidates: entries.map((entry) => ({
+                        ...entry,
+                        semanticMatch: evaluation?.status === 'recommended'
+                            && evaluation.recommendation === 'reuse'
+                            && evaluation.selectedPrincipleId === entry.principleId,
+                    })),
+                },
+                ...(evaluation ? { evaluation } : {}),
+                nextAction,
+            }, null, 2));
+            return;
+        }
+        console.log(`\nPrinciple Candidate Review: ${opts.candidateId}\n`);
+        console.log(`  Title:        ${candidate.title}`);
+        console.log(`  Description:  ${candidate.description}`);
+        console.log(`  Status:       ${candidate.status}`);
+        console.log(`  Task:         ${candidate.taskId}`);
+        console.log(`  Claim:        ${recommendation.text || candidate.description || ''}`);
+        console.log(`  Trigger:      ${recommendation.triggerPattern ?? ''}`);
+        console.log(`  Action:       ${recommendation.action ?? ''}`);
+        console.log(`\n  Reuse Proposal (${entries.length} of ${proposal.eligibleCount} eligible, Top-3):\n`);
+        if (entries.length === 0) {
+            console.log('    No credible existing Principle found — the intake gate will create a new one.\n');
+        }
+        entries.forEach((entry, index) => {
+            console.log(`    ${index + 1}. ${entry.principleId}  (score ${entry.score.toFixed(3)})`);
+            for (const reason of entry.reasons) {
+                console.log(`       reason: ${reason}`);
+            }
+            console.log(`       text:    ${entry.existingPrinciple.text}`);
+            console.log(`       trigger: ${entry.existingPrinciple.triggerPattern}`);
+            console.log(`       action:  ${entry.existingPrinciple.action}`);
+            console.log(`       status:  ${entry.existingPrinciple.status}`);
+        });
+        console.log('');
+        if (evaluation === null) {
+            // Capability disabled (or nothing to evaluate): lexical-only review,
+            // exactly the pre-3C-4 output.
+        }
+        else if (evaluation.status === 'recommended') {
+            console.log('  Semantic evaluation (advisory — the Owner decides):');
+            console.log(`    recommendation: ${evaluation.recommendation}`);
+            if (evaluation.selectedPrincipleId) {
+                console.log(`    principle:      ${evaluation.selectedPrincipleId}`);
+            }
+            console.log(`    rationale:      ${evaluation.rationale}`);
+            console.log(`    confidence:     ${evaluation.confidence}`);
+        }
+        else {
+            console.log('  Semantic evaluation: UNAVAILABLE (lexical proposal only — not semantically judged)');
+            console.log(`    reason: ${evaluation.reason}`);
+        }
+        console.log(`\n  Next Action:  ${nextAction}\n`);
+    }
+    catch (err) {
+        if (err instanceof CandidateIntakeError || err.name === 'CandidateIntakeError') {
+            const e = err;
+            console.error(`Review failed [${e.code ?? 'unknown'}]: ${e.message}`);
+        }
+        else {
+            console.error(`Review failed: ${String(err)}`);
+        }
+        process.exit(1);
+    }
+    finally {
+        await stateManager.close();
+    }
+}
 // ── Audit ─────────────────────────────────────────────────────────────────────
 /**
  * pd candidate audit --workspace <path> [--json]