pumuki 6.3.72 → 6.3.73

package/integrations/lifecycle/governanceObservationSnapshot.ts

@@ -0,0 +1,288 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { readEvidenceResult } from '../evidence/readEvidence';
+import { readSddStatus } from '../sdd';
+import type { SddStatusPayload } from '../sdd/types';
+import type { LifecycleExperimentalFeaturesSnapshot } from './experimentalFeaturesSnapshot';
+import type { ILifecycleGitService } from './gitService';
+import { LifecycleGitService } from './gitService';
+import type { LifecyclePolicyValidationSnapshot } from './policyValidationSnapshot';
+import { writeInfo } from './cliOutputs';
+
+const DEFAULT_PROTECTED_BRANCHES = new Set(['main', 'master', 'develop', 'dev']);
+
+export type GovernanceEvidenceSummary = {
+  path: string;
+  readable: 'missing' | 'invalid' | 'valid';
+  snapshot_stage?: string;
+  snapshot_outcome?: 'PASS' | 'WARN' | 'BLOCK';
+  matched_warn_count?: number;
+  matched_blocking_count?: number;
+  findings_count?: number;
+  ai_gate_status?: 'ALLOWED' | 'BLOCKED';
+  human_summary_preview: string[];
+};
+
+export type GovernanceContractSurface = {
+  agents_md: boolean;
+  skills_lock_json: boolean;
+  skills_sources_json: boolean;
+  vendor_skills_dir: boolean;
+  pumuki_adapter_json: boolean;
+};
+
+export type GovernanceObservationSnapshot = {
+  schema_version: '1';
+  sdd: {
+    experimental_raw: string | null;
+    effective_mode: 'off' | 'advisory' | 'strict';
+    experimental_source: string;
+  };
+  sdd_session: {
+    active: boolean;
+    valid: boolean;
+    change_id: string | null;
+    remaining_seconds: number | null;
+  };
+  policy_strict: {
+    pre_write: boolean;
+    pre_commit: boolean;
+    pre_push: boolean;
+    ci: boolean;
+  };
+  enterprise_warn_as_block_env: boolean;
+  evidence: GovernanceEvidenceSummary;
+  git: {
+    current_branch: string | null;
+    on_protected_branch_hint: boolean;
+  };
+  contract_surface: GovernanceContractSurface;
+  attention_codes: ReadonlyArray<string>;
+  governance_effective: 'green' | 'attention' | 'blocked';
+  agent_bootstrap_hints: ReadonlyArray<string>;
+};
+
+const truthyEnv = (value: string | undefined): boolean => {
+  if (typeof value !== 'string') {
+    return false;
+  }
+  const normalized = value.trim().toLowerCase();
+  return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'strict';
+};
+
+const readCurrentBranch = (git: ILifecycleGitService, repoRoot: string): string | null => {
+  try {
+    const branch = git.runGit(['rev-parse', '--abbrev-ref', 'HEAD'], repoRoot).trim();
+    return branch.length > 0 ? branch : null;
+  } catch {
+    return null;
+  }
+};
+
+const readSddStatusSafe = (repoRoot: string): SddStatusPayload => {
+  try {
+    return readSddStatus(repoRoot);
+  } catch {
+    return {
+      repoRoot,
+      openspec: {
+        installed: false,
+        projectInitialized: false,
+        minimumVersion: '0.0.0',
+        recommendedVersion: '0.0.0',
+        compatible: false,
+      },
+      session: {
+        repoRoot,
+        active: false,
+        valid: false,
+      },
+    };
+  }
+};
+
+const buildContractSurface = (repoRoot: string): GovernanceContractSurface => ({
+  agents_md: existsSync(join(repoRoot, 'AGENTS.md')),
+  skills_lock_json: existsSync(join(repoRoot, 'skills.lock.json')),
+  skills_sources_json: existsSync(join(repoRoot, 'skills.sources.json')),
+  vendor_skills_dir: existsSync(join(repoRoot, 'vendor', 'skills')),
+  pumuki_adapter_json: existsSync(join(repoRoot, '.pumuki', 'adapter.json')),
+});
+
+const summarizeEvidence = (repoRoot: string): GovernanceEvidenceSummary => {
+  const evidenceResult = readEvidenceResult(repoRoot);
+  const path = evidenceResult.source_descriptor.path;
+  if (evidenceResult.kind === 'missing') {
+    return { path, readable: 'missing', human_summary_preview: [] };
+  }
+  if (evidenceResult.kind === 'invalid') {
+    return {
+      path,
+      readable: 'invalid',
+      human_summary_preview: [evidenceResult.detail ?? evidenceResult.reason],
+    };
+  }
+
+  const snapshot = evidenceResult.evidence.snapshot;
+  const hints = evidenceResult.evidence.operational_hints?.human_summary_lines ?? [];
+  const breakdown = evidenceResult.evidence.operational_hints?.rule_execution_breakdown;
+  return {
+    path,
+    readable: 'valid',
+    snapshot_stage: snapshot.stage,
+    snapshot_outcome: snapshot.outcome,
+    matched_warn_count: breakdown?.matched_warn_count,
+    matched_blocking_count: breakdown?.matched_blocking_count,
+    findings_count: Array.isArray(snapshot.findings) ? snapshot.findings.length : 0,
+    ai_gate_status: evidenceResult.evidence.ai_gate.status,
+    human_summary_preview: hints.slice(0, 5),
+  };
+};
+
+const buildHints = (
+  surface: GovernanceContractSurface,
+  branch: string | null,
+  protectedBranchHint: boolean
+): string[] => {
+  const hints: string[] = [];
+  if (surface.agents_md) {
+    hints.push('AGENTS.md presente: aplica el contrato del repo antes de dar governance en verde.');
+  }
+  if (!surface.skills_lock_json) {
+    hints.push('Falta skills.lock.json: genera lock canónico de skills antes de cerrar la gobernanza.');
+  }
+  if (!surface.pumuki_adapter_json) {
+    hints.push('Falta .pumuki/adapter.json: instala el adaptador si quieres wiring IDE/MCP explícito.');
+  }
+  if (protectedBranchHint && branch) {
+    hints.push(`La rama "${branch}" cae en el set protegido por defecto: usa feature/* o refactor/*.`);
+  }
+  hints.push('SDD/OpenSpec: usa PUMUKI_EXPERIMENTAL_SDD=advisory|strict cuando el loop SDD esté activo.');
+  hints.push('WARN-as-BLOCK: activa PUMUKI_ENTERPRISE_STRICT_WARN_AS_BLOCK=1 si el repo exige promoción dura.');
+  return hints;
+};
+
+export const readGovernanceObservationSnapshot = (params: {
+  repoRoot: string;
+  experimentalFeatures: LifecycleExperimentalFeaturesSnapshot;
+  policyValidation: LifecyclePolicyValidationSnapshot;
+  git?: ILifecycleGitService;
+}): GovernanceObservationSnapshot => {
+  const git = params.git ?? new LifecycleGitService();
+  const { repoRoot, experimentalFeatures, policyValidation } = params;
+  const rawSdd = process.env.PUMUKI_EXPERIMENTAL_SDD?.trim();
+  const sddStatus = readSddStatusSafe(repoRoot);
+  const evidence = summarizeEvidence(repoRoot);
+  const branch = readCurrentBranch(git, repoRoot);
+  const onProtected = typeof branch === 'string' && DEFAULT_PROTECTED_BRANCHES.has(branch.trim().toLowerCase());
+  const surface = buildContractSurface(repoRoot);
+  const warnAsBlock = truthyEnv(process.env.PUMUKI_ENTERPRISE_STRICT_WARN_AS_BLOCK);
+
+  const attention: string[] = [];
+  if (evidence.readable === 'invalid') {
+    attention.push('EVIDENCE_INVALID_OR_CHAIN');
+  }
+  if (evidence.readable === 'valid' && evidence.ai_gate_status === 'BLOCKED') {
+    attention.push('AI_GATE_BLOCKED');
+  }
+  if (evidence.readable === 'valid' && evidence.snapshot_outcome === 'WARN') {
+    attention.push('EVIDENCE_SNAPSHOT_WARN');
+  }
+  if (evidence.readable === 'valid' && evidence.snapshot_outcome === 'BLOCK') {
+    attention.push('EVIDENCE_SNAPSHOT_BLOCK');
+  }
+  if (sddStatus.session.active === true && sddStatus.session.valid !== true) {
+    attention.push('SDD_SESSION_INVALID_OR_EXPIRED');
+  }
+  if (!policyValidation.stages.PRE_WRITE.strict) {
+    attention.push('POLICY_PRE_WRITE_NOT_STRICT');
+  }
+  if (!policyValidation.stages.PRE_COMMIT.strict) {
+    attention.push('POLICY_PRE_COMMIT_NOT_STRICT');
+  }
+  if (!policyValidation.stages.PRE_PUSH.strict) {
+    attention.push('POLICY_PRE_PUSH_NOT_STRICT');
+  }
+  if (!policyValidation.stages.CI.strict) {
+    attention.push('POLICY_CI_NOT_STRICT');
+  }
+  if (onProtected) {
+    attention.push('GITFLOW_PROTECTED_BRANCH_CONTEXT');
+  }
+
+  let governanceEffective: GovernanceObservationSnapshot['governance_effective'] = 'green';
+  if (
+    evidence.readable === 'invalid'
+    || (evidence.readable === 'valid' && evidence.ai_gate_status === 'BLOCKED')
+    || (evidence.readable === 'valid' && evidence.snapshot_outcome === 'BLOCK')
+  ) {
+    governanceEffective = 'blocked';
+  } else if (attention.length > 0) {
+    governanceEffective = 'attention';
+  }
+
+  return {
+    schema_version: '1',
+    sdd: {
+      experimental_raw: rawSdd && rawSdd.length > 0 ? rawSdd : null,
+      effective_mode: experimentalFeatures.features.sdd.mode,
+      experimental_source: experimentalFeatures.features.sdd.source,
+    },
+    sdd_session: {
+      active: sddStatus.session.active,
+      valid: sddStatus.session.valid,
+      change_id: sddStatus.session.changeId ?? null,
+      remaining_seconds:
+        typeof sddStatus.session.remainingSeconds === 'number' ? sddStatus.session.remainingSeconds : null,
+    },
+    policy_strict: {
+      pre_write: policyValidation.stages.PRE_WRITE.strict,
+      pre_commit: policyValidation.stages.PRE_COMMIT.strict,
+      pre_push: policyValidation.stages.PRE_PUSH.strict,
+      ci: policyValidation.stages.CI.strict,
+    },
+    enterprise_warn_as_block_env: warnAsBlock,
+    evidence,
+    git: {
+      current_branch: branch,
+      on_protected_branch_hint: onProtected,
+    },
+    contract_surface: surface,
+    attention_codes: attention,
+    governance_effective: governanceEffective,
+    agent_bootstrap_hints: buildHints(surface, branch, onProtected),
+  };
+};
+
+export const buildGovernanceObservationSummaryLines = (
+  snapshot: GovernanceObservationSnapshot
+): string[] => {
+  const lines = [
+    `Governance: ${snapshot.governance_effective.toUpperCase()}`,
+    `Contract: AGENTS=${snapshot.contract_surface.agents_md ? 'yes' : 'no'} skills.lock=${snapshot.contract_surface.skills_lock_json ? 'yes' : 'no'} skills.sources=${snapshot.contract_surface.skills_sources_json ? 'yes' : 'no'} vendor/skills=${snapshot.contract_surface.vendor_skills_dir ? 'yes' : 'no'} adapter=${snapshot.contract_surface.pumuki_adapter_json ? 'yes' : 'no'}`,
+    `SDD: env=${snapshot.sdd.experimental_raw ?? '(unset)'} effective=${snapshot.sdd.effective_mode} session_active=${snapshot.sdd_session.active} session_valid=${snapshot.sdd_session.valid} change=${snapshot.sdd_session.change_id ?? 'none'}`,
+    `Evidence: readable=${snapshot.evidence.readable} stage=${snapshot.evidence.snapshot_stage ?? 'n/a'} outcome=${snapshot.evidence.snapshot_outcome ?? 'n/a'} ai_gate=${snapshot.evidence.ai_gate_status ?? 'n/a'} findings=${snapshot.evidence.findings_count ?? 'n/a'}`,
+    `GitFlow: branch=${snapshot.git.current_branch ?? 'unknown'} protected_hint=${snapshot.git.on_protected_branch_hint ? 'yes' : 'no'}`,
+    `Policy strict: PRE_WRITE=${snapshot.policy_strict.pre_write} PRE_COMMIT=${snapshot.policy_strict.pre_commit} PRE_PUSH=${snapshot.policy_strict.pre_push} CI=${snapshot.policy_strict.ci}`,
+  ];
+  if (snapshot.attention_codes.length > 0) {
+    lines.push(`Attention: ${snapshot.attention_codes.join(', ')}`);
+  }
+  return lines;
+};
+
+export const printGovernanceObservationHuman = (snapshot: GovernanceObservationSnapshot): void => {
+  writeInfo('[pumuki] governance truth (S1 / governance console baseline):');
+  for (const line of buildGovernanceObservationSummaryLines(snapshot)) {
+    writeInfo(`[pumuki]   ${line}`);
+  }
+  for (const hint of snapshot.evidence.human_summary_preview) {
+    writeInfo(`[pumuki]   evidence hint: ${hint}`);
+  }
+};
+
+export const doctorGovernanceIsBlocking = (snapshot: GovernanceObservationSnapshot): boolean =>
+  snapshot.governance_effective === 'blocked';
+
+export const doctorGovernanceNeedsAttention = (snapshot: GovernanceObservationSnapshot): boolean =>
+  snapshot.governance_effective !== 'green';

package/integrations/lifecycle/index.ts

@@ -1,4 +1,6 @@
 export { runLifecycleDoctor, doctorHasBlockingIssues } from './doctor';
+export { runLifecycleAudit } from './audit';
+export type { LifecycleAuditResult, LifecycleAuditStage } from './audit';
 export { runLifecycleInstall } from './install';
 export { runLifecycleUninstall } from './uninstall';
 export { runLifecycleRemove } from './remove';

package/integrations/lifecycle/status.ts

@@ -9,6 +9,15 @@ import {
   readLifecyclePolicyValidationSnapshot,
   type LifecyclePolicyValidationSnapshot,
 } from './policyValidationSnapshot';
+import {
+  readGovernanceObservationSnapshot,
+  type GovernanceObservationSnapshot,
+} from './governanceObservationSnapshot';
+import {
+  readGovernanceNextAction,
+  type GovernanceNextActionReader,
+  type GovernanceNextActionSummary,
+} from './governanceNextAction';
 import { readLifecycleState, type LifecycleState } from './state';
 
 export type LifecycleStatus = {
@@ -22,11 +31,14 @@ export type LifecycleStatus = {
   trackedNodeModulesCount: number;
   policyValidation: LifecyclePolicyValidationSnapshot;
   experimentalFeatures: LifecycleExperimentalFeaturesSnapshot;
+  governanceObservation: GovernanceObservationSnapshot;
+  governanceNextAction: GovernanceNextActionSummary;
 };
 
 export const readLifecycleStatus = (params?: {
   cwd?: string;
   git?: ILifecycleGitService;
+  governanceNextActionReader?: GovernanceNextActionReader;
 }): LifecycleStatus => {
   const git = params?.git ?? new LifecycleGitService();
   const cwd = params?.cwd ?? process.cwd();
@@ -38,6 +50,19 @@ export const readLifecycleStatus = (params?: {
     repoRoot,
     lifecycleVersion: lifecycleState.version,
   });
+  const policyValidation = readLifecyclePolicyValidationSnapshot(repoRoot);
+  const experimentalFeatures = readLifecycleExperimentalFeaturesSnapshot();
+  const governanceObservation = readGovernanceObservationSnapshot({
+    repoRoot,
+    experimentalFeatures,
+    policyValidation,
+    git,
+  });
+  const governanceNextAction = (params?.governanceNextActionReader ?? readGovernanceNextAction)({
+    repoRoot,
+    stage: 'PRE_WRITE',
+    governanceObservation,
+  });
 
   return {
     repoRoot,
@@ -48,7 +73,9 @@ export const readLifecycleStatus = (params?: {
     hooksDirectory: hooksDirectory.path,
     hooksDirectoryResolution: hooksDirectory.source,
     trackedNodeModulesCount,
-    policyValidation: readLifecyclePolicyValidationSnapshot(repoRoot),
-    experimentalFeatures: readLifecycleExperimentalFeaturesSnapshot(),
+    policyValidation,
+    experimentalFeatures,
+    governanceNextAction,
+    governanceObservation,
   };
 };

package/integrations/mcp/autoExecuteAiStart.ts

@@ -1,3 +1,7 @@
+import {
+  buildGovernanceValidateCommand,
+  resolveGovernanceCatalogAction,
+} from '../gate/governanceActionCatalog';
 import { evaluateAiGate, type AiGateStage, type AiGateViolation } from '../gate/evaluateAiGate';
 import { collectWorktreeAtomicSlices } from '../git/worktreeAtomicSlices';
 import { resolveLearningContextExperimentalFeature } from '../policy/experimentalFeatures';
@@ -56,90 +60,87 @@ const confidenceFromViolation = (violationCode: string | null): number => {
   return 50;
 };
 
-const nextActionFromViolation = (
-  violation: AiGateViolation | undefined,
-  repoRoot: string
-): AutoExecuteNextAction => {
-  if (!violation) {
-    return {
-      kind: 'info',
-      message: 'Gate listo. Puedes continuar con implementación.',
-    };
-  }
-  switch (violation.code) {
-    case 'EVIDENCE_MISSING':
+const normalizeGovernanceCatalogCode = (code: string): string => {
+  switch (code) {
     case 'EVIDENCE_INVALID':
     case 'EVIDENCE_CHAIN_INVALID':
-    case 'EVIDENCE_STALE':
-      return {
-        kind: 'run_command',
-        message: 'Regenera o refresca evidencia y vuelve a evaluar PRE_WRITE.',
-        command: 'npx --yes --package pumuki@latest pumuki sdd validate --stage=PRE_WRITE --json',
-      };
-    case 'EVIDENCE_ACTIVE_RULE_IDS_EMPTY_FOR_CODE_CHANGES':
-      return {
-        kind: 'run_command',
-        message:
-          'No hay active_rule_ids para plataforma de código detectada. Reconciliación strict de policy/skills y revalidación PRE_WRITE.',
-        command:
-          'npx --yes --package pumuki@latest pumuki policy reconcile --strict --json && npx --yes --package pumuki@latest pumuki sdd validate --stage=PRE_WRITE --json',
-      };
-    case 'EVIDENCE_PLATFORM_SKILLS_SCOPE_INCOMPLETE':
-    case 'EVIDENCE_PLATFORM_SKILLS_BUNDLES_MISSING':
-    case 'EVIDENCE_SKILLS_CONTRACT_INCOMPLETE':
-      return {
-        kind: 'run_command',
-        message:
-          'Completa cobertura de skills por plataforma (prefijos + bundles) y revalida PRE_WRITE.',
-        command: 'npx --yes --package pumuki@latest pumuki sdd validate --stage=PRE_WRITE --json',
-      };
-    case 'EVIDENCE_PLATFORM_CRITICAL_SKILLS_RULES_MISSING':
-    case 'EVIDENCE_CROSS_PLATFORM_CRITICAL_ENFORCEMENT_INCOMPLETE':
-      return {
-        kind: 'run_command',
-        message:
-          'Reconcilia policy/skills en modo estricto (incluida skills.ios.critical-test-quality cuando aplique) y revalida PRE_WRITE.',
-        command:
-          'npx --yes --package pumuki@latest pumuki policy reconcile --strict --json && npx --yes --package pumuki@latest pumuki sdd validate --stage=PRE_WRITE --json',
-      };
-    case 'EVIDENCE_PREWRITE_WORKTREE_OVER_LIMIT':
-    case 'EVIDENCE_PREWRITE_WORKTREE_WARN':
-      {
-        const plan = collectWorktreeAtomicSlices({
-          repoRoot,
-          maxSlices: 3,
-          maxFilesPerSlice: 4,
-        });
-        if (plan.slices.length > 0) {
-          const firstSlice = plan.slices[0];
-          return {
-            kind: 'run_command',
-            message:
-              `Particiona el worktree en slices atómicos por scope. Primer lote sugerido: ${firstSlice?.scope ?? 'scope-desconocido'}.`,
-            command:
-              `${firstSlice?.staged_command ?? 'git add -p'} && npx --yes --package pumuki@latest pumuki sdd validate --stage=PRE_WRITE --json`,
-          };
-        }
-      }
-      return {
-        kind: 'run_command',
-        message:
-          'Particiona el worktree en slices atómicos y revalida PRE_WRITE para continuar sin fricción.',
-        command:
-          'git status --short && git add -p && npx --yes --package pumuki@latest pumuki sdd validate --stage=PRE_WRITE --json',
-      };
+      return 'EVIDENCE_INVALID_OR_CHAIN';
     case 'GITFLOW_PROTECTED_BRANCH':
-      return {
-        kind: 'run_command',
-        message: 'Cambia a una rama feature/* antes de continuar.',
-        command: 'git checkout -b feature/<descripcion-kebab-case>',
-      };
+      return 'GITFLOW_PROTECTED_BRANCH_CONTEXT';
     default:
+      return code;
+  }
+};
+
+const resolveAutoExecuteRemediation = (params: {
+  violation: AiGateViolation | undefined;
+  repoRoot: string;
+  stage: AiGateStage;
+  allowed: boolean;
+}): {
+  instruction: string;
+  nextAction: AutoExecuteNextAction;
+} => {
+  if (!params.violation) {
+    const readyAction = resolveGovernanceCatalogAction({
+      code: 'READY',
+      stage: params.stage,
+    });
+    return {
+      instruction: readyAction.instruction,
+      nextAction: readyAction.next_action,
+    };
+  }
+
+  if (
+    params.violation.code === 'EVIDENCE_PREWRITE_WORKTREE_OVER_LIMIT'
+    || params.violation.code === 'EVIDENCE_PREWRITE_WORKTREE_WARN'
+  ) {
+    const validateCommand = buildGovernanceValidateCommand(params.stage);
+    const plan = collectWorktreeAtomicSlices({
+      repoRoot: params.repoRoot,
+      maxSlices: 3,
+      maxFilesPerSlice: 4,
+    });
+    if (plan.slices.length > 0) {
+      const firstSlice = plan.slices[0];
       return {
-        kind: 'info',
-        message: 'Corrige la violación bloqueante y vuelve a ejecutar auto_execute_ai_start.',
+        instruction: 'Particiona el worktree en slices atómicos antes de continuar.',
+        nextAction: {
+          kind: params.allowed ? 'info' : 'run_command',
+          message:
+            `Particiona el worktree en slices atómicos por scope. Primer lote sugerido: ${firstSlice?.scope ?? 'scope-desconocido'}.`,
+          command: params.allowed
+            ? undefined
+            : `${firstSlice?.staged_command ?? 'git add -p'} && ${validateCommand}`,
+        },
       };
+    }
+    return {
+      instruction: 'Particiona el worktree en slices atómicos antes de continuar.',
+      nextAction: {
+        kind: params.allowed ? 'info' : 'run_command',
+        message: 'Particiona el worktree en slices atómicos y revalida PRE_WRITE para continuar sin fricción.',
+        command: params.allowed
+          ? undefined
+          : `git status --short && git add -p && ${validateCommand}`,
+      },
+    };
   }
+
+  const governanceAction = resolveGovernanceCatalogAction({
+    code: normalizeGovernanceCatalogCode(params.violation.code),
+    stage: params.stage,
+  });
+  return {
+    instruction: governanceAction.instruction,
+    nextAction: params.allowed
+      ? {
+        kind: 'info',
+        message: governanceAction.next_action.message,
+      }
+      : governanceAction.next_action,
+  };
 };
 
 export type EnterpriseAutoExecuteAiStartResult = {
@@ -190,19 +191,20 @@ export const runEnterpriseAutoExecuteAiStart = (params: {
   const action: AutoExecuteAction = evaluation.allowed ? 'proceed' : 'ask';
   const phase = toAutoExecutePhase(action);
   const confidencePct = confidenceFromViolation(firstViolation?.code ?? null);
-  const nextAction = evaluation.allowed
-    ? {
-      kind: 'info' as const,
-      message: 'Gate en verde. Continúa con la implementación.',
-    }
-    : nextActionFromViolation(firstViolation, params.repoRoot);
+  const remediation = resolveAutoExecuteRemediation({
+    violation: firstViolation,
+    repoRoot: params.repoRoot,
+    stage,
+    allowed: evaluation.allowed,
+  });
+  const nextAction = remediation.nextAction;
 
   let message = toHumanMessage({
     action,
     confidencePct,
     reasonCode,
   });
-  let instruction = nextAction.message;
+  let instruction = remediation.instruction;
   if (learningContext?.recommended_actions[0]) {
     message = `${message} Learning: ${learningContext.recommended_actions[0]}`;
     instruction = `${instruction} Learning: ${learningContext.recommended_actions[0]}`;

package/integrations/mcp/preFlightCheck.ts

@@ -1,11 +1,14 @@
+import {
+  resolveGovernanceCatalogAction,
+  type GovernanceCatalogNextAction,
+} from '../gate/governanceActionCatalog';
 import { evaluateAiGate, type AiGateStage, type AiGateViolation } from '../gate/evaluateAiGate';
 import { collectWorktreeAtomicSlices } from '../git/worktreeAtomicSlices';
 import { resolveLearningContextExperimentalFeature } from '../policy/experimentalFeatures';
 import { readSddLearningContext, type SddLearningContext } from '../sdd/learningInsights';
 
 const ACTIONABLE_HINTS_BY_CODE: Readonly<Record<string, string>> = {
-  EVIDENCE_MISSING:
-    'Ejecuta una auditoría (1/2/3/4 u opciones de motor 11–14) para regenerar .ai_evidence.json.',
+  EVIDENCE_MISSING: 'Ejecuta una auditoría (1/2/3/4) para regenerar .ai_evidence.json.',
   EVIDENCE_INVALID: 'Regenera .ai_evidence.json desde una opción de auditoría.',
   EVIDENCE_INTEGRITY_MISSING: 'Refresca evidencia para regenerar metadatos de integridad.',
   EVIDENCE_ACTIVE_RULE_IDS_EMPTY_FOR_CODE_CHANGES:
@@ -41,6 +44,18 @@ const ACTIONABLE_HINTS_BY_CODE: Readonly<Record<string, string>> = {
   GITFLOW_PROTECTED_BRANCH: 'Evita trabajo directo en ramas protegidas (usa feature/*).',
 };
 
+const normalizeGovernanceCatalogCode = (code: string): string => {
+  switch (code) {
+    case 'EVIDENCE_INVALID':
+    case 'EVIDENCE_CHAIN_INVALID':
+      return 'EVIDENCE_INVALID_OR_CHAIN';
+    case 'GITFLOW_PROTECTED_BRANCH':
+      return 'GITFLOW_PROTECTED_BRANCH_CONTEXT';
+    default:
+      return code;
+  }
+};
+
 const buildPreFlightHints = (params: {
   repoRoot: string;
   stage: AiGateStage;
@@ -115,6 +130,8 @@ export type EnterprisePreFlightCheckResult = {
     phase: 'GREEN' | 'RED';
     message: string;
     instruction: string;
+    reason_code: string;
+    next_action: GovernanceCatalogNextAction;
     stage: ReturnType<typeof evaluateAiGate>['stage'];
     policy: ReturnType<typeof evaluateAiGate>['policy'];
     violations: ReturnType<typeof evaluateAiGate>['violations'];
@@ -154,13 +171,30 @@ export const runEnterprisePreFlightCheck = (params: {
     upstream: evaluation.repo_state.git.upstream,
     learningContext,
   });
+  const firstViolation = evaluation.violations[0];
+  const reasonCode = firstViolation?.code ?? 'READY';
+  const governanceAction = firstViolation
+    ? resolveGovernanceCatalogAction({
+      code: normalizeGovernanceCatalogCode(firstViolation.code),
+      stage: evaluation.stage,
+    })
+    : resolveGovernanceCatalogAction({
+      code: 'READY',
+      stage: evaluation.stage,
+    });
   const phase: 'GREEN' | 'RED' = evaluation.allowed ? 'GREEN' : 'RED';
   const message = evaluation.allowed
     ? '✅ Pre-flight aprobado: puedes continuar con la implementación.'
-    : `🔴 Pre-flight bloqueado: corrige ${evaluation.violations[0]?.code ?? 'la causa'} y vuelve a ejecutar.`;
-  const instruction = evaluation.allowed
+    : `🔴 Pre-flight bloqueado: corrige ${reasonCode} y vuelve a ejecutar.`;
+  const instruction = !firstViolation && evaluation.allowed
     ? 'Implementa el cambio mínimo para pasar en verde y vuelve a validar.'
-    : hints[0] ?? 'Corrige la causa bloqueante y vuelve a ejecutar el pre-flight.';
+    : governanceAction.instruction;
+  const nextAction: GovernanceCatalogNextAction = evaluation.allowed
+    ? {
+      kind: 'info',
+      message: governanceAction.next_action.message,
+    }
+    : governanceAction.next_action;
 
   return {
     tool: 'pre_flight_check',
@@ -173,6 +207,8 @@ export const runEnterprisePreFlightCheck = (params: {
       phase,
       message,
       instruction,
+      reason_code: reasonCode,
+      next_action: nextAction,
       stage: evaluation.stage,
       policy: evaluation.policy,
       violations: evaluation.violations,