pumuki 6.3.26 → 6.3.28

package/integrations/lifecycle/cli.ts

@@ -22,11 +22,17 @@ import {
   openSddSession,
   readSddStatus,
   refreshSddSession,
+  runSddSyncDocs,
   type SddStage,
+  type SddSessionState,
 } from '../sdd';
 import { evaluateAiGate } from '../gate/evaluateAiGate';
 import { runEnterpriseAiGateCheck } from '../mcp/aiGateCheck';
 import { emitAuditSummaryNotificationFromAiGate } from '../notifications/emitAuditSummaryNotification';
+import {
+  buildPreWriteAutomationTrace,
+  type PreWriteAutomationTrace,
+} from './preWriteAutomation';
 import { buildLocalHotspotsReport, type LocalHotspotsReport } from './analyticsHotspots';
 import { resolveHotspotsSaasIngestionAuditPath } from './saasIngestionAudit';
 import { readHotspotsSaasIngestionPayload } from './saasIngestionContract';
@@ -48,7 +54,7 @@ type LifecycleCommand =
   | 'adapter'
   | 'analytics';
 
-type SddCommand = 'status' | 'validate' | 'session';
+type SddCommand = 'status' | 'validate' | 'session' | 'sync-docs';
 type LoopCommand = 'run' | 'status' | 'stop' | 'resume' | 'list' | 'export';
 type AnalyticsCommand = 'hotspots';
 type AnalyticsHotspotsCommand = 'report' | 'diagnose';
@@ -60,6 +66,7 @@ type ParsedArgs = {
   purgeArtifacts: boolean;
   updateSpec?: string;
   json: boolean;
+  doctorDeep?: boolean;
   sddCommand?: SddCommand;
   loopCommand?: LoopCommand;
   loopSessionId?: string;
@@ -70,6 +77,7 @@ type ParsedArgs = {
   sddSessionAction?: SddSessionAction;
   sddChangeId?: string;
   sddTtlMinutes?: number;
+  sddDryRun?: boolean;
   adapterCommand?: 'install';
   adapterAgent?: AdapterAgent;
   adapterDryRun?: boolean;
@@ -87,7 +95,7 @@ Pumuki lifecycle commands:
   pumuki uninstall [--purge-artifacts]
   pumuki remove
   pumuki update [--latest|--spec=<package-spec>]
-  pumuki doctor
+  pumuki doctor [--deep] [--json]
   pumuki status
   pumuki loop run --objective=<text> [--max-attempts=<n>] [--json]
   pumuki loop status --session=<session-id> [--json]
@@ -103,6 +111,7 @@ Pumuki lifecycle commands:
   pumuki sdd session --open --change=<change-id> [--ttl-minutes=<n>] [--json]
   pumuki sdd session --refresh [--ttl-minutes=<n>] [--json]
   pumuki sdd session --close [--json]
+  pumuki sdd sync-docs [--dry-run] [--json]
 `.trim();
 
 const LOOP_RUN_POLICY: GatePolicy = {
@@ -119,6 +128,24 @@ const writeError = (message: string): void => {
   process.stderr.write(`${message}\n`);
 };
 
+class LifecycleCliExitError extends Error {
+  readonly exitCode: number;
+  readonly stream: 'stdout' | 'stderr';
+
+  constructor(
+    message: string,
+    options: {
+      exitCode: number;
+      stream: 'stdout' | 'stderr';
+    }
+  ) {
+    super(message);
+    this.name = 'LifecycleCliExitError';
+    this.exitCode = options.exitCode;
+    this.stream = options.stream;
+  }
+}
+
 const withOptionalLocation = (message: string, location?: string): string => {
   if (!location || location.trim().length === 0) {
     return message;
@@ -126,6 +153,20 @@ const withOptionalLocation = (message: string, location?: string): string => {
   return `${message} -> ${location}`;
 };
 
+const renderSddChangeDescriptor = (session: SddSessionState): string => {
+  const canonical = session.changeId?.trim();
+  if (!canonical || canonical.length === 0) {
+    return 'none';
+  }
+  const alias = session.changeAlias?.trim();
+  if (!alias || alias.length === 0 || alias === canonical) {
+    return canonical;
+  }
+  return `${canonical} alias=${alias}`;
+};
+
+const isHelpFlag = (value: string | undefined): boolean => value === '--help' || value === '-h';
+
 const isLifecycleCommand = (value: string): value is LifecycleCommand =>
   value === 'install' ||
   value === 'uninstall' ||
@@ -379,8 +420,17 @@ const printHotspotsPublishDiagnostics = (diagnostics: HotspotsPublishDiagnostics
 
 export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs => {
   const commandRaw = argv[0];
-  if (!commandRaw || commandRaw === '--help' || commandRaw === '-h') {
-    throw new Error(HELP_TEXT);
+  if (!commandRaw) {
+    throw new LifecycleCliExitError(HELP_TEXT, {
+      exitCode: 1,
+      stream: 'stderr',
+    });
+  }
+  if (isHelpFlag(commandRaw)) {
+    throw new LifecycleCliExitError(HELP_TEXT, {
+      exitCode: 0,
+      stream: 'stdout',
+    });
   }
   if (!isLifecycleCommand(commandRaw)) {
     throw new Error(`Unknown command "${commandRaw}".\n\n${HELP_TEXT}`);
@@ -389,6 +439,7 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
   let purgeArtifacts = false;
   let updateSpec: ParsedArgs['updateSpec'];
   let json = false;
+  let doctorDeep = false;
   let sddCommand: ParsedArgs['sddCommand'];
   let loopCommand: ParsedArgs['loopCommand'];
   let loopSessionId: ParsedArgs['loopSessionId'];
@@ -399,6 +450,7 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
   let sddSessionAction: ParsedArgs['sddSessionAction'];
   let sddChangeId: ParsedArgs['sddChangeId'];
   let sddTtlMinutes: ParsedArgs['sddTtlMinutes'];
+  let sddDryRun = false;
   let adapterCommand: ParsedArgs['adapterCommand'];
   let adapterAgent: ParsedArgs['adapterAgent'];
   let adapterDryRun = false;
@@ -411,11 +463,23 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
 
   if (commandRaw === 'analytics') {
     const subcommandRaw = argv[1] ?? '';
+    if (isHelpFlag(subcommandRaw)) {
+      throw new LifecycleCliExitError(HELP_TEXT, {
+        exitCode: 0,
+        stream: 'stdout',
+      });
+    }
     if (subcommandRaw !== 'hotspots') {
       throw new Error(`Unsupported analytics command "${subcommandRaw}".\n\n${HELP_TEXT}`);
     }
     analyticsCommand = 'hotspots';
     const hotspotsActionRaw = argv[2] ?? '';
+    if (isHelpFlag(hotspotsActionRaw)) {
+      throw new LifecycleCliExitError(HELP_TEXT, {
+        exitCode: 0,
+        stream: 'stdout',
+      });
+    }
     if (hotspotsActionRaw !== 'report' && hotspotsActionRaw !== 'diagnose') {
       throw new Error(
         `Unsupported analytics hotspots action "${hotspotsActionRaw}".\n\n${HELP_TEXT}`
@@ -423,6 +487,12 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
     }
     analyticsHotspotsCommand = hotspotsActionRaw;
     for (const arg of argv.slice(3)) {
+      if (isHelpFlag(arg)) {
+        throw new LifecycleCliExitError(HELP_TEXT, {
+          exitCode: 0,
+          stream: 'stdout',
+        });
+      }
       if (arg === '--json') {
         json = true;
         continue;
@@ -483,6 +553,12 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
 
   if (commandRaw === 'loop') {
     const subcommandRaw = argv[1] ?? '';
+    if (isHelpFlag(subcommandRaw)) {
+      throw new LifecycleCliExitError(HELP_TEXT, {
+        exitCode: 0,
+        stream: 'stdout',
+      });
+    }
     if (
       subcommandRaw !== 'run' &&
       subcommandRaw !== 'status' &&
@@ -495,6 +571,12 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
     }
     loopCommand = subcommandRaw;
     for (const arg of argv.slice(2)) {
+      if (isHelpFlag(arg)) {
+        throw new LifecycleCliExitError(HELP_TEXT, {
+          exitCode: 0,
+          stream: 'stdout',
+        });
+      }
       if (arg === '--json') {
         json = true;
         continue;
@@ -573,16 +655,29 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
 
   if (commandRaw === 'sdd') {
     const subcommandRaw = argv[1] ?? 'status';
+    if (isHelpFlag(subcommandRaw)) {
+      throw new LifecycleCliExitError(HELP_TEXT, {
+        exitCode: 0,
+        stream: 'stdout',
+      });
+    }
     if (
       subcommandRaw !== 'status' &&
       subcommandRaw !== 'validate' &&
-      subcommandRaw !== 'session'
+      subcommandRaw !== 'session' &&
+      subcommandRaw !== 'sync-docs'
     ) {
       throw new Error(`Unsupported SDD subcommand "${subcommandRaw}".\n\n${HELP_TEXT}`);
     }
     sddCommand = subcommandRaw;
 
     for (const arg of argv.slice(2)) {
+      if (isHelpFlag(arg)) {
+        throw new LifecycleCliExitError(HELP_TEXT, {
+          exitCode: 0,
+          stream: 'stdout',
+        });
+      }
       if (arg === '--json') {
         json = true;
         continue;
@@ -615,6 +710,10 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
         sddTtlMinutes = minutes;
         continue;
       }
+      if (arg === '--dry-run') {
+        sddDryRun = true;
+        continue;
+      }
       throw new Error(`Unsupported argument "${arg}".\n\n${HELP_TEXT}`);
     }
 
@@ -635,6 +734,20 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
         sddStage: sddStage ?? 'PRE_COMMIT',
       };
     }
+    if (sddCommand === 'sync-docs') {
+      if (sddStage || sddSessionAction || sddChangeId || typeof sddTtlMinutes === 'number') {
+        throw new Error(
+          `"pumuki sdd sync-docs" only supports [--dry-run] [--json].\n\n${HELP_TEXT}`
+        );
+      }
+      return {
+        command: commandRaw,
+        purgeArtifacts: false,
+        json,
+        sddCommand,
+        sddDryRun,
+      };
+    }
 
     if (!sddSessionAction) {
       throw new Error(
@@ -660,12 +773,24 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
 
   if (commandRaw === 'adapter') {
     const subcommandRaw = argv[1] ?? '';
+    if (isHelpFlag(subcommandRaw)) {
+      throw new LifecycleCliExitError(HELP_TEXT, {
+        exitCode: 0,
+        stream: 'stdout',
+      });
+    }
     if (subcommandRaw !== 'install') {
       throw new Error(`Unsupported adapter subcommand "${subcommandRaw}".\n\n${HELP_TEXT}`);
     }
     adapterCommand = 'install';
 
     for (const arg of argv.slice(2)) {
+      if (isHelpFlag(arg)) {
+        throw new LifecycleCliExitError(HELP_TEXT, {
+          exitCode: 0,
+          stream: 'stdout',
+        });
+      }
       if (arg === '--json') {
         json = true;
         continue;
@@ -694,6 +819,12 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
   }
 
   for (const arg of argv.slice(1)) {
+    if (isHelpFlag(arg)) {
+      throw new LifecycleCliExitError(HELP_TEXT, {
+        exitCode: 0,
+        stream: 'stdout',
+      });
+    }
     if (arg === '--json') {
       json = true;
       continue;
@@ -710,16 +841,27 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
       updateSpec = arg.slice('--spec='.length).trim();
       continue;
     }
+    if (arg === '--deep') {
+      if (commandRaw !== 'doctor') {
+        throw new Error(`Unsupported argument "${arg}".\n\n${HELP_TEXT}`);
+      }
+      doctorDeep = true;
+      continue;
+    }
 
     throw new Error(`Unsupported argument "${arg}".\n\n${HELP_TEXT}`);
   }
 
-  return {
+  const parsedArgs: ParsedArgs = {
     command: commandRaw,
     purgeArtifacts,
     updateSpec,
     json,
   };
+  if (doctorDeep) {
+    parsedArgs.doctorDeep = true;
+  }
+  return parsedArgs;
 };
 
 const printDoctorReport = (report: LifecycleDoctorReport): void => {
@@ -734,6 +876,14 @@ const printDoctorReport = (report: LifecycleDoctorReport): void => {
   writeInfo(
     `[pumuki] hook pre-push: ${report.hookStatus['pre-push'].managedBlockPresent ? 'managed' : 'missing'}`
   );
+  if (report.deep?.enabled) {
+    writeInfo(`[pumuki][deep] checks: ${report.deep.checks.length}`);
+    for (const check of report.deep.checks) {
+      writeInfo(
+        `[pumuki][deep] ${check.id}: ${check.status.toUpperCase()} - ${check.message}`
+      );
+    }
+  }
 
   if (report.issues.length === 0) {
     writeInfo('[pumuki] doctor verdict: PASS');
@@ -752,6 +902,14 @@ const PRE_WRITE_TELEMETRY_CHAIN = 'pumuki->mcp->ai_gate->ai_evidence';
 type PreWriteValidationEnvelope = {
   sdd: ReturnType<typeof evaluateSddPolicy>;
   ai_gate: ReturnType<typeof evaluateAiGate>;
+  automation: {
+    attempted: boolean;
+    actions: Array<{
+      action: 'refresh_evidence' | 'refresh_mcp_receipt';
+      status: 'OK' | 'FAILED';
+      details: string;
+    }>;
+  };
   telemetry: {
     chain: typeof PRE_WRITE_TELEMETRY_CHAIN;
     stage: SddStage;
@@ -769,6 +927,131 @@ const defaultLifecycleCliDependencies: LifecycleCliDependencies = {
   runPlatformGate,
 };
 
+const PRE_WRITE_HINTS_BY_CODE: Readonly<Record<string, string>> = {
+  EVIDENCE_MISSING: 'Regenera evidencia ejecutando una auditoría completa antes de continuar.',
+  EVIDENCE_INVALID: 'Corrige el contrato de .ai_evidence.json y vuelve a ejecutar el gate.',
+  EVIDENCE_INTEGRITY_MISSING: 'Regenera evidencia para crear la metadata de integridad criptográfica.',
+  EVIDENCE_INTEGRITY_UNAVAILABLE: 'Regenera evidencia desde una auditoría válida para restaurar integridad.',
+  EVIDENCE_INTEGRITY_SCHEMA_INVALID: 'Regenera evidencia; el bloque de integridad no cumple el contrato.',
+  EVIDENCE_INTEGRITY_HASH_FORMAT_INVALID: 'Regenera evidencia; los hashes de integridad son inválidos.',
+  EVIDENCE_INTEGRITY_PREVIOUS_CHAIN_HASH_INVALID:
+    'Regenera evidencia para reparar previous_chain_hash.',
+  EVIDENCE_INTEGRITY_TIMESTAMP_MISMATCH: 'Regenera evidencia para alinear timestamp e integridad.',
+  EVIDENCE_INTEGRITY_PAYLOAD_HASH_MISMATCH: 'Regenera evidencia; el payload hash no coincide.',
+  EVIDENCE_INTEGRITY_CHAIN_HASH_MISMATCH: 'Regenera evidencia; la cadena criptográfica no coincide.',
+  EVIDENCE_INTEGRITY_SIGNATURE_REQUIRED: 'Configura firma o desactiva exigencia de firma explícita.',
+  EVIDENCE_INTEGRITY_SIGNATURE_FORMAT_INVALID:
+    'Regenera evidencia o corrige metadatos de firma (algorithm/key_id/value).',
+  EVIDENCE_INTEGRITY_SIGNATURE_KEY_MISSING:
+    'Configura PUMUKI_EVIDENCE_SIGNING_KEY para verificar firma localmente.',
+  EVIDENCE_INTEGRITY_SIGNATURE_KEY_MISMATCH:
+    'Alinea PUMUKI_EVIDENCE_SIGNING_KEY_ID con el key_id usado para firmar la evidencia.',
+  EVIDENCE_INTEGRITY_SIGNATURE_INVALID: 'Regenera evidencia firmada; la firma actual no verifica.',
+  EVIDENCE_STALE: 'Refresca evidencia para este repo y rama.',
+  EVIDENCE_REPO_ROOT_MISMATCH: 'Regenera evidencia desde este repositorio.',
+  EVIDENCE_BRANCH_MISMATCH: 'Regenera evidencia en la rama actual.',
+  EVIDENCE_RULES_COVERAGE_MISSING: 'Ejecuta auditoría completa para recalcular rules_coverage.',
+  EVIDENCE_RULES_COVERAGE_INCOMPLETE: 'Asegura unevaluated=0 y coverage_ratio=1.',
+  GITFLOW_PROTECTED_BRANCH: 'Trabaja en feature/* y evita ramas protegidas.',
+  MCP_ENTERPRISE_RECEIPT_MISSING: 'Invoca ai_gate_check desde pumuki-enterprise MCP antes de PRE_WRITE.',
+  MCP_ENTERPRISE_RECEIPT_INVALID: 'Corrige recibo MCP y vuelve a invocar ai_gate_check.',
+  MCP_ENTERPRISE_RECEIPT_STALE: 'Vuelve a ejecutar ai_gate_check para emitir recibo fresco.',
+  MCP_ENTERPRISE_RECEIPT_STAGE_MISMATCH: 'Reejecuta ai_gate_check con stage PRE_WRITE.',
+  MCP_ENTERPRISE_RECEIPT_REPO_ROOT_MISMATCH: 'Genera el recibo MCP en este mismo repositorio.',
+  WAIVER_POLICY_INVALID: 'Corrige el archivo de waivers y vuelve a ejecutar la validación.',
+};
+
+const wrapPreWritePanelLine = (value: string, width: number): string[] => {
+  if (width < 20 || value.length <= width) {
+    return [value];
+  }
+  const words = value.split(/\s+/);
+  const lines: string[] = [];
+  let current = '';
+  for (const word of words) {
+    if (current.length === 0) {
+      current = word;
+      continue;
+    }
+    if (`${current} ${word}`.length <= width) {
+      current = `${current} ${word}`;
+      continue;
+    }
+    lines.push(current);
+    current = word;
+  }
+  if (current.length > 0) {
+    lines.push(current);
+  }
+  return lines;
+};
+
+const renderPreWritePanel = (lines: ReadonlyArray<string>): string => {
+  const terminalWidth = Number.isFinite(process.stdout.columns ?? NaN)
+    ? Number(process.stdout.columns)
+    : 110;
+  const width = Math.min(140, Math.max(86, terminalWidth - 2));
+  const innerWidth = width - 4;
+  const normalized = lines.flatMap((line) => wrapPreWritePanelLine(line, innerWidth));
+  const top = `╔${'═'.repeat(width - 2)}╗`;
+  const bottom = `╚${'═'.repeat(width - 2)}╝`;
+  const body = normalized.map((line) => `║ ${line.padEnd(innerWidth, ' ')} ║`);
+  return [top, ...body, bottom].join('\n');
+};
+
+const buildPreWriteValidationPanel = (params: {
+  sdd: ReturnType<typeof evaluateSddPolicy>;
+  aiGate: ReturnType<typeof evaluateAiGate>;
+  automation: PreWriteAutomationTrace;
+}): string => {
+  const git = params.aiGate.repo_state.git;
+  const receipt = params.aiGate.mcp_receipt;
+  const policyTrace = params.aiGate.policy.trace;
+  const lines: string[] = [
+    'PRE-FLIGHT CHECK',
+    `Stage: ${params.sdd.stage} · SDD: ${params.sdd.decision.code} · AI Gate: ${params.aiGate.status}`,
+    `Branch: ${git.branch ?? 'unknown'} · Upstream: ${git.upstream ?? 'none'}`,
+    `Worktree: dirty=${git.dirty ? 'yes' : 'no'} staged=${git.staged} unstaged=${git.unstaged} ahead=${git.ahead} behind=${git.behind}`,
+    `Policy: source=${policyTrace.source} bundle=${policyTrace.bundle} hash=${policyTrace.hash}`,
+    `Policy signature: version=${policyTrace.version ?? 'n/a'} signature=${policyTrace.signature ?? 'n/a'}`,
+    `Evidence: kind=${params.aiGate.evidence.kind} age=${params.aiGate.evidence.age_seconds ?? 'n/a'}s max=${params.aiGate.evidence.max_age_seconds}s`,
+    `Evidence source: ${params.aiGate.evidence.source} path=${params.aiGate.evidence.path}`,
+    `Evidence digest: ${params.aiGate.evidence.digest ?? 'n/a'} generated_at=${params.aiGate.evidence.generated_at ?? 'n/a'}`,
+    `Evidence integrity: status=${params.aiGate.evidence.integrity.status} chain_hash=${params.aiGate.evidence.integrity.chain_hash ?? 'n/a'} prev=${params.aiGate.evidence.integrity.previous_chain_hash ?? 'n/a'} signature=${params.aiGate.evidence.integrity.signature_present ? 'present' : 'absent'} verified=${params.aiGate.evidence.integrity.signature_verified === null ? 'n/a' : params.aiGate.evidence.integrity.signature_verified ? 'yes' : 'no'}`,
+    `Waivers: status=${params.aiGate.waivers.status} applied=${params.aiGate.waivers.applied.length} path=${params.aiGate.waivers.path}`,
+    `MCP receipt: required=${receipt.required ? 'yes' : 'no'} kind=${receipt.kind} age=${receipt.age_seconds ?? 'n/a'}s max=${receipt.max_age_seconds ?? 'n/a'}s`,
+    `Auto-heal: attempted=${params.automation.attempted ? 'yes' : 'no'} actions=${params.automation.actions.length}`,
+    `Violations: ${params.aiGate.violations.length}`,
+  ];
+
+  if (params.automation.actions.length > 0) {
+    lines.push('');
+    lines.push('Auto-heal actions:');
+    for (const action of params.automation.actions) {
+      lines.push(`- ${action.action}: ${action.status} (${action.details})`);
+    }
+  }
+
+  if (params.aiGate.violations.length > 0) {
+    lines.push('');
+    lines.push('Blocking causes:');
+    for (const violation of params.aiGate.violations) {
+      lines.push(`- ${violation.code}: ${violation.message}`);
+    }
+    lines.push('');
+    lines.push('Operational hints:');
+    for (const violation of params.aiGate.violations) {
+      const hint = PRE_WRITE_HINTS_BY_CODE[violation.code];
+      if (!hint) {
+        continue;
+      }
+      lines.push(`- ${violation.code}: ${hint}`);
+    }
+  }
+
+  return renderPreWritePanel(lines);
+};
+
 const resolveSddDecisionLocation = (
   result: ReturnType<typeof evaluateSddPolicy>
 ) => {
@@ -779,8 +1062,10 @@ const resolveSddDecisionLocation = (
     case 'OPENSPEC_PROJECT_MISSING':
     case 'SDD_VALIDATION_FAILED':
     case 'SDD_VALIDATION_ERROR':
+    case 'SDD_VALIDATION_EMPTY':
       return 'openspec/changes:1';
     case 'SDD_CHANGE_MISSING':
+    case 'SDD_CHANGE_INCOMPLETE':
       return changeId && changeId.trim().length > 0
         ? `openspec/changes/${changeId.trim()}:1`
         : 'openspec/changes:1';
@@ -808,10 +1093,15 @@ const resolveAiGateViolationLocation = (code: string) => {
 
 const buildPreWriteValidationEnvelope = (
   result: ReturnType<typeof evaluateSddPolicy>,
-  aiGate: ReturnType<typeof evaluateAiGate>
+  aiGate: ReturnType<typeof evaluateAiGate>,
+  automation: PreWriteAutomationTrace
 ): PreWriteValidationEnvelope => ({
   sdd: result,
   ai_gate: aiGate,
+  automation: {
+    attempted: automation.attempted,
+    actions: [...automation.actions],
+  },
   telemetry: {
     chain: PRE_WRITE_TELEMETRY_CHAIN,
     stage: result.stage,
@@ -866,6 +1156,31 @@ export const runLifecycleCli = async (
           if (result.openSpecBootstrap.skippedReason === 'NO_PACKAGE_JSON') {
             writeInfo('[pumuki] openspec bootstrap skipped npm install (package.json not found)');
           }
+          if (result.openSpecBootstrap.skippedReason === 'NPM_INSTALL_FAILED') {
+            writeInfo('[pumuki] openspec bootstrap npm install failed; continuing in standalone mode (hooks installed)');
+            if (result.openSpecBootstrap.skippedDetails) {
+              writeInfo(`[pumuki] openspec bootstrap detail: ${result.openSpecBootstrap.skippedDetails}`);
+            }
+          }
+          if (result.openSpecBootstrap.skippedReason === 'ENGINE_MISMATCH') {
+            writeInfo('[pumuki] openspec bootstrap skipped npm install due to repository engines mismatch; continuing in standalone mode (hooks installed)');
+            if (result.openSpecBootstrap.skippedDetails) {
+              writeInfo(`[pumuki] openspec bootstrap detail: ${result.openSpecBootstrap.skippedDetails}`);
+            }
+          }
+        }
+        const consumerBootstrap = result.consumerPackageBootstrap;
+        if (consumerBootstrap.packageInstalled) {
+          writeInfo(
+            `[pumuki] consumer package bootstrap: installed=yes source=${consumerBootstrap.dependencySource ?? 'devDependencies'} spec=${consumerBootstrap.targetSpec ?? 'n/a'}`
+          );
+        } else if (consumerBootstrap.skippedReason) {
+          writeInfo(
+            `[pumuki] consumer package bootstrap: installed=no reason=${consumerBootstrap.skippedReason.toLowerCase()}`
+          );
+          if (consumerBootstrap.skippedDetails) {
+            writeInfo(`[pumuki] consumer package bootstrap detail: ${consumerBootstrap.skippedDetails}`);
+          }
         }
         return 0;
       }
@@ -906,8 +1221,14 @@ export const runLifecycleCli = async (
         return 0;
       }
       case 'doctor': {
-        const report = runLifecycleDoctor();
-        printDoctorReport(report);
+        const report = runLifecycleDoctor({
+          deep: parsed.doctorDeep,
+        });
+        if (parsed.json) {
+          writeInfo(JSON.stringify(report, null, 2));
+        } else {
+          printDoctorReport(report);
+        }
         return report.issues.some((issue) => issue.severity === 'error') ? 1 : 0;
       }
       case 'status': {
@@ -1150,6 +1471,26 @@ export const runLifecycleCli = async (
         return 1;
       }
       case 'sdd': {
+        if (parsed.sddCommand === 'sync-docs') {
+          const syncResult = runSddSyncDocs({
+            repoRoot: process.cwd(),
+            dryRun: parsed.sddDryRun,
+          });
+          if (parsed.json) {
+            writeInfo(JSON.stringify(syncResult, null, 2));
+          } else {
+            writeInfo(
+              `[pumuki][sdd] sync-docs: change=${syncResult.changeId} dry-run=${syncResult.dryRun ? 'yes' : 'no'} changed=${syncResult.changed ? 'yes' : 'no'} file=${syncResult.targetPathRelative}`
+            );
+            if (syncResult.diffPreview.length > 0) {
+              writeInfo('[pumuki][sdd] sync-docs diff preview:');
+              writeInfo(syncResult.diffPreview);
+            } else {
+              writeInfo('[pumuki][sdd] sync-docs diff preview: no changes.');
+            }
+          }
+          return 0;
+        }
         if (parsed.sddCommand === 'status') {
           const sddStatus = readSddStatus();
           if (parsed.json) {
@@ -1166,7 +1507,7 @@ export const runLifecycleCli = async (
               `[pumuki][sdd] openspec project initialized: ${sddStatus.openspec.projectInitialized ? 'yes' : 'no'}`
             );
             writeInfo(
-              `[pumuki][sdd] session: active=${sddStatus.session.active ? 'yes' : 'no'} valid=${sddStatus.session.valid ? 'yes' : 'no'} change=${sddStatus.session.changeId ?? 'none'}`
+              `[pumuki][sdd] session: active=${sddStatus.session.active ? 'yes' : 'no'} valid=${sddStatus.session.valid ? 'yes' : 'no'} change=${renderSddChangeDescriptor(sddStatus.session)}`
             );
             if (typeof sddStatus.session.remainingSeconds === 'number') {
               writeInfo(
@@ -1181,17 +1522,33 @@ export const runLifecycleCli = async (
             stage: parsed.sddStage ?? 'PRE_COMMIT',
           });
           const shouldEvaluateAiGate = result.stage === 'PRE_WRITE';
-          const aiGate = shouldEvaluateAiGate
+          let aiGate = shouldEvaluateAiGate
             ? runEnterpriseAiGateCheck({
               repoRoot: process.cwd(),
               stage: result.stage,
+              requireMcpReceipt: true,
             }).result
             : null;
+          const automationTrace: PreWriteAutomationTrace = {
+            attempted: false,
+            actions: [],
+          };
+          if (result.stage === 'PRE_WRITE' && aiGate) {
+            const auto = await buildPreWriteAutomationTrace({
+              repoRoot: process.cwd(),
+              sdd: result,
+              aiGate,
+              runPlatformGate: activeDependencies.runPlatformGate,
+            });
+            aiGate = auto.aiGate;
+            automationTrace.attempted = auto.trace.attempted;
+            automationTrace.actions = auto.trace.actions;
+          }
           if (parsed.json) {
             writeInfo(
               JSON.stringify(
                 aiGate
-                  ? buildPreWriteValidationEnvelope(result, aiGate)
+                  ? buildPreWriteValidationEnvelope(result, aiGate, automationTrace)
                   : result,
                 null,
                 2
@@ -1213,6 +1570,11 @@ export const runLifecycleCli = async (
               );
             }
             if (aiGate) {
+              writeInfo(buildPreWriteValidationPanel({
+                sdd: result,
+                aiGate,
+                automation: automationTrace,
+              }));
               writeInfo(
                 `[pumuki][ai-gate] stage=${aiGate.stage} status=${aiGate.status} violations=${aiGate.violations.length}`
               );
@@ -1251,7 +1613,7 @@ export const runLifecycleCli = async (
               writeInfo(JSON.stringify(session, null, 2));
             } else {
               writeInfo(
-                `[pumuki][sdd] session opened: change=${session.changeId} ttlMinutes=${session.ttlMinutes ?? 'unknown'} valid=${session.valid ? 'yes' : 'no'}`
+                `[pumuki][sdd] session opened: change=${renderSddChangeDescriptor(session)} ttlMinutes=${session.ttlMinutes ?? 'unknown'} valid=${session.valid ? 'yes' : 'no'}`
               );
             }
             return 0;
@@ -1264,7 +1626,7 @@ export const runLifecycleCli = async (
               writeInfo(JSON.stringify(session, null, 2));
             } else {
               writeInfo(
-                `[pumuki][sdd] session refreshed: change=${session.changeId ?? 'none'} ttlMinutes=${session.ttlMinutes ?? 'unknown'} valid=${session.valid ? 'yes' : 'no'}`
+                `[pumuki][sdd] session refreshed: change=${renderSddChangeDescriptor(session)} ttlMinutes=${session.ttlMinutes ?? 'unknown'} valid=${session.valid ? 'yes' : 'no'}`
               );
             }
             return 0;
@@ -1305,6 +1667,14 @@ export const runLifecycleCli = async (
         return 1;
     }
   } catch (error) {
+    if (error instanceof LifecycleCliExitError) {
+      if (error.stream === 'stdout') {
+        writeInfo(error.message);
+      } else {
+        writeError(error.message);
+      }
+      return error.exitCode;
+    }
     const message = error instanceof Error ? error.message : 'Unexpected lifecycle CLI error.';
     writeError(message);
     return 1;