pumuki 6.3.49 → 6.3.51

package/integrations/git/stageRunners.ts

@@ -22,8 +22,11 @@ import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { readEvidence, readEvidenceResult } from '../evidence/readEvidence';
 import type { EvidenceReadResult } from '../evidence/readEvidence';
+import type { SnapshotFinding } from '../evidence/schema';
 import { ensureRuntimeArtifactsIgnored } from '../lifecycle/artifacts';
 import { runPolicyReconcile } from '../lifecycle/policyReconcile';
+import { isSeverityAtLeast } from '../../core/rules/Severity';
+import type { SddDecision } from '../sdd';
 
 const PRE_PUSH_UPSTREAM_REQUIRED_MESSAGE =
   'pumuki pre-push blocked: branch has no upstream tracking reference. Configure upstream first (for example: git push --set-upstream origin <branch>) and retry.';
@@ -36,11 +39,14 @@ const PRE_PUSH_UPSTREAM_MISALIGNED_AHEAD_THRESHOLD = 5;
 const PRE_COMMIT_EVIDENCE_MAX_AGE_SECONDS = 900;
 const PRE_PUSH_EVIDENCE_MAX_AGE_SECONDS = 1800;
 const DEFAULT_BLOCKED_REMEDIATION = 'Corrige la causa del bloqueo y vuelve a ejecutar el gate.';
+const EVIDENCE_FILE_PATH = '.ai_evidence.json';
 
 const BLOCKED_REMEDIATION_BY_CODE: Readonly<Record<string, string>> = {
   EVIDENCE_MISSING: 'Regenera .ai_evidence.json ejecutando una auditoría.',
   EVIDENCE_INVALID: 'Corrige/regenera .ai_evidence.json y vuelve a ejecutar el gate.',
   EVIDENCE_CHAIN_INVALID: 'Regenera evidencia para restaurar la cadena criptográfica.',
+  EVIDENCE_STAGE_SYNC_FAILED:
+    'Sincroniza la evidencia trackeada y reintenta: git add -- .ai_evidence.json && git commit --amend --no-edit',
   EVIDENCE_STALE: 'Refresca evidencia antes de continuar.',
   EVIDENCE_REPO_ROOT_MISMATCH: 'Regenera evidencia desde este mismo repositorio.',
   EVIDENCE_BRANCH_MISMATCH: 'Regenera evidencia en la rama actual y reintenta.',
@@ -102,6 +108,9 @@ type StageRunnerDependencies = {
   isQuietMode: () => boolean;
   ensureRuntimeArtifactsIgnored: (repoRoot: string) => void;
   runPolicyReconcile: typeof runPolicyReconcile;
+  isPathTracked: (repoRoot: string, relativePath: string) => boolean;
+  stagePath: (repoRoot: string, relativePath: string) => void;
+  resolveHeadOid: (repoRoot: string) => string | null;
 };
 
 const defaultDependencies: StageRunnerDependencies = {
@@ -158,6 +167,24 @@ const defaultDependencies: StageRunnerDependencies = {
     }
   },
   runPolicyReconcile,
+  isPathTracked: (repoRoot, relativePath) => {
+    try {
+      new GitService().runGit(['ls-files', '--error-unmatch', '--', relativePath], repoRoot);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  stagePath: (repoRoot, relativePath) => {
+    new GitService().runGit(['add', '--', relativePath], repoRoot);
+  },
+  resolveHeadOid: (repoRoot) => {
+    try {
+      return new GitService().runGit(['rev-parse', 'HEAD'], repoRoot).trim();
+    } catch {
+      return null;
+    }
+  },
 };
 
 const getDependencies = (
@@ -177,6 +204,14 @@ const notifyAuditSummaryForStage = (
   });
 };
 
+const resolvePrimaryBlockedStageFinding = (
+  findings: ReadonlyArray<SnapshotFinding>
+): SnapshotFinding | undefined => (
+  findings.find((finding) => {
+    return isSeverityAtLeast(finding.severity, 'ERROR');
+  }) ?? findings[0]
+);
+
 const notifyGateBlockedForStage = (params: {
   dependencies: StageRunnerDependencies;
   stage: 'PRE_COMMIT' | 'PRE_PUSH' | 'CI';
@@ -190,10 +225,10 @@ const notifyGateBlockedForStage = (params: {
     evidence?.snapshot.stage === params.stage
       ? evidence.snapshot.findings
       : [];
-  const firstStageFinding = stageFindings[0];
+  const primaryStageFinding = resolvePrimaryBlockedStageFinding(stageFindings);
   const firstViolation = evidence?.ai_gate.violations[0];
-  const causeCode = firstStageFinding?.code ?? firstViolation?.code ?? params.fallbackCauseCode;
-  const causeMessage = firstStageFinding?.message ?? firstViolation?.message ?? params.fallbackCauseMessage;
+  const causeCode = primaryStageFinding?.code ?? firstViolation?.code ?? params.fallbackCauseCode;
+  const causeMessage = primaryStageFinding?.message ?? firstViolation?.message ?? params.fallbackCauseMessage;
   const remediation =
     BLOCKED_REMEDIATION_BY_CODE[causeCode]
     ?? params.fallbackRemediation
@@ -327,12 +362,14 @@ const runHookGateAttempt = async (params: {
   dependencies: StageRunnerDependencies;
   stage: HookStage;
   scope: Parameters<typeof runPlatformGate>[0]['scope'];
+  sddDecisionOverride?: Pick<SddDecision, 'allowed' | 'code' | 'message'>;
 }): Promise<{ exitCode: number; policyTrace: HookPolicyTrace }> => {
   const resolved = params.dependencies.resolvePolicyForStage(params.stage);
   const exitCode = await params.dependencies.runPlatformGate({
     policy: resolved.policy,
     policyTrace: resolved.trace,
     scope: params.scope,
+    sddDecisionOverride: params.sddDecisionOverride,
   });
   return {
     exitCode,
@@ -345,11 +382,13 @@ const runHookGateWithPolicyRetry = async (params: {
   repoRoot: string;
   stage: HookStage;
   scope: Parameters<typeof runPlatformGate>[0]['scope'];
+  sddDecisionOverride?: Pick<SddDecision, 'allowed' | 'code' | 'message'>;
 }): Promise<{ exitCode: number; policyTrace: HookPolicyTrace }> => {
   const firstAttempt = await runHookGateAttempt({
     dependencies: params.dependencies,
     stage: params.stage,
     scope: params.scope,
+    sddDecisionOverride: params.sddDecisionOverride,
   });
   if (firstAttempt.exitCode === 0) {
     return firstAttempt;
@@ -375,9 +414,44 @@ const runHookGateWithPolicyRetry = async (params: {
     dependencies: params.dependencies,
     stage: params.stage,
     scope: params.scope,
+    sddDecisionOverride: params.sddDecisionOverride,
   });
 };
 
+const syncTrackedEvidenceAfterSuccessfulPreCommit = (params: {
+  dependencies: StageRunnerDependencies;
+  repoRoot: string;
+}): boolean => {
+  const evidenceAbsolutePath = join(params.repoRoot, EVIDENCE_FILE_PATH);
+  if (!existsSync(evidenceAbsolutePath)) {
+    return false;
+  }
+  if (!params.dependencies.isPathTracked(params.repoRoot, EVIDENCE_FILE_PATH)) {
+    return false;
+  }
+  try {
+    params.dependencies.stagePath(params.repoRoot, EVIDENCE_FILE_PATH);
+    return false;
+  } catch (error) {
+    const details = error instanceof Error ? error.message : String(error);
+    process.stderr.write(
+      `[pumuki][evidence-sync] unable to restage tracked ${EVIDENCE_FILE_PATH}: ${details}\n`
+    );
+    params.dependencies.notifyGateBlocked({
+      repoRoot: params.repoRoot,
+      stage: 'PRE_COMMIT',
+      totalViolations: 1,
+      causeCode: 'EVIDENCE_STAGE_SYNC_FAILED',
+      causeMessage:
+        `Unable to restage tracked ${EVIDENCE_FILE_PATH} after successful PRE_COMMIT gate.`,
+      remediation: BLOCKED_REMEDIATION_BY_CODE.EVIDENCE_STAGE_SYNC_FAILED
+        ?? DEFAULT_BLOCKED_REMEDIATION,
+    });
+    notifyAuditSummaryForStage(params.dependencies, 'PRE_COMMIT');
+    return true;
+  }
+};
+
 const ZERO_HASH = /^0+$/;
 
 const toEvidenceAgeSeconds = (
@@ -450,6 +524,61 @@ const shouldAllowBootstrapPrePush = (rawInput: string): boolean => {
   return false;
 };
 
+const resolveExplicitPrePushRange = (
+  rawInput: string
+): { fromRef: string; toRef: string } | undefined => {
+  const lines = rawInput
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+
+  const eligibleRanges = lines
+    .map((line) => {
+      const [localRef, localOid, remoteRef, remoteOid] = line.split(/\s+/);
+      if (!localRef || !localOid || !remoteRef || !remoteOid) {
+        return undefined;
+      }
+      const localIsDeletion = ZERO_HASH.test(localOid);
+      const remoteIsNewBranch = ZERO_HASH.test(remoteOid);
+      if (localIsDeletion || remoteIsNewBranch) {
+        return undefined;
+      }
+      return {
+        fromRef: remoteOid,
+        toRef: localOid,
+      };
+    })
+    .filter((value): value is { fromRef: string; toRef: string } => Boolean(value));
+
+  if (eligibleRanges.length !== 1) {
+    return undefined;
+  }
+
+  return eligibleRanges[0];
+};
+
+const resolveHistoricalPrePushSddOverride = (params: {
+  dependencies: StageRunnerDependencies;
+  repoRoot: string;
+  explicitPrePushRange?: { fromRef: string; toRef: string };
+}): Pick<SddDecision, 'allowed' | 'code' | 'message'> | undefined => {
+  const explicitRange = params.explicitPrePushRange;
+  if (!explicitRange) {
+    return undefined;
+  }
+  const headOid = params.dependencies.resolveHeadOid(params.repoRoot);
+  if (!headOid || explicitRange.toRef === headOid) {
+    return undefined;
+  }
+  return {
+    allowed: true,
+    code: 'ALLOWED',
+    message:
+      `SDD enforcement suspended for PRE_PUSH historical publish targeting ${explicitRange.toRef.slice(0, 12)} ` +
+      `instead of current HEAD ${headOid.slice(0, 12)}.`,
+  };
+};
+
 const PRE_PUSH_TOPIC_BRANCH_PREFIXES = [
   'feature/',
   'bugfix/',
@@ -568,6 +697,15 @@ export async function runPreCommitStage(
   ) {
     return 1;
   }
+  if (
+    result.exitCode === 0 &&
+    syncTrackedEvidenceAfterSuccessfulPreCommit({
+      dependencies: activeDependencies,
+      repoRoot,
+    })
+  ) {
+    return 1;
+  }
   emitSuccessfulHookGateSummary({
     dependencies: activeDependencies,
     stage: 'PRE_COMMIT',
@@ -594,9 +732,9 @@ export async function runPrePushStage(
   const repoRoot = activeDependencies.resolveRepoRoot();
   const manifestSnapshot = captureManifestGuardSnapshot(repoRoot);
   activeDependencies.ensureRuntimeArtifactsIgnored(repoRoot);
+  const prePushInput = activeDependencies.readPrePushStdin();
   const upstreamRef = activeDependencies.resolveUpstreamRef();
   if (!upstreamRef) {
-    const prePushInput = activeDependencies.readPrePushStdin();
     const bootstrapBaseRef = activeDependencies.resolvePrePushBootstrapBaseRef();
     const bootstrapByPrePushStdIn = shouldAllowBootstrapPrePush(prePushInput);
     const bootstrapByFallbackBase = !bootstrapByPrePushStdIn && bootstrapBaseRef !== 'HEAD';
@@ -691,6 +829,15 @@ export async function runPrePushStage(
     return 1;
   }
 
+  const explicitPrePushRange = resolveExplicitPrePushRange(prePushInput);
+  const prePushFromRef = explicitPrePushRange?.fromRef ?? upstreamRef;
+  const prePushToRef = explicitPrePushRange?.toRef ?? 'HEAD';
+  const historicalPrePushSddOverride = resolveHistoricalPrePushSddOverride({
+    dependencies: activeDependencies,
+    repoRoot,
+    explicitPrePushRange,
+  });
+
   const misalignedUpstream = detectPrePushUpstreamMisalignment({
     dependencies: activeDependencies,
     upstreamRef,
@@ -713,8 +860,8 @@ export async function runPrePushStage(
       dependencies: activeDependencies,
       repoRoot,
       stage: 'PRE_PUSH',
-      fromRef: upstreamRef,
-      toRef: 'HEAD',
+      fromRef: prePushFromRef,
+      toRef: prePushToRef,
     })
   ) {
     return 1;
@@ -726,9 +873,10 @@ export async function runPrePushStage(
     stage: 'PRE_PUSH',
     scope: {
       kind: 'range',
-      fromRef: upstreamRef,
-      toRef: 'HEAD',
+      fromRef: prePushFromRef,
+      toRef: prePushToRef,
     },
+    sddDecisionOverride: historicalPrePushSddOverride,
   });
   if (
     enforceManifestGuard({

package/integrations/lifecycle/watch.ts

@@ -365,7 +365,6 @@ export const runLifecycleWatch = async (
       params?.onTick?.(lastTick);
     } else {
       evaluations += 1;
-      const resolvedPolicy = activeDependencies.resolvePolicyForStage(stage);
       const gateScope = toGateScope(scope);
       const facts = await activeDependencies.resolveFactsForGateScope({
         scope: gateScope,
@@ -374,7 +373,9 @@ export const runLifecycleWatch = async (
       const changedFiles = collectChangedFilesFromFacts(facts);
       const evaluatedFiles = collectEvaluatedFilesFromFacts(facts);
       const scopeHasFileDelta = changedFiles.length > 0 || evaluatedFiles.length > 0;
-      const runEvaluation = async (): Promise<{
+      const runEvaluation = async (
+        resolvedPolicy: ResolvedStagePolicy
+      ): Promise<{
         gateExitCode: number;
         evidence: AiEvidenceV2_1 | undefined;
         allFindings: ReadonlyArray<SnapshotFinding>;
@@ -439,7 +440,7 @@ export const runLifecycleWatch = async (
         };
       };
 
-      let evaluation = await runEvaluation();
+      let evaluation = await runEvaluation(activeDependencies.resolvePolicyForStage(stage));
       if (autoPolicyReconcileEnabled && evaluation.gateExitCode !== 0) {
         const findingCodes = new Set<string>([
           ...evaluation.allFindings.map((finding) => finding.code),
@@ -455,7 +456,7 @@ export const runLifecycleWatch = async (
             apply: true,
           });
           if (reconcile.autofix.status === 'APPLIED') {
-            evaluation = await runEvaluation();
+            evaluation = await runEvaluation(activeDependencies.resolvePolicyForStage(stage));
           }
         }
       }

package/integrations/sdd/evidenceScaffold.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { mkdirSync, writeFileSync } from 'node:fs';
-import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, relative, resolve } from 'node:path';
 import { readEvidenceResult, type EvidenceReadResult } from '../evidence/readEvidence';
 
 export type SddEvidenceScaffoldTestStatus = 'passed' | 'failed';
@@ -80,8 +80,12 @@ const resolveRepoBoundPath = (params: {
     rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) ||
     isAbsolute(rel)
   ) {
+    const remediation =
+      params.flagName === '--test-output'
+        ? ` Try "${params.flagName}=.pumuki/runtime/${basename(params.candidatePath) || 'test-output.log'}".`
+        : '';
     throw new Error(
-      `[pumuki][sdd] ${params.flagName} must resolve inside repository root: ${params.candidatePath}`
+      `[pumuki][sdd] ${params.flagName} must resolve inside repository root: ${params.candidatePath}.${remediation}`
     );
   }
   return resolved;

package/integrations/sdd/policy.ts

@@ -24,6 +24,8 @@ const SDD_SESSION_REFRESH_COMMAND =
   'npx --yes --package pumuki@latest pumuki sdd session --refresh --ttl-minutes=90';
 const SDD_SESSION_OPEN_AUTO_COMMAND =
   'npx --yes --package pumuki@latest pumuki sdd session --open --change=auto';
+const SDD_SESSION_OPEN_EXPLICIT_COMMAND =
+  'npx --yes --package pumuki@latest pumuki sdd session --open --change=<id>';
 const SDD_COMPLETENESS_CONTRACT_VERSION = '1.0';
 
 const resolveMissingSessionGuidance = (repoRoot: string): {
@@ -49,11 +51,10 @@ const resolveMissingSessionGuidance = (repoRoot: string): {
   if (availableChangeIds.length > 1) {
     return {
       message:
-        `SDD session is not active. Run \`${SDD_SESSION_OPEN_AUTO_COMMAND}\` to auto-pick one change ` +
-        `or \`npx --yes --package pumuki@latest pumuki sdd session --open --change=<id>\` ` +
-        `for explicit selection. Active changes: ${availableChangeIds.join(', ')}.`,
-      command: SDD_SESSION_OPEN_AUTO_COMMAND,
-      fallbackCommand: SDD_SESSION_OPEN_AUTO_COMMAND,
+        `SDD session is not active. Run \`${SDD_SESSION_OPEN_EXPLICIT_COMMAND}\` ` +
+        `with one active change id. Active changes: ${availableChangeIds.join(', ')}.`,
+      command: SDD_SESSION_OPEN_EXPLICIT_COMMAND,
+      fallbackCommand: SDD_SESSION_OPEN_EXPLICIT_COMMAND,
       availableChangeIds,
     };
   }

package/package.json

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

package/scripts/adapter-readiness-markdown-next-actions-lib.ts

@@ -26,7 +26,7 @@ export const appendAdapterReadinessNextActionsSection = (params: {
   }
   if (hasAdapterRuntimeBlocker(params.source)) {
     params.lines.push(
-      '- Execute `docs/validation/adapter-hook-runtime-validation.md`, then regenerate adapter readiness report.'
+      '- Execute `docs/validation/adapter-hook-runtime-runbook.md`, then regenerate adapter readiness report.'
     );
   }
   params.lines.push('');

package/scripts/build-phase8-ready-handoff-summary.sh

@@ -41,7 +41,7 @@ GENERATED_AT="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
   echo
   echo "- [ ] Confirm reports are \`READY\`: blockers, closure-status, external-handoff, startup-unblock."
   echo "- [ ] Publish final external handoff artifacts/URLs."
-  echo "- [ ] Update \`docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md\`: mark \`P8-3\` ✅ and set \`P8-4\` 🚧."
+  echo "- [ ] Update \`docs/tracking/historico-validacion-ruralgo-03-03-2026.md\`: mark \`P8-3\` ✅ and set \`P8-4\` 🚧."
   echo "- [ ] Close \`P8-4\` once URLs are attached and handoff is complete."
   echo
   echo "## Latest Run URLs"

package/scripts/check-refactor-progress-single-active.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-FILE="${1:-docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md}"
+FILE="${1:-docs/tracking/historico-validacion-ruralgo-03-03-2026.md}"
 
 if [[ ! -f "${FILE}" ]]; then
   echo "[progress-single-active] missing file: ${FILE}" >&2

package/scripts/check-tracking-single-active.sh

@@ -1,15 +1,32 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+MASTER_FILE="docs/tracking/maestro-de-seguimiento.md"
+
+resolve_default_tracking_file() {
+  if [[ -f "${MASTER_FILE}" ]]; then
+    local active_file
+    active_file="$(
+      sed -n 's/^- Plan activo: `\([^`]*\)`.*/\1/p' "${MASTER_FILE}" | head -n 1
+    )"
+    if [[ -n "${active_file}" ]]; then
+      printf '%s\n' "${active_file}"
+      return 0
+    fi
+  fi
+
+  printf '%s\n' "docs/tracking/plan-activo-pumuki.md"
+}
+
 if [[ "$#" -gt 0 ]]; then
   FILES=("$@")
 else
   FILES=(
-    "docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md"
+    "$(resolve_default_tracking_file)"
   )
 fi
 
-ACTIVE_PATTERN='^- 🚧 `P[0-9A-Za-z.-]+` '
+ACTIVE_PATTERN='^- 🚧 (`?P[0-9A-Za-z.-]+`?)'
 HAS_ERROR=0
 
 for FILE in "${FILES[@]}"; do

package/scripts/close-phase5-escalation-submission.sh

@@ -19,7 +19,7 @@ FOLLOW_UP_ETA="$3"
 SUBMITTED_AT_UTC="${4:-$(date -u +"%Y-%m-%dT%H:%M:%SZ")}"
 
 HANDOFF_FILE="docs/validation/consumer-startup-escalation-handoff-latest.md"
-PROGRESS_FILE="docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md"
+PROGRESS_FILE="docs/tracking/historico-validacion-ruralgo-03-03-2026.md"
 TODO_FILE="docs/TODO.md"
 
 if [[ ! -f "${HANDOFF_FILE}" || ! -f "${PROGRESS_FILE}" || ! -f "${TODO_FILE}" ]]; then

package/scripts/phase5-blockers-markdown-next-actions-blocked-lib.ts

@@ -29,7 +29,7 @@ export const appendPhase5BlockersBlockedNextActions = (params: {
   }
   if (hasAdapterRuntimeBlocker(params.summary)) {
     params.lines.push(
-      '- Execute `docs/validation/adapter-hook-runtime-validation.md` in a real Adapter session and regenerate reports.'
+      '- Execute `docs/validation/adapter-hook-runtime-runbook.md` in a real Adapter session and regenerate reports.'
     );
   }
   if (hasConsumerTriageBlocker(params.summary)) {