pumuki 6.3.95 → 6.3.96

package/docs/operations/RELEASE_NOTES.md

@@ -1,3 +1,7 @@
+## 2026-04-20 (v6.3.96)
+- **Diagnóstico explícito de skills faltantes**: `status`, `doctor` y el AI gate ya no degradan a señales genéricas cuando falta una skill requerida o su fuente es ilegible; ahora emiten `SKILLS_REQUIRED_SOURCE_MISSING` o `SKILLS_REQUIRED_SOURCE_UNREADABLE` con nombre de skill, ruta concreta y resolución accionable.
+- **Rollout recomendado**: publicar `pumuki@6.3.96`, repin inmediato en `Flux_training` y repetir la repro del repo sin `docs/codex-skills`, confirmando que `status --json` y `doctor --json` incluyen la ruta `docs/codex-skills/windsurf-rules-backend.md` en `skills_contract.source_diagnostics`.
+
 ## 2026-04-20 (v6.3.95)
 - **Enforcement operativo de trazabilidad contractual**: `pumuki sdd evidence` exige ahora `--traceability-markdown=<path>` cuando el repositorio declara en `AGENTS.md` la matriz mínima `ARCHIVO | SKILL | REGLA | EVIDENCIA | ESTADO`; el comando falla si falta la cabecera exacta o si no existe al menos una fila real.
 - **Rollout recomendado**: publicar `pumuki@6.3.95`, repin inmediato en `Flux_training` y repetir la doble repro de `pumuki sdd evidence`: sin `--traceability-markdown` debe bloquear, y con un markdown repo-local que contenga la matriz contractual debe pasar.

package/integrations/config/skillsCustomRules.ts

@@ -49,6 +49,15 @@ export type CompiledImportedSkillsRulesResult = Omit<
   'outputPath'
 >;
 
+export type SkillImportSourceDiagnostic = {
+  skillName: string;
+  canonicalSkillName: string;
+  sourcePath: string;
+  sourceType: 'declared_path' | 'required_skill';
+  issue: 'missing' | 'unreadable';
+  resolution: string;
+};
+
 type VendorSkillManifestEntry = {
   name: string;
   file: string;
@@ -423,22 +432,57 @@ const loadVendorSkillsManifest = (
   return bySkillName;
 };
 
-export const resolveSkillImportSources = (params: {
+const buildSkillImportResolution = (sourcePath: string): string => {
+  const normalized = sourcePath.replace(/\\/g, '/');
+  if (normalized.includes('/docs/codex-skills/') || normalized.startsWith('docs/codex-skills/')) {
+    return `Restaura ${sourcePath} o ejecuta ./scripts/sync-codex-skills.sh para resincronizar las skills vendorizadas.`;
+  }
+  if (normalized.includes('/vendor/skills/') || normalized.startsWith('vendor/skills/')) {
+    return `Restaura ${sourcePath} desde vendor/skills o resincroniza las dependencias del repositorio.`;
+  }
+  return `Corrige la ruta declarada o restaura ${sourcePath} para que la skill requerida vuelva a estar disponible.`;
+};
+
+const canReadSkillSourceFile = (sourcePath: string): boolean => {
+  try {
+    readFileSync(sourcePath, 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const resolveSkillImportSourcesWithDiagnostics = (params: {
   repoRoot?: string;
   explicitSources?: ReadonlyArray<string>;
-}): string[] => {
+}): { sourceFiles: string[]; diagnostics: SkillImportSourceDiagnostic[] } => {
   const repoRoot = params.repoRoot ?? process.cwd();
   const resolved = new Map<string, { path: string; priority: number }>();
   const vendoredManifest = loadVendorSkillsManifest(repoRoot);
-
-  const pushIfExists = (rawPath: string): void => {
+  const diagnostics: SkillImportSourceDiagnostic[] = [];
+
+  const registerDiagnostic = (
+    rawPath: string,
+    skillName: string,
+    canonicalSkillName: string,
+    sourceType: SkillImportSourceDiagnostic['sourceType'],
+    issue: SkillImportSourceDiagnostic['issue'],
+  ): void => {
     const normalized = normalizePath({
       repoRoot,
       path: rawPath,
     });
-    if (!existsSync(normalized)) {
-      return;
-    }
+    diagnostics.push({
+      skillName,
+      canonicalSkillName,
+      sourcePath: normalized,
+      sourceType,
+      issue,
+      resolution: buildSkillImportResolution(normalized),
+    });
+  };
+
+  const pushResolved = (normalized: string): void => {
     const skillKey = toCanonicalImportedSkillName(sourceSkillNameFromPath(normalized));
     const priority = isVendoredSkillMarkdownPath(normalized) ? 2 : 1;
     const current = resolved.get(skillKey);
@@ -451,13 +495,36 @@ export const resolveSkillImportSources = (params: {
     }
   };
 
+  const registerSource = (
+    rawPath: string,
+    skillName: string,
+    canonicalSkillName: string,
+    sourceType: SkillImportSourceDiagnostic['sourceType'],
+  ): void => {
+    const normalized = normalizePath({
+      repoRoot,
+      path: rawPath,
+    });
+    if (!existsSync(normalized)) {
+      registerDiagnostic(rawPath, skillName, canonicalSkillName, sourceType, 'missing');
+      return;
+    }
+    if (!canReadSkillSourceFile(normalized)) {
+      registerDiagnostic(rawPath, skillName, canonicalSkillName, sourceType, 'unreadable');
+      return;
+    }
+    pushResolved(normalized);
+  };
+
   if (params.explicitSources && params.explicitSources.length > 0) {
     for (const source of params.explicitSources) {
-      pushIfExists(source);
+      const normalized = normalizePath({ repoRoot, path: source });
+      registerSource(source, sourceSkillNameFromPath(normalized), toCanonicalImportedSkillName(sourceSkillNameFromPath(normalized)), 'declared_path');
     }
-    return [...resolved.values()]
-      .map((item) => item.path)
-      .sort();
+    return {
+      sourceFiles: [...resolved.values()].map((item) => item.path).sort(),
+      diagnostics,
+    };
   }
 
   for (const profileFile of ['AGENTS.md', 'SKILLS.md']) {
@@ -467,23 +534,37 @@ export const resolveSkillImportSources = (params: {
     }
     const content = readFileSync(profilePath, 'utf8');
     for (const candidate of extractSkillPathsFromText(content)) {
-      pushIfExists(candidate);
+      const normalized = normalizePath({ repoRoot, path: candidate });
+      const skillName = sourceSkillNameFromPath(normalized);
+      registerSource(candidate, skillName, toCanonicalImportedSkillName(skillName), 'declared_path');
     }
     for (const requiredSkillName of extractRequiredSkillNamesFromText(content)) {
       const canonicalName = toCanonicalImportedSkillName(requiredSkillName);
       const manifestPath = vendoredManifest.get(canonicalName);
       if (manifestPath) {
-        pushIfExists(manifestPath);
+        registerSource(manifestPath, requiredSkillName, canonicalName, 'required_skill');
         continue;
       }
-      pushIfExists(`vendor/skills/${requiredSkillName}/SKILL.md`);
-      pushIfExists(`vendor/skills/${canonicalName}/SKILL.md`);
+      const canonicalVendoredPath = `vendor/skills/${canonicalName}/SKILL.md`;
+      const requiredVendoredPath = `vendor/skills/${requiredSkillName}/SKILL.md`;
+      const selectedPath = existsSync(normalizePath({ repoRoot, path: requiredVendoredPath }))
+        ? requiredVendoredPath
+        : canonicalVendoredPath;
+      registerSource(selectedPath, requiredSkillName, canonicalName, 'required_skill');
     }
   }
 
-  return [...resolved.values()]
-    .map((item) => item.path)
-    .sort();
+  return {
+    sourceFiles: [...resolved.values()].map((item) => item.path).sort(),
+    diagnostics,
+  };
+};
+
+export const resolveSkillImportSources = (params: {
+  repoRoot?: string;
+  explicitSources?: ReadonlyArray<string>;
+}): string[] => {
+  return resolveSkillImportSourcesWithDiagnostics(params).sourceFiles;
 };
 
 export const compileImportedSkillsRules = (params: {

package/integrations/gate/evaluateAiGate.ts

@@ -12,6 +12,10 @@ import {
   loadEffectiveSkillsLock,
   loadRequiredSkillsLock,
 } from '../config/skillsEffectiveLock';
+import {
+  resolveSkillImportSourcesWithDiagnostics,
+  type SkillImportSourceDiagnostic,
+} from '../config/skillsCustomRules';
 import {
   resolveSkillsEnforcement,
   type SkillsEnforcementResolution,
@@ -56,6 +60,7 @@ export type AiGateSkillsContractAssessment = {
   status: 'PASS' | 'FAIL' | 'NOT_APPLICABLE';
   detected_platforms: ReadonlyArray<PreWriteSkillsPlatform>;
   requirements: ReadonlyArray<AiGateSkillsContractPlatformRequirement>;
+  source_diagnostics: ReadonlyArray<SkillImportSourceDiagnostic>;
   violations: ReadonlyArray<AiGateViolation>;
 };
 
@@ -725,6 +730,20 @@ const collectPreWriteCrossPlatformCriticalViolations = (params: {
   ];
 };
 
+const toRequiredSkillSourceViolations = (
+  diagnostics: ReadonlyArray<SkillImportSourceDiagnostic>,
+  skillsEnforcement: SkillsEnforcementResolution
+): AiGateViolation[] =>
+  diagnostics.map((diagnostic) =>
+    toSkillsViolation(
+      skillsEnforcement,
+      diagnostic.issue === 'missing'
+        ? 'SKILLS_REQUIRED_SOURCE_MISSING'
+        : 'SKILLS_REQUIRED_SOURCE_UNREADABLE',
+      `La skill requerida "${diagnostic.skillName}" no está disponible en ${diagnostic.sourcePath}. ${diagnostic.resolution}`
+    )
+  );
+
 const toSkillsContractAssessment = (params: {
   stage: AiGateStage;
   repoRoot: string;
@@ -734,12 +753,22 @@ const toSkillsContractAssessment = (params: {
   skillsEnforcement: SkillsEnforcementResolution;
 }): AiGateSkillsContractAssessment => {
   const requiredPlatforms = toLockRequiredPlatforms(params.requiredLock);
+  const sourceDiagnostics = resolveSkillImportSourcesWithDiagnostics({
+    repoRoot: params.repoRoot,
+  }).diagnostics;
 
   if (params.evidenceResult.kind !== 'valid') {
+    const sourceViolations = toRequiredSkillSourceViolations(
+      sourceDiagnostics,
+      params.skillsEnforcement
+    );
     return {
       stage: params.stage,
-      enforced: requiredPlatforms.length > 0,
-      status: requiredPlatforms.length > 0 ? 'FAIL' : 'NOT_APPLICABLE',
+      enforced: requiredPlatforms.length > 0 || sourceDiagnostics.length > 0,
+      status:
+        requiredPlatforms.length > 0 || sourceDiagnostics.length > 0
+          ? 'FAIL'
+          : 'NOT_APPLICABLE',
       detected_platforms: [],
       requirements: requiredPlatforms.map((platform) => ({
         platform,
@@ -758,8 +787,10 @@ const toSkillsContractAssessment = (params: {
           ...PREWRITE_TRANSVERSAL_CRITICAL_SKILLS_RULES[platform],
         ],
       })),
-      violations:
-        requiredPlatforms.length > 0
+      source_diagnostics: sourceDiagnostics,
+      violations: [
+        ...sourceViolations,
+        ...(requiredPlatforms.length > 0
           ? [
               toSkillsViolation(
                 params.skillsEnforcement,
@@ -767,7 +798,8 @@ const toSkillsContractAssessment = (params: {
                 `Required repo skills exist, but active platforms could not be detected for ${params.stage}.`
               ),
             ]
-          : [],
+          : []),
+      ],
     };
   }
 
@@ -825,11 +857,15 @@ const toSkillsContractAssessment = (params: {
     ) {
       return {
         stage: params.stage,
-        enforced: false,
-        status: 'NOT_APPLICABLE',
+        enforced: sourceDiagnostics.length > 0,
+        status: sourceDiagnostics.length > 0 ? 'FAIL' : 'NOT_APPLICABLE',
         detected_platforms: [],
         requirements: [],
-        violations: [],
+        source_diagnostics: sourceDiagnostics,
+        violations: toRequiredSkillSourceViolations(
+          sourceDiagnostics,
+          params.skillsEnforcement
+        ),
       };
     }
     const requirements: AiGateSkillsContractPlatformRequirement[] = requiredPlatforms.map((platform) => ({
@@ -856,7 +892,12 @@ const toSkillsContractAssessment = (params: {
       status: 'FAIL',
       detected_platforms: [],
       requirements,
+      source_diagnostics: sourceDiagnostics,
       violations: [
+        ...toRequiredSkillSourceViolations(
+          sourceDiagnostics,
+          params.skillsEnforcement
+        ),
         toSkillsViolation(
           params.skillsEnforcement,
           'EVIDENCE_SKILLS_PLATFORMS_UNDETECTED',
@@ -868,11 +909,15 @@ const toSkillsContractAssessment = (params: {
   if (assessmentPlatforms.length === 0) {
     return {
       stage: params.stage,
-      enforced: false,
-      status: 'NOT_APPLICABLE',
+      enforced: sourceDiagnostics.length > 0,
+      status: sourceDiagnostics.length > 0 ? 'FAIL' : 'NOT_APPLICABLE',
       detected_platforms: [],
       requirements: [],
-      violations: [],
+      source_diagnostics: sourceDiagnostics,
+      violations: toRequiredSkillSourceViolations(
+        sourceDiagnostics,
+        params.skillsEnforcement
+      ),
     };
   }
 
@@ -884,7 +929,10 @@ const toSkillsContractAssessment = (params: {
   );
 
   const requirements: AiGateSkillsContractPlatformRequirement[] = [];
-  const violations: AiGateViolation[] = [];
+  const violations: AiGateViolation[] = toRequiredSkillSourceViolations(
+    sourceDiagnostics,
+    params.skillsEnforcement
+  );
   if (requiredPlatforms.length > 0 && detectedPlatforms.length === 0) {
     violations.push(
       toSkillsViolation(
@@ -995,6 +1043,7 @@ const toSkillsContractAssessment = (params: {
     status: violations.length === 0 ? 'PASS' : 'FAIL',
     detected_platforms: detectedPlatforms,
     requirements,
+    source_diagnostics: sourceDiagnostics,
     violations,
   };
 };
@@ -1596,6 +1645,11 @@ export const evaluateAiGate = (
     || (params.stage === 'PRE_WRITE' && requiredSkillsPlatforms.length === 0)
         ? []
       : [
+          ...skillsContract.violations.filter(
+            (violation) =>
+              violation.code === 'SKILLS_REQUIRED_SOURCE_MISSING'
+              || violation.code === 'SKILLS_REQUIRED_SOURCE_UNREADABLE'
+          ),
           toSkillsViolation(
             skillsEnforcement,
             'EVIDENCE_SKILLS_CONTRACT_INCOMPLETE',

package/integrations/lifecycle/governanceObservationSnapshot.ts

@@ -4,6 +4,10 @@ import { readEvidenceResult } from '../evidence/readEvidence';
 import { readRepoTrackingState } from '../evidence/trackingContract';
 import type { RepoTrackingState } from '../evidence/schema';
 import { loadRequiredSkillsLock } from '../config/skillsEffectiveLock';
+import {
+  resolveSkillImportSourcesWithDiagnostics,
+  type SkillImportSourceDiagnostic,
+} from '../config/skillsCustomRules';
 import { readSddStatus } from '../sdd';
 import type { SddStatusPayload } from '../sdd/types';
 import type { LifecycleExperimentalFeaturesSnapshot } from './experimentalFeaturesSnapshot';
@@ -54,6 +58,7 @@ export type GovernanceSkillsContractSummary = {
   status: 'PASS' | 'FAIL' | 'NOT_APPLICABLE';
   detected_platforms: ReadonlyArray<GovernanceSkillsContractPlatform>;
   requirements: ReadonlyArray<GovernanceSkillsContractPlatformRequirement>;
+  source_diagnostics: ReadonlyArray<SkillImportSourceDiagnostic>;
   violations: ReadonlyArray<GovernanceSkillsContractViolation>;
 };
 
@@ -228,15 +233,29 @@ const toCoverageDetectedPlatforms = (
 
 const summarizeSkillsContract = (repoRoot: string): GovernanceSkillsContractSummary => {
   const requiredPlatforms = toRequiredSkillsPlatforms(repoRoot);
+  const sourceDiagnostics = resolveSkillImportSourcesWithDiagnostics({ repoRoot }).diagnostics;
   const evidenceResult = readEvidenceResult(repoRoot);
   if (evidenceResult.kind !== 'valid') {
     return {
       stage: 'PRE_WRITE',
-      enforced: false,
-      status: 'NOT_APPLICABLE',
+      enforced: requiredPlatforms.length > 0 || sourceDiagnostics.length > 0,
+      status:
+        requiredPlatforms.length > 0 || sourceDiagnostics.length > 0
+          ? 'FAIL'
+          : 'NOT_APPLICABLE',
       detected_platforms: [],
       requirements: [],
-      violations: [],
+      source_diagnostics: sourceDiagnostics,
+      violations: sourceDiagnostics.map((diagnostic) => ({
+        severity: 'ERROR',
+        code:
+          diagnostic.issue === 'missing'
+            ? 'SKILLS_REQUIRED_SOURCE_MISSING'
+            : 'SKILLS_REQUIRED_SOURCE_UNREADABLE',
+        message:
+          `La skill requerida "${diagnostic.skillName}" no está disponible en ` +
+          `${diagnostic.sourcePath}. ${diagnostic.resolution}`,
+      })),
     };
   }
 
@@ -246,11 +265,21 @@ const summarizeSkillsContract = (repoRoot: string): GovernanceSkillsContractSumm
   if (assessmentPlatforms.length === 0) {
     return {
       stage: 'PRE_WRITE',
-      enforced: false,
-      status: 'NOT_APPLICABLE',
+      enforced: sourceDiagnostics.length > 0,
+      status: sourceDiagnostics.length > 0 ? 'FAIL' : 'NOT_APPLICABLE',
       detected_platforms: [],
       requirements: [],
-      violations: [],
+      source_diagnostics: sourceDiagnostics,
+      violations: sourceDiagnostics.map((diagnostic) => ({
+        severity: 'ERROR',
+        code:
+          diagnostic.issue === 'missing'
+            ? 'SKILLS_REQUIRED_SOURCE_MISSING'
+            : 'SKILLS_REQUIRED_SOURCE_UNREADABLE',
+        message:
+          `La skill requerida "${diagnostic.skillName}" no está disponible en ` +
+          `${diagnostic.sourcePath}. ${diagnostic.resolution}`,
+      })),
     };
   }
 
@@ -266,6 +295,18 @@ const summarizeSkillsContract = (repoRoot: string): GovernanceSkillsContractSumm
 
   const requirements: GovernanceSkillsContractPlatformRequirement[] = [];
   const violations: GovernanceSkillsContractViolation[] = [];
+  for (const diagnostic of sourceDiagnostics) {
+    violations.push({
+      severity: 'ERROR',
+      code:
+        diagnostic.issue === 'missing'
+          ? 'SKILLS_REQUIRED_SOURCE_MISSING'
+          : 'SKILLS_REQUIRED_SOURCE_UNREADABLE',
+      message:
+        `La skill requerida "${diagnostic.skillName}" no está disponible en ` +
+        `${diagnostic.sourcePath}. ${diagnostic.resolution}`,
+    });
+  }
   for (const platform of assessmentPlatforms) {
     const requiredRulePrefix = GOVERNANCE_SKILLS_RULE_PREFIXES[platform];
     const requiredBundles = [...GOVERNANCE_REQUIRED_SKILLS_BUNDLES[platform]];
@@ -355,6 +396,7 @@ const summarizeSkillsContract = (repoRoot: string): GovernanceSkillsContractSumm
     status: violations.length === 0 ? 'PASS' : 'FAIL',
     detected_platforms: detectedPlatforms,
     requirements,
+    source_diagnostics: sourceDiagnostics,
     violations,
   };
 };
@@ -485,12 +527,16 @@ export const readGovernanceObservationSnapshot = (params: {
   if (skillsContract.status === 'FAIL') {
     attention.push('SKILLS_CONTRACT_INCOMPLETE');
   }
+  if (skillsContract.source_diagnostics.length > 0) {
+    attention.push('SKILLS_REQUIRED_SOURCE_INVALID');
+  }
 
   let governanceEffective: GovernanceObservationSnapshot['governance_effective'] = 'green';
   if (
     evidence.readable === 'invalid'
     || (evidence.readable === 'valid' && evidence.ai_gate_status === 'BLOCKED')
     || (evidence.readable === 'valid' && evidence.snapshot_outcome === 'BLOCK')
+    || skillsContract.source_diagnostics.length > 0
   ) {
     governanceEffective = 'blocked';
   } else if (attention.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pumuki",
-  "version": "6.3.95",
+  "version": "6.3.96",
   "description": "Enterprise-grade AST Intelligence System with multi-platform support (iOS, Android, Backend, Frontend) and Feature-First + DDD + Clean Architecture enforcement. Includes dynamic violations API for intelligent querying.",
   "main": "index.js",
   "bin": {