pumuki 6.3.94 → 6.3.96

package/docs/operations/RELEASE_NOTES.md

@@ -1,3 +1,11 @@
+## 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.
+
 ## 2026-04-20 (v6.3.94)
 - **Subtitle de bloqueo 100% en español**: la causa primaria visible de notificaciones ya traduce explícitamente los mensajes exactos de `console.log usage is not allowed in frontend code.` y `...backend code.` antes de construir el `subtitle`, evitando el último escape de copy inglés en bloqueos reales de frontend/backend.
 - **Rollout recomendado**: publicar `pumuki@6.3.94`, repin inmediato en `Flux_training` y repetir un rojo real de frontend con `PUMUKI_SKIP_CHAINED_PRE_WRITE=1 pnpm exec pumuki-pre-commit`, confirmando que el `subtitle` contiene `Se detectó uso de "console.log" en frontend.` y no la frase inglesa raw.

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/cli.ts

@@ -152,6 +152,7 @@ export type ParsedArgs = {
   sddEvidenceTestStatus?: SddEvidenceScaffoldTestStatus;
   sddEvidenceTestOutput?: string;
   sddEvidenceFromEvidence?: string;
+  sddEvidenceTraceabilityMarkdown?: string;
   sddStateSyncDryRun?: boolean;
   sddStateSyncScenarioId?: string;
   sddStateSyncStatus?: SddStateSyncStatus;
@@ -208,7 +209,7 @@ Pumuki lifecycle commands:
   pumuki sdd sync [--change=<change-id>] [--stage=PRE_WRITE|PRE_COMMIT|PRE_PUSH|CI] [--task=<task-id>] [--from-evidence=<path>] [--dry-run] [--json]
   pumuki sdd learn --change=<change-id> [--stage=PRE_WRITE|PRE_COMMIT|PRE_PUSH|CI] [--task=<task-id>] [--from-evidence=<path>] [--dry-run] [--json]
   pumuki sdd auto-sync --change=<change-id> [--stage=PRE_WRITE|PRE_COMMIT|PRE_PUSH|CI] [--task=<task-id>] [--from-evidence=<path>] [--dry-run] [--json]
-  pumuki sdd evidence --scenario-id=<id> --test-command=<command> --test-status=passed|failed [--test-output=<path>] [--from-evidence=<path>] [--dry-run] [--json]
+  pumuki sdd evidence --scenario-id=<id> --test-command=<command> --test-status=passed|failed [--test-output=<path>] [--from-evidence=<path>] [--traceability-markdown=<path>] [--dry-run] [--json]
   pumuki sdd state-sync [--scenario-id=<id>] [--status=todo|in_progress|blocked|done] [--from-evidence=<path>] [--board-path=<path>] [--force] [--dry-run] [--json]
   aliases de --stage: RED=PRE_WRITE, GREEN=PRE_COMMIT, REFACTOR=PRE_PUSH, CLOSE=CI
 `.trim();
@@ -612,6 +613,7 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
   let sddEvidenceTestStatus: ParsedArgs['sddEvidenceTestStatus'];
   let sddEvidenceTestOutput: ParsedArgs['sddEvidenceTestOutput'];
   let sddEvidenceFromEvidence: ParsedArgs['sddEvidenceFromEvidence'];
+  let sddEvidenceTraceabilityMarkdown: ParsedArgs['sddEvidenceTraceabilityMarkdown'];
   let sddStateSyncDryRun = false;
   let sddStateSyncScenarioId: ParsedArgs['sddStateSyncScenarioId'];
   let sddStateSyncStatus: ParsedArgs['sddStateSyncStatus'];
@@ -1095,6 +1097,17 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
         sddEvidenceTestOutput = testOutputPath;
         continue;
       }
+      if (arg.startsWith('--traceability-markdown=')) {
+        if (sddCommand !== 'evidence') {
+          throw new Error(`--traceability-markdown is only supported with "pumuki sdd evidence".\n\n${HELP_TEXT}`);
+        }
+        const traceabilityMarkdownPath = arg.slice('--traceability-markdown='.length).trim();
+        if (traceabilityMarkdownPath.length === 0) {
+          throw new Error(`Invalid --traceability-markdown value "${arg}".`);
+        }
+        sddEvidenceTraceabilityMarkdown = traceabilityMarkdownPath;
+        continue;
+      }
       if (arg.startsWith('--from-evidence=')) {
         if (sddCommand === 'sync-docs') {
           sddSyncDocsFromEvidence = parseSddEvidencePath(
@@ -1255,7 +1268,7 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
         sddAutoSyncChange
       ) {
         throw new Error(
-          `"pumuki sdd evidence" only supports --scenario-id=<id> --test-command=<command> --test-status=passed|failed [--test-output=<path>] [--from-evidence=<path>] [--dry-run] [--json].\n\n${HELP_TEXT}`
+          `"pumuki sdd evidence" only supports --scenario-id=<id> --test-command=<command> --test-status=passed|failed [--test-output=<path>] [--from-evidence=<path>] [--traceability-markdown=<path>] [--dry-run] [--json].\n\n${HELP_TEXT}`
         );
       }
       if (!sddEvidenceScenarioId) {
@@ -1278,6 +1291,7 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
         sddEvidenceTestStatus,
         ...(sddEvidenceTestOutput ? { sddEvidenceTestOutput } : {}),
         ...(sddEvidenceFromEvidence ? { sddEvidenceFromEvidence } : {}),
+        ...(sddEvidenceTraceabilityMarkdown ? { sddEvidenceTraceabilityMarkdown } : {}),
       };
     }
     if (sddCommand === 'state-sync') {

package/integrations/lifecycle/cliSdd.ts

@@ -451,6 +451,7 @@ export const runSddCommand = async (parsed: ParsedArgs, activeDependencies: Life
             testStatus: parsed.sddEvidenceTestStatus,
             testOutputPath: parsed.sddEvidenceTestOutput,
             fromEvidencePath: parsed.sddEvidenceFromEvidence,
+            traceabilityMarkdownPath: parsed.sddEvidenceTraceabilityMarkdown,
           });
           if (parsed.json) {
             writeInfo(JSON.stringify(evidenceResult, null, 2));

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/integrations/sdd/evidenceScaffold.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, relative, resolve } from 'node:path';
 import { readEvidenceResult, type EvidenceReadResult } from '../evidence/readEvidence';
 
@@ -15,6 +15,7 @@ export type SddEvidenceScaffoldResult = {
     testStatus: SddEvidenceScaffoldTestStatus;
     testOutputPath: string | null;
     fromEvidencePath: string | null;
+    traceabilityMarkdownPath: string | null;
   };
   output: {
     path: string;
@@ -44,6 +45,13 @@ export type SddEvidenceScaffoldResult = {
       source: 'pumuki-sdd-evidence';
       stack: 'sdd-evidence-scaffold';
     };
+    traceability: {
+      required: boolean;
+      path: string | null;
+      header_present: boolean;
+      rows: number;
+      status: 'valid';
+    };
     // Legacy fields kept for state-sync compatibility in existing consumers.
     scenario_id: string;
     test_run: {
@@ -65,10 +73,13 @@ export type SddEvidenceScaffoldResult = {
 const computeDigest = (value: string): string =>
   `sha256:${createHash('sha256').update(value, 'utf8').digest('hex')}`;
 
+const TRACEABILITY_HEADER = '| ARCHIVO | SKILL | REGLA | EVIDENCIA | ESTADO |';
+const TRACEABILITY_CONTRACT_MARKER = 'ARCHIVO | SKILL | REGLA | EVIDENCIA | ESTADO';
+
 const resolveRepoBoundPath = (params: {
   repoRoot: string;
   candidatePath: string;
-  flagName: '--from-evidence' | '--test-output';
+  flagName: '--from-evidence' | '--test-output' | '--traceability-markdown';
 }): string => {
   const repoRootAbsolute = resolve(params.repoRoot);
   const resolved = isAbsolute(params.candidatePath)
@@ -141,6 +152,87 @@ const resolveScenarioReference = (scenarioId: string): string => {
   return `${normalized}.feature`;
 };
 
+const repoRequiresTraceabilityMatrix = (repoRoot: string): boolean => {
+  const agentsPath = resolve(repoRoot, 'AGENTS.md');
+  if (!existsSync(agentsPath)) {
+    return false;
+  }
+  const contents = readFileSync(agentsPath, 'utf8');
+  return (
+    contents.includes('Plantilla obligatoria de trazabilidad por turno') ||
+    contents.includes(TRACEABILITY_CONTRACT_MARKER)
+  );
+};
+
+const validateTraceabilityMarkdown = (params: {
+  repoRoot: string;
+  required: boolean;
+  traceabilityMarkdownPath?: string;
+}): {
+  path: string | null;
+  header_present: boolean;
+  rows: number;
+} => {
+  if (!params.required) {
+    return {
+      path: params.traceabilityMarkdownPath?.trim() ? params.traceabilityMarkdownPath.trim() : null,
+      header_present: false,
+      rows: 0,
+    };
+  }
+  const candidate = params.traceabilityMarkdownPath?.trim() ?? '';
+  if (candidate.length === 0) {
+    throw new Error(
+      `[pumuki][sdd] evidence requires --traceability-markdown=<path> because this repository declares the contractual traceability matrix (${TRACEABILITY_HEADER}).`
+    );
+  }
+  const absolutePath = resolveRepoBoundPath({
+    repoRoot: params.repoRoot,
+    candidatePath: candidate,
+    flagName: '--traceability-markdown',
+  });
+  if (!existsSync(absolutePath)) {
+    throw new Error(
+      `[pumuki][sdd] traceability markdown file does not exist: ${candidate}. Add the contractual matrix and retry.`
+    );
+  }
+  const markdown = readFileSync(absolutePath, 'utf8');
+  const lines = markdown.split(/\r?\n/);
+  const headerIndex = lines.findIndex((line) => line.trim() === TRACEABILITY_HEADER);
+  if (headerIndex < 0) {
+    throw new Error(
+      `[pumuki][sdd] traceability markdown must include the contractual header ${TRACEABILITY_HEADER}.`
+    );
+  }
+  let rows = 0;
+  for (const line of lines.slice(headerIndex + 1)) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) {
+      if (rows > 0) {
+        break;
+      }
+      continue;
+    }
+    if (/^\|\s*-+\s*\|/.test(trimmed)) {
+      continue;
+    }
+    if (trimmed === TRACEABILITY_HEADER) {
+      continue;
+    }
+    rows += 1;
+  }
+  if (rows === 0) {
+    throw new Error(
+      '[pumuki][sdd] traceability markdown must include at least one data row under the contractual matrix header.'
+    );
+  }
+  return {
+    path: relative(params.repoRoot, absolutePath).split('\\').join('/'),
+    header_present: true,
+    rows,
+  };
+};
+
 export const runSddEvidenceScaffold = (params?: {
   repoRoot?: string;
   dryRun?: boolean;
@@ -149,6 +241,7 @@ export const runSddEvidenceScaffold = (params?: {
   testStatus?: SddEvidenceScaffoldTestStatus;
   testOutputPath?: string;
   fromEvidencePath?: string;
+  traceabilityMarkdownPath?: string;
   outputPath?: string;
   now?: () => Date;
   evidenceReader?: (repoRoot: string) => EvidenceReadResult;
@@ -195,6 +288,12 @@ export const runSddEvidenceScaffold = (params?: {
     evidenceResult: evidenceReader(repoRoot),
     fromEvidencePath,
   });
+  const traceabilityRequired = repoRequiresTraceabilityMatrix(repoRoot);
+  const traceability = validateTraceabilityMarkdown({
+    repoRoot,
+    required: traceabilityRequired,
+    traceabilityMarkdownPath: params?.traceabilityMarkdownPath,
+  });
 
   const now = params?.now ?? (() => new Date());
   const generatedAt = now().toISOString();
@@ -232,6 +331,13 @@ export const runSddEvidenceScaffold = (params?: {
       source: 'pumuki-sdd-evidence',
       stack: 'sdd-evidence-scaffold',
     },
+    traceability: {
+      required: traceabilityRequired,
+      path: traceability.path,
+      header_present: traceability.header_present,
+      rows: traceability.rows,
+      status: 'valid',
+    },
     scenario_id: scenarioId,
     test_run: {
       command: testCommand,
@@ -267,6 +373,7 @@ export const runSddEvidenceScaffold = (params?: {
       testStatus,
       testOutputPath,
       fromEvidencePath,
+      traceabilityMarkdownPath: traceability.path,
     },
     output: {
       path: outputRelativePath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pumuki",
-  "version": "6.3.94",
+  "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": {