pumuki 6.3.39 → 6.3.41

package/docs/validation/README.md

@@ -5,6 +5,7 @@ Este directorio contiene solo documentación oficial y estable de validación pa
 ## Documentación oficial vigente
 
 - `adapter-hook-runtime-validation.md`
+- `ast-intelligence-roadmap.md`
 - `c022-phase-acceptance-contract.md`
 - `detection-audit-baseline.md`
 - `enterprise-consumer-isolation-policy.md`
@@ -14,7 +15,7 @@ Este directorio contiene solo documentación oficial y estable de validación pa
 ## Estado operativo actual
 
 - Master de seguimiento: `docs/registro-maestro-de-seguimiento.md`.
-- Plan activo: `docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md`.
+- Plan activo: `docs/seguimiento-activo-pumuki-saas-supermercados.md`.
 - Suite contractual enterprise (MVP): `npm run -s validation:contract-suite:enterprise`.
   - Perfiles activos del reporte JSON:
     - `minimal`

package/docs/validation/ast-intelligence-roadmap.md

@@ -0,0 +1,96 @@
+# AST Intelligence por Nodos (RFC + PoC)
+
+Estado: implementado en modo incremental (issue `#616`).
+
+## Objetivo
+
+Evolucionar de validación heurística clásica a validación AST por nodos, multilenguaje y trazable desde reglas compiladas de skills.
+
+## Alcance implementado (PoC v1)
+
+- Modo dual de validación legacy + AST (`off/shadow/strict`).
+- Comparación determinista por regla `skills.*` contra nodos `ast_nodes=[...]` compilados en runtime (`skills-ir:*`).
+- Métricas de divergencia por ejecución:
+  - `mapped_rules`
+  - `divergences`
+  - `false_positives`
+  - `false_negatives`
+  - `latency_ms`
+  - `languages`
+- Integración directa en gate de `PRE_COMMIT`, `PRE_PUSH`, `CI`.
+
+PoC cubre lenguajes críticos ya usados en el runtime actual:
+
+- TypeScript
+- Swift
+- Kotlin
+
+## Arquitectura objetivo (30/60/90)
+
+### 0-30 días (P0)
+
+- Consolidar modo dual como baseline estable:
+  - `off`: desactivado.
+  - `shadow`: compara y reporta sin bloquear.
+  - `strict`: bloquea si hay divergencias.
+- Mantener compatibilidad total con rulepacks existentes.
+- Publicar métricas mínimas para auditoría de divergencias.
+
+### 31-60 días (P1)
+
+- Backends AST por lenguaje con extractor dedicado (TS/Swift/Kotlin en prioridad).
+- Trazabilidad 1:1 `skill rule -> ast node -> finding`.
+- Telemetría con series temporales de FP/FN por stage.
+
+### 61-90 días (P2)
+
+- Rollout gradual por porcentaje/repositorio.
+- Políticas por stage para strict automático cuando FP/FN estén bajo umbral.
+- Contratos de regresión multi-repo (fixtures enterprise).
+
+## Contrato de compatibilidad (legacy + nuevo)
+
+- El modo legacy sigue siendo la referencia de bloqueo por defecto.
+- El modo AST entra en:
+  - `shadow` para medir paridad.
+  - `strict` para enforcement cuando la paridad sea aceptable.
+- No se rompe compatibilidad con bundles/rules actuales; el modo dual usa la metadata runtime `skills-ir:*`.
+
+## Rollout y rollback
+
+### Rollout
+
+1. Activar en `shadow`:
+
+```bash
+PUMUKI_AST_INTELLIGENCE_DUAL_MODE=shadow
+```
+
+2. Observar divergencias por stage/repositorio.
+3. Promover a `strict` cuando divergencias y latencia estén dentro de umbral.
+
+### Rollback inmediato
+
+```bash
+PUMUKI_AST_INTELLIGENCE_DUAL_MODE=off
+```
+
+## Umbrales recomendados para pasar a strict
+
+- `false_positives` y `false_negatives` cerca de 0 de forma sostenida.
+- `latency_ms` aceptable para hooks locales.
+- Sin regresiones en `test:stage-gates`.
+
+## Evidencia técnica de esta entrega
+
+- Runtime:
+  - `integrations/git/astIntelligenceDualValidation.ts`
+  - `integrations/git/runPlatformGate.ts`
+  - `integrations/git/runPlatformGateEvaluation.ts`
+- Tests:
+  - `integrations/git/__tests__/astIntelligenceDualValidation.test.ts`
+  - `integrations/git/__tests__/runPlatformGateAstIntelligenceDualMode.test.ts`
+  - `integrations/git/__tests__/runPlatformGateEvaluation.test.ts`
+- Validación:
+  - `npm run -s typecheck`
+  - `npm run -s test:stage-gates`

package/integrations/config/skillsCustomRules.ts

@@ -28,6 +28,7 @@ type CustomSkillsRuleV1 = {
   confidence?: SkillsRuleConfidence;
   locked?: boolean;
   evaluationMode?: SkillsRuleEvaluationMode;
+  ast_node_ids?: string[];
 };
 
 export type CustomSkillsRulesFileV1 = {
@@ -113,6 +114,14 @@ const isCustomRule = (value: unknown): value is CustomSkillsRuleV1 => {
   ) {
     return false;
   }
+  if (
+    typeof value.ast_node_ids !== 'undefined' &&
+    (!Array.isArray(value.ast_node_ids) ||
+      value.ast_node_ids.length === 0 ||
+      !value.ast_node_ids.every(isNonEmptyString))
+  ) {
+    return false;
+  }
   if (typeof value.locked !== 'undefined' && typeof value.locked !== 'boolean') {
     return false;
   }
@@ -196,6 +205,10 @@ const toCustomRulesFile = (
       confidence: rule.confidence,
       locked: rule.locked ?? false,
       evaluationMode: rule.evaluationMode ?? 'AUTO',
+      ast_node_ids:
+        rule.astNodeIds && rule.astNodeIds.length > 0
+          ? [...new Set(rule.astNodeIds)].sort()
+          : undefined,
     }))
     .sort((left, right) => left.id.localeCompare(right.id));
 
@@ -239,6 +252,7 @@ export const loadCustomSkillsLock = (
 
   const rules: SkillsCompiledRule[] = payload.rules.map((rule) => ({
     ...rule,
+    astNodeIds: rule.ast_node_ids,
     sourceSkill: 'custom-guidelines',
     sourcePath: '.pumuki/custom-rules.json',
     evaluationMode: rule.evaluationMode ?? 'AUTO',

package/integrations/config/skillsDetectorRegistry.ts

@@ -1,4 +1,4 @@
-import type { SkillsCompiledRule } from './skillsLock';
+import { normalizeSkillsAstNodeIds, type SkillsCompiledRule } from './skillsLock';
 
 type SkillsDetectorKind = 'heuristic';
 
@@ -153,3 +153,13 @@ export const resolveMappedHeuristicRuleIds = (
 ): ReadonlyArray<string> => {
   return registryByRuleId[ruleId]?.mappedHeuristicRuleIds ?? [];
 };
+
+export const resolveMappedHeuristicRuleIdsForCompiledRule = (
+  rule: SkillsCompiledRule
+): ReadonlyArray<string> => {
+  const dynamicAstNodeIds = normalizeSkillsAstNodeIds(rule.astNodeIds);
+  if (dynamicAstNodeIds.length > 0) {
+    return dynamicAstNodeIds;
+  }
+  return resolveMappedHeuristicRuleIds(rule.id);
+};

package/integrations/config/skillsLock.ts

@@ -10,6 +10,7 @@ export type SkillsStage = Exclude<GateStage, 'STAGED'>;
 export type SkillsRuleConfidence = 'HIGH' | 'MEDIUM' | 'LOW';
 export type SkillsRuleEvaluationMode = 'AUTO' | 'DECLARATIVE';
 export type SkillsRuleOrigin = 'core' | 'custom';
+export type SkillsAstNodeId = string;
 
 export type SkillsCompiledRule = {
   id: string;
@@ -23,6 +24,7 @@ export type SkillsCompiledRule = {
   locked?: boolean;
   evaluationMode?: SkillsRuleEvaluationMode;
   origin?: SkillsRuleOrigin;
+  astNodeIds?: ReadonlyArray<SkillsAstNodeId>;
 };
 
 export type SkillsLockBundle = {
@@ -43,6 +45,7 @@ export type SkillsLockV1 = {
 const SKILLS_LOCK_FILE = 'skills.lock.json';
 const SEMVER_PATTERN = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
 const SHA256_PATTERN = /^[A-Fa-f0-9]{64}$/;
+const AST_NODE_ID_PATTERN = /^heuristics\.[A-Za-z0-9._-]+\.ast$/;
 
 const severityValues = new Set<Severity>(['INFO', 'WARN', 'ERROR', 'CRITICAL']);
 const stageValues = new Set<SkillsStage>(['PRE_COMMIT', 'PRE_PUSH', 'CI']);
@@ -90,6 +93,23 @@ const isRuleEvaluationMode = (value: unknown): value is SkillsRuleEvaluationMode
   return typeof value === 'string' && evaluationModeValues.has(value as SkillsRuleEvaluationMode);
 };
 
+const isAstNodeId = (value: unknown): value is SkillsAstNodeId => {
+  return typeof value === 'string' && AST_NODE_ID_PATTERN.test(value.trim());
+};
+
+export const normalizeSkillsAstNodeIds = (
+  astNodeIds?: ReadonlyArray<SkillsAstNodeId>
+): SkillsAstNodeId[] => {
+  if (!astNodeIds || astNodeIds.length === 0) {
+    return [];
+  }
+
+  const normalized = astNodeIds
+    .map((value) => value.trim().toLowerCase())
+    .filter((value) => AST_NODE_ID_PATTERN.test(value));
+  return [...new Set(normalized)].sort();
+};
+
 const isRuleOrigin = (value: unknown): value is SkillsRuleOrigin => {
   return typeof value === 'string' && originValues.has(value as SkillsRuleOrigin);
 };
@@ -146,6 +166,15 @@ const isSkillsCompiledRule = (value: unknown): value is SkillsCompiledRule => {
     return false;
   }
 
+  if (
+    typeof value.astNodeIds !== 'undefined' &&
+    (!Array.isArray(value.astNodeIds) ||
+      value.astNodeIds.length === 0 ||
+      value.astNodeIds.some((item) => !isAstNodeId(item)))
+  ) {
+    return false;
+  }
+
   if (typeof value.origin !== 'undefined' && !isRuleOrigin(value.origin)) {
     return false;
   }
@@ -221,6 +250,7 @@ const normalizedRuleForHash = (rule: SkillsCompiledRule): Record<string, string
     locked: rule.locked ?? false,
     evaluationMode: rule.evaluationMode ?? null,
     origin: rule.origin ?? null,
+    astNodeIds: normalizeSkillsAstNodeIds(rule.astNodeIds),
   };
 };
 

package/integrations/config/skillsMarkdownRules.ts

@@ -13,6 +13,7 @@ const MARKDOWN_LINK_PATTERN = /\[([^\]]+)\]\(([^)]+)\)/g;
 const INLINE_CODE_PATTERN = /`([^`]+)`/g;
 const MARKDOWN_BOLD_PATTERN = /[*_]{1,3}/g;
 const MULTISPACE_PATTERN = /\s+/g;
+const AST_NODE_ID_PATTERN = /\bheuristics\.[a-z0-9._-]+\.ast\b/gi;
 const RULE_KEYWORDS =
   /\b(always|siempre|prefer|use|usar|avoid|evitar|never|nunca|must|obligatorio|required|disallow|do not|no)\b/i;
 
@@ -132,6 +133,15 @@ const extractRuleCandidateLines = (markdown: string): string[] => {
   return candidates;
 };
 
+const extractAstNodeIdsFromLine = (line: string): string[] => {
+  const matches = line.match(AST_NODE_ID_PATTERN);
+  if (!matches) {
+    return [];
+  }
+  const normalized = matches.map((token) => token.trim().toLowerCase());
+  return [...new Set(normalized)].sort();
+};
+
 const resolvePlatformFromBundle = (
   bundleName: string
 ): SkillsCompiledRule['platform'] => {
@@ -301,6 +311,7 @@ export const extractCompiledRulesFromSkillMarkdown = (params: {
     if (description.length < 6) {
       continue;
     }
+    const astNodeIds = extractAstNodeIdsFromLine(rawLine);
 
     const knownRuleId = normalizeKnownRuleTarget(platform, normalizeForLookup(description));
     let nextId: string;
@@ -325,9 +336,8 @@ export const extractCompiledRulesFromSkillMarkdown = (params: {
     }
     usedIds.add(nextId);
 
-    const evaluationMode: SkillsRuleEvaluationMode = knownRuleId
-      ? 'AUTO'
-      : 'DECLARATIVE';
+    const evaluationMode: SkillsRuleEvaluationMode =
+      knownRuleId || astNodeIds.length > 0 ? 'AUTO' : 'DECLARATIVE';
 
     rules.push({
       id: nextId,
@@ -341,6 +351,7 @@ export const extractCompiledRulesFromSkillMarkdown = (params: {
       locked: true,
       evaluationMode,
       origin: params.origin ?? 'core',
+      ...(astNodeIds.length > 0 ? { astNodeIds } : {}),
     });
   }
 

package/integrations/config/skillsRuleSet.ts

@@ -13,7 +13,7 @@ import {
 import { loadSkillsPolicy, type SkillsBundlePolicy } from './skillsPolicy';
 import type { DetectedPlatforms } from '../platform/detectPlatforms';
 import { loadEffectiveSkillsLock } from './skillsEffectiveLock';
-import { resolveMappedHeuristicRuleIds } from './skillsDetectorRegistry';
+import { resolveMappedHeuristicRuleIdsForCompiledRule } from './skillsDetectorRegistry';
 
 export type SkillsRuleSetLoadResult = {
   rules: RuleSet;
@@ -240,6 +240,22 @@ const toCode = (ruleId: string): string => {
   return `SKILLS_${ruleId.replace(/[^A-Za-z0-9]+/g, '_').toUpperCase()}`;
 };
 
+const toSkillsRuntimeIrSource = (params: {
+  rule: SkillsCompiledRule;
+  mappedHeuristicRuleIds: ReadonlyArray<string>;
+}): string => {
+  const astNodeIds = [...params.mappedHeuristicRuleIds].sort();
+  const astNodeToken = astNodeIds.length > 0 ? astNodeIds.join(',') : 'none';
+  const evaluationMode = resolveRuleEvaluationMode(params.rule);
+  return (
+    `skills-ir:rule=${params.rule.id};` +
+    `source_skill=${params.rule.sourceSkill};` +
+    `source_path=${params.rule.sourcePath};` +
+    `evaluation_mode=${evaluationMode};` +
+    `ast_nodes=[${astNodeToken}]`
+  );
+};
+
 const stageApplies = (
   currentStage: Exclude<GateStage, 'STAGED'>,
   ruleStage?: Exclude<GateStage, 'STAGED'>
@@ -333,7 +349,7 @@ const toRuleDefinition = (params: {
   repoRoot: string;
   observedFilePaths?: ReadonlyArray<string>;
 }): RuleDefinition | undefined => {
-  const mappedHeuristicRuleIds = resolveMappedHeuristicRuleIds(params.rule.id);
+  const mappedHeuristicRuleIds = resolveMappedHeuristicRuleIdsForCompiledRule(params.rule);
 
   if (!stageApplies(params.stage, params.rule.stage)) {
     return undefined;
@@ -345,6 +361,10 @@ const toRuleDefinition = (params: {
     bundlePolicy: params.bundlePolicy,
     stage: params.stage,
   });
+  const runtimeIrSource = toSkillsRuntimeIrSource({
+    rule: params.rule,
+    mappedHeuristicRuleIds,
+  });
 
   if (evaluationMode === 'AUTO') {
     if (mappedHeuristicRuleIds.length === 0) {
@@ -377,6 +397,7 @@ const toRuleDefinition = (params: {
         kind: 'Finding',
         message: params.rule.description,
         code: toCode(params.rule.id),
+        source: runtimeIrSource,
       },
       scope: resolveScopeForPlatform(
         params.rule.platform,
@@ -403,6 +424,7 @@ const toRuleDefinition = (params: {
       kind: 'Finding',
       message: `[Declarative] ${params.rule.description}`,
       code: `${toCode(params.rule.id)}_DECLARATIVE`,
+      source: runtimeIrSource,
     },
     scope: resolveScopeForPlatform(
       params.rule.platform,
@@ -500,7 +522,7 @@ export const loadSkillsRuleSetForStage = (
         continue;
       }
 
-      const mappedRuleIds = resolveMappedHeuristicRuleIds(compiledRule.id);
+      const mappedRuleIds = resolveMappedHeuristicRuleIdsForCompiledRule(compiledRule);
       const evaluationMode = resolveRuleEvaluationMode(compiledRule);
       if (evaluationMode === 'AUTO' && mappedRuleIds.length === 0) {
         unsupportedAutoRuleIds.add(compiledRule.id);

package/integrations/evidence/readEvidence.test.ts

@@ -3,6 +3,7 @@ import { writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import test from 'node:test';
 import { withTempDir } from '../__tests__/helpers/tempDir';
+import { getCurrentPumukiVersion } from '../lifecycle/packageInfo';
 import type { AiEvidenceV2_1 } from './schema';
 import { readEvidence, readEvidenceResult } from './readEvidence';
 import { buildEvidenceChain } from './evidenceChain';
@@ -49,8 +50,8 @@ const sampleEvidence = (): AiEvidenceV2_1 => {
       },
       lifecycle: {
         installed: true,
-        package_version: '6.3.16',
-        lifecycle_version: '6.3.16',
+        package_version: getCurrentPumukiVersion(),
+        lifecycle_version: getCurrentPumukiVersion(),
         hooks: {
           pre_commit: 'managed',
           pre_push: 'managed',

package/integrations/evidence/readEvidence.ts

@@ -25,8 +25,15 @@ export type EvidenceReadResult =
 const toDigest = (value: string): string =>
   `sha256:${createHash('sha256').update(value, 'utf8').digest('hex')}`;
 
-export const readEvidenceResult = (repoRoot: string): EvidenceReadResult => {
-  const evidencePath = resolve(repoRoot, '.ai_evidence.json');
+export const readEvidenceResult = (
+  repoRoot: string,
+  options?: { evidencePath?: string }
+): EvidenceReadResult => {
+  const evidencePathInput = options?.evidencePath?.trim();
+  const evidencePath =
+    typeof evidencePathInput === 'string' && evidencePathInput.length > 0
+      ? resolve(repoRoot, evidencePathInput)
+      : resolve(repoRoot, '.ai_evidence.json');
   if (!existsSync(evidencePath)) {
     return {
       kind: 'missing',
@@ -126,7 +133,10 @@ export const readEvidenceResult = (repoRoot: string): EvidenceReadResult => {
   }
 };
 
-export const readEvidence = (repoRoot: string): AiEvidenceV2_1 | undefined => {
-  const result = readEvidenceResult(repoRoot);
+export const readEvidence = (
+  repoRoot: string,
+  options?: { evidencePath?: string }
+): AiEvidenceV2_1 | undefined => {
+  const result = readEvidenceResult(repoRoot, options);
   return result.kind === 'valid' ? result.evidence : undefined;
 };

package/integrations/evidence/repoState.ts

@@ -2,6 +2,7 @@ import { execFileSync as runBinarySync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { readLifecycleStatus } from '../lifecycle/status';
+import { resolvePumukiVersionMetadata } from '../lifecycle/packageInfo';
 import type { RepoHardModeState, RepoHookState, RepoState } from './schema';
 
 type HookStateShape = { exists: boolean; managedBlockPresent: boolean };
@@ -129,6 +130,9 @@ export const captureRepoState = (repoRoot: string): RepoState => {
   const unstaged = statusLines.filter((line) => line[1] && line[1] !== ' ').length;
   const { ahead, behind } = toAheadBehind(repoRoot, upstream);
   const lifecycle = readLifecycleStatusSafe(repoRoot);
+  const versionMetadata = resolvePumukiVersionMetadata({ repoRoot });
+  const consumerFacingVersion = versionMetadata.resolvedVersion;
+  const installedVersion = versionMetadata.consumerInstalledVersion;
   const hardModeState = readHardModeState(repoRoot);
 
   return {
@@ -145,8 +149,12 @@ export const captureRepoState = (repoRoot: string): RepoState => {
     },
     lifecycle: {
       installed: lifecycle.lifecycleState.installed === 'true',
-      package_version: lifecycle.packageVersion ?? null,
-      lifecycle_version: lifecycle.lifecycleState.version ?? null,
+      // package/lifecycle version should be stable from consumer perspective.
+      package_version: consumerFacingVersion,
+      lifecycle_version: consumerFacingVersion,
+      package_version_source: versionMetadata.source,
+      package_version_runtime: versionMetadata.runtimeVersion,
+      package_version_installed: installedVersion,
       hooks: {
         pre_commit: toHookState(lifecycle.hookStatus['pre-commit']),
         pre_push: toHookState(lifecycle.hookStatus['pre-push']),

package/integrations/evidence/schema.test.ts

@@ -1,5 +1,6 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
+import { getCurrentPumukiVersion } from '../lifecycle/packageInfo';
 import type { AiEvidenceV2_1, CompatibilityViolation, HumanIntentState, SnapshotFinding } from './schema';
 
 const sampleIntent = (): HumanIntentState => ({
@@ -122,8 +123,8 @@ test('AiEvidenceV2_1 soporta snapshot/ledger/platforms/rulesets con contrato 2.1
       },
       lifecycle: {
         installed: true,
-        package_version: '6.3.16',
-        lifecycle_version: '6.3.16',
+        package_version: getCurrentPumukiVersion(),
+        lifecycle_version: getCurrentPumukiVersion(),
         hooks: {
           pre_commit: 'managed',
           pre_push: 'managed',

package/integrations/evidence/schema.ts

@@ -169,6 +169,9 @@ export type RepoState = {
     installed: boolean;
     package_version: string | null;
     lifecycle_version: string | null;
+    package_version_source?: 'consumer-node-modules' | 'runtime-package';
+    package_version_runtime?: string | null;
+    package_version_installed?: string | null;
     hooks: {
       pre_commit: RepoHookState;
       pre_push: RepoHookState;

package/integrations/evidence/writeEvidence.test.ts

@@ -4,6 +4,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import test from 'node:test';
 import { withTempDir } from '../__tests__/helpers/tempDir';
+import { getCurrentPumukiVersion } from '../lifecycle/packageInfo';
 import type { AiEvidenceV2_1 } from './schema';
 import { writeEvidence } from './writeEvidence';
 
@@ -135,8 +136,8 @@ const sampleEvidence = (repoRoot: string): AiEvidenceV2_1 => ({
     },
     lifecycle: {
       installed: true,
-      package_version: '6.3.16',
-      lifecycle_version: '6.3.16',
+      package_version: getCurrentPumukiVersion(),
+      lifecycle_version: getCurrentPumukiVersion(),
       hooks: {
         pre_commit: 'managed',
         pre_push: 'managed',