pumuki 6.3.37 → 6.3.39

package/integrations/git/stageRunners.ts

@@ -6,9 +6,17 @@ import {
 } from './resolveGitRefs';
 import { runPlatformGate } from './runPlatformGate';
 import { GitService } from './GitService';
-import { emitAuditSummaryNotificationFromEvidence } from '../notifications/emitAuditSummaryNotification';
+import {
+  evaluateGitAtomicity,
+  type GitAtomicityEvaluation,
+  type GitAtomicityStage,
+} from './gitAtomicity';
+import {
+  emitAuditSummaryNotificationFromEvidence,
+  emitGateBlockedNotification,
+} from '../notifications/emitAuditSummaryNotification';
 import { readFileSync } from 'node:fs';
-import { readEvidenceResult } from '../evidence/readEvidence';
+import { readEvidence, readEvidenceResult } from '../evidence/readEvidence';
 import type { EvidenceReadResult } from '../evidence/readEvidence';
 
 const PRE_PUSH_UPSTREAM_REQUIRED_MESSAGE =
@@ -16,6 +24,20 @@ const PRE_PUSH_UPSTREAM_REQUIRED_MESSAGE =
 
 const PRE_COMMIT_EVIDENCE_MAX_AGE_SECONDS = 900;
 const PRE_PUSH_EVIDENCE_MAX_AGE_SECONDS = 1800;
+const DEFAULT_BLOCKED_REMEDIATION = 'Corrige la causa del bloqueo y vuelve a ejecutar el gate.';
+
+const 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_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.',
+  GITFLOW_PROTECTED_BRANCH: 'Trabaja en feature/* y evita ramas protegidas.',
+  PRE_PUSH_UPSTREAM_MISSING: 'Ejecuta: git push --set-upstream origin <branch>',
+};
 
 type StageRunnerDependencies = {
   resolvePolicyForStage: typeof resolvePolicyForStage;
@@ -23,13 +45,28 @@ type StageRunnerDependencies = {
   resolvePrePushBootstrapBaseRef: typeof resolvePrePushBootstrapBaseRef;
   resolveCiBaseRef: typeof resolveCiBaseRef;
   runPlatformGate: typeof runPlatformGate;
+  evaluateGitAtomicity: (params: {
+    repoRoot: string;
+    stage: GitAtomicityStage;
+    fromRef?: string;
+    toRef?: string;
+  }) => GitAtomicityEvaluation;
   resolveRepoRoot: () => string;
   readPrePushStdin: () => string;
   notifyAuditSummaryFromEvidence: (params: {
     repoRoot: string;
     stage: 'PRE_COMMIT' | 'PRE_PUSH' | 'CI';
   }) => void;
+  notifyGateBlocked: (params: {
+    repoRoot: string;
+    stage: 'PRE_COMMIT' | 'PRE_PUSH' | 'CI';
+    totalViolations: number;
+    causeCode: string;
+    causeMessage: string;
+    remediation: string;
+  }) => void;
   readEvidenceResult: (repoRoot: string) => EvidenceReadResult;
+  readEvidence: typeof readEvidence;
   now: () => number;
   writeHookGateSummary: (message: string) => void;
   isQuietMode: () => boolean;
@@ -41,6 +78,13 @@ const defaultDependencies: StageRunnerDependencies = {
   resolvePrePushBootstrapBaseRef,
   resolveCiBaseRef,
   runPlatformGate,
+  evaluateGitAtomicity: (params) =>
+    evaluateGitAtomicity({
+      repoRoot: params.repoRoot,
+      stage: params.stage,
+      fromRef: params.fromRef,
+      toRef: params.toRef,
+    }),
   resolveRepoRoot: () => new GitService().resolveRepoRoot(),
   readPrePushStdin: () => {
     const envInput = process.env.PUMUKI_PRE_PUSH_STDIN;
@@ -62,7 +106,11 @@ const defaultDependencies: StageRunnerDependencies = {
       stage,
     });
   },
+  notifyGateBlocked: (params) => {
+    emitGateBlockedNotification(params);
+  },
   readEvidenceResult,
+  readEvidence,
   now: () => Date.now(),
   writeHookGateSummary: (message) => {
     process.stdout.write(`${message}\n`);
@@ -87,6 +135,32 @@ const notifyAuditSummaryForStage = (
   });
 };
 
+const notifyGateBlockedForStage = (params: {
+  dependencies: StageRunnerDependencies;
+  stage: 'PRE_COMMIT' | 'PRE_PUSH' | 'CI';
+  fallbackCauseCode: string;
+  fallbackCauseMessage: string;
+  fallbackRemediation: string;
+}): void => {
+  const repoRoot = params.dependencies.resolveRepoRoot();
+  const evidence = params.dependencies.readEvidence(repoRoot);
+  const firstViolation = evidence?.ai_gate.violations[0];
+  const causeCode = firstViolation?.code ?? params.fallbackCauseCode;
+  const causeMessage = firstViolation?.message ?? params.fallbackCauseMessage;
+  const remediation =
+    BLOCKED_REMEDIATION_BY_CODE[causeCode]
+    ?? params.fallbackRemediation
+    ?? DEFAULT_BLOCKED_REMEDIATION;
+  params.dependencies.notifyGateBlocked({
+    repoRoot,
+    stage: params.stage,
+    totalViolations: evidence?.ai_gate.violations.length ?? 0,
+    causeCode,
+    causeMessage,
+    remediation,
+  });
+};
+
 const ZERO_HASH = /^0+$/;
 
 const toEvidenceAgeSeconds = (
@@ -159,10 +233,53 @@ const shouldAllowBootstrapPrePush = (rawInput: string): boolean => {
   return false;
 };
 
+const enforceGitAtomicityGate = (params: {
+  dependencies: StageRunnerDependencies;
+  repoRoot: string;
+  stage: 'PRE_COMMIT' | 'PRE_PUSH' | 'CI';
+  fromRef?: string;
+  toRef?: string;
+}): boolean => {
+  const atomicity = params.dependencies.evaluateGitAtomicity({
+    repoRoot: params.repoRoot,
+    stage: params.stage,
+    fromRef: params.fromRef,
+    toRef: params.toRef,
+  });
+  if (!atomicity.enabled || atomicity.allowed) {
+    return false;
+  }
+  const firstViolation = atomicity.violations[0];
+  if (!firstViolation) {
+    return false;
+  }
+  process.stderr.write(`[pumuki][git-atomicity] ${firstViolation.code}: ${firstViolation.message}\n`);
+  params.dependencies.notifyGateBlocked({
+    repoRoot: params.repoRoot,
+    stage: params.stage,
+    totalViolations: atomicity.violations.length,
+    causeCode: firstViolation.code,
+    causeMessage: firstViolation.message,
+    remediation: firstViolation.remediation,
+  });
+  notifyAuditSummaryForStage(params.dependencies, params.stage);
+  return true;
+};
+
 export async function runPreCommitStage(
   dependencies: Partial<StageRunnerDependencies> = {}
 ): Promise<number> {
   const activeDependencies = getDependencies(dependencies);
+  const repoRoot = activeDependencies.resolveRepoRoot();
+  if (
+    enforceGitAtomicityGate({
+      dependencies: activeDependencies,
+      repoRoot,
+      stage: 'PRE_COMMIT',
+    })
+  ) {
+    return 1;
+  }
   const resolved = activeDependencies.resolvePolicyForStage('PRE_COMMIT');
   const exitCode = await activeDependencies.runPlatformGate({
     policy: resolved.policy,
@@ -177,6 +294,15 @@ export async function runPreCommitStage(
     policyTrace: resolved.trace,
     exitCode,
   });
+  if (exitCode !== 0) {
+    notifyGateBlockedForStage({
+      dependencies: activeDependencies,
+      stage: 'PRE_COMMIT',
+      fallbackCauseCode: 'PRE_COMMIT_GATE_BLOCKED',
+      fallbackCauseMessage: 'Gate blocked pre-commit stage.',
+      fallbackRemediation: DEFAULT_BLOCKED_REMEDIATION,
+    });
+  }
   notifyAuditSummaryForStage(activeDependencies, 'PRE_COMMIT');
   return exitCode;
 }
@@ -185,17 +311,30 @@ export async function runPrePushStage(
   dependencies: Partial<StageRunnerDependencies> = {}
 ): Promise<number> {
   const activeDependencies = getDependencies(dependencies);
+  const repoRoot = activeDependencies.resolveRepoRoot();
   const upstreamRef = activeDependencies.resolveUpstreamRef();
   if (!upstreamRef) {
     const prePushInput = activeDependencies.readPrePushStdin();
     if (shouldAllowBootstrapPrePush(prePushInput)) {
+      const bootstrapBaseRef = activeDependencies.resolvePrePushBootstrapBaseRef();
+      if (
+        enforceGitAtomicityGate({
+          dependencies: activeDependencies,
+          repoRoot,
+          stage: 'PRE_PUSH',
+          fromRef: bootstrapBaseRef,
+          toRef: 'HEAD',
+        })
+      ) {
+        return 1;
+      }
       const resolved = activeDependencies.resolvePolicyForStage('PRE_PUSH');
       const exitCode = await activeDependencies.runPlatformGate({
         policy: resolved.policy,
         policyTrace: resolved.trace,
         scope: {
           kind: 'range',
-          fromRef: activeDependencies.resolvePrePushBootstrapBaseRef(),
+          fromRef: bootstrapBaseRef,
           toRef: 'HEAD',
         },
       });
@@ -209,10 +348,29 @@ export async function runPrePushStage(
       return exitCode;
     }
     process.stderr.write(`${PRE_PUSH_UPSTREAM_REQUIRED_MESSAGE}\n`);
+    notifyGateBlockedForStage({
+      dependencies: activeDependencies,
+      stage: 'PRE_PUSH',
+      fallbackCauseCode: 'PRE_PUSH_UPSTREAM_MISSING',
+      fallbackCauseMessage: 'Branch has no upstream tracking reference.',
+      fallbackRemediation: 'Ejecuta: git push --set-upstream origin <branch>',
+    });
     notifyAuditSummaryForStage(activeDependencies, 'PRE_PUSH');
     return 1;
   }
 
+  if (
+    enforceGitAtomicityGate({
+      dependencies: activeDependencies,
+      repoRoot,
+      stage: 'PRE_PUSH',
+      fromRef: upstreamRef,
+      toRef: 'HEAD',
+    })
+  ) {
+    return 1;
+  }
+
   const resolved = activeDependencies.resolvePolicyForStage('PRE_PUSH');
   const exitCode = await activeDependencies.runPlatformGate({
     policy: resolved.policy,
@@ -229,6 +387,15 @@ export async function runPrePushStage(
     policyTrace: resolved.trace,
     exitCode,
   });
+  if (exitCode !== 0) {
+    notifyGateBlockedForStage({
+      dependencies: activeDependencies,
+      stage: 'PRE_PUSH',
+      fallbackCauseCode: 'PRE_PUSH_GATE_BLOCKED',
+      fallbackCauseMessage: 'Gate blocked pre-push stage.',
+      fallbackRemediation: DEFAULT_BLOCKED_REMEDIATION,
+    });
+  }
   notifyAuditSummaryForStage(activeDependencies, 'PRE_PUSH');
   return exitCode;
 }
@@ -237,16 +404,38 @@ export async function runCiStage(
   dependencies: Partial<StageRunnerDependencies> = {}
 ): Promise<number> {
   const activeDependencies = getDependencies(dependencies);
+  const repoRoot = activeDependencies.resolveRepoRoot();
+  const ciBaseRef = activeDependencies.resolveCiBaseRef();
+  if (
+    enforceGitAtomicityGate({
+      dependencies: activeDependencies,
+      repoRoot,
+      stage: 'CI',
+      fromRef: ciBaseRef,
+      toRef: 'HEAD',
+    })
+  ) {
+    return 1;
+  }
   const resolved = activeDependencies.resolvePolicyForStage('CI');
   const exitCode = await activeDependencies.runPlatformGate({
     policy: resolved.policy,
     policyTrace: resolved.trace,
     scope: {
       kind: 'range',
-      fromRef: activeDependencies.resolveCiBaseRef(),
+      fromRef: ciBaseRef,
       toRef: 'HEAD',
     },
   });
+  if (exitCode !== 0) {
+    notifyGateBlockedForStage({
+      dependencies: activeDependencies,
+      stage: 'CI',
+      fallbackCauseCode: 'CI_GATE_BLOCKED',
+      fallbackCauseMessage: 'Gate blocked CI stage.',
+      fallbackRemediation: DEFAULT_BLOCKED_REMEDIATION,
+    });
+  }
   notifyAuditSummaryForStage(activeDependencies, 'CI');
   return exitCode;
 }

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": "npx --yes pumuki-pre-commit"
+            "command": "npx --yes --package pumuki@latest pumuki-pre-commit"
           },
           "pre_push": {
-            "command": "npx --yes 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": "npx --yes pumuki-pre-commit"
+              "command": "npx --yes --package pumuki@latest pumuki-pre-commit"
             },
             "pre_push": {
-              "command": "npx --yes 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": "npx --yes pumuki-pre-commit"
+            "command": "npx --yes --package pumuki@latest pumuki-pre-commit"
           },
           "pre_push": {
-            "command": "npx --yes 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": "npx --yes pumuki-pre-commit",
-        "pushCommand": "npx --yes 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": "npx --yes pumuki-pre-commit"
+            "command": "npx --yes --package pumuki@latest pumuki-pre-commit"
           },
           "pre_push": {
-            "command": "npx --yes 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

@@ -38,7 +38,10 @@ import {
 } from '../sdd';
 import { evaluateAiGate } from '../gate/evaluateAiGate';
 import { runEnterpriseAiGateCheck } from '../mcp/aiGateCheck';
-import { emitAuditSummaryNotificationFromAiGate } from '../notifications/emitAuditSummaryNotification';
+import {
+  emitAuditSummaryNotificationFromAiGate,
+  emitGateBlockedNotification,
+} from '../notifications/emitAuditSummaryNotification';
 import {
   buildPreWriteAutomationTrace,
   type PreWriteAutomationTrace,
@@ -972,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}`
   );
@@ -1055,12 +1061,14 @@ type PreWriteOpenSpecBootstrapTrace = {
 
 type LifecycleCliDependencies = {
   emitAuditSummaryNotificationFromAiGate: typeof emitAuditSummaryNotificationFromAiGate;
+  emitGateBlockedNotification: typeof emitGateBlockedNotification;
   runPlatformGate: typeof runPlatformGate;
   collectRemoteCiDiagnostics: typeof collectRemoteCiDiagnostics;
 };
 
 const defaultLifecycleCliDependencies: LifecycleCliDependencies = {
   emitAuditSummaryNotificationFromAiGate,
+  emitGateBlockedNotification,
   runPlatformGate,
   collectRemoteCiDiagnostics,
 };
@@ -1082,6 +1090,9 @@ const PRE_WRITE_HINTS_BY_CODE: Readonly<Record<string, string>> = {
   MCP_ENTERPRISE_RECEIPT_REPO_ROOT_MISMATCH: 'Genera el recibo MCP en este mismo repositorio.',
 };
 
+const PRE_WRITE_DEFAULT_REMEDIATION =
+  'Corrige la causa bloqueante y vuelve a ejecutar: npx --yes --package pumuki@latest pumuki-pre-write';
+
 const PRE_WRITE_OPENSPEC_AUTOREMEDIABLE_CODES = new Set<string>([
   'OPENSPEC_MISSING',
   'OPENSPEC_VERSION_UNSUPPORTED',
@@ -1113,6 +1124,16 @@ const resolvePreWriteNextAction = (params: {
   };
 };
 
+const resolvePreWriteBlockedRemediation = (params: {
+  causeCode: string;
+  nextAction?: PreWriteValidationEnvelope['next_action'];
+}): string => {
+  if (params.nextAction?.command) {
+    return params.nextAction.command;
+  }
+  return PRE_WRITE_HINTS_BY_CODE[params.causeCode] ?? PRE_WRITE_DEFAULT_REMEDIATION;
+};
+
 const wrapPreWritePanelLine = (value: string, width: number): string[] => {
   if (width < 20 || value.length <= width) {
     return [value];
@@ -1404,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'}`
           );
@@ -1818,9 +1842,34 @@ export const runLifecycleCli = async (
             });
           }
           if (!result.decision.allowed) {
+            activeDependencies.emitGateBlockedNotification({
+              repoRoot: process.cwd(),
+              stage: result.stage,
+              totalViolations: aiGate?.violations.length ?? 0,
+              causeCode: result.decision.code,
+              causeMessage: result.decision.message,
+              remediation: resolvePreWriteBlockedRemediation({
+                causeCode: result.decision.code,
+                nextAction,
+              }),
+            });
             return 1;
           }
           if (aiGate && !aiGate.allowed) {
+            const firstViolation = aiGate.violations[0];
+            const causeCode = firstViolation?.code ?? 'AI_GATE_BLOCKED';
+            const causeMessage = firstViolation?.message ?? 'AI gate blocked PRE_WRITE stage.';
+            activeDependencies.emitGateBlockedNotification({
+              repoRoot: process.cwd(),
+              stage: result.stage,
+              totalViolations: aiGate.violations.length,
+              causeCode,
+              causeMessage,
+              remediation: resolvePreWriteBlockedRemediation({
+                causeCode,
+                nextAction,
+              }),
+            });
             return 1;
           }
           return 0;

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[] = [];
@@ -99,10 +102,16 @@ const buildDoctorIssues = (params: {
     params.lifecycleState.installed === 'true' &&
     !Object.values(params.hookStatus).every((entry) => entry.managedBlockPresent)
   ) {
+    const totalHooks = Object.keys(params.hookStatus).length;
+    const managedHooks = Object.values(params.hookStatus).filter(
+      (entry) => entry.managedBlockPresent
+    ).length;
     issues.push({
       severity: 'warning',
       message:
-        'Lifecycle state says installed=true but one or more managed hook blocks are missing.',
+        `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".',
     });
   }
 
@@ -517,7 +526,7 @@ const buildCompatibilityContract = (params: {
     overall: overallCompatible ? 'compatible' : 'incompatible',
     pumuki: {
       installed: pumukiInstalled,
-      version: getCurrentPumukiVersion(),
+      version: getCurrentPumukiVersion({ repoRoot: params.repoRoot }),
     },
     openspec: {
       required: openSpecRequired,
@@ -635,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
@@ -654,10 +665,12 @@ export const runLifecycleDoctor = (params?: {
 
   return {
     repoRoot,
-    packageVersion: getCurrentPumukiVersion(),
+    packageVersion: getCurrentPumukiVersion({ repoRoot }),
     lifecycleState,
     trackedNodeModulesPaths,
     hookStatus,
+    hooksDirectory: hooksDirectory.path,
+    hooksDirectoryResolution: hooksDirectory.source,
     policyValidation: readLifecyclePolicyValidationSnapshot(repoRoot),
     issues,
     deep,

package/integrations/lifecycle/hookBlock.ts

@@ -24,26 +24,52 @@ const managedBlockPattern = new RegExp(
   'g'
 );
 
+const toHookRunner = (params: {
+  hook: PumukiManagedHook;
+  runner: string;
+}): string => {
+  if (params.hook === 'pre-push') {
+    return `  PUMUKI_PRE_PUSH_STDIN="$PUMUKI_PRE_PUSH_STDIN" ${params.runner} "$@"`;
+  }
+  return `  ${params.runner}`;
+};
+
 export const buildPumukiManagedHookBlock = (hook: PumukiManagedHook): string => {
   const cli = HOOK_COMMANDS[hook];
-  const prePushCommand =
-    '  PUMUKI_PRE_PUSH_STDIN="$(cat)"\n' +
-    `  PUMUKI_PRE_PUSH_STDIN="$PUMUKI_PRE_PUSH_STDIN" npx --yes ${cli} "$@"`;
-  const hookCommand =
-    hook === 'pre-push' ? prePushCommand : `  npx --yes ${cli}`;
+  const localBinPath = `./node_modules/.bin/${cli}`;
+  const localNodeEntry = `./node_modules/pumuki/bin/${cli}.js`;
 
   return [
     PUMUKI_MANAGED_BLOCK_START,
-    'if command -v npx >/dev/null 2>&1; then',
-    hookCommand,
+    ...(hook === 'pre-push' ? ['PUMUKI_PRE_PUSH_STDIN="$(cat)"'] : []),
+    `if [ -x "${localBinPath}" ]; then`,
+    toHookRunner({
+      hook,
+      runner: localBinPath,
+    }),
+    `elif [ -f "${localNodeEntry}" ] && command -v node >/dev/null 2>&1; then`,
+    toHookRunner({
+      hook,
+      runner: `node ${localNodeEntry}`,
+    }),
+    `elif command -v ${cli} >/dev/null 2>&1; then`,
+    toHookRunner({
+      hook,
+      runner: cli,
+    }),
+    'elif command -v npx >/dev/null 2>&1; then',
+    toHookRunner({
+      hook,
+      runner: `npx --yes --package pumuki@latest ${cli}`,
+    }),
+    'else',
+    `  echo "[pumuki] unable to resolve ${cli} runner. Install dependencies or ensure npx is available." >&2`,
+    '  exit 1',
+    'fi',
     '  status=$?',
     '  if [ "$status" -ne 0 ]; then',
     '    exit "$status"',
     '  fi',
-    'else',
-    '  echo "[pumuki] npx was not found in PATH." >&2',
-    '  exit 1',
-    'fi',
     PUMUKI_MANAGED_BLOCK_END,
   ].join('\n');
 };