pumuki 6.3.54 → 6.3.55

package/README.md

@@ -83,12 +83,12 @@ Expected behavior:
 
 Version drift quick check:
 
-- `status --json` and `doctor --json` expose `version.effective`, `version.runtime`, `version.consumerInstalled`, `version.lifecycleInstalled`, `version.driftWarning`, and `version.alignmentCommand`.
-- If `driftWarning` is not `null`, align the consumer with:
+- `status --json` and `doctor --json` expose `version.effective`, `version.runtime`, `version.consumerInstalled`, `version.lifecycleInstalled`, `version.driftWarning`, `version.alignmentCommand`, `version.pathExecutionHazard`, `version.pathExecutionWarning`, and `version.pathExecutionWorkaroundCommand`.
+- If `driftWarning` is not `null`, prefer the exact command already exposed in `version.alignmentCommand`.
+- If `pathExecutionHazard` is `true`, avoid `npx/npm exec` for the install step and use the safe local workaround reported by Pumuki, for example:
 
 ```bash
-npm install --save-exact pumuki@6.3.52
-npx --yes pumuki update --latest
+node ./node_modules/pumuki/bin/pumuki.js install
 ```
 
 ## Why Pumuki

package/docs/operations/RELEASE_NOTES.md

@@ -5,6 +5,25 @@ Detailed commit history remains available through Git history (`git log` / `git
 
 ## 2026-03 (enterprise hardening updates)
 
+### 2026-03-06 (v6.3.55)
+
+- Safe remediation for consumers whose repository path breaks `PATH` execution:
+  - `status` / `doctor` now detect when the repo root contains the platform `PATH` delimiter,
+  - the JSON contract exposes:
+    - `version.pathExecutionHazard`
+    - `version.pathExecutionWarning`
+    - `version.pathExecutionWorkaroundCommand`
+  - `version.alignmentCommand` now falls back to a safe local-node invocation when `npx/npm exec` would be unsafe.
+- Human-readable lifecycle output now explains the problem directly:
+  - `execution warning: ...`
+  - `execution workaround: node ./node_modules/pumuki/bin/pumuki.js ...`
+- Operational impact:
+  - consumers like `SAAS:APP_SUPERMERCADOS` no longer depend on broken `PATH` rewriting for lifecycle remediation,
+  - the workaround is deterministic and machine-readable instead of tribal knowledge.
+- Validation evidence:
+  - `npx --yes tsx@4.21.0 --test integrations/lifecycle/__tests__/packageInfo.test.ts integrations/lifecycle/__tests__/status.test.ts integrations/lifecycle/__tests__/doctor.test.ts integrations/lifecycle/__tests__/cli.test.ts` (`pass`)
+  - `npm run -s typecheck` (`PASS`)
+
 ### 2026-03-06 (v6.3.54)
 
 - Consumer package/runtime correctness:

package/docs/product/API_REFERENCE.md

@@ -158,6 +158,9 @@ Machine-readable fields exposed by both `pumuki status --json` and `pumuki docto
 - `version.driftFromLifecycleInstalled`
 - `version.driftWarning`
 - `version.alignmentCommand`
+- `version.pathExecutionHazard`
+- `version.pathExecutionWarning`
+- `version.pathExecutionWorkaroundCommand`
 
 Compatibility note:
 
@@ -172,6 +175,9 @@ Interpretation contract:
 - `lifecycleInstalled`: version recorded in managed lifecycle metadata.
 - `driftWarning`: compact human-readable explanation when those values diverge.
 - `alignmentCommand`: exact remediation command to align dependency and lifecycle state with the current runtime version.
+- `pathExecutionHazard`: boolean flag raised when the repo root contains the platform `PATH` delimiter and `npx/npm exec` can fail to resolve `pumuki`.
+- `pathExecutionWarning`: compact warning explaining why `PATH` resolution is unsafe in that repo.
+- `pathExecutionWorkaroundCommand`: safe local-node entrypoint to use when `pathExecutionHazard=true`.
 
 ## Evidence API
 

package/docs/product/USAGE.md

@@ -328,10 +328,14 @@ Plain `npm uninstall pumuki` removes only the dependency; it does not remove man
     "runtime": "6.3.52",
     "consumerInstalled": "6.3.47",
     "lifecycleInstalled": "6.3.46",
-    "source": "consumerInstalled",
+    "source": "consumer-node-modules",
     "driftFromRuntime": true,
     "driftFromLifecycleInstalled": true,
-    "driftWarning": "Version drift detectado: effective=6.3.47 runtime=6.3.52 lifecycle=6.3.46."
+    "driftWarning": "Version drift detectado: effective=6.3.47 runtime=6.3.52 lifecycle=6.3.46.",
+    "alignmentCommand": "npm install --save-exact pumuki@6.3.52 && npx --yes --package pumuki@6.3.52 pumuki install",
+    "pathExecutionHazard": false,
+    "pathExecutionWarning": null,
+    "pathExecutionWorkaroundCommand": null
   }
 }
 ```
@@ -345,17 +349,20 @@ How to read it:
 - `source`: source chosen to compute `effective`.
 - `driftWarning`: compact explanation when those values diverge.
 - `alignmentCommand`: exact command to align consumer dependency and lifecycle state with the current runtime.
+- `pathExecutionHazard`: tells you whether the repo root itself can break `PATH`-based execution.
+- `pathExecutionWarning`: compact explanation of that hazard.
+- `pathExecutionWorkaroundCommand`: safe local-node entrypoint to use when `PATH` execution is unsafe.
 
 Recommended remediation when drift appears:
 
 ```bash
-npm install --save-exact pumuki@6.3.52
-npx --yes pumuki update --latest
+<use version.alignmentCommand>
 npx --yes pumuki status --json
 npx --yes pumuki doctor --json
 ```
 
 Use this sequence to align dependency, hooks, and lifecycle metadata in the same consumer.
+If `pathExecutionHazard=true`, use the local workaround printed by Pumuki instead of `npx/npm exec`.
 
 Loop runtime behavior:
 - `pumuki loop run` creates a session in `.pumuki/loop-sessions/`.

package/integrations/lifecycle/cli.ts

@@ -1496,6 +1496,14 @@ const printDoctorReport = (
       writeInfo(`[pumuki] version remediation: ${report.version.alignmentCommand}`);
     }
   }
+  if (report.version.pathExecutionWarning) {
+    writeInfo(`[pumuki] execution warning: ${report.version.pathExecutionWarning}`);
+    if (report.version.pathExecutionWorkaroundCommand) {
+      writeInfo(
+        `[pumuki] execution workaround: ${report.version.pathExecutionWorkaroundCommand} <command>`
+      );
+    }
+  }
   writeInfo(
     `[pumuki] hooks path: ${report.hooksDirectory} (${report.hooksDirectoryResolution})`
   );
@@ -2126,6 +2134,14 @@ export const runLifecycleCli = async (
               writeInfo(`[pumuki] version remediation: ${status.version.alignmentCommand}`);
             }
           }
+          if (status.version.pathExecutionWarning) {
+            writeInfo(`[pumuki] execution warning: ${status.version.pathExecutionWarning}`);
+            if (status.version.pathExecutionWorkaroundCommand) {
+              writeInfo(
+                `[pumuki] execution workaround: ${status.version.pathExecutionWorkaroundCommand} <command>`
+              );
+            }
+          }
           writeInfo(`[pumuki] lifecycle installed: ${status.lifecycleState.installed ?? 'false'}`);
           writeInfo(
             `[pumuki] hooks path: ${status.hooksDirectory} (${status.hooksDirectoryResolution})`

package/integrations/lifecycle/packageInfo.ts

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { delimiter, join } from 'node:path';
 import packageJson from '../../package.json';
 
 const readConsumerInstalledVersion = (repoRoot: string): string | null => {
@@ -34,10 +34,31 @@ export type LifecycleVersionReport = {
   driftFromLifecycleInstalled: boolean;
   driftWarning: string | null;
   alignmentCommand: string | null;
+  pathExecutionHazard: boolean;
+  pathExecutionWarning: string | null;
+  pathExecutionWorkaroundCommand: string | null;
 };
 
-export const buildLifecycleAlignmentCommand = (runtimeVersion: string): string =>
-  `npm install --save-exact pumuki@${runtimeVersion} && npx --yes --package pumuki@${runtimeVersion} pumuki install`;
+const buildLocalPumukiCommand = (): string =>
+  process.platform === 'win32'
+    ? 'node .\\node_modules\\pumuki\\bin\\pumuki.js'
+    : 'node ./node_modules/pumuki/bin/pumuki.js';
+
+const hasPathExecutionHazard = (repoRoot?: string): boolean =>
+  typeof repoRoot === 'string' &&
+  repoRoot.trim().length > 0 &&
+  repoRoot.includes(delimiter);
+
+export const buildLifecycleAlignmentCommand = (
+  runtimeVersion: string,
+  repoRoot?: string
+): string => {
+  const installStep = `npm install --save-exact pumuki@${runtimeVersion}`;
+  const runStep = hasPathExecutionHazard(repoRoot)
+    ? `${buildLocalPumukiCommand()} install`
+    : `npx --yes --package pumuki@${runtimeVersion} pumuki install`;
+  return `${installStep} && ${runStep}`;
+};
 
 export const resolvePumukiVersionMetadata = (params?: { repoRoot?: string }): PumukiVersionMetadata => {
   const runtimeVersion = packageJson.version;
@@ -83,6 +104,8 @@ export const buildLifecycleVersionReport = (params?: {
     driftFromRuntime ? `runtime=${metadata.runtimeVersion}` : null,
     driftFromLifecycleInstalled ? `lifecycle=${lifecycleInstalled}` : null,
   ].filter((value): value is string => value !== null);
+  const pathExecutionHazard = hasPathExecutionHazard(params?.repoRoot);
+  const pathExecutionWorkaroundCommand = pathExecutionHazard ? buildLocalPumukiCommand() : null;
 
   return {
     effective: metadata.resolvedVersion,
@@ -97,6 +120,13 @@ export const buildLifecycleVersionReport = (params?: {
         ? `Version drift detectado: effective=${metadata.resolvedVersion} ${driftTargets.join(' ')}.`
         : null,
     alignmentCommand:
-      driftTargets.length > 0 ? buildLifecycleAlignmentCommand(metadata.runtimeVersion) : null,
+      driftTargets.length > 0
+        ? buildLifecycleAlignmentCommand(metadata.runtimeVersion, params?.repoRoot)
+        : null,
+    pathExecutionHazard,
+    pathExecutionWarning: pathExecutionHazard
+      ? `La ruta del repositorio contiene "${delimiter}", que rompe PATH en este sistema y puede hacer fallar invocaciones con npx/npm exec.`
+      : null,
+    pathExecutionWorkaroundCommand,
   };
 };

package/package.json

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