pumuki 6.3.37 → 6.3.39

package/VERSION

@@ -1 +1 @@
-v6.3.37
+v6.3.39

package/docs/README.md

@@ -5,7 +5,7 @@ Canonical index for active Pumuki documentation.
 ## Seguimiento Activo (único)
 
 - Maestro: `docs/registro-maestro-de-seguimiento.md`
-- Plan activo: `docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md`
+- Plan activo: `docs/seguimiento-activo-pumuki-saas-supermercados.md`
 - Política: una sola tarea en construcción (`🚧`) en el plan activo.
 
 ## Product and Architecture

package/docs/RELEASE_NOTES.md

@@ -5,6 +5,59 @@ Detailed commit history remains available through Git history (`git log` / `git
 
 ## 2026-03 (enterprise hardening updates)
 
+### 2026-03-04 (v6.3.39)
+
+- Adapter/runtime bootstrap hardening:
+  - adapter-generated hooks/CI templates now use `npx --yes --package pumuki@latest ...` for deterministic command resolution in consumer repos.
+- Git-range robustness:
+  - commit-range facts now guard unresolved refs (`rev-parse --verify`) and avoid ambiguous failures on repos without `HEAD`.
+- Cross-platform critical enforcement:
+  - gate now blocks when a detected platform does not have critical (`CRITICAL/ERROR`) skills rules active/evaluated.
+  - finding id: `governance.skills.cross-platform-critical.incomplete`.
+- Git atomicity by default:
+  - atomicity guard is enabled by default in core gate flow (`PRE_COMMIT/PRE_PUSH/CI`).
+  - keeps env/config overrides for enterprise tuning without patching source.
+- Versioned hooks diagnostics hardening (`core.hooksPath`):
+  - lifecycle hook resolution now includes fallback to local `.git/config` (`core.hooksPath`) when `git rev-parse --git-path hooks` is unavailable.
+  - `status/doctor` now expose effective hook path metadata (`hooksDirectory`, `hooksDirectoryResolution`) and print it in human-readable mode.
+- Validation hardening:
+  - `test:stage-gates` stabilized and green with current contracts (`1020 pass / 0 fail / 4 skip`).
+  - fixtures aligned to evidence v2.1 (`evidence_chain`, `evidence.source`) and architecture guardrail overrides updated for `integrations/lifecycle/cli.ts`.
+- Traceability:
+  - commits: `104fc92`, `2f175ec`, `da7b073`, `2c40a4c`, `b124599`, `2aeb435`
+- Consumer quick verification:
+  - `npx --yes --package pumuki@latest pumuki status --json`
+  - `npx --yes --package pumuki@latest pumuki doctor --json`
+  - `npm run -s typecheck`
+  - `npm run -s test:stage-gates`
+
+### 2026-03-04 (v6.3.38)
+
+- Blocked notification UX hardening for macOS:
+  - short, human-readable Spanish banner (`🔴 Pumuki bloqueado`) with stage + summarized cause.
+  - remediation-first body (`Solución: ...`) to maximize visibility in truncated notification banners.
+- Optional blocked-dialog workflow (`PUMUKI_MACOS_BLOCKED_DIALOG=1`):
+  - full cause/remediation modal for critical blocks.
+  - anti-spam controls in dialog:
+    - `Mantener activas`
+    - `Silenciar 30 min`
+    - `Desactivar`
+  - `giving up after 15` timeout to avoid local execution hangs.
+- Notification delivery contract update:
+  - config supports `muteUntil` in `.pumuki/system-notifications.json`.
+  - delivery result now reports `reason=muted` while silence window is active.
+- Regression baseline alignment:
+  - `integrations/git/__tests__/stageRunners.test.ts` updated to run with core skills enabled in test harness, matching current gate contract and eliminating false failures.
+- Traceability:
+  - commits: `2f957a2`, `ceb1849`, `98fc108`, `ae90f31`
+- Consumer quick verification:
+  - `npx --yes tsx@4.21.0 --test scripts/__tests__/framework-menu-system-notifications.test.ts`
+  - `npx --yes tsx@4.21.0 --test integrations/git/__tests__/stageRunners.test.ts`
+  - `PUMUKI_MACOS_BLOCKED_DIALOG=1 npx --yes tsx@4.21.0 -e "import { emitSystemNotification } from './scripts/framework-menu-system-notifications-lib'; console.log(JSON.stringify(emitSystemNotification({ repoRoot: process.cwd(), event: { kind: 'gate.blocked', stage: 'PRE_COMMIT', totalViolations: 1, causeCode: 'BACKEND_AVOID_EXPLICIT_ANY', causeMessage: 'Avoid explicit any in backend code.', remediation: 'Tipa el valor y elimina any explícito en backend.' } })));"`
+  - expected signal:
+    - banner appears with concise remediation text,
+    - optional dialog appears with anti-spam actions when flag is enabled.
+
 ### 2026-03-04 (v6.3.37)
 
 - Policy-as-code enterprise hardening shipped:

package/docs/registro-maestro-de-seguimiento.md

@@ -5,14 +5,15 @@
 - Referenciar un único plan activo con fases, tasks y leyenda.
 
 ## Estado actual
-- Plan activo: `docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md`
-- Estado del plan: EN CURSO
-- Última task cerrada (`✅`): `P12.F2.T72` (hardening `policy-as-code` completado: issue `#606` cerrada con PR `#608`).
-- Task activa (`🚧`): `P12.F2.T73` (preparar/publicar release incremental con el hardening de `#606`).
+- Plan activo: `docs/seguimiento-activo-pumuki-saas-supermercados.md`
+- Estado del plan: EJECUCION
+- Última task cerrada (`✅`): PUMUKI-019 (hardening de diagnóstico para hooks versionados `core.hooksPath` con fallback robusto + cobertura de no-regresión).
+- Task activa (`🚧`): PUMUKI-020 (publicación del siguiente corte tras cierre de PUMUKI-019).
+- Nuevos pendientes añadidos (`⏳`): ninguno en este bloque inmediato.
 
 ## Historial resumido
-- No se mantienen MDs históricos de seguimiento en este repositorio.
-- La trazabilidad histórica relevante debe consolidarse dentro del plan activo o en documentación oficial no temporal.
+- Bloque RuralGO cerrado: `docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md`.
+- Se inicia bloque SAAS_SUPERMERCADOS con plan activo único y legible.
 
 ## Regla de operación
 - Debe existir exactamente una task `🚧` en el plan activo.

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

@@ -0,0 +1,129 @@
+# Plan Activo Pumuki SAAS Supermercados
+
+## Leyenda
+
+- ✅ Cerrado
+- 🚧 En construccion (maximo 1)
+- ⏳ Pendiente
+- ⛔ Bloqueado
+
+## Objetivo
+
+- Resolver e implementar bugs y mejoras reportados en:
+  - `/Users/juancarlosmerlosalbarracin/Developer/Projects/SAAS:APP_SUPERMERCADOS/docs/pumuki/PUMUKI_BUGS_MEJORAS.md`
+- Mantener trazabilidad: hallazgo -> fix -> test -> release notes.
+
+## Fase 0. Intake y priorizacion
+
+- ✅ Consolidar hallazgos y deduplicar causas raiz del MD canónico.
+- ✅ Priorizar por impacto inicial:
+  - P1: `PUMUKI-001`, `PUMUKI-003`, `PUMUKI-005`, `PUMUKI-007`
+  - P2: `PUMUKI-002`, `PUMUKI-004`, `PUMUKI-006`
+
+## Fase 1. Bugs P1 (ejecucion tecnica)
+
+- ✅ PUMUKI-001: Compatibilidad de receipt MCP entre stages (`PRE_WRITE` vs `PRE_COMMIT`) sin bloqueo falso.
+- ✅ PUMUKI-003: Endurecer resolución de binarios en hooks/scripts para evitar `command not found`.
+- ✅ PUMUKI-005: Soporte robusto para repos con `:` en path (evitar dependencia frágil de PATH).
+- ✅ PUMUKI-007: Soportar repos sin commits (`HEAD` ausente) sin error ambiguo.
+
+## Fase 2. Mejoras P2
+
+- ✅ PUMUKI-002: Rule-pack opcional de atomicidad Git + trazabilidad de commit message.
+- ✅ PUMUKI-004: Mejorar diagnóstico de hooks efectivos en escenarios versionados/custom.
+- ✅ PUMUKI-006: Alinear `package_version` reportada por MCP con versión local efectiva del repo consumidor.
+
+## Fase 2.1 Paridad legacy (CLI vs MCP) en SAAS_SUPERMERCADOS
+
+- ✅ PUMUKI-008: Feedback iterativo en chat no equivalente a flujo legacy.
+  - Evidencia: en ejecución MCP no aparece feedback operativo por iteración del modelo como en el grafo legacy.
+  - Esperado: resumen corto y humano en cada iteración (`stage`, `decision`, `next_action`).
+  - Entregable: tool MCP de pre-flight para chat con salida estable y accionable.
+- ✅ PUMUKI-009: Desalineación operativa entre `ai_gate_check` y `pre_flight_check`.
+  - Evidencia: `ai_gate_check => BLOCKED (EVIDENCE_STALE)` mientras `pre_flight_check => allowed=true`.
+  - Esperado: criterio homogéneo o explicación explícita y trazable de por qué uno bloquea y el otro permite.
+  - Entregable: decisión unificada desde el mismo evaluador/política.
+- ✅ PUMUKI-010: Respuesta no accionable en `auto_execute_ai_start` para confianza media.
+  - Evidencia: `success=true`, `action=ask`, `message=Medium confidence (undefined%)...`.
+  - Esperado: `next_action` determinista + confidence numérico consistente + remediación concreta.
+  - Entregable: contrato MCP estable (`confidence_pct`, `reason_code`, `next_action`).
+- ✅ PUMUKI-011: Notificación macOS obligatoria en cualquier bloqueo de gate/fase.
+  - Requisito hard: cuando Pumuki bloquee (`PRE_WRITE`, `PRE_COMMIT`, `PRE_PUSH`, `CI`), lanzar notificación nativa macOS con sonido.
+  - Contenido mínimo: `🔴 BLOQUEADO`, causa exacta (`code + message`) y `cómo solucionarlo` (`next_action`).
+  - Entregable: comportamiento consistente en CLI, hooks y herramientas MCP con formato humano.
+  - Ajuste UX (2026-03-04): mensaje corto y legible para humanos.
+  - Nuevo formato: subtítulo con causa resumida + cuerpo iniciando por `Solución: ...` para que no se corte la remediación.
+  - ✅ PoC (2026-03-04): modo opcional de diálogo completo para bloqueo en macOS con `PUMUKI_MACOS_BLOCKED_DIALOG=1` (banner corto + modal con causa/solución completas).
+  - ✅ PoC anti-spam (2026-03-04): diálogo con acciones de control (`Mantener activas`, `Silenciar 30 min`, `Desactivar`) + timeout automático de 15s para no bloquear flujo.
+
+## Decisión de producto (hard)
+
+- La automatización es obligatoria: minimizar pasos manuales en bootstrap, pre-flight, gate y remediación.
+- Objetivo operativo: que instalación + wiring de agente dejen el flujo listo para ejecutar y reportar bloqueos sin intervención manual extra.
+
+## Aclaración operativa (para no perderse)
+
+- CLI: lo ejecutan hooks Git (`pre-commit`, `pre-push`) y comandos manuales (`pumuki ...`).
+- MCP: lo consume el agente/herramienta (Codex/Cursor/Windsurf...) cuando está configurado.
+- `pumuki install`: instala hooks Git y bootstrap base.
+- `pumuki adapter install --agent=<...>`: cablea hooks de agente + servidores MCP en el entorno del agente.
+
+## Fase 3. Cierre
+
+- ✅ Ejecutar suite de tests de regresión afectada.
+  - Evidencia (2026-03-04): `npx --yes tsx@4.21.0 --test scripts/__tests__/framework-menu-system-notifications.test.ts integrations/git/__tests__/stageRunners.test.ts integrations/lifecycle/__tests__/lifecycle.test.ts` -> `44 pass / 0 fail`.
+- ✅ Actualizar `CHANGELOG.md` y `docs/RELEASE_NOTES.md` con fixes reales.
+  - Evidencia (2026-03-04): se documenta en `6.3.38` (CHANGELOG) y en `v6.3.38` (RELEASE_NOTES) el paquete de mejoras `PUMUKI-011` + baseline test alignment.
+- ✅ Publicar versión cuando las tareas en construcción/pending críticas estén cerradas.
+  - Evidencia (2026-03-04): `npm publish --access public` => `+ pumuki@6.3.38` y verificación remota `npm view pumuki version` => `6.3.38`.
+
+## Fase 4. Post-release
+
+- ✅ Monitorizar feedback de repos consumidores y registrar nuevos hallazgos canónicos.
+  - Evidencia (2026-03-04): se activa nuevo frente real en consumer repo con backlog dedicado en `/Users/juancarlosmerlosalbarracin/Developer/Projects/SAAS:APP_SUPERMERCADOS/docs/pumuki/PUMUKI_BUGS_MEJORAS.md`.
+- ✅ Priorizar nuevos bugs/mejoras y abrir siguiente ciclo de implementación.
+  - Evidencia (2026-03-04): ciclo técnico arrancado en `ast-intelligence-hooks` con ejecución sobre bugs reales reportados desde SAAS.
+
+## Fase 4.1 Ciclo técnico actual (core Pumuki)
+
+- ✅ PUMUKI-012: Endurecer comandos de adapter templates para hooks/CI sin dependencia frágil de `./node_modules/.bin`.
+  - Fix: `integrations/lifecycle/adapter.templates.json` ahora usa `npx --yes --package pumuki@latest ...` en `pre_write/pre_commit/pre_push/ci`.
+  - Test: `integrations/lifecycle/__tests__/adapter.test.ts`, `integrations/lifecycle/__tests__/doctor.test.ts`, `integrations/lifecycle/__tests__/cli.test.ts`.
+- ✅ PUMUKI-013: Blindar resolución de rango Git cuando `HEAD`/refs no son resolubles (repos sin commits o refs ambiguas).
+  - Fix: `integrations/git/getCommitRangeFacts.ts` añade guardas `rev-parse --verify` + fallback seguro sin crash.
+  - Test: `integrations/git/__tests__/getCommitRangeFacts.test.ts` (nuevo caso repo sin commits) y `integrations/git/__tests__/runPlatformGateFacts.test.ts`.
+- ✅ PUMUKI-014: Enforcement crítico transversal por plataforma (sin huecos entre skills activas y evaluación real).
+  - Fix: `integrations/git/runPlatformGate.ts` incorpora `governance.skills.cross-platform-critical.incomplete` y bloquea cuando una plataforma detectada no tiene reglas críticas (`CRITICAL/ERROR`) activas/evaluadas.
+  - Test: `integrations/git/__tests__/runPlatformGate.test.ts` añade casos de bloqueo/allow para cobertura crítica multi-plataforma.
+- ✅ PUMUKI-015: Ejecutar validación extendida de no-regresión (suite stage-gates focal + smoke de hooks) y cerrar trazabilidad final de este bloque crítico.
+  - Evidencia (2026-03-04): `npm run -s test:stage-gates` -> `1018 pass / 0 fail / 4 skip`.
+  - Fixes incluidos para estabilizar la suite:
+    - `integrations/lifecycle/__tests__/saasIngestionBuilder.test.ts` (fixture de evidencia v2.1 con `evidence_chain` válido).
+    - `scripts/__tests__/framework-menu-consumer-preflight.test.ts` (contrato `evidence.source` completo en fixtures).
+    - `scripts/__tests__/architecture-file-size-guardrails.test.ts` (override explícito para `integrations/lifecycle/cli.ts` en límites de líneas/imports).
+- ✅ PUMUKI-016: Preparar release notes del siguiente corte con trazabilidad de commits y validación ejecutada.
+  - Evidencia (2026-03-04):
+    - `CHANGELOG.md` actualizado en `[Unreleased]` con `adapter hooks`, `commit-range` y `cross-platform critical enforcement`.
+    - `docs/RELEASE_NOTES.md` actualizado con bloque `next cut candidate, post v6.3.38`.
+- ✅ PUMUKI-017: Ejecutar siguiente bug/mejora del backlog SAAS (`PUMUKI-002`: enforcement de atomicidad Git por defecto) con RED->GREEN->REFACTOR.
+  - Fix:
+    - `integrations/git/gitAtomicity.ts` activa atomicidad por defecto (`enabled: true`) manteniendo override por env/config.
+    - `integrations/git/__tests__/gitAtomicity.test.ts` actualiza contrato base a enforcement activo por defecto.
+  - Evidencia (2026-03-04):
+    - `npx --yes tsx@4.21.0 --test integrations/git/__tests__/gitAtomicity.test.ts` -> `3 pass / 0 fail`.
+    - `npx --yes tsx@4.21.0 --test integrations/git/__tests__/stageRunners.test.ts` -> `21 pass / 0 fail`.
+    - `npx --yes tsx@4.21.0 --test integrations/lifecycle/__tests__/cli.test.ts` -> `29 pass / 0 fail`.
+- ✅ PUMUKI-018: Preparar cierre de corte/publicación tras validación acumulada de PUMUKI-012..017.
+  - Evidencia (2026-03-04):
+    - `npm run -s test:stage-gates` -> `1018 pass / 0 fail / 4 skip` tras ajuste de regresión en `integrations/git/__tests__/hookGateSummary.test.ts`.
+    - Smoke complementario ya validado dentro del bloque: `gitAtomicity`, `stageRunners`, `lifecycle/cli`, `typecheck`.
+- ✅ PUMUKI-019: Ejecutar siguiente bug/mejora del backlog SAAS de prioridad media (`PUMUKI-004`: hooks versionados `core.hooksPath`).
+  - Fix:
+    - `integrations/lifecycle/hookManager.ts` añade resolución robusta de hooks con fallback a `.git/config` (`core.hooksPath`) cuando no está disponible `git rev-parse --git-path hooks`.
+    - `integrations/lifecycle/status.ts` y `integrations/lifecycle/doctor.ts` exponen metadatos de ruta efectiva (`hooksDirectory`, `hooksDirectoryResolution`).
+    - `integrations/lifecycle/cli.ts` imprime ruta efectiva de hooks en `status` y `doctor` modo texto para diagnóstico humano.
+  - Evidencia (2026-03-04):
+    - `npx --yes tsx@4.21.0 --test integrations/lifecycle/__tests__/hookManager.test.ts integrations/lifecycle/__tests__/status.test.ts integrations/lifecycle/__tests__/doctor.test.ts integrations/lifecycle/__tests__/cli.test.ts` -> `50 pass / 0 fail`.
+    - `npm run -s test:stage-gates` -> `1020 pass / 0 fail / 4 skip`.
+    - `npm run -s typecheck` -> `PASS`.
+- 🚧 PUMUKI-020: Preparar publicación del siguiente corte cuando PUMUKI-019 quede cerrada sin regresiones.

package/docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md

@@ -1994,10 +1994,34 @@ Criterio de salida F5:
     - `npx --yes tsx@4.21.0 --test integrations/gate/__tests__/stagePolicies.test.ts integrations/git/__tests__/runPlatformGate.test.ts integrations/lifecycle/__tests__/status.test.ts integrations/lifecycle/__tests__/doctor.test.ts integrations/lifecycle/__tests__/cli.test.ts` => `81 passed, 0 failed`.
     - `npm run -s typecheck` => `exit 0`.
 
-- 🚧 `P12.F2.T73` Preparar y publicar release con el hardening de `#606`.
+- ✅ `P12.F2.T73` Preparar y publicar release con el hardening de `#606`.
+  - cierre ejecutado:
+    - release branch creada: `release/6.3.37`.
+    - versionado aplicado en `package.json`, `package-lock.json`, `VERSION` y release notes.
+    - PR de release mergeada: `#610` (`commit acbdb73`).
+    - publicación npm completada con éxito (`npm publish --access public`).
+    - propagación validada: `latest=6.3.37`.
+  - evidencia:
+    - `npx --yes tsx@4.21.0 --test integrations/gate/__tests__/stagePolicies.test.ts integrations/git/__tests__/runPlatformGate.test.ts integrations/lifecycle/__tests__/status.test.ts integrations/lifecycle/__tests__/doctor.test.ts integrations/lifecycle/__tests__/cli.test.ts` => `81 passed, 0 failed`.
+    - `npm run -s typecheck` => `exit 0`.
+    - `npm view pumuki dist-tags --json` => `"latest": "6.3.37"`.
+    - `npm view pumuki@6.3.37 version` => `6.3.37`.
+
+- ✅ **Cierre consolidado del bloque P12.F2** (ID interno: `P12.F2.T74`).
+  - cierre ejecutado:
+    - bloque `P12.F2` consolidado con trazabilidad completa (issues/PRs/releases y evidencias de validación).
+    - backlog siguiente preparado en modo standby, sin deuda técnica abierta obligatoria del bloque actual.
+    - confirmada publicación estable `pumuki@6.3.37` como baseline para nuevos proyectos.
+  - evidencia:
+    - `gh issue view 606 --json state` => `CLOSED`.
+    - `gh pr view 608 --json state,mergedAt` => `MERGED`.
+    - `gh pr view 610 --json state,mergedAt` => `MERGED`.
+    - `npm view pumuki dist-tags --json` => `"latest": "6.3.37"`.
+
+- 🚧 **En espera de nueva orden** (ID interno: `P12.F2.T75`; sin deuda técnica pendiente de este bloque).
   - salida esperada:
-    - versionar release incremental y notas de publicación.
-    - publicar en npm y verificar propagación `dist-tags`.
+    - mantener una sola `🚧` activa por política del tablero.
+    - no ejecutar trabajo técnico nuevo hasta instrucción explícita del usuario.
 
 Criterio de salida F6:
 - veredicto final trazable y cierre administrativo completo.

package/integrations/gate/evaluateAiGate.ts

@@ -81,6 +81,12 @@ const DEFAULT_MAX_AGE_SECONDS: Readonly<Record<AiGateStage, number>> = {
 };
 
 const DEFAULT_PROTECTED_BRANCHES = new Set(['main', 'master', 'develop', 'dev']);
+const MCP_RECEIPT_STAGE_ORDER: Readonly<Record<AiGateStage, number>> = {
+  PRE_WRITE: 0,
+  PRE_COMMIT: 1,
+  PRE_PUSH: 2,
+  CI: 3,
+};
 
 const toErrorViolation = (code: string, message: string): AiGateViolation => ({
   code,
@@ -335,6 +341,13 @@ const toPolicyStage = (stage: AiGateStage): SkillsStage => {
   return stage;
 };
 
+const isMcpReceiptStageCompatible = (params: {
+  receiptStage: AiGateStage;
+  requestedStage: AiGateStage;
+}): boolean => {
+  return MCP_RECEIPT_STAGE_ORDER[params.receiptStage] >= MCP_RECEIPT_STAGE_ORDER[params.requestedStage];
+};
+
 const collectMcpReceiptViolations = (params: {
   required: boolean;
   stage: AiGateStage;
@@ -405,11 +418,16 @@ const collectMcpReceiptViolations = (params: {
       )
     );
   }
-  if (receiptRead.receipt.stage !== params.stage) {
+  if (
+    !isMcpReceiptStageCompatible({
+      receiptStage: receiptRead.receipt.stage,
+      requestedStage: params.stage,
+    })
+  ) {
     violations.push(
       toErrorViolation(
         'MCP_ENTERPRISE_RECEIPT_STAGE_MISMATCH',
-        `MCP receipt stage mismatch (${receiptRead.receipt.stage} != ${params.stage}).`
+        `MCP receipt stage mismatch (${receiptRead.receipt.stage} incompatible with ${params.stage}).`
       )
     );
   }

package/integrations/git/GitService.ts

@@ -2,6 +2,7 @@ import { execFileSync as runBinarySync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { Fact } from '../../core/facts/Fact';
+import type { GitChange } from './gitDiffUtils';
 import { parseNameStatus, hasAllowedExtension, buildFactsFromChanges } from './gitDiffUtils';
 export { parseNameStatus } from './gitDiffUtils';
 
@@ -77,7 +78,16 @@ export class GitService implements IGitService {
   }
 
   getStagedAndUnstagedFacts(extensions: ReadonlyArray<string>): ReadonlyArray<Fact> {
-    const trackedChanges = parseNameStatus(this.runGit(['diff', '--name-status', 'HEAD']))
+    const hasHeadCommit = this.hasHeadCommit();
+    const trackedNameStatus = hasHeadCommit
+      ? this.runGit(['diff', '--name-status', 'HEAD'])
+      : [
+        this.runGit(['diff', '--cached', '--name-status']),
+        this.runGit(['diff', '--name-status']),
+      ]
+        .filter((chunk) => chunk.trim().length > 0)
+        .join('\n');
+    const trackedChanges = this.deduplicateChangesByPath(parseNameStatus(trackedNameStatus))
       .filter((change) => hasAllowedExtension(change.path, extensions));
     const untrackedPaths = this.runGit(['ls-files', '--others', '--exclude-standard'])
       .split('\n')
@@ -100,6 +110,23 @@ export class GitService implements IGitService {
     );
   }
 
+  private hasHeadCommit(): boolean {
+    try {
+      this.runGit(['rev-parse', '--verify', 'HEAD']);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private deduplicateChangesByPath(changes: ReadonlyArray<GitChange>): ReadonlyArray<GitChange> {
+    const byPath = new Map<string, GitChange>();
+    for (const change of changes) {
+      byPath.set(change.path, change);
+    }
+    return Array.from(byPath.values());
+  }
+
   private readWorkingTreeFile(repoRoot: string, filePath: string): string {
     try {
       return readFileSync(join(repoRoot, filePath), 'utf8');

package/integrations/git/getCommitRangeFacts.ts

@@ -5,6 +5,24 @@ import { GitService } from './GitService';
 
 const defaultGit: IGitService = new GitService();
 
+const isResolvableRef = (git: IGitService, ref: string): boolean => {
+  try {
+    git.runGit(['rev-parse', '--verify', ref]);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const isRangeResolutionError = (error: unknown): boolean => {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  return /unknown revision|bad revision|ambiguous argument|fatal:\s+invalid object name/i.test(
+    error.message
+  );
+};
+
 export async function getFactsForCommitRange(params: {
   fromRef: string;
   toRef: string;
@@ -12,11 +30,23 @@ export async function getFactsForCommitRange(params: {
   git?: IGitService;
 }): Promise<ReadonlyArray<Fact>> {
   const git = params.git ?? defaultGit;
-  const diffOutput = git.runGit([
-    'diff',
-    '--name-status',
-    `${params.fromRef}..${params.toRef}`,
-  ]);
+  if (!isResolvableRef(git, params.fromRef) || !isResolvableRef(git, params.toRef)) {
+    return [];
+  }
+
+  let diffOutput = '';
+  try {
+    diffOutput = git.runGit([
+      'diff',
+      '--name-status',
+      `${params.fromRef}..${params.toRef}`,
+    ]);
+  } catch (error) {
+    if (isRangeResolutionError(error)) {
+      return [];
+    }
+    throw error;
+  }
   const changes = parseNameStatus(diffOutput).filter((change) =>
     hasAllowedExtension(change.path, params.extensions)
   );