pumuki 6.3.69 → 6.3.71

package/README.md

@@ -37,7 +37,7 @@ npx --yes pumuki status
 npx --yes pumuki doctor --json
 ```
 
-Desde **6.3.63**, `npm install` en la raíz de un repo **Git** dispara un `postinstall` que ejecuta **`pumuki install` solo** (hooks `pre-commit` / `pre-push`, lifecycle, evidencia cuando aplica). **Pumuki no depende de ningún IDE** para el baseline: no toca `.cursor/` ni otros ficheros de editor por defecto. Desde **6.3.68**, cada hook gestionado ejecuta **`pumuki-pre-write` antes** de `pumuki-pre-commit` / `pumuki-pre-push` (stage **PRE_WRITE** vía Git). Saltar solo PRE_WRITE en hooks: `PUMUKI_SKIP_CHAINED_PRE_WRITE=1`. Desde **6.3.69**, esos mismos hooks aplican también **git-flow en ramas protegidas** (`GITFLOW_PROTECTED_BRANCH`) e **higiene de worktree** (`PUMUKI_PREWRITE_WORKTREE_*` / códigos `EVIDENCE_PREWRITE_WORKTREE_*`) cuando la evidencia es válida; el **modal macOS** de bloqueo (Desactivar / Silenciar 30 min / Mantener activas) queda **activo por defecto** si las notificaciones están habilitadas (`"blockedDialogEnabled": false` o `PUMUKI_MACOS_BLOCKED_DIALOG=0` para apagarlo). Tras install, si no existía, aparece **`.pumuki/adapter.json`** con los comandos de hooks y **MCP stdio** para referencia o para clientes que los registren manualmente. Para generar también config de IDE: **`pumuki install --with-mcp --agent=cursor`** (u otro) o **`pumuki bootstrap --enterprise --agent=…`**. Desactivar el postinstall: `PUMUKI_SKIP_POSTINSTALL=1`. En CI suele saltarse solo (`CI=true`). En **6.3.64+**, las notificaciones del sistema en plataformas sin banner nativo se reflejan en **stderr** por defecto (`PUMUKI_DISABLE_STDERR_NOTIFICATIONS=1` para silenciarlas). En **6.3.69+**, un `gate.blocked` en macOS también deja una copia en **stderr** por defecto (`PUMUKI_DISABLE_GATE_BLOCKED_STDERR_MIRROR=1` para desactivar solo eso).
+Desde **6.3.63**, `npm install` en la raíz de un repo **Git** dispara un `postinstall` que ejecuta **`pumuki install` solo** (hooks `pre-commit` / `pre-push`, lifecycle, evidencia cuando aplica). **Pumuki no depende de ningún IDE** para el baseline: no toca `.cursor/` ni otros ficheros de editor por defecto. Desde **6.3.68**, cada hook gestionado ejecuta **`pumuki-pre-write` antes** de `pumuki-pre-commit` / `pumuki-pre-push` (stage **PRE_WRITE** vía Git). Saltar solo PRE_WRITE en hooks: `PUMUKI_SKIP_CHAINED_PRE_WRITE=1`. Desde **6.3.69**, esos mismos hooks aplican también **git-flow en ramas protegidas** (`GITFLOW_PROTECTED_BRANCH`) e **higiene de worktree** (`PUMUKI_PREWRITE_WORKTREE_*` / códigos `EVIDENCE_PREWRITE_WORKTREE_*`) cuando la evidencia es válida; el **modal macOS** de bloqueo (Desactivar / Silenciar 30 min / Mantener activas) queda **activo por defecto** si las notificaciones están habilitadas (`"blockedDialogEnabled": false` o `PUMUKI_MACOS_BLOCKED_DIALOG=0` para apagarlo). Tras install, si no existía, aparece **`.pumuki/adapter.json`** con los comandos de hooks y **MCP stdio** para referencia o para clientes que los registren manualmente. Para generar también config de IDE: **`pumuki install --with-mcp --agent=cursor`** (u otro) o **`pumuki bootstrap --enterprise --agent=…`**. Desactivar el postinstall: `PUMUKI_SKIP_POSTINSTALL=1`. En CI suele saltarse solo (`CI=true`). En **6.3.64+**, las notificaciones del sistema en plataformas sin banner nativo se reflejan en **stderr** por defecto (`PUMUKI_DISABLE_STDERR_NOTIFICATIONS=1` para silenciarlas). En **6.3.69+**, un `gate.blocked` en macOS también deja una copia en **stderr** por defecto (`PUMUKI_DISABLE_GATE_BLOCKED_STDERR_MIRROR=1` para desactivar solo eso). Desde **6.3.70**, si **`.ai_evidence.json` está versionado** y **PRE_PUSH** no bloquea, ese archivo **no se reescribe** en el push (compatibilidad con **pre-commit** como hook de **pre-push**); para forzar escritura: `PUMUKI_PRE_PUSH_ALWAYS_WRITE_TRACKED_EVIDENCE=1`. Con modal de bloqueo activo, el panel interactivo prioriza foco/clics y se evita el banner duplicado.
 
 Fallback (equivalent in pasos separados):
 

package/docs/operations/RELEASE_NOTES.md

@@ -6,6 +6,20 @@ 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).
+- **macOS bloqueo**: un solo canal interactivo cuando el modal está activo (sin banner `osascript` paralelo); panel Swift más fiable para foco y clics en botones.
+- **Rollout**: `pumuki@6.3.70`, repin en monorepos (p. ej. RuralGO); `npm test` / `git push` con hooks encadenados como validación.
+
 ### 2026-04-05 (v6.3.69)
 
 - **Hooks = política de repo**: `PRE_COMMIT` / `PRE_PUSH` / `CI` / `PRE_WRITE` incorporan **`GITFLOW_PROTECTED_BRANCH`** y **higiene de worktree** (`EVIDENCE_PREWRITE_WORKTREE_*`, env `PUMUKI_PREWRITE_WORKTREE_*`) vía fusión con `evaluateAiGate` en `runPlatformGate`.

package/docs/product/CONFIGURATION.md

@@ -317,6 +317,22 @@ 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`).
+
 Codes emitted:
 
 - `EVIDENCE_PREWRITE_WORKTREE_WARN` (warning, still `ALLOWED`)

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
 
@@ -679,6 +683,7 @@ npm run toolkit:clean-artifacts -- --dry-run
 - Fails safe (`exit 1`) with guidance when no upstream is configured.
 - Evaluates `upstream..HEAD` commit range.
 - Requires valid SDD/OpenSpec status (session + active change + validation).
+- Si `.ai_evidence.json` está **versionado** en git y el resultado del gate **no** es `BLOCK` (`PASS`/`WARN`), Pumuki **no reescribe** ese archivo en disco. Así se evita que integraciones tipo `pre-commit` (p. ej. como hook de `pre-push`) fallen con “files were modified by this hook” tras un `decision=ALLOW`. El snapshot en el último commit sigue siendo el generado en `PRE_COMMIT` hasta el siguiente commit. Para forzar la escritura del snapshot `PRE_PUSH` en un fichero trackeado, usa `PUMUKI_PRE_PUSH_ALWAYS_WRITE_TRACKED_EVIDENCE=1` (puede exigir un flujo de commit/evidencia explícito).
 
 ### CI
 
@@ -706,13 +711,19 @@ Resolver source: `integrations/git/resolveGitRefs.ts`.
 
 ## Evidence output
 
-Each run writes deterministic evidence to:
+Cada ejecución del gate escribe evidencia determinista en:
 
 - `.ai_evidence.json`
 
+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/generateEvidence.test.ts

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import test from 'node:test';
 import { withTempDir } from '../__tests__/helpers/tempDir';
@@ -61,6 +61,29 @@ test('generateEvidence compone build + write y persiste .ai_evidence.json', asyn
   });
 });
 
+test('generateEvidence omite escritura a disco cuando skipDiskWrite y repoRoot son válidos', async () => {
+  await withTempDir('pumuki-generate-evidence-skip-', async (tempRoot) => {
+    initGitRepo(tempRoot);
+    const evidencePath = join(tempRoot, '.ai_evidence.json');
+    writeFileSync(evidencePath, '{"version":"2.1","pinned":true}\n', 'utf8');
+
+    const result = generateEvidence({
+      stage: 'PRE_PUSH',
+      gateOutcome: 'PASS',
+      findings: [],
+      detectedPlatforms: {},
+      loadedRulesets: [],
+      repoRoot: tempRoot,
+      skipDiskWrite: true,
+    });
+
+    assert.equal(result.evidence.snapshot.stage, 'PRE_PUSH');
+    assert.equal(result.write.ok, true);
+    assert.equal(result.write.skipped, true);
+    assert.equal(readFileSync(evidencePath, 'utf8'), '{"version":"2.1","pinned":true}\n');
+  });
+});
+
 test('generateEvidence mantiene evidencia en memoria aunque write falle', async () => {
   await withTempDir('pumuki-generate-evidence-write-error-', async (tempRoot) => {
     initGitRepo(tempRoot);

package/integrations/evidence/generateEvidence.ts

@@ -1,7 +1,10 @@
+import { join } from 'node:path';
 import { buildEvidence, type BuildEvidenceParams } from './buildEvidence';
 import type { AiEvidenceV2_1 } from './schema';
 import { writeEvidence, type WriteEvidenceResult } from './writeEvidence';
 
+const EVIDENCE_FILE_BASENAME = '.ai_evidence.json';
+
 export type GenerateEvidenceResult = {
   evidence: AiEvidenceV2_1;
   write: WriteEvidenceResult;
@@ -9,11 +12,25 @@ export type GenerateEvidenceResult = {
 
 export type GenerateEvidenceParams = BuildEvidenceParams & {
   repoRoot?: string;
+  skipDiskWrite?: boolean;
 };
 
 export const generateEvidence = (params: GenerateEvidenceParams): GenerateEvidenceResult => {
-  const { repoRoot, ...buildParams } = params;
+  const { repoRoot, skipDiskWrite, ...buildParams } = params;
   const evidence = buildEvidence(buildParams);
+  if (skipDiskWrite === true) {
+    if (typeof repoRoot !== 'string' || repoRoot.length === 0) {
+      throw new Error('generateEvidence: repoRoot is required when skipDiskWrite is true');
+    }
+    return {
+      evidence,
+      write: {
+        ok: true,
+        path: join(repoRoot, EVIDENCE_FILE_BASENAME),
+        skipped: true,
+      },
+    };
+  }
   const write = writeEvidence(evidence, { repoRoot });
   return { evidence, write };
 };

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

@@ -22,6 +22,7 @@ export type WriteEvidenceResult = {
   ok: boolean;
   path: string;
   error?: string;
+  skipped?: boolean;
 };
 
 const EVIDENCE_FILE_NAME = '.ai_evidence.json';
@@ -341,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/runPlatformGateEvidence.ts

@@ -1,6 +1,7 @@
 import type { Finding } from '../../core/gate/Finding';
 import type { GateOutcome } from '../../core/gate/GateOutcome';
 import type { GateStage } from '../../core/gate/GateStage';
+import { GitService } from './GitService';
 import { rulePackVersions } from '../../core/rules/presets/rulePackVersions';
 import type { RuleSet } from '../../core/rules/RuleSet';
 import type { SkillsRuleSetLoadResult } from '../config/skillsRuleSet';
@@ -17,14 +18,51 @@ import { normalizeSnapshotRulesCoverage } from '../evidence/rulesCoverage';
 import type { TddBddSnapshot } from '../tdd/types';
 import { emitGateTelemetryEvent } from '../telemetry/gateTelemetry';
 
+const TRACKED_EVIDENCE_RELATIVE_PATH = '.ai_evidence.json';
+
+const isTruthyEnvFlag = (value?: string): boolean => {
+  if (!value) {
+    return false;
+  }
+  const normalized = value.trim().toLowerCase();
+  return normalized === '1' || normalized === 'true' || normalized === 'yes';
+};
+
+const defaultIsEvidencePathTracked = (repoRoot: string, relativePath: string): boolean => {
+  try {
+    new GitService().runGit(['ls-files', '--error-unmatch', '--', relativePath], repoRoot);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const shouldSkipPrePushTrackedEvidenceDiskWrite = (params: {
+  stage: GateStage;
+  gateOutcome: GateOutcome;
+  repoRoot: string;
+  isEvidencePathTracked: (repoRoot: string, relativePath: string) => boolean;
+}): boolean => {
+  if (isTruthyEnvFlag(process.env.PUMUKI_PRE_PUSH_ALWAYS_WRITE_TRACKED_EVIDENCE)) {
+    return false;
+  }
+  return (
+    params.stage === 'PRE_PUSH' &&
+    params.gateOutcome !== 'BLOCK' &&
+    params.isEvidencePathTracked(params.repoRoot, TRACKED_EVIDENCE_RELATIVE_PATH)
+  );
+};
+
 export type PlatformGateEvidenceDependencies = {
   generateEvidence: typeof generateEvidence;
   emitGateTelemetryEvent: typeof emitGateTelemetryEvent;
+  isEvidencePathTracked: (repoRoot: string, relativePath: string) => boolean;
 };
 
 const defaultDependencies: PlatformGateEvidenceDependencies = {
   generateEvidence,
   emitGateTelemetryEvent,
+  isEvidencePathTracked: defaultIsEvidencePathTracked,
 };
 
 export const emitPlatformGateEvidence = (params: {
@@ -58,6 +96,12 @@ export const emitPlatformGateEvidence = (params: {
   const evaluationMetrics = normalizeSnapshotEvaluationMetrics(params.evaluationMetrics);
   const rulesCoverage = normalizeSnapshotRulesCoverage(params.stage, params.rulesCoverage);
   const repoState = captureRepoState(params.repoRoot);
+  const skipDiskWrite = shouldSkipPrePushTrackedEvidenceDiskWrite({
+    stage: params.stage,
+    gateOutcome: params.gateOutcome,
+    repoRoot: params.repoRoot,
+    isEvidencePathTracked: activeDependencies.isEvidencePathTracked,
+  });
 
   activeDependencies.generateEvidence({
     stage: params.stage,
@@ -70,6 +114,7 @@ export const emitPlatformGateEvidence = (params: {
     ...(params.tddBdd ? { tddBdd: params.tddBdd } : {}),
     ...(params.memoryShadow ? { memoryShadow: params.memoryShadow } : {}),
     repoRoot: params.repoRoot,
+    ...(skipDiskWrite ? { skipDiskWrite: true } : {}),
     previousEvidence: params.evidenceService.loadPreviousEvidence(params.repoRoot),
     detectedPlatforms: params.evidenceService.toDetectedPlatformsRecord(params.detectedPlatforms),
     loadedRulesets: params.evidenceService.buildRulesetState({

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.69",
+  "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": {

package/scripts/framework-menu-system-notifications-macos-swift-source.ts

@@ -1,6 +1,10 @@
 export const SWIFT_BLOCKED_DIALOG_SOURCE = String.raw`import AppKit
 import Foundation
 
+final class KeyableFloatingPanel: NSPanel {
+  override var canBecomeKey: Bool { true }
+}
+
 struct DialogConfig {
   let title: String
   let cause: String
@@ -108,12 +112,13 @@ final class DialogController: NSObject, NSApplicationDelegate, NSWindowDelegate
       y: screenFrame.minY + margin
     )
 
-    let panel = NSPanel(
+    let panel = KeyableFloatingPanel(
       contentRect: NSRect(x: origin.x, y: origin.y, width: width, height: height),
       styleMask: [.titled, .closable, .fullSizeContentView],
       backing: .buffered,
       defer: false
     )
+    panel.becomesKeyOnlyIfNeeded = false
     panel.level = .floating
     panel.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary]
     panel.titleVisibility = .hidden

package/scripts/framework-menu-system-notifications-macos.ts

@@ -5,7 +5,7 @@ import {
   type SystemNotificationCommandRunnerWithOutput,
   type SystemNotificationsConfig,
 } from './framework-menu-system-notifications-types';
-import { resolveBlockedDialogEnabled } from './framework-menu-system-notifications-macos-dialog';
+import { resolveBlockedDialogEnabled } from './framework-menu-system-notifications-macos-dialog-enabled';
 import { emitMacOsBannerStage } from './framework-menu-system-notifications-macos-banner-stage';
 import { emitMacOsBlockedDialogStage } from './framework-menu-system-notifications-macos-blocked-stage';
 import { finalizeMacOsNotificationDelivery } from './framework-menu-system-notifications-macos-result';
@@ -13,6 +13,21 @@ import { finalizeMacOsNotificationDelivery } from './framework-menu-system-notif
 export { runSystemCommand, runSystemCommandWithOutput } from './framework-menu-system-notifications-macos-runner';
 export { resolveBlockedDialogEnabled } from './framework-menu-system-notifications-macos-dialog';
 
+const shouldSkipMacOsBannerForInteractiveBlockedDialog = (params: {
+  event: PumukiCriticalNotificationEvent;
+  repoRoot?: string;
+  config: SystemNotificationsConfig;
+  env: NodeJS.ProcessEnv;
+}): boolean => {
+  if (params.event.kind !== 'gate.blocked') {
+    return false;
+  }
+  if (typeof params.repoRoot !== 'string') {
+    return false;
+  }
+  return resolveBlockedDialogEnabled({ env: params.env, config: params.config });
+};
+
 export const deliverMacOsNotification = (params: {
   event: PumukiCriticalNotificationEvent;
   payload: Parameters<typeof emitMacOsBannerStage>[0]['payload'];
@@ -29,11 +44,20 @@ export const deliverMacOsNotification = (params: {
     nowMs: number;
   }) => void;
 }): SystemNotificationEmitResult => {
-  const bannerResult = emitMacOsBannerStage({
-    payload: params.payload,
-    runCommand: params.runCommand,
+  const skipBanner = shouldSkipMacOsBannerForInteractiveBlockedDialog({
+    event: params.event,
+    repoRoot: params.repoRoot,
+    config: params.config,
+    env: params.env,
   });
 
+  const bannerResult = skipBanner
+    ? { delivered: true as const, reason: 'delivered' as const }
+    : emitMacOsBannerStage({
+        payload: params.payload,
+        runCommand: params.runCommand,
+      });
+
   emitMacOsBlockedDialogStage({
     event: params.event,
     repoRoot: params.repoRoot,