pumuki 6.3.94 → 6.3.95

package/docs/operations/RELEASE_NOTES.md

@@ -1,3 +1,7 @@
+## 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/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/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.95",
   "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": {