pumuki 6.3.38 → 6.3.39

package/VERSION

@@ -1 +1 @@
-v6.3.38
+v6.3.39

package/docs/RELEASE_NOTES.md

@@ -5,6 +5,32 @@ 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:

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

@@ -7,9 +7,9 @@
 ## Estado actual
 - Plan activo: `docs/seguimiento-activo-pumuki-saas-supermercados.md`
 - Estado del plan: EJECUCION
-- Última task cerrada (`✅`): Fase 3.2 (actualización de `CHANGELOG.md` + `docs/RELEASE_NOTES.md` con fixes reales).
-- Task activa (`🚧`): Fase 3.3 publicación de versión.
-- Nuevos pendientes añadidos (`⏳`): sin cambios.
+- Ú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
 - Bloque RuralGO cerrado: `docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md`.

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

@@ -73,5 +73,57 @@
 - ✅ 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 `Unreleased` (CHANGELOG) y en `next patch candidate` (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): 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/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)
   );

package/integrations/git/gitAtomicity.ts

@@ -32,7 +32,7 @@ const DEFAULT_COMMIT_PATTERN =
   '^(feat|fix|chore|refactor|docs|test|perf|build|ci|revert)(\\([^)]+\\))?:\\s.+$';
 
 const defaultConfig: GitAtomicityConfig = {
-  enabled: false,
+  enabled: true,
   maxFiles: 25,
   maxScopes: 2,
   enforceCommitMessagePattern: true,

package/integrations/git/runPlatformGate.ts

@@ -235,6 +235,10 @@ const PLATFORM_REQUIRED_SKILLS_BUNDLES: Record<
   frontend: ['frontend-guidelines'],
 };
 
+const isCriticalProfileSeverity = (severity: string): boolean => {
+  return severity === 'CRITICAL' || severity === 'ERROR';
+};
+
 const toNormalizedPath = (value: string): string => value.replace(/\\/g, '/').trim();
 
 const collectObservedPathsFromFacts = (
@@ -511,6 +515,66 @@ const toPlatformSkillsCoverageBlockingFinding = (params: {
   };
 };
 
+const toCrossPlatformCriticalEnforcementBlockingFinding = (params: {
+  stage: 'PRE_COMMIT' | 'PRE_PUSH' | 'CI';
+  detectedPlatforms: DetectedPlatforms;
+  skillsRules: SkillsRuleSetLoadResult['rules'];
+  evaluatedRuleIds: ReadonlyArray<string>;
+}): Finding | undefined => {
+  const detectedPlatformKeys = (
+    ['ios', 'android', 'backend', 'frontend'] as const
+  ).filter((platform) => params.detectedPlatforms[platform]?.detected === true);
+
+  if (detectedPlatformKeys.length === 0) {
+    return undefined;
+  }
+
+  const evaluatedRuleIds = new Set(params.evaluatedRuleIds);
+  const gaps: string[] = [];
+
+  for (const platform of detectedPlatformKeys) {
+    const rulePrefix = PLATFORM_SKILLS_RULE_PREFIXES[platform];
+    const criticalSkillRules = params.skillsRules
+      .filter(
+        (rule) =>
+          rule.id.startsWith(rulePrefix) &&
+          isCriticalProfileSeverity(rule.severity)
+      )
+      .map((rule) => rule.id)
+      .sort();
+
+    if (criticalSkillRules.length === 0) {
+      gaps.push(`${platform}{critical_profile_rules=missing}`);
+      continue;
+    }
+
+    const evaluatedCriticalSkillRules = criticalSkillRules.filter((ruleId) =>
+      evaluatedRuleIds.has(ruleId)
+    );
+    if (evaluatedCriticalSkillRules.length === 0) {
+      gaps.push(
+        `${platform}{critical_profile_rules=${criticalSkillRules.length}; evaluated=0}`
+      );
+    }
+  }
+
+  if (gaps.length === 0) {
+    return undefined;
+  }
+
+  return {
+    ruleId: 'governance.skills.cross-platform-critical.incomplete',
+    severity: 'ERROR',
+    code: 'SKILLS_CROSS_PLATFORM_CRITICAL_INCOMPLETE_S0',
+    message:
+      `Cross-platform critical enforcement incomplete at ${params.stage}: ${gaps.join(' | ')}. ` +
+      'Ensure each detected platform has critical-profile skill rules active and evaluated.',
+    filePath: '.ai_evidence.json',
+    matchedBy: 'SkillsCrossPlatformCriticalGuard',
+    source: 'skills-cross-platform-critical',
+  };
+};
+
 export async function runPlatformGate(params: {
   policy: GatePolicy;
   auditMode?: 'gate' | 'engine';
@@ -642,6 +706,17 @@ export async function runPlatformGate(params: {
           evaluatedRuleIds: coverage?.evaluatedRuleIds ?? [],
         })
       : undefined;
+  const crossPlatformCriticalFinding =
+    params.policy.stage === 'PRE_COMMIT' ||
+    params.policy.stage === 'PRE_PUSH' ||
+    params.policy.stage === 'CI'
+      ? toCrossPlatformCriticalEnforcementBlockingFinding({
+          stage: params.policy.stage,
+          detectedPlatforms,
+          skillsRules: skillsRuleSet.rules,
+          evaluatedRuleIds: coverage?.evaluatedRuleIds ?? [],
+        })
+      : undefined;
   const skillsScopeComplianceFinding =
     params.policy.stage === 'PRE_COMMIT' ||
     params.policy.stage === 'PRE_PUSH' ||
@@ -720,6 +795,7 @@ export async function runPlatformGate(params: {
       ...(policyAsCodeBlockingFinding ? [policyAsCodeBlockingFinding] : []),
       ...(unsupportedSkillsMappingFinding ? [unsupportedSkillsMappingFinding] : []),
       ...(platformSkillsCoverageFinding ? [platformSkillsCoverageFinding] : []),
+      ...(crossPlatformCriticalFinding ? [crossPlatformCriticalFinding] : []),
       ...(skillsScopeComplianceFinding ? [skillsScopeComplianceFinding] : []),
       ...(coverageBlockingFinding ? [coverageBlockingFinding] : []),
       ...tddBddEvaluation.findings,
@@ -727,6 +803,7 @@ export async function runPlatformGate(params: {
     ]
     : unsupportedSkillsMappingFinding
       || platformSkillsCoverageFinding
+      || crossPlatformCriticalFinding
       || skillsScopeComplianceFinding
       || coverageBlockingFinding
       || policyAsCodeBlockingFinding
@@ -737,6 +814,7 @@ export async function runPlatformGate(params: {
         ...(policyAsCodeBlockingFinding ? [policyAsCodeBlockingFinding] : []),
         ...(unsupportedSkillsMappingFinding ? [unsupportedSkillsMappingFinding] : []),
         ...(platformSkillsCoverageFinding ? [platformSkillsCoverageFinding] : []),
+        ...(crossPlatformCriticalFinding ? [crossPlatformCriticalFinding] : []),
         ...(skillsScopeComplianceFinding ? [skillsScopeComplianceFinding] : []),
         ...(coverageBlockingFinding ? [coverageBlockingFinding] : []),
         ...tddBddEvaluation.findings,
@@ -750,6 +828,7 @@ export async function runPlatformGate(params: {
     policyAsCodeBlockingFinding ||
     unsupportedSkillsMappingFinding ||
     platformSkillsCoverageFinding ||
+    crossPlatformCriticalFinding ||
     skillsScopeComplianceFinding ||
     coverageBlockingFinding ||
     hasTddBddBlockingFinding

package/integrations/lifecycle/adapter.templates.json

@@ -5,16 +5,16 @@
       "payload": {
         "hooks": {
           "pre_write": {
-            "command": "npx --yes pumuki-pre-write"
+            "command": "npx --yes --package pumuki@latest pumuki-pre-write"
           },
           "pre_commit": {
-            "command": "./node_modules/.bin/pumuki-pre-commit"
+            "command": "npx --yes --package pumuki@latest pumuki-pre-commit"
           },
           "pre_push": {
-            "command": "./node_modules/.bin/pumuki-pre-push"
+            "command": "npx --yes --package pumuki@latest pumuki-pre-push"
           },
           "ci": {
-            "command": "npx --yes pumuki-ci"
+            "command": "npx --yes --package pumuki@latest pumuki-ci"
           }
         },
         "mcp": {
@@ -35,16 +35,16 @@
         "pumuki": {
           "hooks": {
             "pre_write": {
-              "command": "npx --yes pumuki-pre-write"
+              "command": "npx --yes --package pumuki@latest pumuki-pre-write"
             },
             "pre_commit": {
-              "command": "./node_modules/.bin/pumuki-pre-commit"
+              "command": "npx --yes --package pumuki@latest pumuki-pre-commit"
             },
             "pre_push": {
-              "command": "./node_modules/.bin/pumuki-pre-push"
+              "command": "npx --yes --package pumuki@latest pumuki-pre-push"
             },
             "ci": {
-              "command": "npx --yes pumuki-ci"
+              "command": "npx --yes --package pumuki@latest pumuki-ci"
             }
           }
         },
@@ -97,16 +97,16 @@
         },
         "pumukiHooks": {
           "pre_write": {
-            "command": "npx --yes pumuki-pre-write"
+            "command": "npx --yes --package pumuki@latest pumuki-pre-write"
           },
           "pre_commit": {
-            "command": "./node_modules/.bin/pumuki-pre-commit"
+            "command": "npx --yes --package pumuki@latest pumuki-pre-commit"
           },
           "pre_push": {
-            "command": "./node_modules/.bin/pumuki-pre-push"
+            "command": "npx --yes --package pumuki@latest pumuki-pre-push"
           },
           "ci": {
-            "command": "npx --yes pumuki-ci"
+            "command": "npx --yes --package pumuki@latest pumuki-ci"
           }
         }
       }
@@ -116,10 +116,10 @@
     {
       "path": ".codeium/adapter/hooks.json",
       "payload": {
-        "preCommand": "npx --yes pumuki-pre-write",
-        "postCommand": "./node_modules/.bin/pumuki-pre-commit",
-        "pushCommand": "./node_modules/.bin/pumuki-pre-push",
-        "ciCommand": "npx --yes pumuki-ci",
+        "preCommand": "npx --yes --package pumuki@latest pumuki-pre-write",
+        "postCommand": "npx --yes --package pumuki@latest pumuki-pre-commit",
+        "pushCommand": "npx --yes --package pumuki@latest pumuki-pre-push",
+        "ciCommand": "npx --yes --package pumuki@latest pumuki-ci",
         "mcpCommand": "npx --yes --package pumuki@latest pumuki-mcp-enterprise-stdio"
       }
     },
@@ -169,16 +169,16 @@
       "payload": {
         "hooks": {
           "pre_write": {
-            "command": "npx --yes pumuki-pre-write"
+            "command": "npx --yes --package pumuki@latest pumuki-pre-write"
           },
           "pre_commit": {
-            "command": "./node_modules/.bin/pumuki-pre-commit"
+            "command": "npx --yes --package pumuki@latest pumuki-pre-commit"
           },
           "pre_push": {
-            "command": "./node_modules/.bin/pumuki-pre-push"
+            "command": "npx --yes --package pumuki@latest pumuki-pre-push"
           },
           "ci": {
-            "command": "npx --yes pumuki-ci"
+            "command": "npx --yes --package pumuki@latest pumuki-ci"
           }
         },
         "mcp": {

package/integrations/lifecycle/cli.ts

@@ -975,6 +975,9 @@ const printDoctorReport = (
 ): void => {
   writeInfo(`[pumuki] repo: ${report.repoRoot}`);
   writeInfo(`[pumuki] package version: ${report.packageVersion}`);
+  writeInfo(
+    `[pumuki] hooks path: ${report.hooksDirectory} (${report.hooksDirectoryResolution})`
+  );
   writeInfo(
     `[pumuki] tracked node_modules paths: ${report.trackedNodeModulesPaths.length}`
   );
@@ -1422,6 +1425,9 @@ export const runLifecycleCli = async (
           writeInfo(`[pumuki] package version: ${status.packageVersion}`);
           writeInfo(`[pumuki] lifecycle installed: ${status.lifecycleState.installed ?? 'false'}`);
           writeInfo(`[pumuki] lifecycle version: ${status.lifecycleState.version ?? 'unknown'}`);
+          writeInfo(
+            `[pumuki] hooks path: ${status.hooksDirectory} (${status.hooksDirectoryResolution})`
+          );
           writeInfo(
             `[pumuki] hooks: pre-commit=${status.hookStatus['pre-commit'].managedBlockPresent ? 'managed' : 'missing'}, pre-push=${status.hookStatus['pre-push'].managedBlockPresent ? 'managed' : 'missing'}`
           );

package/integrations/lifecycle/doctor.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { readEvidenceResult } from '../evidence/readEvidence';
 import { resolvePolicyForStage } from '../gate/stagePolicies';
-import { getPumukiHooksStatus } from './hookManager';
+import { getPumukiHooksStatus, resolvePumukiHooksDirectory } from './hookManager';
 import { LifecycleGitService, type ILifecycleGitService } from './gitService';
 import { getCurrentPumukiVersion } from './packageInfo';
 import {
@@ -75,6 +75,8 @@ export type LifecycleDoctorReport = {
   lifecycleState: LifecycleState;
   trackedNodeModulesPaths: ReadonlyArray<string>;
   hookStatus: ReturnType<typeof getPumukiHooksStatus>;
+  hooksDirectory: string;
+  hooksDirectoryResolution: 'git-rev-parse' | 'git-config' | 'default';
   policyValidation: LifecyclePolicyValidationSnapshot;
   issues: ReadonlyArray<DoctorIssue>;
   deep?: DoctorDeepReport;
@@ -83,6 +85,7 @@ export type LifecycleDoctorReport = {
 const buildDoctorIssues = (params: {
   trackedNodeModulesPaths: ReadonlyArray<string>;
   hookStatus: ReturnType<typeof getPumukiHooksStatus>;
+  hooksDirectory: string;
   lifecycleState: LifecycleState;
 }): ReadonlyArray<DoctorIssue> => {
   const issues: DoctorIssue[] = [];
@@ -107,6 +110,7 @@ const buildDoctorIssues = (params: {
       severity: 'warning',
       message:
         `Lifecycle state says installed=true but managed hook blocks are incomplete (${managedHooks}/${totalHooks}). ` +
+        `Effective hooks path: ${params.hooksDirectory}. ` +
         'If you use versioned hooks via core.hooksPath, ensure those hooks include the PUMUKI MANAGED block or rerun "pumuki install".',
     });
   }
@@ -640,12 +644,14 @@ export const runLifecycleDoctor = (params?: {
   const cwd = params?.cwd ?? process.cwd();
   const repoRoot = git.resolveRepoRoot(cwd);
   const trackedNodeModulesPaths = git.trackedNodeModulesPaths(repoRoot);
+  const hooksDirectory = resolvePumukiHooksDirectory(repoRoot);
   const hookStatus = getPumukiHooksStatus(repoRoot);
   const lifecycleState = readLifecycleState(git, repoRoot);
 
   const issues = buildDoctorIssues({
     trackedNodeModulesPaths,
     hookStatus,
+    hooksDirectory: hooksDirectory.path,
     lifecycleState,
   });
   const deep = params?.deep
@@ -663,6 +669,8 @@ export const runLifecycleDoctor = (params?: {
     lifecycleState,
     trackedNodeModulesPaths,
     hookStatus,
+    hooksDirectory: hooksDirectory.path,
+    hooksDirectoryResolution: hooksDirectory.source,
     policyValidation: readLifecyclePolicyValidationSnapshot(repoRoot),
     issues,
     deep,

package/integrations/lifecycle/hookManager.ts

@@ -16,6 +16,16 @@ export type HookUninstallResult = {
   changedHooks: ReadonlyArray<PumukiManagedHook>;
 };
 
+export type PumukiHooksDirectoryResolutionSource =
+  | 'git-rev-parse'
+  | 'git-config'
+  | 'default';
+
+export type PumukiHooksDirectoryResolution = {
+  path: string;
+  source: PumukiHooksDirectoryResolutionSource;
+};
+
 const HOOK_FILE_MODE = 0o755;
 
 const resolveGitPath = (repoRoot: string, gitPathTarget: string): string | null => {
@@ -34,8 +44,82 @@ const resolveGitPath = (repoRoot: string, gitPathTarget: string): string | null
   }
 };
 
+const readCoreHooksPathFromGitConfig = (repoRoot: string): string | null => {
+  const configPath = join(repoRoot, '.git', 'config');
+  if (!existsSync(configPath)) {
+    return null;
+  }
+
+  let contents = '';
+  try {
+    contents = readFileSync(configPath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  let inCoreSection = false;
+  for (const rawLine of contents.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line.length === 0 || line.startsWith(';') || line.startsWith('#')) {
+      continue;
+    }
+
+    if (line.startsWith('[') && line.endsWith(']')) {
+      inCoreSection = /^\[core\]$/i.test(line);
+      continue;
+    }
+
+    if (!inCoreSection) {
+      continue;
+    }
+
+    const match = /^hookspath\s*=\s*(.+)$/i.exec(line);
+    if (!match) {
+      continue;
+    }
+
+    let hooksPath = match[1]?.trim() ?? '';
+    if (hooksPath.startsWith('"') && hooksPath.endsWith('"')) {
+      hooksPath = hooksPath.slice(1, -1);
+    }
+    if (hooksPath.length === 0) {
+      continue;
+    }
+    return hooksPath;
+  }
+
+  return null;
+};
+
+export const resolvePumukiHooksDirectory = (
+  repoRoot: string
+): PumukiHooksDirectoryResolution => {
+  const gitPathHooks = resolveGitPath(repoRoot, 'hooks');
+  if (gitPathHooks) {
+    return {
+      path: gitPathHooks,
+      source: 'git-rev-parse',
+    };
+  }
+
+  const hooksPathFromConfig = readCoreHooksPathFromGitConfig(repoRoot);
+  if (hooksPathFromConfig) {
+    return {
+      path: isAbsolute(hooksPathFromConfig)
+        ? hooksPathFromConfig
+        : resolve(repoRoot, hooksPathFromConfig),
+      source: 'git-config',
+    };
+  }
+
+  return {
+    path: join(repoRoot, '.git', 'hooks'),
+    source: 'default',
+  };
+};
+
 const resolveHooksDirectory = (repoRoot: string): string =>
-  resolveGitPath(repoRoot, 'hooks') ?? join(repoRoot, '.git', 'hooks');
+  resolvePumukiHooksDirectory(repoRoot).path;
 
 const resolveHookPath = (repoRoot: string, hook: PumukiManagedHook): string =>
   join(resolveHooksDirectory(repoRoot), hook);

package/integrations/lifecycle/status.ts

@@ -1,4 +1,4 @@
-import { getPumukiHooksStatus } from './hookManager';
+import { getPumukiHooksStatus, resolvePumukiHooksDirectory } from './hookManager';
 import { LifecycleGitService, type ILifecycleGitService } from './gitService';
 import { getCurrentPumukiVersion } from './packageInfo';
 import {
@@ -12,6 +12,8 @@ export type LifecycleStatus = {
   packageVersion: string;
   lifecycleState: LifecycleState;
   hookStatus: ReturnType<typeof getPumukiHooksStatus>;
+  hooksDirectory: string;
+  hooksDirectoryResolution: 'git-rev-parse' | 'git-config' | 'default';
   trackedNodeModulesCount: number;
   policyValidation: LifecyclePolicyValidationSnapshot;
 };
@@ -23,6 +25,7 @@ export const readLifecycleStatus = (params?: {
   const git = params?.git ?? new LifecycleGitService();
   const cwd = params?.cwd ?? process.cwd();
   const repoRoot = git.resolveRepoRoot(cwd);
+  const hooksDirectory = resolvePumukiHooksDirectory(repoRoot);
   const trackedNodeModulesCount = git.trackedNodeModulesPaths(repoRoot).length;
 
   return {
@@ -30,6 +33,8 @@ export const readLifecycleStatus = (params?: {
     packageVersion: getCurrentPumukiVersion({ repoRoot }),
     lifecycleState: readLifecycleState(git, repoRoot),
     hookStatus: getPumukiHooksStatus(repoRoot),
+    hooksDirectory: hooksDirectory.path,
+    hooksDirectoryResolution: hooksDirectory.source,
     trackedNodeModulesCount,
     policyValidation: readLifecyclePolicyValidationSnapshot(repoRoot),
   };

package/package.json

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