pumuki 6.3.70 → 6.3.71

package/docs/operations/RELEASE_NOTES.md

@@ -6,6 +6,14 @@ This file keeps only the operational highlights and rollout notes that matter wh
 
 ## 2026-04 (CLI stability and macOS notifications)
 
+### 2026-04-06 (v6.3.71)
+
+- **Evidencia v2.1**: bloque `operational_hints` (`requires_second_pass`, resumen operativo, desglose por severidad de reglas). Alineado con PRE_COMMIT solo-docs + evidencia trackeada (INC-069) cuando no se re-stagea el JSON automáticamente.
+- **Monorepo**: `PUMUKI_GATE_SCOPE_PATH_PREFIXES` acota el primer alcance de hechos por prefijos de ruta.
+- **Paridad CI/local**: `pumuki doctor --parity` y fichero opcional `.pumuki/ci-parity-expected.json` (fallo con exit 1 si hay drift respecto al esperado).
+- **MCP y hooks**: mismas pistas de remediación por código de violación vía catálogo compartido.
+- **Rollout**: `pumuki@6.3.71`; repin en consumidores cuando se publique npm; validar hooks y `doctor --parity` si fijáis expectativas de CI.
+
 ### 2026-04-06 (v6.3.70)
 
 - **Consumidores con pre-commit en pre-push**: con `.ai_evidence.json` **versionado**, `PRE_PUSH` en **ALLOW/WARN** omite persistir en disco para no ensuciar el árbol tras el gate; variable `PUMUKI_PRE_PUSH_ALWAYS_WRITE_TRACKED_EVIDENCE=1` si necesitas el snapshot `PRE_PUSH` en fichero trackeado (puede exigir flujo de commit explícito).

package/docs/product/CONFIGURATION.md

@@ -317,6 +317,18 @@ Environment variables:
 - `PUMUKI_PREWRITE_WORKTREE_WARN_THRESHOLD` (default: `12`)
 - `PUMUKI_PREWRITE_WORKTREE_BLOCK_THRESHOLD` (default: `24`)
 
+## Alcance del gate por prefijos (monorepos)
+
+- `PUMUKI_GATE_SCOPE_PATH_PREFIXES`: prefijos de ruta separados por **coma** o **punto y coma** (p. ej. `apps/backend,apps/web-app`). Se normalizan barras invertidas a `/`. El **primer** conjunto de hechos del alcance del stage (p. ej. staged o rango de commits) se filtra a rutas bajo esos prefijos. Hechos sin ruta de archivo reconocible (p. ej. algunas dependencias) se conservan para no romper reglas transversales.
+
+## Paridad local vs CI (`pumuki doctor`)
+
+- Fichero opcional **`.pumuki/ci-parity-expected.json`** (commit en el repo consumer): JSON mínimo con los campos que quieras fijar, p. ej. `pumuki_package_version`, `pre_commit_policy_hash`, `pre_commit_policy_bundle`. Con `pumuki doctor --parity` (y opcionalmente `--json`), Pumuki calcula el perfil actual y, si existe el fichero esperado, rellena `parity_comparison`; cualquier desajuste hace **exit code 1**.
+
+## Evidencia en PRE_COMMIT con índice solo documentación
+
+- `PUMUKI_PRE_COMMIT_ALWAYS_RESTAGE_TRACKED_EVIDENCE` (`1|true|yes`): fuerza el `git add` automático de `.ai_evidence.json` después de un `PRE_COMMIT` exitoso aunque el índice solo contenga rutas `*.md` / `*.mdx` (además de la propia evidencia). Por defecto, en ese alcance Pumuki **no** ensarta la evidencia en el commit: el snapshot se refresca en disco y puedes decidir si lo incluyes (`git add -- .ai_evidence.json`). Cubre el caso de commits puramente documentales sin mezclar un diff grande de evidencia (p. ej. informes upstream tipo PUMUKI-INC-069).
+
 ## Evidencia en PRE_PUSH con `.ai_evidence.json` trackeado
 
 - `PUMUKI_PRE_PUSH_ALWAYS_WRITE_TRACKED_EVIDENCE` (`1|true|yes`): fuerza la escritura del snapshot en `PRE_PUSH` aunque `.ai_evidence.json` esté versionado. Por defecto (sin esta variable), si el fichero está en el índice de git y el outcome no es `BLOCK`, Pumuki **no** muta el archivo para no romper hooks encadenados (p. ej. `pre-commit` ejecutado desde `pre-push`).

package/docs/product/USAGE.md

@@ -287,6 +287,8 @@ npx --yes pumuki install --with-mcp --agent=codex
 npx --yes pumuki doctor
 # include deterministic adapter/mcp wiring health checks
 npx --yes pumuki doctor --deep --json
+# parity profile vs .pumuki/ci-parity-expected.json (CI/local alignment)
+npx --yes pumuki doctor --parity --json
 
 # show lifecycle status
 npx --yes pumuki status
@@ -671,7 +673,9 @@ npm run toolkit:clean-artifacts -- --dry-run
 
 - Reads staged changes with `git diff --cached --name-status`.
 - Builds facts from staged content.
+- Opcional: `PUMUKI_GATE_SCOPE_PATH_PREFIXES` acota el primer alcance de hechos a prefijos del monorepo (ver `docs/product/CONFIGURATION.md`).
 - Requires valid SDD/OpenSpec status (session + active change + validation).
+- Si `.ai_evidence.json` está **versionado** y el hook refresca el snapshot en disco tras un gate **no** bloqueante, por defecto Pumuki vuelve a hacer `git add` de ese fichero **salvo** que lo único en el índice (ignorando `.ai_evidence.json` / `.AI_EVIDENCE.json`) sean rutas de documentación (`*.md`, `*.mdx`). En ese caso la evidencia se actualiza en disco pero **no** se ensarta en el commit: puedes añadirla manualmente (`git add -- .ai_evidence.json`) o activar el comportamiento anterior con `PUMUKI_PRE_COMMIT_ALWAYS_RESTAGE_TRACKED_EVIDENCE=1` (ver `docs/product/CONFIGURATION.md`). En stderr (si no va en modo silencioso) verás un aviso `[pumuki][evidence-sync]`.
 
 ### PRE_PUSH
 
@@ -711,11 +715,15 @@ Cada ejecución del gate escribe evidencia determinista en:
 
 - `.ai_evidence.json`
 
-Excepción: en `PRE_PUSH`, si el fichero está trackeado y el outcome no es `BLOCK`, la escritura al path anterior se omite (ver sección PRE_PUSH arriba). La telemetría interna del gate sigue generándose; solo se evita mutar el árbol de trabajo.
+Excepciones:
+
+- En `PRE_PUSH`, si el fichero está trackeado y el outcome no es `BLOCK`, la escritura al path anterior se omite (ver sección PRE_PUSH arriba). La telemetría interna del gate sigue generándose; solo se evita mutar el árbol de trabajo.
+- En `PRE_COMMIT`, si el fichero está trackeado y el índice es solo documentación (`*.md` / `*.mdx`), el fichero puede actualizarse en disco sin auto-`git add` (ver sección PRE_COMMIT arriba).
 
 Schema and behavior:
 
 - `version: "2.1"` is the source of truth
+- `operational_hints` (opcional pero recomendado en runs recientes): `requires_second_pass` (boolean), `second_pass_reason` (string o null), `human_summary_lines` (1–4 líneas legibles), `rule_execution_breakdown` (conteos evaluated / blocking / warn / info / skipped out-of-scope). Útil para tooling y para entender el resultado sin abrir todo el snapshot.
 - `snapshot` + `ledger`
 - `platforms` and `rulesets` tracking
 - `snapshot.sdd_metrics` tracks stage-level SDD enforcement metadata

package/integrations/evidence/buildEvidence.ts

@@ -7,6 +7,7 @@ import type {
   ConsolidationSuppressedFinding,
   CompatibilityViolation,
   EvidenceLines,
+  EvidenceOperationalHints,
   HumanIntentState,
   LedgerEntry,
   PlatformState,
@@ -23,6 +24,7 @@ import { buildSnapshotPlatformSummaries } from './platformSummary';
 import { resolveHumanIntent } from './humanIntent';
 import { normalizeSnapshotEvaluationMetrics } from './evaluationMetrics';
 import { normalizeSnapshotRulesCoverage } from './rulesCoverage';
+import { buildEvidenceOperationalHints } from './operationalHints';
 
 type BuildFindingInput = Finding & {
   file?: string;
@@ -50,6 +52,9 @@ export type BuildEvidenceParams = {
   };
   sddMetrics?: SddMetrics;
   repoState?: RepoState;
+  operationalHintsExtra?: Partial<
+    Pick<EvidenceOperationalHints, 'requires_second_pass' | 'second_pass_reason'>
+  >;
 };
 
 const normalizeLines = (lines?: EvidenceLines): EvidenceLines | undefined => {
@@ -766,9 +771,19 @@ export function buildEvidence(params: BuildEvidenceParams): AiEvidenceV2_1 {
     previousEvidence: params.previousEvidence,
   });
 
+  const operational_hints = buildEvidenceOperationalHints({
+    stage: params.stage,
+    outcome,
+    findings: normalizedFindings,
+    rulesCoverage: normalizedRulesCoverage,
+    evaluationMetrics: normalizedEvaluationMetrics,
+    extra: params.operationalHintsExtra,
+  });
+
   return {
     version: '2.1',
     timestamp: now,
+    operational_hints,
     snapshot: {
       stage: params.stage,
       audit_mode: params.auditMode ?? 'gate',

package/integrations/evidence/operationalHints.ts

@@ -0,0 +1,110 @@
+import type { GateOutcome } from '../../core/gate/GateOutcome';
+import type { GateStage } from '../../core/gate/GateStage';
+import { resolveRemediationHintOrDefault } from '../gate/remediationCatalog';
+import type {
+  EvidenceOperationalHints,
+  EvidenceRuleExecutionBreakdown,
+  SnapshotEvaluationMetrics,
+  SnapshotFinding,
+  SnapshotRulesCoverage,
+} from './schema';
+
+const truncate = (value: string, max: number): string => {
+  const t = value.trim();
+  if (t.length <= max) {
+    return t;
+  }
+  return `${t.slice(0, max - 1)}…`;
+};
+
+const buildRuleExecutionBreakdown = (params: {
+  findings: ReadonlyArray<SnapshotFinding>;
+  rulesCoverage?: SnapshotRulesCoverage;
+  evaluationMetrics?: SnapshotEvaluationMetrics;
+}): EvidenceRuleExecutionBreakdown => {
+  const matched_blocking_count = params.findings.filter(
+    (f) =>
+      f.severity === 'ERROR' ||
+      f.severity === 'CRITICAL' ||
+      f.blocking === true
+  ).length;
+  const matched_warn_count = params.findings.filter((f) => f.severity === 'WARN').length;
+  const matched_info_count = params.findings.filter((f) => f.severity === 'INFO').length;
+  const evaluated_count =
+    params.rulesCoverage?.counts?.evaluated ?? params.evaluationMetrics?.evaluated_rule_ids.length ?? 0;
+  const active = params.rulesCoverage?.counts?.active ?? 0;
+  const evaluatedFromCoverage = params.rulesCoverage?.counts?.evaluated;
+  const skipped_out_of_scope_count =
+    typeof params.rulesCoverage?.counts?.unevaluated === 'number'
+      ? params.rulesCoverage.counts.unevaluated
+      : active > 0 && typeof evaluatedFromCoverage === 'number'
+        ? Math.max(0, active - evaluatedFromCoverage)
+        : 0;
+
+  return {
+    evaluated_count: Math.max(0, evaluated_count),
+    matched_blocking_count,
+    matched_warn_count,
+    matched_info_count,
+    skipped_out_of_scope_count: Math.max(0, skipped_out_of_scope_count),
+  };
+};
+
+const buildHumanSummaryLines = (params: {
+  stage: GateStage;
+  outcome: GateOutcome;
+  findings: ReadonlyArray<SnapshotFinding>;
+}): string[] => {
+  const lines: string[] = [`${params.stage}: outcome=${params.outcome}.`];
+  if (params.outcome === 'BLOCK') {
+    const blocking =
+      params.findings.find((f) => f.severity === 'CRITICAL' || f.severity === 'ERROR') ??
+      params.findings.find((f) => f.blocking === true) ??
+      params.findings[0];
+    if (blocking) {
+      lines.push(`${blocking.code}: ${truncate(blocking.message, 140)}`);
+      lines.push(resolveRemediationHintOrDefault(blocking.code));
+    }
+    return lines.slice(0, 3);
+  }
+  const warn = params.findings.find((f) => f.severity === 'WARN');
+  if (warn) {
+    lines.push(`WARN ${warn.code}: ${truncate(warn.message, 120)}`);
+  }
+  return lines.slice(0, 3);
+};
+
+export const buildEvidenceOperationalHints = (params: {
+  stage: GateStage;
+  outcome: GateOutcome;
+  findings: ReadonlyArray<SnapshotFinding>;
+  rulesCoverage?: SnapshotRulesCoverage;
+  evaluationMetrics?: SnapshotEvaluationMetrics;
+  extra?: Partial<Pick<EvidenceOperationalHints, 'requires_second_pass' | 'second_pass_reason'>>;
+}): EvidenceOperationalHints => {
+  const breakdown = buildRuleExecutionBreakdown({
+    findings: params.findings,
+    rulesCoverage: params.rulesCoverage,
+    evaluationMetrics: params.evaluationMetrics,
+  });
+  let human_summary_lines = buildHumanSummaryLines({
+    stage: params.stage,
+    outcome: params.outcome,
+    findings: params.findings,
+  });
+  if (params.extra?.requires_second_pass === true) {
+    human_summary_lines = [
+      ...human_summary_lines,
+      'La evidencia trackeada se actualizó en disco pero no entró en el índice; si debe ir en este commit: git add -- .ai_evidence.json',
+    ];
+  }
+  return {
+    requires_second_pass: params.extra?.requires_second_pass ?? false,
+    second_pass_reason:
+      params.extra?.requires_second_pass === true
+        ? (params.extra.second_pass_reason ?? null)
+        : null,
+    human_summary_lines: human_summary_lines.slice(0, 4),
+    rule_execution_breakdown: breakdown,
+  };
+};

package/integrations/evidence/schema.ts

@@ -206,10 +206,26 @@ export type EvidenceChain = {
   sequence: number;
 };
 
+export type EvidenceRuleExecutionBreakdown = {
+  evaluated_count: number;
+  matched_blocking_count: number;
+  matched_warn_count: number;
+  matched_info_count: number;
+  skipped_out_of_scope_count: number;
+};
+
+export type EvidenceOperationalHints = {
+  requires_second_pass: boolean;
+  second_pass_reason: string | null;
+  human_summary_lines: string[];
+  rule_execution_breakdown?: EvidenceRuleExecutionBreakdown;
+};
+
 export type AiEvidenceV2_1 = {
   version: '2.1';
   timestamp: string;
   evidence_chain?: EvidenceChain;
+  operational_hints?: EvidenceOperationalHints;
   snapshot: Snapshot;
   ledger: LedgerEntry[];
   platforms: Record<string, PlatformState>;

package/integrations/evidence/writeEvidence.ts

@@ -342,6 +342,9 @@ const toStableEvidence = (
   return {
     version: '2.1',
     timestamp: evidence.timestamp,
+    ...(typeof evidence.operational_hints !== 'undefined'
+      ? { operational_hints: evidence.operational_hints }
+      : {}),
     snapshot: {
       stage: evidence.snapshot.stage,
       audit_mode: normalizedAuditMode,

package/integrations/gate/remediationCatalog.ts

@@ -0,0 +1,40 @@
+export const DEFAULT_GATE_REMEDIATION =
+  'Corrige la causa del bloqueo y vuelve a ejecutar el gate.';
+
+export const REMEDIATION_HINT_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.',
+  EVIDENCE_RULES_COVERAGE_MISSING: 'Ejecuta auditoría completa para recalcular rules_coverage.',
+  EVIDENCE_RULES_COVERAGE_INCOMPLETE: 'Asegura coverage_ratio=1 y unevaluated=0.',
+  ACTIVE_RULE_IDS_EMPTY_FOR_CODE_CHANGES_HIGH:
+    'Reconcilia policy/skills y reintenta PRE_COMMIT: npx --yes --package pumuki@latest pumuki policy reconcile --strict --json && npx --yes --package pumuki@latest pumuki-pre-commit',
+  EVIDENCE_ACTIVE_RULE_IDS_EMPTY_FOR_CODE_CHANGES:
+    'Reconcilia policy/skills y revalida PRE_WRITE: npx --yes --package pumuki@latest pumuki policy reconcile --strict --json && npx --yes --package pumuki@latest pumuki sdd validate --stage=PRE_WRITE --json',
+  GITFLOW_PROTECTED_BRANCH: 'Trabaja en feature/* y evita ramas protegidas.',
+  EVIDENCE_PREWRITE_WORKTREE_OVER_LIMIT:
+    'Reduce archivos staged/unstaged por debajo del umbral (o ajusta PUMUKI_PREWRITE_WORKTREE_*); divide el trabajo en commits más pequeños.',
+  EVIDENCE_PREWRITE_WORKTREE_WARN:
+    'El worktree supera el umbral de aviso; reduce alcance antes del siguiente commit/push.',
+  PRE_PUSH_UPSTREAM_MISSING: 'Ejecuta: git push --set-upstream origin <branch>',
+  PRE_PUSH_UPSTREAM_MISALIGNED:
+    'Alinea upstream con la rama actual: git branch --unset-upstream && git push --set-upstream origin <branch>',
+  MANIFEST_MUTATION_DETECTED:
+    'Los hooks/gates no deben modificar manifests. Revisa wiring y ejecuta upgrade explícito solo cuando aplique (por ejemplo: pumuki update --latest).',
+};
+
+export const resolveRemediationHintForViolationCode = (code: string): string | undefined => {
+  const trimmed = code.trim();
+  if (trimmed.length === 0) {
+    return undefined;
+  }
+  return REMEDIATION_HINT_BY_CODE[trimmed];
+};
+
+export const resolveRemediationHintOrDefault = (code: string): string =>
+  resolveRemediationHintForViolationCode(code) ?? DEFAULT_GATE_REMEDIATION;

package/integrations/git/filterFactsByPathPrefixes.ts

@@ -0,0 +1,61 @@
+import type { Fact } from '../../core/facts/Fact';
+
+const normalizePath = (value: string): string => value.replace(/\\/g, '/').replace(/^\/+/, '');
+
+export const resolveGateScopePathPrefixesFromEnv = (): string[] => {
+  const raw = process.env.PUMUKI_GATE_SCOPE_PATH_PREFIXES?.trim();
+  if (!raw) {
+    return [];
+  }
+  return Array.from(
+    new Set(
+      raw
+        .split(/[,;]/)
+        .map((segment) => normalizePath(segment.trim()))
+        .filter((segment) => segment.length > 0)
+    )
+  ).sort((a, b) => a.localeCompare(b));
+};
+
+const primaryPathForFact = (fact: Fact): string | null => {
+  if (fact.kind === 'FileContent' || fact.kind === 'FileChange') {
+    return fact.path;
+  }
+  if (fact.kind === 'Heuristic') {
+    return fact.filePath ?? null;
+  }
+  if (fact.kind === 'Dependency') {
+    return fact.from;
+  }
+  return null;
+};
+
+const pathMatchesAnyPrefix = (path: string, prefixes: ReadonlyArray<string>): boolean => {
+  const normalized = normalizePath(path);
+  for (const prefix of prefixes) {
+    if (normalized === prefix) {
+      return true;
+    }
+    const withSlash = prefix.endsWith('/') ? prefix : `${prefix}/`;
+    if (normalized.startsWith(withSlash)) {
+      return true;
+    }
+  }
+  return false;
+};
+
+export const filterFactsByPathPrefixes = (
+  facts: ReadonlyArray<Fact>,
+  prefixes: ReadonlyArray<string>
+): Fact[] => {
+  if (prefixes.length === 0) {
+    return [...facts];
+  }
+  return facts.filter((fact) => {
+    const primary = primaryPathForFact(fact);
+    if (primary === null) {
+      return true;
+    }
+    return pathMatchesAnyPrefix(primary, prefixes);
+  });
+};

package/integrations/git/runPlatformGate.ts

@@ -35,6 +35,10 @@ import type { TddBddSnapshot } from '../tdd/types';
 import { resolveSkillsEnforcement } from '../policy/skillsEnforcement';
 import { applyTddBddEnforcement } from '../policy/tddBddEnforcement';
 import { collectAiGateRepoPolicyFindings } from './aiGateRepoPolicyFindings';
+import {
+  filterFactsByPathPrefixes,
+  resolveGateScopePathPrefixesFromEnv,
+} from './filterFactsByPathPrefixes';
 
 export type OperationalMemoryShadowRecommendation = {
   recommendedOutcome: 'ALLOW' | 'WARN' | 'BLOCK';
@@ -911,10 +915,14 @@ export async function runPlatformGate(params: {
     }
   }
 
-  const facts = await dependencies.resolveFactsForGateScope({
-    scope: params.scope,
-    git,
-  });
+  const gateScopePathPrefixes = resolveGateScopePathPrefixesFromEnv();
+  const facts = filterFactsByPathPrefixes(
+    await dependencies.resolveFactsForGateScope({
+      scope: params.scope,
+      git,
+    }),
+    gateScopePathPrefixes
+  );
   const stagedPaths = collectStagedPaths(git, repoRoot);
   const factsForPlatformEvaluation = shouldAugmentStagedSkillsContractFactsWithRepoFacts({
     scope: params.scope,

package/integrations/git/stageRunners.ts

@@ -20,7 +20,9 @@ import {
 } from '../notifications/emitAuditSummaryNotification';
 import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { buildEvidenceOperationalHints } from '../evidence/operationalHints';
 import { readEvidence, readEvidenceResult } from '../evidence/readEvidence';
+import { writeEvidence } from '../evidence/writeEvidence';
 import type { EvidenceReadResult } from '../evidence/readEvidence';
 import type { SnapshotFinding } from '../evidence/schema';
 import { ensureRuntimeArtifactsIgnored } from '../lifecycle/artifacts';
@@ -31,6 +33,10 @@ import {
   resolveGitAtomicityEnforcement,
   type GitAtomicityEnforcementResolution,
 } from '../policy/gitAtomicityEnforcement';
+import {
+  DEFAULT_GATE_REMEDIATION as DEFAULT_BLOCKED_REMEDIATION,
+  REMEDIATION_HINT_BY_CODE as BLOCKED_REMEDIATION_BY_CODE,
+} from '../gate/remediationCatalog';
 
 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.';
@@ -40,39 +46,43 @@ const PRE_PUSH_MANUAL_FALLBACK_MESSAGE =
   '[pumuki][pre-push] branch has no upstream and stdin is empty; using working-tree fallback scope.';
 const PRE_PUSH_UPSTREAM_MISALIGNED_AHEAD_THRESHOLD = 5;
 
+const isTruthyEnvFlag = (value?: string): boolean => {
+  if (!value) {
+    return false;
+  }
+  const normalized = value.trim().toLowerCase();
+  return normalized === '1' || normalized === 'true' || normalized === 'yes';
+};
+
+const isDocumentationOnlyStagedPath = (relativePath: string): boolean => {
+  const normalized = relativePath.replace(/\\/g, '/').trim();
+  if (normalized.length === 0) {
+    return false;
+  }
+  return /\.(md|mdx)$/i.test(normalized);
+};
+
+const shouldSkipRestagingTrackedEvidenceForDocumentationOnlyScope = (params: {
+  listStagedIndexPaths: (repoRoot: string) => ReadonlyArray<string>;
+  repoRoot: string;
+}): boolean => {
+  if (isTruthyEnvFlag(process.env.PUMUKI_PRE_COMMIT_ALWAYS_RESTAGE_TRACKED_EVIDENCE)) {
+    return false;
+  }
+  const paths = params.listStagedIndexPaths(params.repoRoot).filter(
+    (p) => p !== '.ai_evidence.json' && p !== '.AI_EVIDENCE.json'
+  );
+  if (paths.length === 0) {
+    return true;
+  }
+  return paths.every(isDocumentationOnlyStagedPath);
+};
+
 const PRE_COMMIT_EVIDENCE_MAX_AGE_SECONDS = 900;
 const PRE_PUSH_EVIDENCE_MAX_AGE_SECONDS = 1800;
 const HOOK_GATE_PROGRESS_REMINDER_MS = 2000;
-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.',
-  EVIDENCE_RULES_COVERAGE_MISSING: 'Ejecuta auditoría completa para recalcular rules_coverage.',
-  EVIDENCE_RULES_COVERAGE_INCOMPLETE: 'Asegura coverage_ratio=1 y unevaluated=0.',
-  ACTIVE_RULE_IDS_EMPTY_FOR_CODE_CHANGES_HIGH:
-    'Reconcilia policy/skills y reintenta PRE_COMMIT: npx --yes --package pumuki@latest pumuki policy reconcile --strict --json && npx --yes --package pumuki@latest pumuki-pre-commit',
-  EVIDENCE_ACTIVE_RULE_IDS_EMPTY_FOR_CODE_CHANGES:
-    'Reconcilia policy/skills y revalida PRE_WRITE: npx --yes --package pumuki@latest pumuki policy reconcile --strict --json && npx --yes --package pumuki@latest pumuki sdd validate --stage=PRE_WRITE --json',
-  GITFLOW_PROTECTED_BRANCH: 'Trabaja en feature/* y evita ramas protegidas.',
-  EVIDENCE_PREWRITE_WORKTREE_OVER_LIMIT:
-    'Reduce archivos staged/unstaged por debajo del umbral (o ajusta PUMUKI_PREWRITE_WORKTREE_*); divide el trabajo en commits más pequeños.',
-  EVIDENCE_PREWRITE_WORKTREE_WARN:
-    'El worktree supera el umbral de aviso; reduce alcance antes del siguiente commit/push.',
-  PRE_PUSH_UPSTREAM_MISSING: 'Ejecuta: git push --set-upstream origin <branch>',
-  PRE_PUSH_UPSTREAM_MISALIGNED:
-    'Alinea upstream con la rama actual: git branch --unset-upstream && git push --set-upstream origin <branch>',
-  MANIFEST_MUTATION_DETECTED:
-    'Los hooks/gates no deben modificar manifests. Revisa wiring y ejecuta upgrade explícito solo cuando aplique (por ejemplo: pumuki update --latest).',
-};
-
 const HOOK_POLICY_RECONCILE_CODES = new Set<string>([
   'SKILLS_PLATFORM_COVERAGE_INCOMPLETE_HIGH',
   'SKILLS_SCOPE_COMPLIANCE_INCOMPLETE_HIGH',
@@ -123,6 +133,7 @@ type StageRunnerDependencies = {
   ensureRuntimeArtifactsIgnored: (repoRoot: string) => void;
   runPolicyReconcile: typeof runPolicyReconcile;
   isPathTracked: (repoRoot: string, relativePath: string) => boolean;
+  listStagedIndexPaths: (repoRoot: string) => ReadonlyArray<string>;
   stagePath: (repoRoot: string, relativePath: string) => void;
   resolveHeadOid: (repoRoot: string) => string | null;
   resolveGitAtomicityEnforcement: () => GitAtomicityEnforcementResolution;
@@ -202,6 +213,13 @@ const defaultDependencies: StageRunnerDependencies = {
       return false;
     }
   },
+  listStagedIndexPaths: (repoRoot) => {
+    const raw = new GitService().runGit(['diff', '--cached', '--name-only'], repoRoot);
+    return raw
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0);
+  },
   stagePath: (repoRoot, relativePath) => {
     new GitService().runGit(['add', '--', relativePath], repoRoot);
   },
@@ -489,6 +507,26 @@ const runHookGateWithPolicyRetry = async (params: {
   }
 };
 
+const patchOperationalHintsAfterDocumentationOnlyEvidenceSync = (repoRoot: string): void => {
+  const evidenceRead = readEvidenceResult(repoRoot);
+  if (evidenceRead.kind !== 'valid') {
+    return;
+  }
+  const evidence = evidenceRead.evidence;
+  const hints = buildEvidenceOperationalHints({
+    stage: evidence.snapshot.stage,
+    outcome: evidence.snapshot.outcome,
+    findings: evidence.snapshot.findings,
+    rulesCoverage: evidence.snapshot.rules_coverage,
+    evaluationMetrics: evidence.snapshot.evaluation_metrics,
+    extra: {
+      requires_second_pass: true,
+      second_pass_reason: 'tracked_evidence_refreshed_on_disk_not_staged_documentation_only_commit',
+    },
+  });
+  writeEvidence({ ...evidence, operational_hints: hints }, { repoRoot });
+};
+
 const syncTrackedEvidenceAfterSuccessfulPreCommit = (params: {
   dependencies: StageRunnerDependencies;
   repoRoot: string;
@@ -500,6 +538,22 @@ const syncTrackedEvidenceAfterSuccessfulPreCommit = (params: {
   if (!params.dependencies.isPathTracked(params.repoRoot, EVIDENCE_FILE_PATH)) {
     return false;
   }
+  if (
+    shouldSkipRestagingTrackedEvidenceForDocumentationOnlyScope({
+      repoRoot: params.repoRoot,
+      listStagedIndexPaths: params.dependencies.listStagedIndexPaths,
+    })
+  ) {
+    if (!params.dependencies.isQuietMode()) {
+      process.stderr.write(
+        `[pumuki][evidence-sync] tracked ${EVIDENCE_FILE_PATH} updated on disk but not auto-staged (documentation-only staged paths: *.md / *.mdx). ` +
+          `Include in this commit if needed: git add -- ${EVIDENCE_FILE_PATH}. ` +
+          `Force previous behavior: PUMUKI_PRE_COMMIT_ALWAYS_RESTAGE_TRACKED_EVIDENCE=1\n`
+      );
+    }
+    patchOperationalHintsAfterDocumentationOnlyEvidenceSync(params.repoRoot);
+    return false;
+  }
   try {
     params.dependencies.stagePath(params.repoRoot, EVIDENCE_FILE_PATH);
     return false;

package/integrations/lifecycle/cli.ts

@@ -5,6 +5,7 @@ import { runPlatformGate } from '../git/runPlatformGate';
 import { collectWorktreeAtomicSlices } from '../git/worktreeAtomicSlices';
 import {
   doctorHasBlockingIssues,
+  doctorHasParityMismatch,
   runLifecycleDoctor,
   type LifecycleDoctorReport,
 } from './doctor';
@@ -115,6 +116,7 @@ export type ParsedArgs = {
   installMcpAgent?: AdapterAgent;
   remoteChecks?: boolean;
   doctorDeep?: boolean;
+  doctorParity?: boolean;
   sddCommand?: SddCommand;
   loopCommand?: LoopCommand;
   loopSessionId?: string;
@@ -180,7 +182,7 @@ Pumuki lifecycle commands:
   pumuki uninstall [--purge-artifacts]
   pumuki remove
   pumuki update [--latest|--spec=<package-spec>]
-  pumuki doctor [--remote-checks] [--deep] [--json]
+  pumuki doctor [--remote-checks] [--deep] [--parity] [--json]
   pumuki status [--json] [--remote-checks]
   pumuki watch [--stage=PRE_COMMIT|PRE_PUSH|CI] [--scope=workingTree|staged|repoAndStaged|repo] [--severity=critical|high|medium|low] [--interval-ms=<n>] [--notify-cooldown-ms=<n>] [--no-notify] [--once|--iterations=<n>] [--json]
   pumuki loop run --objective=<text> [--max-attempts=<n>] [--json]
@@ -567,6 +569,7 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
   let installMcpAgent: ParsedArgs['installMcpAgent'];
   let remoteChecks = false;
   let doctorDeep = false;
+  let doctorParity = false;
   let watchStage: ParsedArgs['watchStage'];
   let watchScope: ParsedArgs['watchScope'];
   let watchIntervalMs: ParsedArgs['watchIntervalMs'];
@@ -1395,6 +1398,10 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
       doctorDeep = true;
       continue;
     }
+    if (arg === '--parity') {
+      doctorParity = true;
+      continue;
+    }
     if (arg === '--purge-artifacts') {
       purgeArtifacts = true;
       continue;
@@ -1417,6 +1424,9 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
   if (doctorDeep && commandRaw !== 'doctor') {
     throw new Error(`--deep is only supported with "pumuki doctor".\n\n${HELP_TEXT}`);
   }
+  if (doctorParity && commandRaw !== 'doctor') {
+    throw new Error(`--parity is only supported with "pumuki doctor".\n\n${HELP_TEXT}`);
+  }
   if (commandRaw !== 'bootstrap' && bootstrapEnterprise) {
     throw new Error(`--enterprise is only supported with "pumuki bootstrap".\n\n${HELP_TEXT}`);
   }
@@ -1444,6 +1454,7 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
     ...(installMcpAgent ? { installMcpAgent } : {}),
     ...(remoteChecks ? { remoteChecks: true } : {}),
     ...(doctorDeep ? { doctorDeep: true } : {}),
+    ...(doctorParity ? { doctorParity: true } : {}),
   };
 };
 
@@ -1516,6 +1527,22 @@ const printDoctorReport = (
     writeInfo(`[pumuki] ${issue.severity.toUpperCase()}: ${issue.message}`);
   }
 
+  if (report.parity_profile) {
+    writeInfo(
+      `[pumuki][doctor][parity] pumuki=${report.parity_profile.pumuki_package_version} bundle=${report.parity_profile.pre_commit_policy_bundle} hash=${report.parity_profile.pre_commit_policy_hash}`
+    );
+  }
+  if (report.parity_comparison) {
+    writeInfo(
+      `[pumuki][doctor][parity] expected_file=${report.parity_comparison.expected_path} matches=${report.parity_comparison.matches ? 'yes' : 'no'}`
+    );
+    for (const mismatch of report.parity_comparison.mismatches) {
+      writeInfo(
+        `[pumuki][doctor][parity] mismatch ${mismatch.field}: expected=${mismatch.expected} actual=${mismatch.actual}`
+      );
+    }
+  }
+
   if (report.deep?.enabled) {
     for (const check of report.deep.checks) {
       writeInfo(
@@ -1527,7 +1554,8 @@ const printDoctorReport = (
     }
   }
 
-  const hasBlocking = doctorHasBlockingIssues(report);
+  const hasBlocking =
+    doctorHasBlockingIssues(report) || doctorHasParityMismatch(report);
   const hasWarnings =
     report.issues.length > 0 ||
     report.deep?.checks.some((check) => check.status !== 'pass') === true;
@@ -2225,6 +2253,7 @@ export const runLifecycleCli = async (
       case 'doctor': {
         const report = runLifecycleDoctor({
           deep: parsed.doctorDeep === true,
+          parity: parsed.doctorParity === true,
         });
         const remoteCiDiagnostics = parsed.remoteChecks
           ? activeDependencies.collectRemoteCiDiagnostics({
@@ -2247,7 +2276,7 @@ export const runLifecycleCli = async (
         } else {
           printDoctorReport(report, remoteCiDiagnostics);
         }
-        return doctorHasBlockingIssues(report) ? 1 : 0;
+        return doctorHasBlockingIssues(report) || doctorHasParityMismatch(report) ? 1 : 0;
       }
       case 'status': {
         const status = readLifecycleStatus();

package/integrations/lifecycle/doctor.ts

@@ -69,6 +69,22 @@ export type DoctorCompatibilityContract = {
   };
 };
 
+export type DoctorParityProfile = {
+  schema_version: '1';
+  pumuki_package_version: string;
+  pre_commit_policy_bundle: string;
+  pre_commit_policy_hash: string;
+  pre_commit_policy_signature: string | null;
+  pre_commit_policy_version: string | null;
+  skills_policy_present: boolean;
+};
+
+export type DoctorParityComparison = {
+  expected_path: string;
+  matches: boolean;
+  mismatches: ReadonlyArray<{ field: string; expected: string; actual: string }>;
+};
+
 export type LifecycleDoctorReport = {
   repoRoot: string;
   packageVersion: string;
@@ -81,6 +97,8 @@ export type LifecycleDoctorReport = {
   policyValidation: LifecyclePolicyValidationSnapshot;
   issues: ReadonlyArray<DoctorIssue>;
   deep?: DoctorDeepReport;
+  parity_profile?: DoctorParityProfile;
+  parity_comparison?: DoctorParityComparison;
 };
 
 const buildDoctorIssues = (params: {
@@ -698,10 +716,87 @@ const buildDoctorDeepReport = (params: {
   };
 };
 
+const buildDoctorParityProfile = (params: {
+  repoRoot: string;
+  packageVersion: string;
+}): DoctorParityProfile => {
+  const policy = resolvePolicyForStage('PRE_COMMIT', params.repoRoot);
+  const skillsPolicyPath = join(params.repoRoot, 'skills.policy.json');
+  return {
+    schema_version: '1',
+    pumuki_package_version: params.packageVersion,
+    pre_commit_policy_bundle: policy.trace.bundle,
+    pre_commit_policy_hash: policy.trace.hash,
+    pre_commit_policy_signature: policy.trace.signature ?? null,
+    pre_commit_policy_version: policy.trace.version ?? null,
+    skills_policy_present: existsSync(skillsPolicyPath),
+  };
+};
+
+const compareDoctorParityProfile = (params: {
+  repoRoot: string;
+  actual: DoctorParityProfile;
+}): DoctorParityComparison | undefined => {
+  const expectedPath = join(params.repoRoot, '.pumuki', 'ci-parity-expected.json');
+  if (!existsSync(expectedPath)) {
+    return undefined;
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(expectedPath, 'utf8')) as unknown;
+  } catch {
+    return {
+      expected_path: expectedPath,
+      matches: false,
+      mismatches: [
+        {
+          field: 'ci-parity-expected.json',
+          expected: 'valid-json',
+          actual: 'parse-error',
+        },
+      ],
+    };
+  }
+  if (!isRecord(raw)) {
+    return {
+      expected_path: expectedPath,
+      matches: false,
+      mismatches: [{ field: 'root', expected: 'object', actual: 'non-object' }],
+    };
+  }
+  const mismatches: Array<{ field: string; expected: string; actual: string }> = [];
+  const expectField = (field: string, expected: unknown, actual: string) => {
+    if (typeof expected === 'string' && expected.trim().length > 0 && expected !== actual) {
+      mismatches.push({ field, expected, actual });
+    }
+  };
+  expectField(
+    'pumuki_package_version',
+    raw.pumuki_package_version,
+    params.actual.pumuki_package_version
+  );
+  expectField(
+    'pre_commit_policy_hash',
+    raw.pre_commit_policy_hash,
+    params.actual.pre_commit_policy_hash
+  );
+  expectField(
+    'pre_commit_policy_bundle',
+    raw.pre_commit_policy_bundle,
+    params.actual.pre_commit_policy_bundle
+  );
+  return {
+    expected_path: expectedPath,
+    matches: mismatches.length === 0,
+    mismatches,
+  };
+};
+
 export const runLifecycleDoctor = (params?: {
   cwd?: string;
   git?: ILifecycleGitService;
   deep?: boolean;
+  parity?: boolean;
 }): LifecycleDoctorReport => {
   const git = params?.git ?? new LifecycleGitService();
   const cwd = params?.cwd ?? process.cwd();
@@ -730,6 +825,18 @@ export const runLifecycleDoctor = (params?: {
     lifecycleVersion: lifecycleState.version,
   });
 
+  const parity_profile =
+    params?.parity === true
+      ? buildDoctorParityProfile({
+        repoRoot,
+        packageVersion: version.effective,
+      })
+      : undefined;
+  const parity_comparison =
+    typeof parity_profile !== 'undefined'
+      ? compareDoctorParityProfile({ repoRoot, actual: parity_profile })
+      : undefined;
+
   return {
     repoRoot,
     packageVersion: version.effective,
@@ -742,8 +849,13 @@ export const runLifecycleDoctor = (params?: {
     policyValidation: readLifecyclePolicyValidationSnapshot(repoRoot),
     issues,
     deep,
+    parity_profile,
+    parity_comparison,
   };
 };
 
 export const doctorHasBlockingIssues = (report: LifecycleDoctorReport): boolean =>
   report.issues.some((issue) => issue.severity === 'error') || report.deep?.blocking === true;
+
+export const doctorHasParityMismatch = (report: LifecycleDoctorReport): boolean =>
+  typeof report.parity_comparison !== 'undefined' && report.parity_comparison.matches === false;

package/integrations/mcp/aiGateCheck.ts

@@ -1,17 +1,8 @@
 import { evaluateAiGate, type AiGateStage } from '../gate/evaluateAiGate';
+import { resolveRemediationHintForViolationCode } from '../gate/remediationCatalog';
 import { resolveLearningContextExperimentalFeature } from '../policy/experimentalFeatures';
 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.',
-  EVIDENCE_INVALID: 'Regenera .ai_evidence.json y vuelve a evaluar.',
-  EVIDENCE_STALE: 'Refresca evidencia antes de continuar.',
-  EVIDENCE_BRANCH_MISMATCH: 'Regenera evidencia en la rama actual.',
-  EVIDENCE_REPO_ROOT_MISMATCH: 'Regenera evidencia desde este repositorio.',
-  PRE_PUSH_UPSTREAM_MISSING: 'Ejecuta git push --set-upstream origin <branch>.',
-  GITFLOW_PROTECTED_BRANCH: 'Crea una rama feature/* y mueve el trabajo allí.',
-};
-
 const PROTECTED_BRANCHES = new Set(['main', 'master', 'develop', 'dev']);
 
 export type EnterpriseAiGateCheckResult = {
@@ -112,7 +103,7 @@ const buildAutoFixes = (
     if (emittedCodes.has(violation.code)) {
       continue;
     }
-    const fix = AUTO_FIX_BY_CODE[violation.code];
+    const fix = resolveRemediationHintForViolationCode(violation.code);
     if (!fix) {
       continue;
     }

package/package.json

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