pumuki 6.3.39 → 6.3.40

package/integrations/lifecycle/watch.ts

@@ -0,0 +1,365 @@
+import { createHash } from 'node:crypto';
+import { setTimeout as sleepTimer } from 'node:timers/promises';
+import { isSeverityAtLeast, type Severity } from '../../core/rules/Severity';
+import type { GateScope } from '../git/runPlatformGateFacts';
+import { runPlatformGate } from '../git/runPlatformGate';
+import { resolvePolicyForStage, type ResolvedStagePolicy } from '../gate/stagePolicies';
+import { readEvidence } from '../evidence/readEvidence';
+import type { AiEvidenceV2_1, SnapshotFinding } from '../evidence/schema';
+import { GitService } from '../git/GitService';
+import {
+  emitAuditSummaryNotificationFromEvidence,
+  emitGateBlockedNotification,
+} from '../notifications/emitAuditSummaryNotification';
+
+export type LifecycleWatchStage = 'PRE_COMMIT' | 'PRE_PUSH' | 'CI';
+export type LifecycleWatchScope = 'workingTree' | 'staged' | 'repoAndStaged' | 'repo';
+export type LifecycleWatchSeverityThreshold = 'critical' | 'high' | 'medium' | 'low';
+
+export type LifecycleWatchTickResult = {
+  tick: number;
+  changed: boolean;
+  evaluated: boolean;
+  stage: LifecycleWatchStage;
+  scope: LifecycleWatchScope;
+  gateExitCode: number | null;
+  gateOutcome: 'BLOCK' | 'WARN' | 'ALLOW' | 'NO_EVIDENCE';
+  threshold: LifecycleWatchSeverityThreshold;
+  thresholdSeverity: Severity;
+  totalFindings: number;
+  findingsAtOrAboveThreshold: number;
+  topCodes: ReadonlyArray<string>;
+  notification:
+    | 'sent'
+    | 'disabled'
+    | 'below-threshold'
+    | 'suppressed-cooldown'
+    | 'suppressed-duplicate'
+    | 'not-delivered'
+    | 'not-evaluated';
+  notificationDeliveryReason?: string;
+};
+
+export type LifecycleWatchResult = {
+  command: 'pumuki watch';
+  repoRoot: string;
+  stage: LifecycleWatchStage;
+  scope: LifecycleWatchScope;
+  intervalMs: number;
+  notifyCooldownMs: number;
+  severityThreshold: LifecycleWatchSeverityThreshold;
+  notifyEnabled: boolean;
+  ticks: number;
+  evaluations: number;
+  notificationsSent: number;
+  notificationsSuppressed: number;
+  lastTick: LifecycleWatchTickResult;
+};
+
+type LifecycleWatchDependencies = {
+  resolveRepoRoot: () => string;
+  readChangeToken: (repoRoot: string) => string;
+  resolvePolicyForStage: (stage: LifecycleWatchStage) => ResolvedStagePolicy;
+  runPlatformGate: typeof runPlatformGate;
+  readEvidence: (repoRoot: string) => AiEvidenceV2_1 | undefined;
+  emitAuditSummaryNotificationFromEvidence: typeof emitAuditSummaryNotificationFromEvidence;
+  emitGateBlockedNotification: typeof emitGateBlockedNotification;
+  nowMs: () => number;
+  sleep: (ms: number) => Promise<void>;
+};
+
+const defaultGitService = new GitService();
+
+const defaultDependencies: LifecycleWatchDependencies = {
+  resolveRepoRoot: () => defaultGitService.resolveRepoRoot(),
+  readChangeToken: (repoRoot) =>
+    defaultGitService.runGit(['status', '--porcelain=v1', '--untracked-files=all'], repoRoot),
+  resolvePolicyForStage: (stage) => resolvePolicyForStage(stage),
+  runPlatformGate,
+  readEvidence,
+  emitAuditSummaryNotificationFromEvidence,
+  emitGateBlockedNotification,
+  nowMs: () => Date.now(),
+  sleep: async (ms) => {
+    await sleepTimer(ms);
+  },
+};
+
+const BLOCKED_REMEDIATION_BY_CODE: Readonly<Record<string, string>> = {
+  EVIDENCE_MISSING: 'Genera evidencia y vuelve a ejecutar el gate.',
+  EVIDENCE_INVALID: 'Regenera la evidencia antes de reintentar.',
+  EVIDENCE_CHAIN_INVALID: 'Regenera evidencia para reparar la cadena criptográfica.',
+  EVIDENCE_STALE: 'Refresca la evidencia y vuelve a intentarlo.',
+  EVIDENCE_BRANCH_MISMATCH: 'Regenera evidencia en esta rama y reintenta.',
+  EVIDENCE_REPO_ROOT_MISMATCH: 'Regenera evidencia desde este repositorio.',
+  PRE_PUSH_UPSTREAM_MISSING: 'Ejecuta: git push --set-upstream origin <branch>.',
+  SDD_SESSION_MISSING: 'Abre sesión SDD y vuelve a intentar.',
+  SDD_SESSION_INVALID: 'Refresca la sesión SDD y vuelve a intentar.',
+  OPENSPEC_MISSING: 'Instala OpenSpec y reintenta la validación.',
+  MCP_ENTERPRISE_RECEIPT_MISSING: 'Genera el receipt enterprise de MCP antes de continuar.',
+};
+
+const THRESHOLD_TO_SEVERITY: Record<LifecycleWatchSeverityThreshold, Severity> = {
+  critical: 'CRITICAL',
+  high: 'ERROR',
+  medium: 'WARN',
+  low: 'INFO',
+};
+
+const toGateScope = (scope: LifecycleWatchScope): GateScope => {
+  if (scope === 'staged') {
+    return { kind: 'staged' };
+  }
+  if (scope === 'repoAndStaged') {
+    return { kind: 'repoAndStaged' };
+  }
+  if (scope === 'repo') {
+    return { kind: 'repo' };
+  }
+  return { kind: 'workingTree' };
+};
+
+const toNotificationSignature = (params: {
+  stage: LifecycleWatchStage;
+  gateOutcome: LifecycleWatchTickResult['gateOutcome'];
+  topCodes: ReadonlyArray<string>;
+  matchedFindings: number;
+}): string =>
+  createHash('sha1')
+    .update(
+      `${params.stage}|${params.gateOutcome}|${params.topCodes.join(',')}|${params.matchedFindings}`,
+      'utf8'
+    )
+    .digest('hex');
+
+const toTopCodes = (findings: ReadonlyArray<SnapshotFinding>): ReadonlyArray<string> => {
+  const seen = new Set<string>();
+  const codes: string[] = [];
+  for (const finding of findings) {
+    if (seen.has(finding.code)) {
+      continue;
+    }
+    seen.add(finding.code);
+    codes.push(finding.code);
+    if (codes.length >= 3) {
+      break;
+    }
+  }
+  return codes;
+};
+
+const toFirstCause = (params: {
+  evidence: AiEvidenceV2_1 | undefined;
+  matchedFindings: ReadonlyArray<SnapshotFinding>;
+}): { code: string; message: string; remediation: string } => {
+  const firstFinding = params.matchedFindings[0];
+  const firstViolation = params.evidence?.ai_gate.violations[0];
+  const code = firstFinding?.code ?? firstViolation?.code ?? 'WATCH_GATE_BLOCKED';
+  const message =
+    firstFinding?.message ??
+    firstViolation?.message ??
+    `Watch gate bloqueado (${code}).`;
+  const remediation =
+    BLOCKED_REMEDIATION_BY_CODE[code] ??
+    'Corrige el bloqueo indicado y vuelve a evaluar.';
+  return {
+    code,
+    message,
+    remediation,
+  };
+};
+
+export const runLifecycleWatch = async (
+  params?: {
+    repoRoot?: string;
+    stage?: LifecycleWatchStage;
+    scope?: LifecycleWatchScope;
+    intervalMs?: number;
+    notifyCooldownMs?: number;
+    severityThreshold?: LifecycleWatchSeverityThreshold;
+    notifyEnabled?: boolean;
+    maxIterations?: number;
+    onTick?: (tick: LifecycleWatchTickResult) => void;
+  },
+  dependencies: Partial<LifecycleWatchDependencies> = {}
+): Promise<LifecycleWatchResult> => {
+  const activeDependencies: LifecycleWatchDependencies = {
+    ...defaultDependencies,
+    ...dependencies,
+  };
+  const repoRoot = params?.repoRoot ?? activeDependencies.resolveRepoRoot();
+  const stage = params?.stage ?? 'PRE_COMMIT';
+  const scope = params?.scope ?? 'workingTree';
+  const intervalMs = Math.max(250, Math.trunc(params?.intervalMs ?? 3000));
+  const notifyCooldownMs = Math.max(0, Math.trunc(params?.notifyCooldownMs ?? 30_000));
+  const severityThreshold = params?.severityThreshold ?? 'high';
+  const thresholdSeverity = THRESHOLD_TO_SEVERITY[severityThreshold];
+  const notifyEnabled = params?.notifyEnabled !== false;
+  const maxIterations =
+    typeof params?.maxIterations === 'number' && params.maxIterations > 0
+      ? Math.trunc(params.maxIterations)
+      : undefined;
+
+  let ticks = 0;
+  let evaluations = 0;
+  let notificationsSent = 0;
+  let notificationsSuppressed = 0;
+  let previousChangeToken: string | undefined;
+  let lastNotificationSignature: string | undefined;
+  let lastNotificationAtMs = 0;
+  let lastTick: LifecycleWatchTickResult = {
+    tick: 0,
+    changed: false,
+    evaluated: false,
+    stage,
+    scope,
+    gateExitCode: null,
+    gateOutcome: 'NO_EVIDENCE',
+    threshold: severityThreshold,
+    thresholdSeverity,
+    totalFindings: 0,
+    findingsAtOrAboveThreshold: 0,
+    topCodes: [],
+    notification: 'not-evaluated',
+  };
+
+  while (true) {
+    ticks += 1;
+    const changeToken = activeDependencies.readChangeToken(repoRoot);
+    const changed = previousChangeToken !== changeToken;
+    const shouldEvaluate = ticks === 1 || changed;
+
+    if (!shouldEvaluate) {
+      lastTick = {
+        ...lastTick,
+        tick: ticks,
+        changed,
+        evaluated: false,
+        notification: 'not-evaluated',
+      };
+      params?.onTick?.(lastTick);
+    } else {
+      evaluations += 1;
+      const resolvedPolicy = activeDependencies.resolvePolicyForStage(stage);
+      const gateExitCode = await activeDependencies.runPlatformGate({
+        policy: resolvedPolicy.policy,
+        policyTrace: resolvedPolicy.trace,
+        scope: toGateScope(scope),
+      });
+      const evidence = activeDependencies.readEvidence(repoRoot);
+      const allFindings = evidence?.snapshot.findings ?? [];
+      const matchedFindings = allFindings.filter((finding) =>
+        isSeverityAtLeast(finding.severity, thresholdSeverity)
+      );
+      const rawGateOutcome =
+        evidence?.snapshot.outcome ??
+        (gateExitCode !== 0 ? 'BLOCK' : 'NO_EVIDENCE');
+      const gateOutcome =
+        rawGateOutcome === 'PASS' ? 'ALLOW' : rawGateOutcome;
+      const topCodes = toTopCodes(matchedFindings);
+      const signature = toNotificationSignature({
+        stage,
+        gateOutcome,
+        topCodes,
+        matchedFindings: matchedFindings.length,
+      });
+
+      let notification: LifecycleWatchTickResult['notification'] = 'below-threshold';
+      let notificationDeliveryReason: string | undefined;
+
+      if (!notifyEnabled) {
+        notification = 'disabled';
+      } else if (matchedFindings.length === 0) {
+        notification = 'below-threshold';
+      } else {
+        const nowMs = activeDependencies.nowMs();
+        const elapsed = nowMs - lastNotificationAtMs;
+        if (
+          notifyCooldownMs > 0 &&
+          typeof lastNotificationSignature === 'string' &&
+          elapsed < notifyCooldownMs
+        ) {
+          notification =
+            signature === lastNotificationSignature
+              ? 'suppressed-duplicate'
+              : 'suppressed-cooldown';
+          notificationsSuppressed += 1;
+        } else {
+          let notificationResult;
+          if (gateExitCode !== 0 || evidence?.ai_gate.status === 'BLOCKED') {
+            const cause = toFirstCause({
+              evidence,
+              matchedFindings,
+            });
+            notificationResult = activeDependencies.emitGateBlockedNotification({
+              repoRoot,
+              stage,
+              totalViolations: matchedFindings.length,
+              causeCode: cause.code,
+              causeMessage: cause.message,
+              remediation: cause.remediation,
+            });
+          } else {
+            notificationResult = activeDependencies.emitAuditSummaryNotificationFromEvidence({
+              repoRoot,
+              stage,
+            });
+          }
+
+          if (notificationResult.delivered) {
+            notification = 'sent';
+            notificationsSent += 1;
+          } else {
+            notification = 'not-delivered';
+            notificationDeliveryReason = notificationResult.reason;
+            notificationsSuppressed += 1;
+          }
+          lastNotificationAtMs = nowMs;
+          lastNotificationSignature = signature;
+        }
+      }
+
+      lastTick = {
+        tick: ticks,
+        changed,
+        evaluated: true,
+        stage,
+        scope,
+        gateExitCode,
+        gateOutcome,
+        threshold: severityThreshold,
+        thresholdSeverity,
+        totalFindings: allFindings.length,
+        findingsAtOrAboveThreshold: matchedFindings.length,
+        topCodes,
+        notification,
+        ...(notificationDeliveryReason
+          ? { notificationDeliveryReason }
+          : {}),
+      };
+      params?.onTick?.(lastTick);
+    }
+
+    previousChangeToken = changeToken;
+
+    if (maxIterations && ticks >= maxIterations) {
+      return {
+        command: 'pumuki watch',
+        repoRoot,
+        stage,
+        scope,
+        intervalMs,
+        notifyCooldownMs,
+        severityThreshold,
+        notifyEnabled,
+        ticks,
+        evaluations,
+        notificationsSent,
+        notificationsSuppressed,
+        lastTick,
+      };
+    }
+
+    await activeDependencies.sleep(intervalMs);
+  }
+};

package/integrations/mcp/aiGateCheck.ts

@@ -13,7 +13,58 @@ export type EnterpriseAiGateCheckResult = {
     violations: ReturnType<typeof evaluateAiGate>['violations'];
     evidence: ReturnType<typeof evaluateAiGate>['evidence'];
     mcp_receipt: ReturnType<typeof evaluateAiGate>['mcp_receipt'];
+    skills_contract: ReturnType<typeof evaluateAiGate>['skills_contract'];
     repo_state: ReturnType<typeof evaluateAiGate>['repo_state'];
+    consistency_hint?: {
+      comparable_with_hook_runner: boolean;
+      reason_code: 'HOOK_RUNNER_CAN_REFRESH_EVIDENCE' | null;
+      message: string;
+    };
+  };
+};
+
+const HOOK_STAGE_SET = new Set<AiGateStage>(['PRE_COMMIT', 'PRE_PUSH', 'CI']);
+
+const isHookRefreshableEvidenceCode = (code: string): boolean =>
+  code.startsWith('EVIDENCE_');
+
+type AiGateCheckDependencies = {
+  evaluateAiGate: typeof evaluateAiGate;
+};
+
+const defaultDependencies: AiGateCheckDependencies = {
+  evaluateAiGate,
+};
+
+const buildConsistencyHint = (
+  evaluation: ReturnType<typeof evaluateAiGate>
+): EnterpriseAiGateCheckResult['result']['consistency_hint'] => {
+  if (!HOOK_STAGE_SET.has(evaluation.stage)) {
+    return {
+      comparable_with_hook_runner: true,
+      reason_code: null,
+      message: 'Stage is directly comparable with ai_gate_check semantics.',
+    };
+  }
+
+  const hasRefreshableEvidenceViolation = evaluation.violations.some((violation) =>
+    isHookRefreshableEvidenceCode(violation.code)
+  );
+
+  if (!evaluation.allowed && hasRefreshableEvidenceViolation) {
+    return {
+      comparable_with_hook_runner: false,
+      reason_code: 'HOOK_RUNNER_CAN_REFRESH_EVIDENCE',
+      message:
+        'ai_gate_check is blocking on evidence integrity/freshness. ' +
+        'Hook stage runners may regenerate evidence before final verdict.',
+    };
+  }
+
+  return {
+    comparable_with_hook_runner: true,
+    reason_code: null,
+    message: 'ai_gate_check verdict is directly comparable with hook stage runner output.',
   };
 };
 
@@ -21,8 +72,12 @@ export const runEnterpriseAiGateCheck = (params: {
   repoRoot: string;
   stage: AiGateStage;
   requireMcpReceipt?: boolean;
-}): EnterpriseAiGateCheckResult => {
-  const evaluation = evaluateAiGate({
+}, dependencies: Partial<AiGateCheckDependencies> = {}): EnterpriseAiGateCheckResult => {
+  const activeDependencies: AiGateCheckDependencies = {
+    ...defaultDependencies,
+    ...dependencies,
+  };
+  const evaluation = activeDependencies.evaluateAiGate({
     repoRoot: params.repoRoot,
     stage: params.stage,
     requireMcpReceipt: params.requireMcpReceipt ?? false,
@@ -41,7 +96,9 @@ export const runEnterpriseAiGateCheck = (params: {
       violations: evaluation.violations,
       evidence: evaluation.evidence,
       mcp_receipt: evaluation.mcp_receipt,
+      skills_contract: evaluation.skills_contract,
       repo_state: evaluation.repo_state,
+      consistency_hint: buildConsistencyHint(evaluation),
     },
   };
 };

package/integrations/mcp/autoExecuteAiStart.ts

@@ -9,7 +9,14 @@ type AutoExecuteNextAction = {
 };
 
 const isEvidenceCode = (code: string): boolean =>
-  code === 'EVIDENCE_MISSING' || code === 'EVIDENCE_INVALID' || code === 'EVIDENCE_STALE';
+  code === 'EVIDENCE_MISSING'
+  || code === 'EVIDENCE_INVALID'
+  || code === 'EVIDENCE_STALE'
+  || code === 'EVIDENCE_SKILLS_CONTRACT_INCOMPLETE'
+  || code === 'EVIDENCE_PREWRITE_WORKTREE_OVER_LIMIT'
+  || code === 'EVIDENCE_PREWRITE_WORKTREE_WARN'
+  || code === 'EVIDENCE_PLATFORM_SKILLS_SCOPE_INCOMPLETE'
+  || code === 'EVIDENCE_PLATFORM_SKILLS_BUNDLES_MISSING';
 
 const confidenceFromViolation = (violationCode: string | null): number => {
   if (!violationCode) {
@@ -40,6 +47,23 @@ const nextActionFromViolation = (violation: AiGateViolation | undefined): AutoEx
         message: 'Refresca evidencia y vuelve a evaluar PRE_WRITE.',
         command: '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_PREWRITE_WORKTREE_OVER_LIMIT':
+    case 'EVIDENCE_PREWRITE_WORKTREE_WARN':
+      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',
+      };
     case 'GITFLOW_PROTECTED_BRANCH':
       return {
         kind: 'run_command',

package/integrations/mcp/preFlightCheck.ts

@@ -3,6 +3,7 @@ import { evaluateAiGate, type AiGateStage, type AiGateViolation } from '../gate/
 const ACTIONABLE_HINTS_BY_CODE: Readonly<Record<string, string>> = {
   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_STALE: 'Refresca evidencia antes de continuar con commit/push.',
   EVIDENCE_TIMESTAMP_INVALID: 'Regenera evidencia para obtener un timestamp válido.',
   EVIDENCE_GATE_BLOCKED: 'Corrige primero las violaciones bloqueantes y vuelve a auditar.',
@@ -14,6 +15,16 @@ const ACTIONABLE_HINTS_BY_CODE: Readonly<Record<string, string>> = {
   EVIDENCE_RULES_COVERAGE_STAGE_MISMATCH: 'Reanuda auditoría en el stage correcto.',
   EVIDENCE_RULES_COVERAGE_INCOMPLETE:
     'Asegura unevaluated=0 y coverage_ratio=1 antes de continuar.',
+  EVIDENCE_PLATFORM_SKILLS_SCOPE_INCOMPLETE:
+    'Activa/evalúa reglas skills.<plataforma>. en la evidencia PRE_WRITE y vuelve a validar.',
+  EVIDENCE_PLATFORM_SKILLS_BUNDLES_MISSING:
+    'Carga los bundles de skills requeridos por plataforma detectada y regenera evidencia.',
+  EVIDENCE_SKILLS_CONTRACT_INCOMPLETE:
+    'Completa el contrato skills/policy para el stage solicitado y vuelve a validar.',
+  EVIDENCE_PREWRITE_WORKTREE_OVER_LIMIT:
+    'Reduce el worktree pendiente en slices atómicos y vuelve a ejecutar PRE_WRITE.',
+  EVIDENCE_PREWRITE_WORKTREE_WARN:
+    'Conviene particionar cambios ahora para evitar bloqueo tardío en commit/push.',
   EVIDENCE_UNSUPPORTED_AUTO_RULES:
     'Mapea todas las reglas AUTO a detectores AST antes de continuar.',
   EVIDENCE_TIMESTAMP_FUTURE: 'Corrige la hora del sistema y regenera evidencia.',
@@ -65,6 +76,7 @@ export type EnterprisePreFlightCheckResult = {
     violations: ReturnType<typeof evaluateAiGate>['violations'];
     evidence: ReturnType<typeof evaluateAiGate>['evidence'];
     mcp_receipt: ReturnType<typeof evaluateAiGate>['mcp_receipt'];
+    skills_contract: ReturnType<typeof evaluateAiGate>['skills_contract'];
     repo_state: ReturnType<typeof evaluateAiGate>['repo_state'];
     hints: ReadonlyArray<string>;
   };
@@ -101,6 +113,7 @@ export const runEnterprisePreFlightCheck = (params: {
       violations: evaluation.violations,
       evidence: evaluation.evidence,
       mcp_receipt: evaluation.mcp_receipt,
+      skills_contract: evaluation.skills_contract,
       repo_state: evaluation.repo_state,
       hints,
     },