pumuki 6.3.44 → 6.3.45

package/docs/RELEASE_NOTES.md

@@ -5,6 +5,24 @@ Detailed commit history remains available through Git history (`git log` / `git
 
 ## 2026-03 (enterprise hardening updates)
 
+### 2026-03-05 (v6.3.45)
+
+- SDD sync canónico ampliado por defecto en consumer:
+  - `pumuki sdd sync-docs` ahora sincroniza, cuando existen, los 3 documentos base:
+    - `docs/strategy/ruralgo-tracking-hub.md`
+    - `docs/technical/08-validation/refactor/operational-summary.md`
+    - `docs/validation/refactor/last-run.json`
+- Auto-sync OpenSpec integral por cambio:
+  - `pumuki sdd auto-sync` incluye por defecto:
+    - `openspec/changes/<change>/tasks.md`
+    - `openspec/changes/<change>/design.md`
+    - `openspec/changes/<change>/retrospective.md`
+- Consumo automático universal de aprendizaje:
+  - `ai_gate_check`, `pre_flight_check` y `auto_execute_ai_start` exponen `learning_context` cuando existe `openspec/changes/<change>/learning.json`.
+- Evidencia de validación:
+  - `npx --yes tsx@4.21.0 --test integrations/mcp/__tests__/aiGateCheck.test.ts integrations/mcp/__tests__/preFlightCheck.test.ts integrations/mcp/__tests__/autoExecuteAiStart.test.ts integrations/sdd/__tests__/syncDocs.test.ts integrations/lifecycle/__tests__/cli.test.ts` (`78 pass / 0 fail`)
+  - `npm run -s typecheck` (`PASS`)
+
 ### 2026-03-05 (v6.3.43)
 
 - `pumuki sdd evidence` alinea su salida con el contrato TDD/BDD del gate:

package/docs/seguimiento-activo-pumuki-saas-supermercados.md

@@ -2099,12 +2099,94 @@
     - `npx --yes tsx@4.21.0 --test integrations/lifecycle/__tests__/watch.test.ts integrations/lifecycle/__tests__/cli.test.ts integrations/lifecycle/__tests__/policyReconcile.test.ts` -> `53 pass / 0 fail`.
     - `npm run -s typecheck` -> `PASS`.
 
-- 🚧 PUMUKI-162: Ejecutar siguiente pendiente activo de Flux (`PUM-011`) para cerrar paridad consumer de `watch --once --json` con `lastTick.changedFiles[]` y `lastTick.evaluatedFiles[]`.
+- ✅ PUMUKI-162: Ejecutar siguiente pendiente activo de Flux (`PUM-011`) para cerrar paridad consumer de `watch --once --json` con `lastTick.changedFiles[]` y `lastTick.evaluatedFiles[]`.
   - Alcance:
     - verificar contrato JSON final en paquete publicado vs consumer runtime,
     - eliminar drift de payload entre core y distribución npm,
     - cerrar con validación reproducible en consumer (sin tocar código funcional del consumer).
-  - Avance actual (2026-03-05):
-    - verificado en core local (`bin/pumuki.js`): `lastTick.changedFiles[]` y `lastTick.evaluatedFiles[]` sí aparecen.
-    - verificado en paquete publicado (`pumuki@latest`): esos campos aún no aparecen en JSON de `watch`.
-    - conclusión: bug activo de rollout/distribución (no de lógica local), pendiente de corte/release para cerrar `PUM-011`.
+  - Resultado (2026-03-05):
+    - release publicado: `pumuki@6.3.44`.
+    - verificación `@latest` en repo temporal:
+      - `lastTick.changedFiles[]` presente.
+      - `lastTick.evaluatedFiles[]` presente.
+    - leyenda Flux actualizada:
+      - `PUM-011` -> `✅ Cerrado`.
+
+- ✅ PUMUKI-163: Ejecutar siguiente pendiente activo de Flux (`PUM-012`) para garantizar contrato JSON estricto (`stdout` solo JSON) cuando se usa `--json`.
+  - Resultado (2026-03-05):
+    - `integrations/git/runPlatformGate.ts` añade `silent?: boolean` para suprimir salida humana en `stdout` al ejecutar en flujos machine-readable.
+    - `integrations/lifecycle/watch.ts` invoca `runPlatformGate(..., { silent: true })` en `watch --json` para mantener contrato estricto de parseo.
+    - cobertura de regresión añadida en `integrations/git/__tests__/runPlatformGate.test.ts`:
+      - `runPlatformGate silent evita salida humana en stdout para contratos JSON`.
+    - validación funcional de contrato:
+      - `node bin/pumuki.js watch --once --stage=PRE_COMMIT --scope=workingTree --json | jq -e '.status'` -> `JSON_PIPE_OK`.
+    - leyenda Flux actualizada:
+      - `PUM-012` -> `✅ Cerrado`.
+      - backlog Flux externo queda en `✅ 100% cerrado`.
+  - Evidencia:
+    - `npx --yes tsx@4.21.0 --test integrations/git/__tests__/runPlatformGate.test.ts integrations/lifecycle/__tests__/watch.test.ts integrations/lifecycle/__tests__/cli.test.ts` -> `81 pass / 0 fail`.
+    - `npm run -s typecheck` -> `PASS`.
+
+- ✅ PUMUKI-164: Priorizar cierre SDD pendiente de RuralGo para `sync-docs` completo (3 docs canónicos por defecto + aprendizaje operativo) y dejar contrato enterprise sin ambigüedad.
+  - Resultado (2026-03-05):
+    - `integrations/sdd/syncDocs.ts` amplía targets por defecto de `sync-docs`:
+      - `docs/strategy/ruralgo-tracking-hub.md` (sección managed auto-creable),
+      - `docs/technical/08-validation/refactor/operational-summary.md` (sección managed auto-creable),
+      - `docs/validation/refactor/last-run.json` (merge JSON determinista con `pumuki_sdd_status`),
+      - manteniendo compatibilidad con target previo (`pumuki-integration-feedback.md`) y sin romper repos que no tengan esos archivos (targets opcionales por existencia).
+    - `applyManagedSection` ahora soporta `createIfMissing` (solo cuando faltan ambos markers) para evitar conflicto falso en docs canónicos nuevos.
+    - test de regresión añadido:
+      - `integrations/sdd/__tests__/syncDocs.test.ts` -> `runSddSyncDocs por defecto sincroniza 3 docs canónicos SDD cuando existen en el repo consumer`.
+    - estado RuralGo actualizado:
+      - `/Users/juancarlosmerlosalbarracin/Developer/Projects/R_GO/docs/technical/08-validation/refactor/pumuki-integration-feedback.md`
+      - bloque “Actualizar 3 docs canónicos del consumer por defecto” -> `✅ Implementado`.
+  - Evidencia:
+    - `npx --yes tsx@4.21.0 --test integrations/sdd/__tests__/syncDocs.test.ts integrations/lifecycle/__tests__/cli.test.ts` -> `59 pass / 0 fail`.
+    - `npm run -s typecheck` -> `PASS`.
+
+- ✅ PUMUKI-165: Priorizar siguiente SDD pendiente de RuralGo para auto-sync integral de artefactos OpenSpec (`tasks.md/design.md/retrospective.md`) por contrato default.
+  - Resultado (2026-03-05):
+    - `integrations/sdd/syncDocs.ts` amplía `runSddAutoSync` para incluir por defecto targets OpenSpec por cambio:
+      - `openspec/changes/<change>/tasks.md`
+      - `openspec/changes/<change>/design.md`
+      - `openspec/changes/<change>/retrospective.md`
+    - comportamiento idempotente y compatible:
+      - crea archivo si no existe (`bootstrapIfMissing`),
+      - inserta/actualiza bloque managed `AUTO_SYNC_STATUS`,
+      - no rompe consumers existentes (targets opcionales/canónicos previos se mantienen).
+    - cobertura actualizada:
+      - `runSddAutoSync dry-run orquesta sync-docs + learning sin modificar archivos` ahora valida 4 archivos sincronizados (canónico + 3 OpenSpec),
+      - `runSddAutoSync aplica sync-docs y persiste learning en modo escritura` valida creación real de `tasks/design/retrospective` con markers.
+    - estado RuralGo actualizado:
+      - `/Users/juancarlosmerlosalbarracin/Developer/Projects/R_GO/docs/technical/08-validation/refactor/pumuki-integration-feedback.md`
+      - bloque “Auto-sync integral de tasks.md/design.md/retrospective.md por defecto” -> `✅ Implementado`.
+  - Evidencia:
+    - `npx --yes tsx@4.21.0 --test integrations/sdd/__tests__/syncDocs.test.ts integrations/lifecycle/__tests__/cli.test.ts` -> `59 pass / 0 fail`.
+    - `npm run -s typecheck` -> `PASS`.
+
+- ✅ PUMUKI-166: Priorizar último pendiente SDD de RuralGo para consumo automático universal de `learning.json` por agente/orquestador.
+  - Resultado (2026-03-05):
+    - nuevo helper `integrations/sdd/learningInsights.ts` para lectura robusta de `openspec/changes/<change>/learning.json` (cambio activo) y derivación de recomendaciones accionables.
+    - integración automática en herramientas MCP:
+      - `integrations/mcp/aiGateCheck.ts`
+      - `integrations/mcp/preFlightCheck.ts`
+      - `integrations/mcp/autoExecuteAiStart.ts`
+    - salida extendida sin romper contrato:
+      - campo `learning_context` en cada tool,
+      - hints/auto_fixes/instruction enriquecidos con recomendaciones de learning cuando existen.
+    - cobertura añadida:
+      - `integrations/mcp/__tests__/aiGateCheck.test.ts` (ingesta + auto_fix learning),
+      - `integrations/mcp/__tests__/preFlightCheck.test.ts` (learning_context en preflight),
+      - `integrations/mcp/__tests__/autoExecuteAiStart.test.ts` (mensaje/instrucción con learning).
+    - estado RuralGo actualizado:
+      - `/Users/juancarlosmerlosalbarracin/Developer/Projects/R_GO/docs/technical/08-validation/refactor/pumuki-integration-feedback.md`
+      - bloque “Consumo automático universal de learning.json por cualquier agente” -> `✅ Implementado`.
+  - Evidencia:
+    - `npx --yes tsx@4.21.0 --test integrations/mcp/__tests__/aiGateCheck.test.ts integrations/mcp/__tests__/preFlightCheck.test.ts integrations/mcp/__tests__/autoExecuteAiStart.test.ts integrations/sdd/__tests__/syncDocs.test.ts integrations/lifecycle/__tests__/cli.test.ts` -> `78 pass / 0 fail`.
+    - `npm run -s typecheck` -> `PASS`.
+
+- 🚧 PUMUKI-167: Preparar release + rollout consumidor tras cierre de backlog SDD/Flux/RuralGo.
+  - Alcance:
+    - consolidar changelog de fixes/mejoras cerradas en este bloque,
+    - publicar nueva versión npm con evidencia de tests en verde,
+    - ejecutar upgrade/update en repos consumidores (`SAAS`, `R_GO`) y validar smoke mínimo post-upgrade.

package/integrations/git/runPlatformGate.ts

@@ -769,6 +769,7 @@ export async function runPlatformGate(params: {
   auditMode?: 'gate' | 'engine';
   policyTrace?: ResolvedStagePolicy['trace'];
   scope: GateScope;
+  silent?: boolean;
   sddShortCircuit?: boolean;
   services?: Partial<GateServices>;
   dependencies?: Partial<GateDependencies>;
@@ -797,7 +798,9 @@ export async function runPlatformGate(params: {
       repoRoot
     );
     if (!sddDecision.allowed) {
-      process.stdout.write(`[pumuki][sdd] ${sddDecision.code}: ${sddDecision.message}\n`);
+      if (params.silent !== true) {
+        process.stdout.write(`[pumuki][sdd] ${sddDecision.code}: ${sddDecision.message}\n`);
+      }
       sddBlockingFinding = toSddBlockingFinding(sddDecision);
       if (shouldShortCircuitSdd) {
         const emptyDetectedPlatforms: DetectedPlatforms = {};
@@ -972,16 +975,18 @@ export async function runPlatformGate(params: {
   const astIntelligenceDualFinding = astIntelligenceDualValidation?.finding;
   if (astIntelligenceDualValidation && astIntelligenceDualValidation.mode !== 'off') {
     const summary = astIntelligenceDualValidation.summary;
-    process.stdout.write(
-      `[pumuki][ast-intelligence] mode=${astIntelligenceDualValidation.mode}` +
-      ` mapped_rules=${summary.mapped_rules}` +
-      ` compared_rules=${summary.compared_rules}` +
-      ` divergences=${summary.divergences}` +
-      ` false_positives=${summary.false_positives}` +
-      ` false_negatives=${summary.false_negatives}` +
-      ` latency_ms=${summary.latency_ms}` +
-      ` languages=[${summary.languages.join(',') || 'none'}]\n`
-    );
+    if (params.silent !== true) {
+      process.stdout.write(
+        `[pumuki][ast-intelligence] mode=${astIntelligenceDualValidation.mode}` +
+        ` mapped_rules=${summary.mapped_rules}` +
+        ` compared_rules=${summary.compared_rules}` +
+        ` divergences=${summary.divergences}` +
+        ` false_positives=${summary.false_positives}` +
+        ` false_negatives=${summary.false_negatives}` +
+        ` latency_ms=${summary.latency_ms}` +
+        ` languages=[${summary.languages.join(',') || 'none'}]\n`
+      );
+    }
   }
   const degradedModeBlocks = params.policyTrace?.degraded?.action === 'block';
   const rulesCoverage = coverage
@@ -1170,9 +1175,11 @@ export async function runPlatformGate(params: {
     } catch (error) {
       const rawReason = error instanceof Error ? error.message : String(error);
       const reason = rawReason.trim().replace(/\s+/g, ' ');
-      process.stdout.write(
-        `[pumuki][memory-shadow] unavailable reason=${reason.length > 0 ? reason : 'unknown_error'}\n`
-      );
+      if (params.silent !== true) {
+        process.stdout.write(
+          `[pumuki][memory-shadow] unavailable reason=${reason.length > 0 ? reason : 'unknown_error'}\n`
+        );
+      }
     }
   }
   const memoryShadow:
@@ -1196,11 +1203,13 @@ export async function runPlatformGate(params: {
       : undefined;
 
   if (memoryShadowRecommendation) {
-    process.stdout.write(
-      `[pumuki][memory-shadow] recommended=${memoryShadowRecommendation.recommendedOutcome}` +
-      ` confidence=${memoryShadowRecommendation.confidence.toFixed(2)}` +
-      ` reasons=${memoryShadowRecommendation.reasonCodes.join(',')}\n`
-    );
+    if (params.silent !== true) {
+      process.stdout.write(
+        `[pumuki][memory-shadow] recommended=${memoryShadowRecommendation.recommendedOutcome}` +
+        ` confidence=${memoryShadowRecommendation.confidence.toFixed(2)}` +
+        ` reasons=${memoryShadowRecommendation.reasonCodes.join(',')}\n`
+      );
+    }
   }
 
   dependencies.emitPlatformGateEvidence({
@@ -1224,7 +1233,9 @@ export async function runPlatformGate(params: {
   });
 
   if (gateOutcome === 'BLOCK') {
+    if (params.silent !== true) {
     dependencies.printGateFindings(findingsWithWaiver);
+    }
     return 1;
   }
 

package/integrations/lifecycle/watch.ts

@@ -309,6 +309,7 @@ export const runLifecycleWatch = async (
           policy: resolvedPolicy.policy,
           policyTrace: resolvedPolicy.trace,
           scope: gateScope,
+          silent: true,
         });
         const evidence = activeDependencies.readEvidence(repoRoot);
         const allFindings = evidence?.snapshot.findings ?? [];

package/integrations/mcp/aiGateCheck.ts

@@ -1,4 +1,5 @@
 import { evaluateAiGate, type AiGateStage } from '../gate/evaluateAiGate';
+import { readSddLearningContext, type SddLearningContext } from '../sdd/learningInsights';
 
 const AUTO_FIX_BY_CODE: Readonly<Record<string, string>> = {
   EVIDENCE_MISSING: 'Ejecuta una auditoría para generar .ai_evidence.json.',
@@ -28,6 +29,7 @@ export type EnterpriseAiGateCheckResult = {
     violations: ReturnType<typeof evaluateAiGate>['violations'];
     warnings: ReadonlyArray<string>;
     auto_fixes: ReadonlyArray<string>;
+    learning_context: SddLearningContext | null;
     evidence: ReturnType<typeof evaluateAiGate>['evidence'];
     mcp_receipt: ReturnType<typeof evaluateAiGate>['mcp_receipt'];
     skills_contract: ReturnType<typeof evaluateAiGate>['skills_contract'];
@@ -99,7 +101,10 @@ const buildWarnings = (evaluation: ReturnType<typeof evaluateAiGate>): ReadonlyA
   return warnings;
 };
 
-const buildAutoFixes = (evaluation: ReturnType<typeof evaluateAiGate>): ReadonlyArray<string> => {
+const buildAutoFixes = (
+  evaluation: ReturnType<typeof evaluateAiGate>,
+  learningContext: SddLearningContext | null
+): ReadonlyArray<string> => {
   const fixes: string[] = [];
   const emittedCodes = new Set<string>();
   for (const violation of evaluation.violations) {
@@ -113,6 +118,11 @@ const buildAutoFixes = (evaluation: ReturnType<typeof evaluateAiGate>): Readonly
     fixes.push(fix);
     emittedCodes.add(violation.code);
   }
+  for (const recommendation of learningContext?.recommended_actions ?? []) {
+    if (!fixes.includes(recommendation)) {
+      fixes.push(recommendation);
+    }
+  }
   return fixes;
 };
 
@@ -143,8 +153,11 @@ export const runEnterpriseAiGateCheck = (params: {
   });
   const branch = evaluation.repo_state.git.branch;
   const timestamp = evaluation.evidence.source.generated_at;
+  const learningContext = readSddLearningContext({
+    repoRoot: params.repoRoot,
+  });
   const warnings = buildWarnings(evaluation);
-  const autoFixes = buildAutoFixes(evaluation);
+  const autoFixes = buildAutoFixes(evaluation, learningContext);
   const message = buildMessage(evaluation);
 
   return {
@@ -163,6 +176,7 @@ export const runEnterpriseAiGateCheck = (params: {
       violations: evaluation.violations,
       warnings,
       auto_fixes: autoFixes,
+      learning_context: learningContext,
       evidence: evaluation.evidence,
       mcp_receipt: evaluation.mcp_receipt,
       skills_contract: evaluation.skills_contract,

package/integrations/mcp/autoExecuteAiStart.ts

@@ -1,5 +1,6 @@
 import { evaluateAiGate, type AiGateStage, type AiGateViolation } from '../gate/evaluateAiGate';
 import { collectWorktreeAtomicSlices } from '../git/worktreeAtomicSlices';
+import { readSddLearningContext, type SddLearningContext } from '../sdd/learningInsights';
 
 type AutoExecuteAction = 'proceed' | 'ask';
 type AutoExecutePhase = 'GREEN' | 'RED';
@@ -154,6 +155,7 @@ export type EnterpriseAutoExecuteAiStartResult = {
     confidence_pct: number;
     reason_code: string;
     next_action: AutoExecuteNextAction;
+    learning_context: SddLearningContext | null;
     gate: {
       stage: ReturnType<typeof evaluateAiGate>['stage'];
       status: ReturnType<typeof evaluateAiGate>['status'];
@@ -174,6 +176,9 @@ export const runEnterpriseAutoExecuteAiStart = (params: {
     stage,
     requireMcpReceipt: params.requireMcpReceipt ?? false,
   });
+  const learningContext = readSddLearningContext({
+    repoRoot: params.repoRoot,
+  });
   const firstViolation = evaluation.violations[0];
   const reasonCode = firstViolation?.code ?? 'READY';
   const action: AutoExecuteAction = evaluation.allowed ? 'proceed' : 'ask';
@@ -186,12 +191,16 @@ export const runEnterpriseAutoExecuteAiStart = (params: {
     }
     : nextActionFromViolation(firstViolation, params.repoRoot);
 
-  const message = toHumanMessage({
+  let message = toHumanMessage({
     action,
     confidencePct,
     reasonCode,
   });
-  const instruction = nextAction.message;
+  let instruction = nextAction.message;
+  if (learningContext?.recommended_actions[0]) {
+    message = `${message} Learning: ${learningContext.recommended_actions[0]}`;
+    instruction = `${instruction} Learning: ${learningContext.recommended_actions[0]}`;
+  }
   const force = action === 'ask' && confidencePct < 50;
 
   return {
@@ -210,6 +219,7 @@ export const runEnterpriseAutoExecuteAiStart = (params: {
       confidence_pct: confidencePct,
       reason_code: reasonCode,
       next_action: nextAction,
+      learning_context: learningContext,
       gate: {
         stage: evaluation.stage,
         status: evaluation.status,

package/integrations/mcp/preFlightCheck.ts

@@ -1,5 +1,6 @@
 import { evaluateAiGate, type AiGateStage, type AiGateViolation } from '../gate/evaluateAiGate';
 import { collectWorktreeAtomicSlices } from '../git/worktreeAtomicSlices';
+import { readSddLearningContext, type SddLearningContext } from '../sdd/learningInsights';
 
 const ACTIONABLE_HINTS_BY_CODE: Readonly<Record<string, string>> = {
   EVIDENCE_MISSING: 'Ejecuta una auditoría (1/2/3/4) para regenerar .ai_evidence.json.',
@@ -44,6 +45,7 @@ const buildPreFlightHints = (params: {
   status: ReturnType<typeof evaluateAiGate>['status'];
   violations: ReadonlyArray<AiGateViolation>;
   upstream: string | null;
+  learningContext: SddLearningContext | null;
 }): ReadonlyArray<string> => {
   const hints: string[] = [];
   const emittedCodes = new Set<string>();
@@ -89,6 +91,14 @@ const buildPreFlightHints = (params: {
       hints.push('Corrige la causa bloqueante y vuelve a ejecutar el pre-flight.');
     }
   }
+  if (params.learningContext) {
+    hints.push(
+      `LEARNING_CONTEXT: change=${params.learningContext.change} file=${params.learningContext.path}`
+    );
+    if (params.learningContext.recommended_actions[0]) {
+      hints.push(`LEARNING_NEXT_ACTION: ${params.learningContext.recommended_actions[0]}`);
+    }
+  }
   return hints;
 };
 
@@ -111,6 +121,7 @@ export type EnterprisePreFlightCheckResult = {
     skills_contract: ReturnType<typeof evaluateAiGate>['skills_contract'];
     repo_state: ReturnType<typeof evaluateAiGate>['repo_state'];
     hints: ReadonlyArray<string>;
+    learning_context: SddLearningContext | null;
     ast_analysis: null;
     tdd_status: null;
   };
@@ -126,6 +137,9 @@ export const runEnterprisePreFlightCheck = (params: {
     stage: params.stage,
     requireMcpReceipt: params.requireMcpReceipt ?? false,
   });
+  const learningContext = readSddLearningContext({
+    repoRoot: params.repoRoot,
+  });
 
   const hints = buildPreFlightHints({
     repoRoot: params.repoRoot,
@@ -133,6 +147,7 @@ export const runEnterprisePreFlightCheck = (params: {
     status: evaluation.status,
     violations: evaluation.violations,
     upstream: evaluation.repo_state.git.upstream,
+    learningContext,
   });
   const phase: 'GREEN' | 'RED' = evaluation.allowed ? 'GREEN' : 'RED';
   const message = evaluation.allowed
@@ -161,6 +176,7 @@ export const runEnterprisePreFlightCheck = (params: {
       skills_contract: evaluation.skills_contract,
       repo_state: evaluation.repo_state,
       hints,
+      learning_context: learningContext,
       ast_analysis: null,
       tdd_status: null,
     },

package/integrations/sdd/learningInsights.ts

@@ -0,0 +1,91 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { readSddSession } from './sessionStore';
+
+type LearningArtifact = {
+  generated_at?: unknown;
+  failed_patterns?: unknown;
+  successful_patterns?: unknown;
+  rule_updates?: unknown;
+  gate_anomalies?: unknown;
+};
+
+export type SddLearningContext = {
+  change: string;
+  path: string;
+  generated_at: string | null;
+  failed_patterns: string[];
+  successful_patterns: string[];
+  rule_updates: string[];
+  gate_anomalies: string[];
+  recommended_actions: string[];
+};
+
+const toStringArray = (value: unknown): string[] => {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter((item): item is string => typeof item === 'string');
+};
+
+const toRecommendedActions = (ruleUpdates: string[]): string[] => {
+  const actions: string[] = [];
+  for (const rule of ruleUpdates) {
+    if (rule === 'evidence.bootstrap.required' || rule === 'evidence.rebuild.required') {
+      actions.push(
+        'Regenera evidencia y vuelve a validar PRE_WRITE para estabilizar el gate.'
+      );
+      continue;
+    }
+    if (rule.startsWith('ai-gate.violation.')) {
+      actions.push('Corrige la violación de gate indicada y reejecuta validate/hook.');
+      continue;
+    }
+    if (rule.startsWith('sdd.')) {
+      actions.push('Completa el contrato SDD del cambio activo antes de cerrar stage.');
+      continue;
+    }
+  }
+  return [...new Set(actions)];
+};
+
+export const readSddLearningContext = (params: {
+  repoRoot: string;
+  change?: string | null;
+}): SddLearningContext | null => {
+  const repoRoot = resolve(params.repoRoot);
+  const explicitChange = params.change?.trim().toLowerCase() ?? null;
+  const session = readSddSession(repoRoot);
+  const change = explicitChange ?? session.changeId ?? null;
+  if (!change) {
+    return null;
+  }
+
+  const relativePath = `openspec/changes/${change}/learning.json`;
+  const absolutePath = resolve(repoRoot, relativePath);
+  if (!existsSync(absolutePath)) {
+    return null;
+  }
+
+  let parsed: LearningArtifact;
+  try {
+    parsed = JSON.parse(readFileSync(absolutePath, 'utf8')) as LearningArtifact;
+  } catch {
+    return null;
+  }
+
+  const ruleUpdates = toStringArray(parsed.rule_updates);
+  return {
+    change,
+    path: relativePath,
+    generated_at:
+      typeof parsed.generated_at === 'string' && parsed.generated_at.trim().length > 0
+        ? parsed.generated_at
+        : null,
+    failed_patterns: toStringArray(parsed.failed_patterns),
+    successful_patterns: toStringArray(parsed.successful_patterns),
+    rule_updates: ruleUpdates,
+    gate_anomalies: toStringArray(parsed.gate_anomalies),
+    recommended_actions: toRecommendedActions(ruleUpdates),
+  };
+};

package/integrations/sdd/syncDocs.ts

@@ -11,6 +11,18 @@ const SDD_STATUS_SECTION = {
   end: '<!-- PUMUKI:END SDD_STATUS -->',
 } as const;
 
+const TRACKING_HUB_SECTION = {
+  id: 'pumuki-sdd-sync',
+  begin: '<!-- PUMUKI:BEGIN SDD_SYNC_STATUS -->',
+  end: '<!-- PUMUKI:END SDD_SYNC_STATUS -->',
+} as const;
+
+const OPERATIONAL_SUMMARY_SECTION = {
+  id: 'pumuki-sdd-sync',
+  begin: '<!-- PUMUKI:BEGIN SDD_SYNC_STATUS -->',
+  end: '<!-- PUMUKI:END SDD_SYNC_STATUS -->',
+} as const;
+
 type ManagedSectionSyncResult = {
   sectionId: string;
   updated: boolean;
@@ -24,11 +36,15 @@ export type SddSyncDocsManagedSection = {
   beginMarker: string;
   endMarker: string;
   renderBody: (repoRoot: string) => string;
+  createIfMissing?: boolean;
 };
 
 export type SddSyncDocsTarget = {
   path: string;
-  sections: ReadonlyArray<SddSyncDocsManagedSection>;
+  sections?: ReadonlyArray<SddSyncDocsManagedSection>;
+  renderWholeFile?: (repoRoot: string, currentSource: string) => string;
+  optional?: boolean;
+  bootstrapIfMissing?: string | ((repoRoot: string) => string);
 };
 
 export type SddSyncDocsFileResult = {
@@ -182,7 +198,51 @@ const formatSddStatusManagedBody = (repoRoot: string): string => {
   ].join('\n');
 };
 
-const DEFAULT_SYNC_DOCS_TARGETS: ReadonlyArray<SddSyncDocsTarget> = [
+const formatTrackingManagedBody = (repoRoot: string): string => {
+  const status = readSddStatus(repoRoot);
+  return [
+    `- source: pumuki sdd sync-docs`,
+    `- repo_root: ${status.repoRoot}`,
+    `- openspec_installed: ${status.openspec.installed ? 'yes' : 'no'}`,
+    `- openspec_version: ${status.openspec.version ?? 'unknown'}`,
+    `- sdd_session_active: ${status.session.active ? 'yes' : 'no'}`,
+    `- sdd_session_valid: ${status.session.valid ? 'yes' : 'no'}`,
+    `- sdd_session_change: ${status.session.changeId ?? 'none'}`,
+  ].join('\n');
+};
+
+const renderLastRunJson = (repoRoot: string, currentSource: string): string => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(currentSource);
+  } catch {
+    throw new Error('[pumuki][sdd] sync-docs invalid JSON in docs/validation/refactor/last-run.json');
+  }
+  if (parsed === null || Array.isArray(parsed) || typeof parsed !== 'object') {
+    throw new Error('[pumuki][sdd] sync-docs expected object JSON in docs/validation/refactor/last-run.json');
+  }
+
+  const status = readSddStatus(repoRoot);
+  const payload = parsed as Record<string, unknown>;
+  const next = {
+    ...payload,
+    pumuki_sdd_status: {
+      source: 'pumuki sdd sync-docs',
+      repo_root: status.repoRoot,
+      openspec_installed: status.openspec.installed,
+      openspec_version: status.openspec.version ?? null,
+      openspec_project_initialized: status.openspec.projectInitialized,
+      openspec_compatible: status.openspec.compatible,
+      session_active: status.session.active,
+      session_valid: status.session.valid,
+      session_change: status.session.changeId ?? null,
+    },
+  };
+
+  return `${JSON.stringify(next, null, 2)}\n`;
+};
+
+const PRIMARY_SYNC_DOCS_TARGETS: ReadonlyArray<SddSyncDocsTarget> = [
   {
     path: 'docs/technical/08-validation/refactor/pumuki-integration-feedback.md',
     sections: [
@@ -196,10 +256,151 @@ const DEFAULT_SYNC_DOCS_TARGETS: ReadonlyArray<SddSyncDocsTarget> = [
   },
 ];
 
+const OPTIONAL_SYNC_DOCS_TARGETS: ReadonlyArray<SddSyncDocsTarget> = [
+  {
+    path: 'docs/strategy/ruralgo-tracking-hub.md',
+    optional: true,
+    sections: [
+      {
+        id: TRACKING_HUB_SECTION.id,
+        beginMarker: TRACKING_HUB_SECTION.begin,
+        endMarker: TRACKING_HUB_SECTION.end,
+        renderBody: formatTrackingManagedBody,
+        createIfMissing: true,
+      },
+    ],
+  },
+  {
+    path: 'docs/technical/08-validation/refactor/operational-summary.md',
+    optional: true,
+    sections: [
+      {
+        id: OPERATIONAL_SUMMARY_SECTION.id,
+        beginMarker: OPERATIONAL_SUMMARY_SECTION.begin,
+        endMarker: OPERATIONAL_SUMMARY_SECTION.end,
+        renderBody: formatTrackingManagedBody,
+        createIfMissing: true,
+      },
+    ],
+  },
+  {
+    path: 'docs/validation/refactor/last-run.json',
+    optional: true,
+    renderWholeFile: renderLastRunJson,
+  },
+];
+
+const DEFAULT_SYNC_DOCS_TARGETS: ReadonlyArray<SddSyncDocsTarget> = [
+  ...PRIMARY_SYNC_DOCS_TARGETS,
+  ...OPTIONAL_SYNC_DOCS_TARGETS,
+];
+
 export const SDD_SYNC_DOCS_CANONICAL_FILES = DEFAULT_SYNC_DOCS_TARGETS.map(
   (target) => target.path
 );
 
+const resolveSyncDocsTargets = (
+  repoRoot: string,
+  targets?: ReadonlyArray<SddSyncDocsTarget>
+): ReadonlyArray<SddSyncDocsTarget> => {
+  if (targets) {
+    return targets;
+  }
+  return DEFAULT_SYNC_DOCS_TARGETS.filter((target) => {
+    if (!target.optional) {
+      return true;
+    }
+    return existsSync(resolve(repoRoot, target.path));
+  });
+};
+
+const OPENSPEC_AUTO_SYNC_SECTION = {
+  id: 'pumuki-auto-sync',
+  begin: '<!-- PUMUKI:BEGIN AUTO_SYNC_STATUS -->',
+  end: '<!-- PUMUKI:END AUTO_SYNC_STATUS -->',
+} as const;
+
+const formatOpenSpecAutoSyncBody = (params: {
+  change: string;
+  stage: SddStage | null;
+  task: string | null;
+  now: () => Date;
+}): string =>
+  [
+    `- source: pumuki sdd auto-sync`,
+    `- change: ${params.change}`,
+    `- stage: ${params.stage ?? 'none'}`,
+    `- task: ${params.task ?? 'none'}`,
+    `- updated_at: ${params.now().toISOString()}`,
+  ].join('\n');
+
+const buildOpenSpecAutoSyncTargets = (params: {
+  change: string;
+  stage: SddStage | null;
+  task: string | null;
+  now: () => Date;
+}): ReadonlyArray<SddSyncDocsTarget> => {
+  const buildDoc = (title: string): string =>
+    [
+      `# ${title}`,
+      '',
+      OPENSPEC_AUTO_SYNC_SECTION.begin,
+      '- source: bootstrap',
+      OPENSPEC_AUTO_SYNC_SECTION.end,
+      '',
+    ].join('\n');
+
+  const renderBody = () =>
+    formatOpenSpecAutoSyncBody({
+      change: params.change,
+      stage: params.stage,
+      task: params.task,
+      now: params.now,
+    });
+
+  return [
+    {
+      path: `openspec/changes/${params.change}/tasks.md`,
+      sections: [
+        {
+          id: OPENSPEC_AUTO_SYNC_SECTION.id,
+          beginMarker: OPENSPEC_AUTO_SYNC_SECTION.begin,
+          endMarker: OPENSPEC_AUTO_SYNC_SECTION.end,
+          renderBody,
+          createIfMissing: true,
+        },
+      ],
+      bootstrapIfMissing: buildDoc('Tasks'),
+    },
+    {
+      path: `openspec/changes/${params.change}/design.md`,
+      sections: [
+        {
+          id: OPENSPEC_AUTO_SYNC_SECTION.id,
+          beginMarker: OPENSPEC_AUTO_SYNC_SECTION.begin,
+          endMarker: OPENSPEC_AUTO_SYNC_SECTION.end,
+          renderBody,
+          createIfMissing: true,
+        },
+      ],
+      bootstrapIfMissing: buildDoc('Design'),
+    },
+    {
+      path: `openspec/changes/${params.change}/retrospective.md`,
+      sections: [
+        {
+          id: OPENSPEC_AUTO_SYNC_SECTION.id,
+          beginMarker: OPENSPEC_AUTO_SYNC_SECTION.begin,
+          endMarker: OPENSPEC_AUTO_SYNC_SECTION.end,
+          renderBody,
+          createIfMissing: true,
+        },
+      ],
+      bootstrapIfMissing: buildDoc('Retrospective'),
+    },
+  ];
+};
+
 const applyManagedSection = (params: {
   filePath: string;
   source: string;
@@ -207,14 +408,46 @@ const applyManagedSection = (params: {
   endMarker: string;
   renderedBody: string;
   sectionId: string;
+  createIfMissing?: boolean;
 }): {
   nextSource: string;
   result: ManagedSectionSyncResult;
 } => {
   const beginIndex = params.source.indexOf(params.beginMarker);
   const endIndex = params.source.indexOf(params.endMarker);
-
-  if (beginIndex === -1 || endIndex === -1 || endIndex < beginIndex) {
+  const missingBegin = beginIndex === -1;
+  const missingEnd = endIndex === -1;
+
+  if (missingBegin || missingEnd) {
+    if (params.createIfMissing === true && missingBegin && missingEnd) {
+      const beforeBody = '';
+      const afterBody = normalizeSectionBody(params.renderedBody);
+      const block = `${params.beginMarker}\n${params.renderedBody}\n${params.endMarker}`;
+      const sourceTrimmedEnd = params.source.replace(/\s*$/, '');
+      const nextSource =
+        sourceTrimmedEnd.length === 0
+          ? `${block}\n`
+          : `${sourceTrimmedEnd}\n\n${block}\n`;
+      return {
+        nextSource,
+        result: {
+          sectionId: params.sectionId,
+          updated: true,
+          before: beforeBody,
+          after: afterBody,
+          diffMarkdown: buildSectionDiffMarkdown({
+            sectionId: params.sectionId,
+            before: beforeBody,
+            after: afterBody,
+          }),
+        },
+      };
+    }
+    throw new Error(
+      `[pumuki][sdd] sync-docs conflict in ${params.filePath}: expected managed markers ${params.beginMarker} ... ${params.endMarker}`
+    );
+  }
+  if (endIndex < beginIndex) {
     throw new Error(
       `[pumuki][sdd] sync-docs conflict in ${params.filePath}: expected managed markers ${params.beginMarker} ... ${params.endMarker}`
     );
@@ -369,7 +602,7 @@ export const runSddSyncDocs = (params?: {
       flagName: '--from-evidence',
     })
     : null;
-  const targets = params?.targets ?? DEFAULT_SYNC_DOCS_TARGETS;
+  const targets = resolveSyncDocsTargets(repoRoot, params?.targets);
   const now = params?.now ?? (() => new Date());
   const evidenceReader =
     params?.evidenceReader ??
@@ -381,45 +614,88 @@ export const runSddSyncDocs = (params?: {
           : undefined
       ));
 
-  const updates = targets.map((target) => {
+  const updates: Array<{
+    relativePath: string;
+    absolutePath: string;
+    currentSource: string;
+    nextSource: string;
+    sections: ManagedSectionSyncResult[];
+  }> = [];
+
+  for (const target of targets) {
     const absolutePath = resolve(repoRoot, target.path);
-    if (!existsSync(absolutePath)) {
-      throw new Error(
-        `[pumuki][sdd] sync-docs missing canonical file: ${target.path}`
-      );
+    const exists = existsSync(absolutePath);
+    let currentSource = '';
+
+    if (!exists) {
+      if (target.bootstrapIfMissing !== undefined) {
+        currentSource =
+          typeof target.bootstrapIfMissing === 'function'
+            ? target.bootstrapIfMissing(repoRoot)
+            : target.bootstrapIfMissing;
+      } else if (target.optional) {
+        continue;
+      } else {
+        throw new Error(
+          `[pumuki][sdd] sync-docs missing canonical file: ${target.path}`
+        );
+      }
+    } else {
+      currentSource = readFileSync(absolutePath, 'utf8');
     }
 
-    const currentSource = readFileSync(absolutePath, 'utf8');
     let nextSource = currentSource;
     const sectionUpdates: ManagedSectionSyncResult[] = [];
 
-    for (const section of target.sections) {
-      const update = applyManagedSection({
-        filePath: target.path,
-        source: nextSource,
-        beginMarker: section.beginMarker,
-        endMarker: section.endMarker,
-        renderedBody: section.renderBody(repoRoot),
-        sectionId: section.id,
+    if (target.renderWholeFile) {
+      nextSource = target.renderWholeFile(repoRoot, nextSource);
+      sectionUpdates.push({
+        sectionId: 'file-content',
+        updated: normalizeSectionBody(currentSource) !== normalizeSectionBody(nextSource),
+        before: normalizeSectionBody(currentSource),
+        after: normalizeSectionBody(nextSource),
+        diffMarkdown: buildSectionDiffMarkdown({
+          sectionId: 'file-content',
+          before: normalizeSectionBody(currentSource),
+          after: normalizeSectionBody(nextSource),
+        }),
       });
-      nextSource = update.nextSource;
-      sectionUpdates.push(update.result);
+    } else {
+      if (!target.sections || target.sections.length === 0) {
+        throw new Error(
+          `[pumuki][sdd] sync-docs invalid target configuration for ${target.path}: expected sections or renderWholeFile`
+        );
+      }
+      for (const section of target.sections) {
+        const update = applyManagedSection({
+          filePath: target.path,
+          source: nextSource,
+          beginMarker: section.beginMarker,
+          endMarker: section.endMarker,
+          renderedBody: section.renderBody(repoRoot),
+          sectionId: section.id,
+          createIfMissing: section.createIfMissing,
+        });
+        nextSource = update.nextSource;
+        sectionUpdates.push(update.result);
+      }
     }
 
-    return {
+    updates.push({
       relativePath: target.path,
       absolutePath,
       currentSource,
       nextSource,
       sections: sectionUpdates,
-    };
-  });
+    });
+  }
 
   if (!dryRun) {
     for (const update of updates) {
-      if (update.currentSource === update.nextSource) {
+      if (update.currentSource === update.nextSource && existsSync(update.absolutePath)) {
         continue;
       }
+      mkdirSync(dirname(update.absolutePath), { recursive: true });
       writeFileSync(update.absolutePath, update.nextSource, 'utf8');
     }
   }
@@ -557,17 +833,30 @@ export const runSddAutoSync = (params?: {
   if (!change) {
     throw new Error('[pumuki][sdd] auto-sync requires --change=<change-id>.');
   }
+  const repoRoot = resolve(params?.repoRoot ?? process.cwd());
+  const now = params?.now ?? (() => new Date());
+  const targets =
+    params?.targets ??
+    [
+      ...resolveSyncDocsTargets(repoRoot),
+      ...buildOpenSpecAutoSyncTargets({
+        change,
+        stage: params?.stage ?? null,
+        task: params?.task?.trim() ? params.task.trim() : null,
+        now,
+      }),
+    ];
 
   const syncResult = runSddSyncDocs({
-    repoRoot: params?.repoRoot,
+    repoRoot,
     dryRun: params?.dryRun,
     change,
     stage: params?.stage,
     task: params?.task,
     fromEvidencePath: params?.fromEvidencePath,
-    now: params?.now,
+    now,
     evidenceReader: params?.evidenceReader,
-    targets: params?.targets,
+    targets,
   });
 
   if (!syncResult.learning) {

package/package.json

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