pumuki 6.3.26 → 6.3.28

package/docs/validation/real-repo-manual-e2e-ruralgo-fork.md

@@ -0,0 +1,372 @@
+# Runbook Manual E2E en Repo Real (ruralgo-fork)
+
+Runbook manual para validar Pumuki end-to-end en un repositorio real (no mock), usando un fork/copia controlada de RuralGO dentro de `~/Developer/Projects`.
+
+## Objetivo
+
+Verificar instalación, gates, lifecycle, comandos loop, servidores MCP y desinstalación limpia en un clon real que ejecutas tú manualmente.
+
+## Rutas
+
+- Repo real de origen (RuralGO): `/Users/juancarlosmerlosalbarracin/Developer/Projects/R_GO`
+- Fork/copia de validación: `/Users/juancarlosmerlosalbarracin/Developer/Projects/ruralgo-fork`
+
+## Espejo mínimo de tracking en el fork (manual)
+
+Antes de empezar las pruebas reales, crea/actualiza este archivo en el fork:
+
+- `ruralgo-fork/docs/strategy/ruralgo-tracking-hub.md`
+
+Plantilla mínima recomendada:
+
+```md
+# RuralGO Tracking Hub (P9)
+
+- Fuente maestra: `ast-intelligence-hooks/docs/validation/p9-ruralgo-fork-validation-tracking.md`
+- Tarea activa: `P9.F0.T3`
+- Última sincronización: <YYYY-MM-DD HH:mm TZ>
+- Estado:
+  - F0: en curso
+  - F1..F6: pendientes
+```
+
+## 0) Preparar fork/copia real en Projects
+
+```bash
+rm -rf /Users/juancarlosmerlosalbarracin/Developer/Projects/ruralgo-fork
+git clone /Users/juancarlosmerlosalbarracin/Developer/Projects/R_GO /Users/juancarlosmerlosalbarracin/Developer/Projects/ruralgo-fork
+cd /Users/juancarlosmerlosalbarracin/Developer/Projects/ruralgo-fork
+git switch develop
+git pull --ff-only origin develop
+```
+
+## 0.1) P9.F0.T3.ST2 — Preparar rama real #1 (API contacto)
+
+```bash
+cd /Users/juancarlosmerlosalbarracin/Developer/Projects/ruralgo-fork
+git switch develop
+git pull --ff-only origin develop
+git switch -c feature/p9-api-contact-contract
+git status --short --branch
+git rev-parse --abbrev-ref HEAD
+```
+
+Esperado:
+- rama activa: `feature/p9-api-contact-contract`
+- base: `develop`
+- upstream todavía no configurado (se configura al abrir PR #1)
+
+Validación automática de precondiciones (desde este repo Pumuki):
+
+```bash
+cd /Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks
+npm run -s validation:p9:ruralgo-branch-ready -- \
+  --repo=/Users/juancarlosmerlosalbarracin/Developer/Projects/ruralgo-fork \
+  --expected-branch=feature/p9-api-contact-contract \
+  --base-ref=origin/develop \
+  --json
+```
+
+Esperado:
+- `"ready": true`
+- `"issues": []`
+
+## 0.2) P9.F0.T3.ST3 — Preparación pendiente rama real #2 (UX contacto)
+
+No crearla todavía para evitar mezclar trabajo de PRs. Se preparará al terminar PR #1:
+
+```bash
+cd /Users/juancarlosmerlosalbarracin/Developer/Projects/ruralgo-fork
+git switch develop
+git pull --ff-only origin develop
+git switch -c feature/p9-ux-contact-states
+```
+
+Esperado:
+- rama activa: `feature/p9-ux-contact-states`
+- base: `develop`
+- solo después de cerrar/encaminar PR #1
+
+Validación automática de precondiciones (cuando toque abrir PR #2):
+
+```bash
+cd /Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks
+npm run -s validation:p9:ruralgo-branch-ready:ux -- \
+  --repo=/Users/juancarlosmerlosalbarracin/Developer/Projects/ruralgo-fork \
+  --json
+```
+
+Esperado:
+- `"ready": true`
+- `"issues": []`
+
+## 0.3) P9.F1.T1 — Verificar runtime exigido por RuralGO
+
+```bash
+cd /Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks
+npm run -s validation:p9:ruralgo-runtime-ready -- \
+  --repo=/Users/juancarlosmerlosalbarracin/Developer/Projects/ruralgo-fork \
+  --json
+```
+
+Si tu shell no respeta `nvm use` (sigue mostrando `node v25`), ejecuta los comandos con:
+
+```bash
+PATH="$HOME/.nvm/versions/node/v20.20.0/bin:$PATH" <comando>
+```
+
+Esperado:
+- `"required.node": "20.20.0"`
+- `"required.npm": "10.8.2"`
+- `"ready": true`
+- `"issues": []`
+
+## 1) Línea base limpia (sin restos de Pumuki)
+
+```bash
+npx --yes --package pumuki@latest pumuki uninstall --purge-artifacts || true
+npm uninstall pumuki --save-exact || true
+rm -rf node_modules package-lock.json .ai_evidence.json artifacts
+git status --short --branch
+```
+
+Esperado:
+- sin hooks gestionados por Pumuki
+- sin `.ai_evidence.json`
+- sin `artifacts/`
+
+Validación automática de baseline limpio:
+
+```bash
+cd /Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks
+npm run -s validation:p9:ruralgo-baseline-clean -- \
+  --repo=/Users/juancarlosmerlosalbarracin/Developer/Projects/ruralgo-fork \
+  --json
+```
+
+Esperado:
+- `"ready": true`
+- `"issues": []`
+
+## 2) Instalar latest + checks de estado
+
+```bash
+npx --yes --package pumuki@latest pumuki install
+npx --yes --package pumuki@latest pumuki status --json
+npx --yes --package pumuki@latest pumuki doctor --json
+ls -la .git/hooks | rg 'pre-commit|pre-push' || true
+```
+
+Esperado:
+- instalación operativa sin depender de `npm install` local
+- hooks `pre-commit` y `pre-push` presentes
+- `status` y `doctor` devuelven JSON válido
+
+Validación automática de salud de instalación (status + hooks + doctor):
+
+```bash
+cd /Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks
+npm run -s validation:p9:ruralgo-install-health -- \
+  --repo=/Users/juancarlosmerlosalbarracin/Developer/Projects/ruralgo-fork \
+  --json
+```
+
+Esperado:
+- `"ready": true`
+- `"snapshot.lifecycleInstalled": true`
+- `"snapshot.preCommitManaged": true`
+- `"snapshot.prePushManaged": true`
+- `"snapshot.doctorVerdictPass": true`
+
+## 2.1) P9.F1.T4 — Verificar baseline versionado (openspec + ai_evidence)
+
+```bash
+cd /Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks
+npm run -s validation:p9:ruralgo-baseline-versioned -- \
+  --repo=/Users/juancarlosmerlosalbarracin/Developer/Projects/ruralgo-fork \
+  --json
+```
+
+Esperado:
+- `"ready": true`
+- `"snapshot.openspecProjectTracked": true`
+- `"snapshot.openspecArchiveGitkeepTracked": true`
+- `"snapshot.openspecSpecsGitkeepTracked": true`
+- `"snapshot.aiEvidenceTracked": true`
+
+## 2.2) P9.F2.T1 — RED del contrato API de contacto (sin implementar endpoint)
+
+Arranca backend en modo test con entorno dummy para aislar errores de infraestructura:
+
+```bash
+cd /Users/juancarlosmerlosalbarracin/Developer/Projects/ruralgo-fork
+PATH="$HOME/.nvm/versions/node/v20.20.0/bin:$PATH" \
+NODE_ENV=test \
+E2E_MODE=true \
+SUPABASE_URL=http://127.0.0.1 \
+SUPABASE_SERVICE_ROLE_KEY=dummy \
+WEBHOOK_URL=http://127.0.0.1 \
+TEST_ADMIN_EMAIL=admin@local.test \
+TEST_ADMIN_PASSWORD=Admin123! \
+TEST_SEEDED_EMAIL=seeded@local.test \
+TEST_SEEDED_PASSWORD=Seeded123! \
+TEST_REGULAR_EMAIL=user@local.test \
+TEST_REGULAR_PASSWORD=User1234! \
+E2E_ORDERS_TEST_EMAIL=e2e@local.test \
+E2E_ORDERS_TEST_PASSWORD=Orders123! \
+npm run -w apps/backend dev
+```
+
+En otra terminal, ejecutar probes RED:
+
+```bash
+curl -s -i -X POST http://127.0.0.1:3000/api/contact-form \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"Ana","email":"ana@example.com","message":"Hola"}'
+
+curl -s -i -X POST http://127.0.0.1:3000/api/contact-form \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"","email":"bad","message":""}'
+
+curl -s -i -X POST http://127.0.0.1:3000/api/contact-form \
+  -H 'Content-Type: application/json' \
+  -H 'X-Force-External-Fail: 1' \
+  -d '{"name":"Ana","email":"ana@example.com","message":"Hola"}'
+```
+
+Esperado en RED actual:
+- respuestas `404 Cannot POST /api/contact-form` en los 3 casos (contrato aún no implementado).
+
+Esperado tras completar GREEN (`P9.F2.T2`):
+- caso válido => `200` con body `{"status":"sent"}`
+- caso inválido => `400` con errores de validación
+- caso `X-Force-External-Fail: 1` => `502` con mensaje saneado
+
+Opcional (solo si el repo consumidor no bloquea por engines):
+
+```bash
+npm install --save-exact pumuki@latest
+```
+
+## 3) Comportamiento del gate: bloquea y luego pasa
+
+Crear una violación intencional:
+
+```bash
+cat > pumuki_e2e_violation.ts <<'TS'
+console.log('violacion intencional');
+TS
+git add pumuki_e2e_violation.ts
+npx --yes --package pumuki@latest pumuki-pre-commit; echo "pre-commit exit=$?"
+```
+
+Corregir y volver a comprobar:
+
+```bash
+cat > pumuki_e2e_violation.ts <<'TS'
+export const pumukiE2e = (): string => 'ok';
+TS
+git add pumuki_e2e_violation.ts
+npx --yes --package pumuki@latest pumuki-pre-commit; echo "pre-commit-fixed exit=$?"
+```
+
+Esperado:
+- la primera ejecución bloquea
+- la segunda ejecución pasa
+
+## 4) Pre-push y gate CI local
+
+```bash
+git branch -f upstream-e2e HEAD
+git branch --set-upstream-to=upstream-e2e feature/p9-api-contact-contract
+npx --yes --package pumuki@latest pumuki-pre-push; echo "pre-push exit=$?"
+GITHUB_BASE_REF=upstream-e2e npx --yes --package pumuki@latest pumuki-ci; echo "ci exit=$?"
+```
+
+Esperado:
+- pre-push y ci validan el scope actual (`staged/diff`) según política
+
+## 5) Smoke de comandos loop
+
+```bash
+SID=$(npx --yes --package pumuki@latest pumuki loop run --objective="manual-e2e" --max-attempts=1 --json | jq -r '.session.id // .session_id')
+echo "SID=$SID"
+npx --yes --package pumuki@latest pumuki loop status --session="$SID" --json
+npx --yes --package pumuki@latest pumuki loop list --json
+npx --yes --package pumuki@latest pumuki loop export --session="$SID" --json
+npx --yes --package pumuki@latest pumuki loop stop --session="$SID" --json
+npx --yes --package pumuki@latest pumuki loop resume --session="$SID" --json || true
+```
+
+Esperado:
+- el ciclo de vida de la sesión loop responde con JSON válido
+
+## 6) Smoke de servidores MCP (manual y visible)
+
+Terminal A:
+
+```bash
+cd /Users/juancarlosmerlosalbarracin/Developer/Projects/ruralgo-fork
+PUMUKI_EVIDENCE_PORT=7441 npx --yes --package pumuki@latest pumuki-mcp-evidence
+```
+
+Terminal B:
+
+```bash
+curl -s http://127.0.0.1:7441/health
+```
+
+Terminal C:
+
+```bash
+cd /Users/juancarlosmerlosalbarracin/Developer/Projects/ruralgo-fork
+PUMUKI_ENTERPRISE_MCP_PORT=7491 npx --yes --package pumuki@latest pumuki-mcp-enterprise
+```
+
+Terminal D:
+
+```bash
+curl -s http://127.0.0.1:7491/health
+```
+
+Esperado:
+- ambos endpoints de health devuelven `status=ok`
+
+## 7) Desinstalación limpia (estado final)
+
+```bash
+npx --yes --package pumuki@latest pumuki uninstall --purge-artifacts
+npm uninstall pumuki --save-exact || true
+rm -rf node_modules package-lock.json .ai_evidence.json artifacts
+ls -la .git/hooks | rg 'pre-commit|pre-push' || true
+git status --short --branch
+```
+
+Esperado:
+- sin hooks gestionados por Pumuki
+- sin artefactos de Pumuki
+- el repo queda controlado y limpio en `ruralgo-fork`
+
+## 8) Cierre espejo P9 (F6.T4.ST2)
+
+Aplica el cierre final en el espejo del consumidor para desbloquear `P9.F6.T4`:
+
+```bash
+cd /Users/juancarlosmerlosalbarracin/Developer/Projects/ruralgo-fork
+mkdir -p docs/strategy
+cat > docs/strategy/ruralgo-tracking-hub.md <<'MD'
+# RuralGO Tracking Hub (P9)
+
+- Fuente maestra: `/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/docs/validation/p9-ruralgo-fork-validation-tracking.md`
+- Estado maestro: `P9.F6.T4.ST1=✅`, `P9.F6.T4.ST2=✅`
+- Veredicto final P9: `GO`
+- Cierre: `P9.T2 => ✅`
+- Última sincronización: $(date '+%Y-%m-%d %H:%M:%S %Z')
+MD
+
+git status --short --branch docs/strategy/ruralgo-tracking-hub.md
+```
+
+Esperado:
+- `docs/strategy/ruralgo-tracking-hub.md` presente y actualizado.
+- cierre explícito del espejo con `P9.T2 => ✅` y veredicto `GO`.

package/integrations/config/skillsCompliance.ts

@@ -0,0 +1,212 @@
+import type { RuleDefinition } from '../../core/rules/RuleDefinition';
+import type { SkillsRuleSetLoadResult } from './skillsRuleSet';
+
+export type SkillsCompliancePlatform = Extract<
+  NonNullable<RuleDefinition['platform']>,
+  'ios' | 'android' | 'backend' | 'frontend'
+>;
+
+export type SkillsComplianceFileEntry = {
+  file_path: string;
+  platform: SkillsCompliancePlatform;
+  required_rule_ids: string[];
+  applied_rule_ids: string[];
+  evidence_rule_ids: string[];
+  missing_rule_ids: string[];
+  status: 'OK' | 'INCOMPLETE';
+};
+
+export type SkillsComplianceSnapshot = {
+  required_rule_ids: string[];
+  applied_rule_ids: string[];
+  evidence_rule_ids: string[];
+  missing_rule_ids: string[];
+  counts: {
+    files_in_scope: number;
+    files_with_missing: number;
+    required: number;
+    applied: number;
+    evidence: number;
+    missing: number;
+  };
+  by_file: SkillsComplianceFileEntry[];
+};
+
+const isTypeScriptOrJavaScript = (path: string): boolean => {
+  const normalized = path.toLowerCase();
+  return (
+    normalized.endsWith('.ts') ||
+    normalized.endsWith('.js') ||
+    normalized.endsWith('.mts') ||
+    normalized.endsWith('.cts') ||
+    normalized.endsWith('.mjs') ||
+    normalized.endsWith('.cjs')
+  );
+};
+
+const isReactPath = (path: string): boolean => {
+  const normalized = path.toLowerCase();
+  return normalized.endsWith('.tsx') || normalized.endsWith('.jsx');
+};
+
+const normalizePath = (path: string): string => {
+  return path.replace(/\\/g, '/').replace(/^\.\//, '').trim();
+};
+
+const inferPlatformFromPath = (
+  path: string
+): SkillsCompliancePlatform | undefined => {
+  const normalized = normalizePath(path).toLowerCase();
+
+  if (normalized.endsWith('.swift')) {
+    return 'ios';
+  }
+
+  if (normalized.endsWith('.kt') || normalized.endsWith('.kts')) {
+    return 'android';
+  }
+
+  if (isReactPath(normalized)) {
+    return 'frontend';
+  }
+
+  if (!isTypeScriptOrJavaScript(normalized)) {
+    return undefined;
+  }
+
+  if (
+    normalized.startsWith('apps/frontend/') ||
+    normalized.startsWith('apps/web/') ||
+    /(^|\/)(frontend|web|client)(\/|$)/.test(normalized)
+  ) {
+    return 'frontend';
+  }
+
+  if (
+    normalized.startsWith('apps/backend/') ||
+    /(^|\/)(backend|server|api)(\/|$)/.test(normalized)
+  ) {
+    return 'backend';
+  }
+
+  return undefined;
+};
+
+const toUniqueSorted = (values: ReadonlyArray<string>): string[] => {
+  return Array.from(
+    new Set(values.map((value) => value.trim()).filter((value) => value.length > 0))
+  ).sort((left, right) => left.localeCompare(right));
+};
+
+const intersectRuleIds = (
+  ruleIds: ReadonlyArray<string>,
+  selectedRuleIds: ReadonlySet<string>
+): string[] => {
+  return toUniqueSorted(ruleIds.filter((ruleId) => selectedRuleIds.has(ruleId)));
+};
+
+const subtractRuleIds = (
+  allRuleIds: ReadonlyArray<string>,
+  excludedRuleIds: ReadonlySet<string>
+): string[] => {
+  return toUniqueSorted(allRuleIds.filter((ruleId) => !excludedRuleIds.has(ruleId)));
+};
+
+const platformOrder: ReadonlyArray<SkillsCompliancePlatform> = [
+  'ios',
+  'android',
+  'backend',
+  'frontend',
+];
+
+const isSupportedPlatform = (
+  platform: RuleDefinition['platform']
+): platform is SkillsCompliancePlatform => {
+  return platform !== undefined && platformOrder.includes(platform as SkillsCompliancePlatform);
+};
+
+export const evaluateSkillsCompliance = (params: {
+  skillsRuleSet: SkillsRuleSetLoadResult;
+  observedFilePaths: ReadonlyArray<string>;
+  activeRuleIds: ReadonlyArray<string>;
+  evaluatedRuleIds: ReadonlyArray<string>;
+  matchedRuleIds: ReadonlyArray<string>;
+}): SkillsComplianceSnapshot | undefined => {
+  const activeRuleIdsSet = new Set(params.activeRuleIds);
+  const evaluatedRuleIdsSet = new Set(params.evaluatedRuleIds);
+  const matchedRuleIdsSet = new Set(params.matchedRuleIds);
+
+  const requiredByPlatform = new Map<SkillsCompliancePlatform, string[]>();
+  for (const rule of params.skillsRuleSet.rules) {
+    if (!isSupportedPlatform(rule.platform)) {
+      continue;
+    }
+    if (!activeRuleIdsSet.has(rule.id)) {
+      continue;
+    }
+    const current = requiredByPlatform.get(rule.platform) ?? [];
+    current.push(rule.id);
+    requiredByPlatform.set(rule.platform, current);
+  }
+
+  if (requiredByPlatform.size === 0) {
+    return undefined;
+  }
+
+  const normalizedObservedFilePaths = toUniqueSorted(
+    params.observedFilePaths.map((path) => normalizePath(path))
+  );
+  const byFile: SkillsComplianceFileEntry[] = [];
+
+  for (const filePath of normalizedObservedFilePaths) {
+    const platform = inferPlatformFromPath(filePath);
+    if (!platform) {
+      continue;
+    }
+
+    const requiredRuleIds = toUniqueSorted(requiredByPlatform.get(platform) ?? []);
+    if (requiredRuleIds.length === 0) {
+      continue;
+    }
+
+    const appliedRuleIds = intersectRuleIds(requiredRuleIds, evaluatedRuleIdsSet);
+    const evidenceRuleIds = intersectRuleIds(requiredRuleIds, matchedRuleIdsSet);
+    const appliedRuleIdsSet = new Set(appliedRuleIds);
+    const missingRuleIds = subtractRuleIds(requiredRuleIds, appliedRuleIdsSet);
+
+    byFile.push({
+      file_path: filePath,
+      platform,
+      required_rule_ids: requiredRuleIds,
+      applied_rule_ids: appliedRuleIds,
+      evidence_rule_ids: evidenceRuleIds,
+      missing_rule_ids: missingRuleIds,
+      status: missingRuleIds.length > 0 ? 'INCOMPLETE' : 'OK',
+    });
+  }
+
+  if (byFile.length === 0) {
+    return undefined;
+  }
+
+  const requiredRuleIds = toUniqueSorted(byFile.flatMap((item) => item.required_rule_ids));
+  const appliedRuleIds = toUniqueSorted(byFile.flatMap((item) => item.applied_rule_ids));
+  const evidenceRuleIds = toUniqueSorted(byFile.flatMap((item) => item.evidence_rule_ids));
+  const missingRuleIds = toUniqueSorted(byFile.flatMap((item) => item.missing_rule_ids));
+
+  return {
+    required_rule_ids: requiredRuleIds,
+    applied_rule_ids: appliedRuleIds,
+    evidence_rule_ids: evidenceRuleIds,
+    missing_rule_ids: missingRuleIds,
+    counts: {
+      files_in_scope: byFile.length,
+      files_with_missing: byFile.filter((item) => item.missing_rule_ids.length > 0).length,
+      required: requiredRuleIds.length,
+      applied: appliedRuleIds.length,
+      evidence: evidenceRuleIds.length,
+      missing: missingRuleIds.length,
+    },
+    by_file: byFile,
+  };
+};