pumuki 6.3.129 → 6.3.130

package/integrations/gate/evaluateAiGate.ts

@@ -1,11 +1,12 @@
 import type { EvidenceReadResult } from '../evidence/readEvidence';
 import { readEvidenceResult } from '../evidence/readEvidence';
 import { captureRepoState } from '../evidence/repoState';
-import type { RepoState } from '../evidence/schema';
+import type { RepoState, RepoTrackingState } from '../evidence/schema';
 import { resolvePolicyForStage } from './stagePolicies';
 import { execFileSync } from 'node:child_process';
 import { existsSync, realpathSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { isSeverityAtLeast } from '../../core/rules/Severity';
 import type { SkillsLockV1, SkillsStage } from '../config/skillsLock';
 import {
   loadEffectiveSkillsLock,
@@ -132,6 +133,10 @@ const PREWRITE_WORKTREE_HYGIENE_WARN_THRESHOLD_ENV = 'PUMUKI_PREWRITE_WORKTREE_W
 const PREWRITE_WORKTREE_HYGIENE_BLOCK_THRESHOLD_ENV = 'PUMUKI_PREWRITE_WORKTREE_BLOCK_THRESHOLD';
 
 const DEFAULT_PROTECTED_BRANCHES = new Set(['main', 'master', 'develop', 'dev']);
+const DEFAULT_GITFLOW_BRANCH_PATTERNS = [
+  /^(?:feature|bugfix|hotfix|chore|refactor|docs)\/[a-z0-9]+(?:-[a-z0-9]+)*$/,
+  /^release\/\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/,
+] as const;
 const PREWRITE_SKILLS_PLATFORMS = ['ios', 'android', 'backend', 'frontend'] as const;
 type PreWriteSkillsPlatform = (typeof PREWRITE_SKILLS_PLATFORMS)[number];
 const PLATFORM_SKILLS_RULE_PREFIXES: Readonly<Record<PreWriteSkillsPlatform, string>> = {
@@ -398,6 +403,45 @@ const collectWorktreeChangedPaths = (repoRoot: string): ReadonlyArray<string> =>
   }
 };
 
+const collectGitChangedPaths = (
+  repoRoot: string,
+  args: ReadonlyArray<string>
+): ReadonlyArray<string> => {
+  try {
+    const output = execFileSync(
+      'git',
+      [...args],
+      {
+        cwd: repoRoot,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }
+    );
+    const files = output
+      .split('\n')
+      .map((line) => parseChangedPath(line))
+      .filter((line): line is string => typeof line === 'string' && line.length > 0);
+    return [...new Set(files)];
+  } catch {
+    return [];
+  }
+};
+
+const collectStagedChangedPaths = (repoRoot: string): ReadonlyArray<string> =>
+  collectGitChangedPaths(repoRoot, ['diff', '--cached', '--name-status', '--find-renames']);
+
+const collectRangeChangedPaths = (params: {
+  repoRoot: string;
+  fromRef: string;
+  toRef: string;
+}): ReadonlyArray<string> =>
+  collectGitChangedPaths(params.repoRoot, [
+    'diff',
+    '--name-status',
+    '--find-renames',
+    `${params.fromRef}...${params.toRef}`,
+  ]);
+
 const isPlatformPath = (platform: PreWriteSkillsPlatform, filePath: string): boolean => {
   const normalized = normalizeChangedPath(filePath).toLowerCase();
   if (platform === 'ios') {
@@ -444,6 +488,47 @@ const isPlatformPath = (platform: PreWriteSkillsPlatform, filePath: string): boo
     || /(^|\/)(frontend|web|client)(\/|$)/.test(normalized);
 };
 
+const toDetectedPlatformsFromPaths = (params: {
+  changedPaths: ReadonlyArray<string>;
+  requiredPlatforms: ReadonlyArray<PreWriteSkillsPlatform>;
+}): ReadonlyArray<PreWriteSkillsPlatform> => {
+  if (params.changedPaths.length === 0) {
+    return [];
+  }
+
+  const detected = new Set<PreWriteSkillsPlatform>();
+  for (const filePath of params.changedPaths) {
+    for (const platform of params.requiredPlatforms) {
+      if (isPlatformPath(platform, filePath)) {
+        detected.add(platform);
+      }
+    }
+  }
+
+  return PREWRITE_SKILLS_PLATFORMS.filter((platform) => detected.has(platform));
+};
+
+const collectStageScopedChangedPaths = (params: {
+  stage: AiGateStage;
+  repoRoot: string;
+  upstream: string | null;
+}): ReadonlyArray<string> => {
+  if (params.stage === 'PRE_WRITE') {
+    return collectWorktreeChangedPaths(params.repoRoot);
+  }
+  if (params.stage === 'PRE_COMMIT') {
+    return collectStagedChangedPaths(params.repoRoot);
+  }
+  if (params.stage === 'PRE_PUSH' && typeof params.upstream === 'string' && params.upstream.length > 0) {
+    return collectRangeChangedPaths({
+      repoRoot: params.repoRoot,
+      fromRef: params.upstream,
+      toRef: 'HEAD',
+    });
+  }
+  return [];
+};
+
 const hasWorktreeCodePlatforms = (params: {
   repoRoot: string;
   requiredPlatforms: ReadonlyArray<PreWriteSkillsPlatform>;
@@ -457,6 +542,22 @@ const hasWorktreeCodePlatforms = (params: {
   );
 };
 
+const toStageScopedDetectedPlatforms = (params: {
+  stage: AiGateStage;
+  repoRoot: string;
+  upstream: string | null;
+  requiredPlatforms: ReadonlyArray<PreWriteSkillsPlatform>;
+}): ReadonlyArray<PreWriteSkillsPlatform> => {
+  return toDetectedPlatformsFromPaths({
+    changedPaths: collectStageScopedChangedPaths({
+      stage: params.stage,
+      repoRoot: params.repoRoot,
+      upstream: params.upstream,
+    }),
+    requiredPlatforms: params.requiredPlatforms,
+  });
+};
+
 const toLockRequiredPlatforms = (
   requiredLock: SkillsLockV1 | undefined
 ): ReadonlyArray<PreWriteSkillsPlatform> => {
@@ -748,8 +849,18 @@ const toSkillsContractAssessment = (params: {
   const coverage = params.evidenceResult.evidence.snapshot.rules_coverage;
   const explicitlyDetectedPlatforms = toDetectedSkillsPlatforms(params.evidenceResult.evidence.platforms);
   const inferredPlatforms = toCoverageInferredPlatforms(coverage);
+  const stageScopedDetectedPlatforms =
+    params.stage !== 'CI' && requiredPlatforms.length > 0
+      ? toStageScopedDetectedPlatforms({
+          stage: params.stage,
+          repoRoot: params.repoRoot,
+          upstream: params.repoState.git.upstream,
+          requiredPlatforms,
+        })
+      : [];
+  const worktreeDetectedPlatforms = stageScopedDetectedPlatforms;
   const repoTreeDetectedPlatforms =
-    params.stage !== 'PRE_WRITE' && requiredPlatforms.length > 0
+    params.stage === 'CI' && requiredPlatforms.length > 0
       ? toRepoTreeDetectedPlatforms({
           repoRoot: params.repoRoot,
           platforms: requiredPlatforms,
@@ -759,20 +870,24 @@ const toSkillsContractAssessment = (params: {
     explicitlyDetectedPlatforms.length > 0
       ? toEffectiveSkillsPlatforms({
           platforms: params.evidenceResult.evidence.platforms,
-          coverage,
-        })
+        coverage,
+      })
       : [];
   const detectedPlatforms =
-    explicitlyDetectedEffectivePlatforms.length > 0
+    stageScopedDetectedPlatforms.length > 0
+      ? stageScopedDetectedPlatforms
+      : explicitlyDetectedEffectivePlatforms.length > 0
       ? explicitlyDetectedEffectivePlatforms
       : inferredPlatforms.length > 0
         ? inferredPlatforms
+        : worktreeDetectedPlatforms.length > 0
+          ? worktreeDetectedPlatforms
         : repoTreeDetectedPlatforms;
   const pendingChanges = resolvePendingChanges(params.repoState);
   const detectedPlatformSet = new Set(detectedPlatforms);
   const assessmentPlatforms =
     requiredPlatforms.length > 0
-      ? params.stage === 'PRE_WRITE' && detectedPlatforms.length > 0
+      ? params.stage !== 'CI' && detectedPlatforms.length > 0
         ? requiredPlatforms.filter((platform) => detectedPlatformSet.has(platform))
         : requiredPlatforms
       : detectedPlatforms;
@@ -1164,6 +1279,63 @@ const collectEvidenceViolations = (
   return { violations, ageSeconds };
 };
 
+const severityOrder: ReadonlyArray<'CRITICAL' | 'ERROR' | 'WARN' | 'INFO'> = [
+  'CRITICAL',
+  'ERROR',
+  'WARN',
+  'INFO',
+];
+
+const toHighestTriggeredSeverity = (
+  severityCounts: Readonly<Record<'INFO' | 'WARN' | 'ERROR' | 'CRITICAL', number>>,
+  threshold: 'INFO' | 'WARN' | 'ERROR' | 'CRITICAL'
+): 'INFO' | 'WARN' | 'ERROR' | 'CRITICAL' | null => {
+  for (const severity of severityOrder) {
+    if (severityCounts[severity] > 0 && isSeverityAtLeast(severity, threshold)) {
+      return severity;
+    }
+  }
+  return null;
+};
+
+const collectEvidencePolicyThresholdViolations = (params: {
+  evidenceResult: EvidenceReadResult;
+  policy: ReturnType<typeof resolvePolicyForStage>['policy'];
+}): AiGateViolation[] => {
+  if (params.evidenceResult.kind !== 'valid') {
+    return [];
+  }
+
+  const severityCounts = params.evidenceResult.evidence.severity_metrics.by_severity;
+  const blockSeverity = toHighestTriggeredSeverity(
+    severityCounts,
+    params.policy.blockOnOrAbove
+  );
+  if (blockSeverity && params.evidenceResult.evidence.ai_gate.status !== 'BLOCKED') {
+    return [
+      toErrorViolation(
+        'EVIDENCE_POLICY_THRESHOLD_BLOCK',
+        `Evidence severities exceed block_on_or_above=${params.policy.blockOnOrAbove} (highest=${blockSeverity}).`
+      ),
+    ];
+  }
+
+  const warnSeverity = toHighestTriggeredSeverity(
+    severityCounts,
+    params.policy.warnOnOrAbove
+  );
+  if (warnSeverity && params.evidenceResult.evidence.ai_gate.status === 'ALLOWED') {
+    return [
+      toWarnViolation(
+        'EVIDENCE_POLICY_THRESHOLD_WARN',
+        `Evidence severities exceed warn_on_or_above=${params.policy.warnOnOrAbove} (highest=${warnSeverity}).`
+      ),
+    ];
+  }
+
+  return [];
+};
+
 const toEvidenceSourceDescriptor = (
   result: EvidenceReadResult,
   repoRoot: string
@@ -1193,17 +1365,81 @@ const collectGitflowViolations = (
   if (!repoState.git.available) {
     return violations;
   }
-  if (repoState.git.branch && protectedBranches.has(repoState.git.branch)) {
+  const branch = repoState.git.branch?.trim() ?? null;
+  const normalizedBranch = branch?.toLowerCase() ?? null;
+  if (branch && normalizedBranch && protectedBranches.has(normalizedBranch)) {
     violations.push(
       toErrorViolation(
         'GITFLOW_PROTECTED_BRANCH',
-        `Direct work on protected branch "${repoState.git.branch}" is not allowed.`
+        `Direct work on protected branch "${branch}" is not allowed.`
+      )
+    );
+    return violations;
+  }
+  if (
+    branch
+    && !DEFAULT_GITFLOW_BRANCH_PATTERNS.some((pattern) => pattern.test(branch))
+  ) {
+    violations.push(
+      toErrorViolation(
+        'GITFLOW_BRANCH_NAMING_INVALID',
+        `Branch "${branch}" does not comply with GitFlow naming. Use feature/*, bugfix/*, hotfix/*, release/*, chore/*, refactor/* or docs/*.`
       )
     );
   }
   return violations;
 };
 
+const DEFAULT_TRACKING_STATE: RepoTrackingState = {
+  enforced: false,
+  canonical_path: null,
+  canonical_present: false,
+  source_file: null,
+  in_progress_count: null,
+  single_in_progress_valid: null,
+  conflict: false,
+  declarations: [],
+};
+
+const collectTrackingViolations = (repoState: RepoState): AiGateViolation[] => {
+  const tracking = repoState.lifecycle.tracking ?? DEFAULT_TRACKING_STATE;
+  if (!tracking.enforced) {
+    return [];
+  }
+
+  if (tracking.conflict) {
+    const declaredPaths = tracking.declarations
+      .map((entry) => `${entry.source_file}:${entry.resolved_path}`)
+      .join(', ');
+    return [
+      toErrorViolation(
+        'TRACKING_CANONICAL_SOURCE_CONFLICT',
+        `Tracking canonical source conflict detected (${declaredPaths}).`
+      ),
+    ];
+  }
+
+  if (!tracking.canonical_path || !tracking.canonical_present) {
+    return [
+      toErrorViolation(
+        'TRACKING_CANONICAL_FILE_MISSING',
+        `Tracking canonical file is missing (${tracking.canonical_path ?? 'undeclared'}).`
+      ),
+    ];
+  }
+
+  if (tracking.single_in_progress_valid === false) {
+    return [
+      toErrorViolation(
+        'TRACKING_CANONICAL_IN_PROGRESS_INVALID',
+        `Tracking canonical file must contain exactly one in-progress task (count=${tracking.in_progress_count ?? 'n/a'}).`
+      ),
+    ];
+  }
+
+  return [];
+};
+
 const resolvePendingChanges = (repoState: RepoState): number | null => {
   if (!repoState.git.available) {
     return null;
@@ -1422,6 +1658,7 @@ export const evaluateAiGate = (
     readMcpAiGateReceipt: activeDependencies.readMcpAiGateReceipt,
   });
   const gitflowViolations = collectGitflowViolations(repoState, protectedBranches);
+  const trackingViolations = collectTrackingViolations(repoState);
   const skillsContract = toSkillsContractAssessment({
     stage: params.stage,
     repoRoot: params.repoRoot,
@@ -1445,10 +1682,16 @@ export const evaluateAiGate = (
             `Skills contract incomplete for ${params.stage}: ${skillsContract.violations.map((violation) => violation.code).join(', ')}.`
           ),
         ];
+  const policyThresholdViolations = collectEvidencePolicyThresholdViolations({
+    evidenceResult,
+    policy: resolvedPolicy.policy,
+  });
   const violations = [
     ...evidenceAssessment.violations,
+    ...policyThresholdViolations,
     ...stageSkillsContractViolations,
     ...gitflowViolations,
+    ...trackingViolations,
     ...mcpReceiptAssessment.violations,
   ];
   const blocked = violations.some((violation) => violation.severity === 'ERROR');

package/integrations/gate/governanceActionCatalog.ts

@@ -0,0 +1,275 @@
+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);
+  }
+};

package/integrations/gate/remediationCatalog.ts

@@ -17,6 +17,14 @@ export const REMEDIATION_HINT_BY_CODE: Readonly<Record<string, string>> = {
   EVIDENCE_ACTIVE_RULE_IDS_EMPTY_FOR_CODE_CHANGES:
     'Reconcilia policy/skills y revalida PRE_WRITE: npx --yes --package pumuki@latest pumuki policy reconcile --strict --json && npx --yes --package pumuki@latest pumuki sdd validate --stage=PRE_WRITE --json',
   GITFLOW_PROTECTED_BRANCH: 'Trabaja en feature/* y evita ramas protegidas.',
+  GITFLOW_BRANCH_NAMING_INVALID:
+    'Renombra o recrea la rama con un prefijo GitFlow válido (feature/*, bugfix/*, hotfix/*, release/*, chore/*, refactor/* o docs/*).',
+  TRACKING_CANONICAL_SOURCE_CONFLICT:
+    'Alinea AGENTS.md y los README canónicos para que todos apunten al mismo MD de seguimiento.',
+  TRACKING_CANONICAL_FILE_MISSING:
+    'Crea o restaura el archivo canónico de tracking declarado por el repo.',
+  TRACKING_CANONICAL_IN_PROGRESS_INVALID:
+    'Deja exactamente una tarea o fase `🚧` en el MD canónico de seguimiento antes de continuar.',
   EVIDENCE_PREWRITE_WORKTREE_OVER_LIMIT:
     'Reduce archivos staged/unstaged por debajo del umbral (o ajusta PUMUKI_PREWRITE_WORKTREE_*); divide el trabajo en commits más pequeños.',
   EVIDENCE_PREWRITE_WORKTREE_WARN:

package/integrations/git/runPlatformGate.ts

@@ -1423,7 +1423,15 @@ export async function runPlatformGate(params: {
 
   if (gateOutcome === 'BLOCK') {
     if (params.silent !== true) {
-    dependencies.printGateFindings(findingsWithWaiver);
+      const renderStage =
+        params.policy.stage === 'PRE_PUSH'
+          ? 'PRE_PUSH'
+          : params.policy.stage === 'CI'
+            ? 'CI'
+            : 'PRE_COMMIT';
+      dependencies.printGateFindings(findingsWithWaiver, {
+        stage: renderStage,
+      });
     }
     return 1;
   }