pumuki 6.3.113 → 6.3.115

package/scripts/pumuki-full-surface-smoke.ts

@@ -0,0 +1,346 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  installedBinMarkerPath,
+  resolveSmokeLayout,
+} from './pumuki-full-surface-smoke-lib';
+
+type SmokeRowKind = 'core' | 'diagnostic';
+
+type SmokeRow = {
+  id: string;
+  bin: string;
+  args: ReadonlyArray<string>;
+  timeoutMs: number;
+  allowNonZero?: boolean;
+  kind: SmokeRowKind;
+};
+
+const parseBooleanEnv = (raw: string | undefined): boolean => {
+  const value = (raw ?? '').trim().toLowerCase();
+  return value === '1' || value === 'true' || value === 'yes';
+};
+
+const includeDiagnosticRowsInStrict = parseBooleanEnv(
+  process.env.PUMUKI_SMOKE_INCLUDE_DIAGNOSTIC_ROWS
+);
+
+const layout = resolveSmokeLayout({
+  scriptFileUrl: import.meta.url,
+  env: process.env,
+});
+
+const { pumukiPackageRoot, smokeCwd, binStrategy, binRoot } = layout;
+const node = process.execPath;
+const binPath = (name: string): string => join(binRoot, 'bin', name);
+
+const run = (row: SmokeRow): { code: number | null; signal: NodeJS.Signals | null; ms: number } => {
+  const started = Date.now();
+  const r = spawnSync(node, [binPath(row.bin), ...row.args], {
+    cwd: smokeCwd,
+    encoding: 'utf8',
+    timeout: row.timeoutMs,
+    maxBuffer: 50 * 1024 * 1024,
+    env: { ...process.env, FORCE_COLOR: '0' },
+  });
+  return { code: r.status, signal: r.signal, ms: Date.now() - started };
+};
+
+const rows: ReadonlyArray<SmokeRow> = [
+  { id: 'cli.help_implicit', bin: 'pumuki.js', args: [], timeoutMs: 15_000, kind: 'core', allowNonZero: true },
+  { id: 'cli.help_explicit', bin: 'pumuki.js', args: ['--help'], timeoutMs: 15_000, kind: 'core' },
+  {
+    id: 'cli.unknown_subcommand',
+    bin: 'pumuki.js',
+    args: ['__no_such_lifecycle_command__'],
+    timeoutMs: 15_000,
+    kind: 'core',
+    allowNonZero: true,
+  },
+  { id: 'doctor.json', bin: 'pumuki.js', args: ['doctor', '--json'], timeoutMs: 60_000, kind: 'core' },
+  {
+    id: 'doctor.deep_json',
+    bin: 'pumuki.js',
+    args: ['doctor', '--deep', '--json'],
+    timeoutMs: 180_000,
+    kind: 'core',
+    allowNonZero: true,
+  },
+  { id: 'doctor.parity_json', bin: 'pumuki.js', args: ['doctor', '--parity', '--json'], timeoutMs: 120_000, kind: 'core' },
+  { id: 'status.json', bin: 'pumuki.js', args: ['status', '--json'], timeoutMs: 90_000, kind: 'core' },
+  {
+    id: 'audit.default_json',
+    bin: 'pumuki.js',
+    args: ['audit', '--json'],
+    timeoutMs: 300_000,
+    kind: 'core',
+    allowNonZero: true,
+  },
+  {
+    id: 'audit.pre_push_json',
+    bin: 'pumuki.js',
+    args: ['audit', '--stage=PRE_PUSH', '--json'],
+    timeoutMs: 300_000,
+    kind: 'core',
+    allowNonZero: true,
+  },
+  {
+    id: 'audit.ci_engine_json',
+    bin: 'pumuki.js',
+    args: ['audit', '--stage=CI', '--engine', '--json'],
+    timeoutMs: 300_000,
+    kind: 'core',
+    allowNonZero: true,
+  },
+  {
+    id: 'watch.once_json',
+    bin: 'pumuki.js',
+    args: [
+      'watch',
+      '--once',
+      '--json',
+      '--stage=PRE_COMMIT',
+      '--scope=repo',
+      '--interval-ms=200',
+      '--no-notify',
+    ],
+    timeoutMs: 180_000,
+    kind: 'diagnostic',
+  },
+  {
+    id: 'watch.once_staged_json',
+    bin: 'pumuki.js',
+    args: [
+      'watch',
+      '--once',
+      '--json',
+      '--stage=PRE_COMMIT',
+      '--scope=staged',
+      '--interval-ms=200',
+      '--no-notify',
+    ],
+    timeoutMs: 180_000,
+    kind: 'diagnostic',
+    allowNonZero: true,
+  },
+  {
+    id: 'loop.list_json',
+    bin: 'pumuki.js',
+    args: ['loop', 'list', '--json'],
+    timeoutMs: 30_000,
+    kind: 'core',
+  },
+  {
+    id: 'loop.run_smoke',
+    bin: 'pumuki.js',
+    args: ['loop', 'run', '--objective=smoke-surface', '--max-attempts=1', '--json'],
+    timeoutMs: 300_000,
+    kind: 'core',
+    allowNonZero: true,
+  },
+  {
+    id: 'adapter.install_dry_repo_json',
+    bin: 'pumuki.js',
+    args: ['adapter', 'install', '--agent=repo', '--dry-run', '--json'],
+    timeoutMs: 30_000,
+    kind: 'core',
+  },
+  {
+    id: 'adapter.install_dry_codex_json',
+    bin: 'pumuki.js',
+    args: ['adapter', 'install', '--agent=codex', '--dry-run', '--json'],
+    timeoutMs: 30_000,
+    kind: 'core',
+  },
+  {
+    id: 'analytics.hotspots_report',
+    bin: 'pumuki.js',
+    args: ['analytics', 'hotspots', 'report', '--top=3', '--since-days=30', '--json'],
+    timeoutMs: 120_000,
+    kind: 'diagnostic',
+    allowNonZero: true,
+  },
+  {
+    id: 'analytics.hotspots_diagnose',
+    bin: 'pumuki.js',
+    args: ['analytics', 'hotspots', 'diagnose', '--json'],
+    timeoutMs: 120_000,
+    kind: 'diagnostic',
+    allowNonZero: true,
+  },
+  {
+    id: 'policy.reconcile_json',
+    bin: 'pumuki.js',
+    args: ['policy', 'reconcile', '--json'],
+    timeoutMs: 120_000,
+    kind: 'diagnostic',
+    allowNonZero: true,
+  },
+  {
+    id: 'policy.reconcile_strict_json',
+    bin: 'pumuki.js',
+    args: ['policy', 'reconcile', '--strict', '--json'],
+    timeoutMs: 120_000,
+    kind: 'diagnostic',
+    allowNonZero: true,
+  },
+  {
+    id: 'sdd.status_json',
+    bin: 'pumuki.js',
+    args: ['sdd', 'status', '--json'],
+    timeoutMs: 60_000,
+    kind: 'diagnostic',
+  },
+  {
+    id: 'sdd.validate_pre_write_json',
+    bin: 'pumuki.js',
+    args: ['sdd', 'validate', '--stage=PRE_WRITE', '--json'],
+    timeoutMs: 120_000,
+    kind: 'diagnostic',
+    allowNonZero: true,
+  },
+  {
+    id: 'sdd.validate_precommit_json',
+    bin: 'pumuki.js',
+    args: ['sdd', 'validate', '--stage=PRE_COMMIT', '--json'],
+    timeoutMs: 120_000,
+    kind: 'diagnostic',
+    allowNonZero: true,
+  },
+  {
+    id: 'sdd.validate_prepush_json',
+    bin: 'pumuki.js',
+    args: ['sdd', 'validate', '--stage=PRE_PUSH', '--json'],
+    timeoutMs: 120_000,
+    kind: 'diagnostic',
+    allowNonZero: true,
+  },
+  {
+    id: 'sdd.validate_ci_json',
+    bin: 'pumuki.js',
+    args: ['sdd', 'validate', '--stage=CI', '--json'],
+    timeoutMs: 120_000,
+    kind: 'diagnostic',
+    allowNonZero: true,
+  },
+  {
+    id: 'hook.pre_write',
+    bin: 'pumuki-pre-write.js',
+    args: [],
+    timeoutMs: 300_000,
+    kind: 'diagnostic',
+    allowNonZero: true,
+  },
+  {
+    id: 'hook.pre_commit',
+    bin: 'pumuki-pre-commit.js',
+    args: [],
+    timeoutMs: 300_000,
+    kind: 'diagnostic',
+    allowNonZero: true,
+  },
+  {
+    id: 'hook.pre_push',
+    bin: 'pumuki-pre-push.js',
+    args: [],
+    timeoutMs: 300_000,
+    kind: 'diagnostic',
+    allowNonZero: true,
+  },
+  {
+    id: 'hook.ci',
+    bin: 'pumuki-ci.js',
+    args: [],
+    timeoutMs: 300_000,
+    kind: 'diagnostic',
+    allowNonZero: true,
+  },
+];
+
+const main = (): number => {
+  if (binStrategy === 'installed') {
+    const marker = installedBinMarkerPath(layout);
+    if (!existsSync(marker)) {
+      process.stderr.write(
+        `[pumuki] smoke: PUMUKI_SMOKE_BIN_STRATEGY=installed pero no existe ${marker}. ` +
+          'Ejecuta npm install en el consumidor o revisa PUMUKI_SMOKE_REPO_ROOT.\n'
+      );
+      return 2;
+    }
+  }
+
+  const lines: string[] = [];
+  lines.push('# Pumuki superficie — smoke');
+  lines.push('');
+  lines.push(`- binStrategy: \`${binStrategy}\` (PUMUKI_SMOKE_BIN_STRATEGY=source|installed)`);
+  lines.push(`- binRoot: \`${binRoot}\``);
+  lines.push(`- pumukiPackageRoot (script host): \`${pumukiPackageRoot}\``);
+  lines.push(`- smokeCwd (gate/doctor cwd): \`${smokeCwd}\``);
+  lines.push(`- node: \`${node}\``);
+  lines.push(
+    `- filas: **${rows.length}** (incluye CLI, doctor/status, audit×3, watch×2, loop, adapter×2, analytics×2, policy×2, sdd×5, hooks×4)`
+  );
+  lines.push(
+    `- modo: \`${includeDiagnosticRowsInStrict ? 'strict+diagnostic' : 'strict-only'}\`` +
+      ' (activar diagnóstico con `PUMUKI_SMOKE_INCLUDE_DIAGNOSTIC_ROWS=1`)'
+  );
+  lines.push('');
+  lines.push('| id | tipo | exit | ms | ok |');
+  lines.push('|----|----|------|----|----|');
+  let strictFailed = 0;
+  let diagnosticFailed = 0;
+  for (const row of rows) {
+    const { code, signal, ms } = run(row);
+    const exit = signal ? `signal:${signal}` : String(code ?? 'null');
+    const ok =
+      signal !== null
+        ? false
+        : row.allowNonZero
+          ? true
+          : code === 0;
+    const isStrict = row.kind === 'core' || includeDiagnosticRowsInStrict;
+    if (!ok) {
+      if (isStrict) {
+        strictFailed += 1;
+      } else {
+        diagnosticFailed += 1;
+      }
+    }
+    lines.push(`| ${row.id} | ${row.kind} | ${exit} | ${ms} | ${ok ? 'yes' : 'no'} |`);
+  }
+  lines.push('');
+  lines.push('## Interpretación de exit codes');
+  lines.push('');
+  lines.push('- `audit` devuelve el **mismo código que el gate** del alcance auditado (p. ej. 1 si hay `BLOCK` en el repo). Eso es correcto, no indica CLI roto.');
+  lines.push('- `doctor --deep` puede devolver **1** si `doctorHasBlockingIssues` (issues `error` o `deep.blocking`) o mismatch de parity esperado.');
+  lines.push('- Los comandos de diagnóstico (`diagnostic`) quedan fuera de fallo estricto por defecto.');
+  lines.push('- `sdd validate` y `policy reconcile --strict` pueden devolver **1** según política del repo; el smoke los marca con `allowNonZero`.');
+  lines.push('');
+  lines.push('## No cubierto aquí (manual o destructivo)');
+  lines.push('');
+  lines.push('- `pumuki install|uninstall|remove|update|bootstrap` (mutan hooks/artefactos).');
+  lines.push('- `pumuki framework` / menú interactivo (`pumuki-framework.js`).');
+  lines.push('- Servidores MCP stdio (`pumuki-mcp-*-stdio.js`): esperan JSON-RPC por stdin; probar con cliente MCP.');
+  lines.push('- `pumuki sdd session|sync|learn|evidence|state-sync|auto-sync`: requieren ids / evidencia / cambios reales.');
+  lines.push('- `pumuki doctor|status --remote-checks`: dependen de red / GitHub.');
+  lines.push('');
+  lines.push('## Otro repo (consumidor)');
+  lines.push('');
+  lines.push(
+    '- **Bins del tree pumuki (desarrollo):** `PUMUKI_SMOKE_REPO_ROOT=/ruta/al/repo npm run -s smoke:pumuki-surface` desde la raíz de **pumuki** (`PUMUKI_SMOKE_BIN_STRATEGY=source` por defecto).'
+  );
+  lines.push(
+    '- **Bins instalados en el consumidor (`node_modules/pumuki`):** `PUMUKI_SMOKE_REPO_ROOT=/ruta/al/repo PUMUKI_SMOKE_BIN_STRATEGY=installed npm run -s smoke:pumuki-surface` o `npm run -s smoke:pumuki-surface-installed` (exige `PUMUKI_SMOKE_REPO_ROOT`).'
+  );
+  lines.push('');
+  lines.push(
+    `**Resumen:** ${strictFailed} filas críticas con fallo estricto (sin allowNonZero),` +
+      ` ${diagnosticFailed} filas diagnósticas con fallo no bloqueante.`
+  );
+  process.stdout.write(lines.join('\n'));
+  process.stdout.write('\n');
+  return strictFailed > 0 ? 1 : 0;
+};
+
+process.exitCode = main();

package/scripts/pumuki-smoke-installed-wrapper.cjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const { join } = require('node:path');
+
+if (!process.env.PUMUKI_SMOKE_REPO_ROOT || !String(process.env.PUMUKI_SMOKE_REPO_ROOT).trim()) {
+  console.error(
+    '[pumuki] smoke:pumuki-surface-installed requires PUMUKI_SMOKE_REPO_ROOT (absolute path to consumer repo).'
+  );
+  process.exit(1);
+}
+
+const root = join(__dirname, '..');
+const env = {
+  ...process.env,
+  PUMUKI_SMOKE_BIN_STRATEGY: 'installed',
+};
+
+const result = spawnSync(
+  'npx',
+  ['--yes', 'tsx@4.21.0', 'scripts/pumuki-full-surface-smoke.ts'],
+  {
+    cwd: root,
+    env,
+    stdio: 'inherit',
+  }
+);
+
+const code = typeof result.status === 'number' ? result.status : 1;
+process.exitCode = code;

package/integrations/evidence/trackingContract.ts

@@ -1,17 +0,0 @@
-import type { RepoTrackingDeclaration, RepoTrackingState } from './schema';
-import { resolveRepoTrackingState } from '../lifecycle/trackingState';
-
-export const readRepoTrackingState = (repoRoot: string): RepoTrackingState => {
-  const state = resolveRepoTrackingState(repoRoot);
-
-  return {
-    enforced: state.enforced,
-    canonical_path: state.canonical_path,
-    canonical_present: state.canonical_present,
-    source_file: state.source_file,
-    in_progress_count: state.in_progress_count,
-    single_in_progress_valid: state.single_in_progress_valid,
-    conflict: state.conflict,
-    declarations: state.declarations as ReadonlyArray<RepoTrackingDeclaration>,
-  };
-};

package/integrations/gate/governanceActionCatalog.ts

@@ -1,275 +0,0 @@
-import type { AiGateStage } from './evaluateAiGate';
-
-export type GovernanceCatalogNextAction = {
-  kind: 'info' | 'run_command';
-  message: string;
-  command?: string;
-};
-
-export type GovernanceCatalogAction = {
-  reason_code: string;
-  instruction: string;
-  next_action: GovernanceCatalogNextAction;
-};
-
-const PRE_WRITE_VALIDATE_COMMAND =
-  'npx --yes --package pumuki@latest pumuki sdd validate --stage=PRE_WRITE --json';
-
-export const buildGovernanceValidateCommand = (stage: AiGateStage): string =>
-  PRE_WRITE_VALIDATE_COMMAND.replace('PRE_WRITE', stage);
-
-export const buildGovernancePolicyReconcileCommand = (stage: AiGateStage): string =>
-  `npx --yes --package pumuki@latest pumuki policy reconcile --strict --json && ${buildGovernanceValidateCommand(stage)}`;
-
-const buildFallbackAction = (code: string): GovernanceCatalogAction => ({
-  reason_code: code,
-  instruction: 'Corrige el bloqueante primario y vuelve a ejecutar la validación del stage actual.',
-  next_action: {
-    kind: 'info',
-    message: 'Corrige el bloqueante primario y vuelve a ejecutar el mismo comando.',
-  },
-});
-
-export const resolveGovernanceCatalogAction = (params: {
-  code: string;
-  stage?: AiGateStage;
-  fallback?: GovernanceCatalogAction;
-}): GovernanceCatalogAction => {
-  const stage = params.stage ?? 'PRE_WRITE';
-  const validateCommand = buildGovernanceValidateCommand(stage);
-  switch (params.code) {
-    case 'READY':
-      return {
-        reason_code: 'READY',
-        instruction: 'Puedes continuar con la siguiente slice mínima y volver a validar al cerrar.',
-        next_action: {
-          kind: 'info',
-          message: 'Gate en verde. Continúa con la implementación.',
-        },
-      };
-    case 'EVIDENCE_INVALID_OR_CHAIN':
-      return {
-        reason_code: 'EVIDENCE_INVALID_OR_CHAIN',
-        instruction: 'Regenera la evidencia canónica antes de continuar.',
-        next_action: {
-          kind: 'run_command',
-          message: 'Regenera o corrige la evidencia canónica (.ai_evidence.json) y vuelve a validar governance.',
-          command: validateCommand,
-        },
-      };
-    case 'AI_GATE_BLOCKED':
-      return {
-        reason_code: 'AI_GATE_BLOCKED',
-        instruction: 'Corrige primero el bloqueo principal del gate antes de continuar.',
-        next_action: {
-          kind: 'run_command',
-          message: 'Revalida el stage tras corregir la evidencia y el bloqueo principal.',
-          command: validateCommand,
-        },
-      };
-    case 'SDD_SESSION_MISSING':
-      return {
-        reason_code: 'SDD_SESSION_MISSING',
-        instruction: 'Abre una sesión SDD válida antes de seguir trabajando.',
-        next_action: {
-          kind: 'run_command',
-          message: 'Abre la sesión SDD del cambio activo y vuelve a validar.',
-          command: 'npx --yes --package pumuki@latest pumuki sdd session --open --change=<id>',
-        },
-      };
-    case 'SDD_SESSION_INVALID':
-    case 'SDD_SESSION_INVALID_OR_EXPIRED':
-      return {
-        reason_code: 'SDD_SESSION_INVALID_OR_EXPIRED',
-        instruction: 'Refresca o reabre la sesión SDD antes de seguir trabajando.',
-        next_action: {
-          kind: 'run_command',
-          message: 'Refresca la sesión SDD y vuelve a validar governance.',
-          command: 'npx --yes --package pumuki@latest pumuki sdd session --refresh --ttl-minutes=90',
-        },
-      };
-    case 'PRE_PUSH_UPSTREAM_MISSING':
-      return {
-        reason_code: 'PRE_PUSH_UPSTREAM_MISSING',
-        instruction: 'Configura el upstream remoto antes de continuar con PRE_PUSH.',
-        next_action: {
-          kind: 'run_command',
-          message: 'Configura tracking remoto para la rama actual.',
-          command: 'git push --set-upstream origin <branch>',
-        },
-      };
-    case 'PRE_PUSH_UPSTREAM_MISALIGNED':
-      return {
-        reason_code: 'PRE_PUSH_UPSTREAM_MISALIGNED',
-        instruction: 'Alinea el upstream remoto con la rama actual antes de continuar.',
-        next_action: {
-          kind: 'run_command',
-          message: 'Reconfigura el upstream remoto de la rama actual.',
-          command: 'git branch --unset-upstream && git push --set-upstream origin <branch>',
-        },
-      };
-    case 'GITFLOW_PROTECTED_BRANCH':
-    case 'GITFLOW_PROTECTED_BRANCH_CONTEXT':
-      return {
-        reason_code: 'GITFLOW_PROTECTED_BRANCH_CONTEXT',
-        instruction: 'Sal de la rama protegida y mueve el trabajo a feature/* o refactor/*.',
-        next_action: {
-          kind: 'run_command',
-          message: 'Crea una rama válida de trabajo antes de seguir.',
-          command: 'git checkout -b feature/<descripcion-kebab-case>',
-        },
-      };
-    case 'GITFLOW_BRANCH_NAMING_INVALID':
-    case 'GITFLOW_BRANCH_NAMING_INVALID_CONTEXT':
-      return {
-        reason_code: 'GITFLOW_BRANCH_NAMING_INVALID_CONTEXT',
-        instruction:
-          'Renombra o recrea la rama actual con un prefijo GitFlow válido antes de continuar.',
-        next_action: {
-          kind: 'run_command',
-          message: 'Crea una rama válida y mueve el trabajo a esa rama antes de seguir.',
-          command: 'git checkout -b feature/<descripcion-kebab-case>',
-        },
-      };
-    case 'TRACKING_CANONICAL_SOURCE_CONFLICT':
-      return {
-        reason_code: 'TRACKING_CANONICAL_SOURCE_CONFLICT',
-        instruction:
-          'Alinea AGENTS.md y los README canónicos para que todos apunten al mismo MD de seguimiento.',
-        next_action: {
-          kind: 'info',
-          message:
-            'Deja una única fuente canónica de tracking y elimina referencias legacy o contradictorias.',
-        },
-      };
-    case 'TRACKING_CANONICAL_FILE_MISSING':
-      return {
-        reason_code: 'TRACKING_CANONICAL_FILE_MISSING',
-        instruction:
-          'Crea o restaura el MD de seguimiento canónico declarado por el repo antes de continuar.',
-        next_action: {
-          kind: 'info',
-          message:
-            'Restaura el archivo canónico de tracking y vuelve a validar governance.',
-        },
-      };
-    case 'TRACKING_CANONICAL_IN_PROGRESS_INVALID':
-      return {
-        reason_code: 'TRACKING_CANONICAL_IN_PROGRESS_INVALID',
-        instruction:
-          'El tracking canónico debe tener exactamente una tarea o fase en construcción.',
-        next_action: {
-          kind: 'info',
-          message:
-            'Corrige el MD canónico para dejar exactamente una `🚧` antes de continuar.',
-        },
-      };
-    case 'POLICY_STAGE_NOT_STRICT':
-      return {
-        reason_code: 'POLICY_STAGE_NOT_STRICT',
-        instruction: 'Reconcilia policy/skills en modo estricto antes de seguir.',
-        next_action: {
-          kind: 'run_command',
-          message: 'Converge policy-as-code y revalida el stage actual.',
-          command: buildGovernancePolicyReconcileCommand(stage),
-        },
-      };
-    case 'SKILLS_CONTRACT_SURFACE_INCOMPLETE':
-    case 'EVIDENCE_SKILLS_CONTRACT_INCOMPLETE':
-      return {
-        reason_code: 'SKILLS_CONTRACT_SURFACE_INCOMPLETE',
-        instruction: 'Materializa el lock/sources de skills antes de dar governance efectiva.',
-        next_action: {
-          kind: 'run_command',
-          message: 'Reconcilia policy/skills y vuelve a validar governance.',
-          command: buildGovernancePolicyReconcileCommand(stage),
-        },
-      };
-    case 'ADAPTER_WIRING_MISSING':
-      return {
-        reason_code: 'ADAPTER_WIRING_MISSING',
-        instruction: 'Instala el adaptador canónico si quieres wiring explícito de IDE/MCP.',
-        next_action: {
-          kind: 'run_command',
-          message: 'Genera `.pumuki/adapter.json` desde la instalación canónica.',
-          command: 'npx --yes --package pumuki@latest pumuki install --with-mcp',
-        },
-      };
-    case 'EVIDENCE_STALE':
-    case 'EVIDENCE_BRANCH_MISMATCH':
-    case 'EVIDENCE_SNAPSHOT_WARN':
-      return {
-        reason_code: params.code === 'EVIDENCE_SNAPSHOT_WARN' ? 'EVIDENCE_SNAPSHOT_WARN' : 'EVIDENCE_STALE',
-        instruction: 'Refresca evidencia y revisa hallazgos WARN antes de continuar.',
-        next_action: {
-          kind: 'run_command',
-          message: 'Revalida el stage actual y revisa findings WARN.',
-          command: validateCommand,
-        },
-      };
-    case 'ACTIVE_RULE_IDS_EMPTY_FOR_CODE_CHANGES_HIGH':
-    case 'EVIDENCE_ACTIVE_RULE_IDS_EMPTY_FOR_CODE_CHANGES':
-      return {
-        reason_code: 'EVIDENCE_ACTIVE_RULE_IDS_EMPTY_FOR_CODE_CHANGES',
-        instruction: 'Reconcilia policy/skills en modo estricto y revalida el stage actual.',
-        next_action: {
-          kind: 'run_command',
-          message: 'Converge policy-as-code y vuelve a validar cobertura de active_rule_ids para reglas activas.',
-          command: buildGovernancePolicyReconcileCommand(stage),
-        },
-      };
-    case 'EVIDENCE_PLATFORM_SKILLS_SCOPE_INCOMPLETE':
-    case 'EVIDENCE_PLATFORM_SKILLS_BUNDLES_MISSING':
-      return {
-        reason_code: params.code,
-        instruction: 'Completa cobertura de skills por plataforma y vuelve a validar.',
-        next_action: {
-          kind: 'run_command',
-          message: 'Completa bundles/prefijos de skills requeridos y revalida el stage actual.',
-          command: validateCommand,
-        },
-      };
-    case 'EVIDENCE_PLATFORM_CRITICAL_SKILLS_RULES_MISSING':
-    case 'EVIDENCE_CROSS_PLATFORM_CRITICAL_ENFORCEMENT_INCOMPLETE':
-      return {
-        reason_code: params.code,
-        instruction: 'Reconcilia policy/skills en modo estricto para enforcement crítico y revalida.',
-        next_action: {
-          kind: 'run_command',
-          message: 'Materializa reglas críticas de plataforma y vuelve a validar el stage actual.',
-          command: buildGovernancePolicyReconcileCommand(stage),
-        },
-      };
-    case 'EVIDENCE_PREWRITE_WORKTREE_OVER_LIMIT':
-    case 'EVIDENCE_PREWRITE_WORKTREE_WARN':
-      return {
-        reason_code: params.code,
-        instruction: 'Particiona el worktree en slices atómicos antes de continuar.',
-        next_action: {
-          kind: 'run_command',
-          message: 'Reduce el worktree pendiente y revalida el stage actual.',
-          command: `git status --short && git add -p && ${validateCommand}`,
-        },
-      };
-    case 'SKILLS_SKILLS_FRONTEND_NO_SOLID_VIOLATIONS':
-      return {
-        reason_code: 'SKILLS_SKILLS_FRONTEND_NO_SOLID_VIOLATIONS',
-        instruction: 'Aplica refactor incremental por componente/hook y vuelve a validar.',
-        next_action: {
-          kind: 'info',
-          message: 'Aplica refactor incremental: extrae 1 componente/hook por commit y vuelve a ejecutar el gate.',
-        },
-      };
-    case 'GOVERNANCE_ATTENTION':
-      return {
-        reason_code: 'GOVERNANCE_ATTENTION',
-        instruction: 'Revisa governance truth y corrige el primer hueco del contrato antes de continuar.',
-        next_action: {
-          kind: 'info',
-          message: 'Revisa governance truth, corrige el primer gap visible y vuelve a validar.',
-        },
-      };
-    default:
-      return params.fallback ?? buildFallbackAction(params.code);
-  }
-};