pumuki 6.3.39 → 6.3.41

package/integrations/sdd/syncDocs.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
 import { readEvidenceResult, type EvidenceReadResult } from '../evidence/readEvidence';
 import { readSddStatus } from './policy';
 import type { SddStage } from './types';
@@ -48,6 +48,7 @@ export type SddSyncDocsResult = {
     change: string | null;
     stage: SddStage | null;
     task: string | null;
+    fromEvidencePath: string | null;
   };
   updated: boolean;
   files: ReadonlyArray<SddSyncDocsFileResult>;
@@ -65,6 +66,14 @@ export type SddSyncDocsResult = {
       successful_patterns: string[];
       rule_updates: string[];
       gate_anomalies: string[];
+      scoring: {
+        profile: 'heuristic-v1';
+        score: number;
+        successful_count: number;
+        failed_count: number;
+        anomaly_count: number;
+        rule_update_count: number;
+      };
       sync_docs: {
         updated: boolean;
         file_paths: string[];
@@ -81,6 +90,7 @@ export type SddLearnResult = {
     change: string;
     stage: SddStage | null;
     task: string | null;
+    fromEvidencePath: string | null;
   };
   learning: NonNullable<SddSyncDocsResult['learning']>;
 };
@@ -93,6 +103,7 @@ export type SddAutoSyncResult = {
     change: string;
     stage: SddStage | null;
     task: string | null;
+    fromEvidencePath: string | null;
   };
   syncDocs: {
     updated: boolean;
@@ -106,6 +117,28 @@ const normalizeSectionBody = (value: string): string => value.trim().replace(/\r
 const computeDigest = (value: string): string =>
   createHash('sha256').update(value, 'utf8').digest('hex');
 
+const resolveRepoBoundPath = (params: {
+  repoRoot: string;
+  candidatePath: string;
+  flagName: '--from-evidence';
+}): string => {
+  const repoRootAbsolute = resolve(params.repoRoot);
+  const resolved = isAbsolute(params.candidatePath)
+    ? resolve(params.candidatePath)
+    : resolve(repoRootAbsolute, params.candidatePath);
+  const rel = relative(repoRootAbsolute, resolved);
+  if (
+    rel === '..' ||
+    rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) ||
+    isAbsolute(rel)
+  ) {
+    throw new Error(
+      `[pumuki][sdd] ${params.flagName} must resolve inside repository root: ${params.candidatePath}`
+    );
+  }
+  return resolved;
+};
+
 const prefixLines = (value: string, marker: '-' | '+'): string =>
   value
     .split('\n')
@@ -281,12 +314,42 @@ const collectLearningSignals = (params: {
   };
 };
 
+const toLearningScore = (params: {
+  successfulPatterns: string[];
+  failedPatterns: string[];
+  gateAnomalies: string[];
+  ruleUpdates: string[];
+}): {
+  profile: 'heuristic-v1';
+  score: number;
+  successful_count: number;
+  failed_count: number;
+  anomaly_count: number;
+  rule_update_count: number;
+} => {
+  const successfulCount = params.successfulPatterns.length;
+  const failedCount = params.failedPatterns.length;
+  const anomalyCount = params.gateAnomalies.length;
+  const ruleUpdateCount = params.ruleUpdates.length;
+  const rawScore = 100 + successfulCount * 4 - failedCount * 25 - anomalyCount * 10 - ruleUpdateCount * 5;
+  const score = Math.max(0, Math.min(100, rawScore));
+  return {
+    profile: 'heuristic-v1',
+    score,
+    successful_count: successfulCount,
+    failed_count: failedCount,
+    anomaly_count: anomalyCount,
+    rule_update_count: ruleUpdateCount,
+  };
+};
+
 export const runSddSyncDocs = (params?: {
   repoRoot?: string;
   dryRun?: boolean;
   change?: string;
   stage?: SddStage;
   task?: string;
+  fromEvidencePath?: string;
   targets?: ReadonlyArray<SddSyncDocsTarget>;
   now?: () => Date;
   evidenceReader?: (repoRoot: string) => EvidenceReadResult;
@@ -296,9 +359,27 @@ export const runSddSyncDocs = (params?: {
   const change = params?.change?.trim() ? params.change.trim() : null;
   const stage = params?.stage ?? null;
   const task = params?.task?.trim() ? params.task.trim() : null;
+  const fromEvidencePath = params?.fromEvidencePath?.trim()
+    ? params.fromEvidencePath.trim()
+    : null;
+  const fromEvidenceAbsolutePath = fromEvidencePath
+    ? resolveRepoBoundPath({
+      repoRoot,
+      candidatePath: fromEvidencePath,
+      flagName: '--from-evidence',
+    })
+    : null;
   const targets = params?.targets ?? DEFAULT_SYNC_DOCS_TARGETS;
   const now = params?.now ?? (() => new Date());
-  const evidenceReader = params?.evidenceReader ?? readEvidenceResult;
+  const evidenceReader =
+    params?.evidenceReader ??
+    ((candidateRepoRoot: string) =>
+      readEvidenceResult(
+        candidateRepoRoot,
+        fromEvidenceAbsolutePath
+          ? { evidencePath: fromEvidenceAbsolutePath }
+          : undefined
+      ));
 
   const updates = targets.map((target) => {
     const absolutePath = resolve(repoRoot, target.path);
@@ -362,6 +443,12 @@ export const runSddSyncDocs = (params?: {
       updated,
       evidenceResult: evidenceReader(repoRoot),
     });
+    const scoring = toLearningScore({
+      successfulPatterns: signals.successfulPatterns,
+      failedPatterns: signals.failedPatterns,
+      gateAnomalies: signals.gateAnomalies,
+      ruleUpdates: signals.ruleUpdates,
+    });
     const artifact = {
       version: '1.0' as const,
       change_id: change,
@@ -372,6 +459,7 @@ export const runSddSyncDocs = (params?: {
       successful_patterns: signals.successfulPatterns,
       rule_updates: signals.ruleUpdates,
       gate_anomalies: signals.gateAnomalies,
+      scoring,
       sync_docs: {
         updated,
         file_paths: files.map((file) => file.path),
@@ -401,6 +489,7 @@ export const runSddSyncDocs = (params?: {
       change,
       stage,
       task,
+      fromEvidencePath,
     },
     updated,
     files,
@@ -414,6 +503,7 @@ export const runSddLearn = (params?: {
   change?: string;
   stage?: SddStage;
   task?: string;
+  fromEvidencePath?: string;
   now?: () => Date;
   evidenceReader?: (repoRoot: string) => EvidenceReadResult;
 }): SddLearnResult => {
@@ -428,6 +518,7 @@ export const runSddLearn = (params?: {
     change,
     stage: params?.stage,
     task: params?.task,
+    fromEvidencePath: params?.fromEvidencePath,
     now: params?.now,
     evidenceReader: params?.evidenceReader,
     targets: [],
@@ -445,6 +536,7 @@ export const runSddLearn = (params?: {
       change,
       stage: result.context.stage,
       task: result.context.task,
+      fromEvidencePath: result.context.fromEvidencePath,
     },
     learning: result.learning,
   };
@@ -456,6 +548,7 @@ export const runSddAutoSync = (params?: {
   change?: string;
   stage?: SddStage;
   task?: string;
+  fromEvidencePath?: string;
   now?: () => Date;
   evidenceReader?: (repoRoot: string) => EvidenceReadResult;
   targets?: ReadonlyArray<SddSyncDocsTarget>;
@@ -471,6 +564,7 @@ export const runSddAutoSync = (params?: {
     change,
     stage: params?.stage,
     task: params?.task,
+    fromEvidencePath: params?.fromEvidencePath,
     now: params?.now,
     evidenceReader: params?.evidenceReader,
     targets: params?.targets,
@@ -488,6 +582,7 @@ export const runSddAutoSync = (params?: {
       change,
       stage: syncResult.context.stage,
       task: syncResult.context.task,
+      fromEvidencePath: syncResult.context.fromEvidencePath,
     },
     syncDocs: {
       updated: syncResult.updated,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pumuki",
-  "version": "6.3.39",
+  "version": "6.3.41",
   "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": {
@@ -49,6 +49,7 @@
     "test:heuristics": "npx --yes tsx@4.21.0 --test core/facts/__tests__/extractHeuristicFacts.test.ts",
     "test:evidence": "npx --yes tsx@4.21.0 --test integrations/evidence/__tests__/buildEvidence.test.ts integrations/evidence/__tests__/humanIntent.test.ts",
     "test:mcp": "npx --yes tsx@4.21.0 --test integrations/mcp/__tests__/*.test.ts",
+    "test:backlog-tooling": "npx --yes tsx@4.21.0 --test scripts/__tests__/backlog-action-reasons-lib.test.ts scripts/__tests__/backlog-json-contract-lib.test.ts scripts/__tests__/backlog-cli-help-exit-code.test.ts scripts/__tests__/backlog-id-issue-map-lib.test.ts scripts/__tests__/reconcile-consumer-backlog-issues.test.ts scripts/__tests__/watch-consumer-backlog.test.ts",
     "test:saas-ingestion": "npx --yes tsx@4.21.0 --test integrations/lifecycle/__tests__/saasIngestionContract.test.ts integrations/lifecycle/__tests__/saasIngestionBuilder.test.ts integrations/lifecycle/__tests__/saasIngestionTransport.test.ts integrations/lifecycle/__tests__/saasIngestionIdempotency.test.ts integrations/lifecycle/__tests__/saasIngestionAuth.test.ts integrations/lifecycle/__tests__/saasIngestionAudit.test.ts integrations/lifecycle/__tests__/saasIngestionMetrics.test.ts integrations/lifecycle/__tests__/saasIngestionGovernance.test.ts integrations/lifecycle/__tests__/saasFederation.test.ts integrations/lifecycle/__tests__/saasEnterpriseAnalytics.test.ts integrations/lifecycle/__tests__/cli.test.ts",
     "test:operational-memory": "npx --yes tsx@4.21.0 --test integrations/lifecycle/__tests__/operationalMemoryContract.test.ts integrations/lifecycle/__tests__/operationalMemorySignals.test.ts integrations/lifecycle/__tests__/operationalMemorySnapshot.test.ts integrations/git/__tests__/runPlatformGate.test.ts integrations/git/__tests__/runPlatformGateEvidence.test.ts integrations/evidence/__tests__/buildEvidence.test.ts integrations/evidence/writeEvidence.test.ts integrations/evidence/generateEvidence.test.ts",
     "test:stage-gates": "npx --yes tsx@4.21.0 --test integrations/config/__tests__/*.test.ts integrations/gate/__tests__/*.test.ts integrations/git/__tests__/*.test.ts integrations/lifecycle/__tests__/*.test.ts integrations/sdd/__tests__/*.test.ts scripts/__tests__/*.test.ts",
@@ -98,6 +99,8 @@
     "validation:phase8:close-ready": "bash scripts/run-phase8-close-ready.sh",
     "validation:progress-single-active": "bash scripts/check-refactor-progress-single-active.sh",
     "validation:tracking-single-active": "bash scripts/check-tracking-single-active.sh",
+    "validation:backlog-reconcile": "node --import tsx scripts/reconcile-consumer-backlog-issues.ts",
+    "validation:backlog-watch": "node --import tsx scripts/watch-consumer-backlog.ts",
     "validation:phase5-escalation:ready-to-submit": "bash scripts/check-phase5-escalation-ready-to-submit.sh",
     "validation:phase5-escalation:prepare": "bash scripts/prepare-phase5-escalation-submission.sh",
     "validation:phase5-escalation:close-submission": "bash scripts/close-phase5-escalation-submission.sh",

package/scripts/backlog-action-reasons-lib.ts

@@ -0,0 +1,38 @@
+export type WatchActionReason =
+  | 'needs_issue'
+  | 'drift_closed_issue'
+  | 'heading_drift';
+
+export type ReconcileActionReason =
+  | 'reference_changes'
+  | 'issue_changes'
+  | 'heading_changes'
+  | 'summary_updated'
+  | 'next_step_updated';
+
+export const buildWatchActionRequiredReasons = (input: {
+  needsIssueCount: number;
+  driftClosedIssueCount: number;
+  headingDriftCount: number;
+}): ReadonlyArray<WatchActionReason> => [
+  ...(input.needsIssueCount > 0 ? (['needs_issue'] as const) : []),
+  ...(input.driftClosedIssueCount > 0 ? (['drift_closed_issue'] as const) : []),
+  ...(input.headingDriftCount > 0 ? (['heading_drift'] as const) : []),
+];
+
+export const buildReconcileActionRequiredReasons = (input: {
+  referenceChangesCount: number;
+  issueChangesCount: number;
+  headingChangesCount: number;
+  summaryUpdated: boolean;
+  nextStepUpdated: boolean;
+}): ReadonlyArray<ReconcileActionReason> => [
+  ...(input.referenceChangesCount > 0 ? (['reference_changes'] as const) : []),
+  ...(input.issueChangesCount > 0 ? (['issue_changes'] as const) : []),
+  ...(input.headingChangesCount > 0 ? (['heading_changes'] as const) : []),
+  ...(input.summaryUpdated ? (['summary_updated'] as const) : []),
+  ...(input.nextStepUpdated ? (['next_step_updated'] as const) : []),
+];
+
+export const formatActionReasonsForHuman = (reasons: ReadonlyArray<string>): string =>
+  reasons.length > 0 ? reasons.join(',') : 'none';

package/scripts/backlog-id-issue-map-lib.ts

@@ -0,0 +1,69 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export const BACKLOG_ID_PATTERN = /^(PUMUKI-(?:M)?\d+|PUMUKI-INC-\d+|FP-\d+|AST-GAP-\d+)$/;
+
+export type BacklogIdIssueMapRecord = Readonly<Record<string, number>>;
+
+const parsePositiveIssueNumber = (value: unknown): number | null => {
+  if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+    return Math.trunc(value);
+  }
+  if (typeof value === 'string') {
+    const parsed = Number.parseInt(value, 10);
+    if (Number.isFinite(parsed) && parsed > 0) {
+      return parsed;
+    }
+  }
+  return null;
+};
+
+export const parseIdIssueMapRecord = (raw: string): BacklogIdIssueMapRecord => {
+  const parsed = JSON.parse(raw) as Record<string, unknown>;
+  const normalized: Record<string, number> = {};
+  for (const [id, value] of Object.entries(parsed)) {
+    if (!BACKLOG_ID_PATTERN.test(id)) {
+      throw new Error(`Invalid id in --id-issue-map: "${id}"`);
+    }
+    const issueNumber = parsePositiveIssueNumber(value);
+    if (issueNumber === null) {
+      throw new Error(`Invalid issue number for "${id}" in --id-issue-map`);
+    }
+    normalized[id] = issueNumber;
+  }
+  return normalized;
+};
+
+export const parseIdIssueMapRecordFile = (
+  filePath: string,
+  readFile: (path: string) => string = (path) => readFileSync(path, 'utf8')
+): BacklogIdIssueMapRecord => {
+  const resolvedPath = resolve(filePath);
+  return parseIdIssueMapRecord(readFile(resolvedPath));
+};
+
+export const mergeIdIssueMapRecords = (
+  base?: BacklogIdIssueMapRecord,
+  override?: BacklogIdIssueMapRecord
+): BacklogIdIssueMapRecord | undefined => {
+  if (!base && !override) {
+    return undefined;
+  }
+  return {
+    ...(base ?? {}),
+    ...(override ?? {}),
+  };
+};
+
+export const recordToIdIssueMap = (
+  record?: BacklogIdIssueMapRecord
+): ReadonlyMap<string, number> | undefined => {
+  if (!record) {
+    return undefined;
+  }
+  const map = new Map<string, number>();
+  for (const [id, issue] of Object.entries(record)) {
+    map.set(id, Math.trunc(issue));
+  }
+  return map;
+};

package/scripts/backlog-json-contract-lib.ts

@@ -0,0 +1,3 @@
+export const BACKLOG_JSON_SCHEMA_VERSION = '1.0.0';
+export const BACKLOG_JSON_COMPAT_MIN_READER_VERSION = '1.0.0';
+export const BACKLOG_JSON_COMPAT_CONTRACT_ID = 'backlog-tooling-json-v1';

package/scripts/framework-menu-consumer-preflight-lib.ts

@@ -60,6 +60,12 @@ const ACTIONABLE_HINTS_BY_CODE: Readonly<Record<string, string>> = {
   EVIDENCE_RULES_COVERAGE_STAGE_MISMATCH: 'reanuda auditoría en el stage correcto.',
   EVIDENCE_RULES_COVERAGE_INCOMPLETE:
     'asegura unevaluated=0 y coverage_ratio=1 antes de continuar.',
+  EVIDENCE_SKILLS_CONTRACT_INCOMPLETE:
+    'completa contrato de skills/policy para el stage actual y vuelve a validar.',
+  EVIDENCE_PREWRITE_WORKTREE_OVER_LIMIT:
+    'reduce el worktree pendiente en slices atómicos y vuelve a ejecutar PRE_WRITE.',
+  EVIDENCE_PREWRITE_WORKTREE_WARN:
+    'conviene particionar cambios ahora para evitar bloqueo tardío en commit/push.',
   EVIDENCE_UNSUPPORTED_AUTO_RULES:
     'mapea todas las reglas AUTO a detectores AST antes de continuar.',
   EVIDENCE_TIMESTAMP_FUTURE: 'corrige la hora del sistema y regenera evidencia.',

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

@@ -1,6 +1,6 @@
 import { execFileSync as runBinarySync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 
 export type PumukiNotificationStage = 'PRE_COMMIT' | 'PRE_PUSH' | 'CI' | 'PRE_WRITE';
 
@@ -41,6 +41,7 @@ export type SystemNotificationsConfig = {
   enabled: boolean;
   channel: 'macos';
   muteUntil?: string;
+  blockedDialogEnabled?: boolean;
 };
 
 export type SystemNotificationEmitResult =
@@ -110,6 +111,37 @@ const isTruthyFlag = (value?: string): boolean => {
   return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on';
 };
 
+const resolveProjectLabel = (params: {
+  repoRoot?: string;
+  projectLabel?: string;
+}): string | null => {
+  const explicit = params.projectLabel
+    ? normalizeNotificationText(params.projectLabel)
+    : '';
+  if (explicit.length > 0) {
+    return truncateNotificationText(explicit, 28);
+  }
+  if (!params.repoRoot) {
+    return null;
+  }
+  const inferred = normalizeNotificationText(basename(params.repoRoot));
+  if (inferred.length === 0) {
+    return null;
+  }
+  return truncateNotificationText(inferred, 28);
+};
+
+const resolveBlockedDialogEnabled = (params: {
+  env: NodeJS.ProcessEnv;
+  config: SystemNotificationsConfig;
+}): boolean => {
+  const raw = params.env.PUMUKI_MACOS_BLOCKED_DIALOG;
+  if (typeof raw === 'string' && raw.trim().length > 0) {
+    return isTruthyFlag(raw);
+  }
+  return params.config.blockedDialogEnabled !== false;
+};
+
 const BLOCKED_CAUSE_SUMMARY_BY_CODE: Readonly<Record<string, string>> = {
   EVIDENCE_MISSING: 'Falta evidencia para validar este paso.',
   EVIDENCE_INVALID: 'La evidencia actual es inválida.',
@@ -253,6 +285,7 @@ export const buildSystemNotificationsConfigFromSelection = (
 ): SystemNotificationsConfig => ({
   enabled,
   channel: 'macos',
+  blockedDialogEnabled: true,
 });
 
 export const persistSystemNotificationsConfig = (repoRoot: string, enabled: boolean): string => {
@@ -273,10 +306,12 @@ export const readSystemNotificationsConfig = (repoRoot: string): SystemNotificat
       enabled?: unknown;
       channel?: unknown;
       muteUntil?: unknown;
+      blockedDialogEnabled?: unknown;
     };
     const config: SystemNotificationsConfig = {
       enabled: parsed.enabled === true,
       channel: 'macos',
+      blockedDialogEnabled: parsed.blockedDialogEnabled !== false,
     };
     if (typeof parsed.muteUntil === 'string' && parsed.muteUntil.trim().length > 0) {
       config.muteUntil = parsed.muteUntil;
@@ -319,6 +354,7 @@ const applyDialogChoice = (params: {
     persistSystemNotificationsConfigFile(params.repoRoot, {
       enabled: false,
       channel: params.config.channel,
+      blockedDialogEnabled: params.config.blockedDialogEnabled !== false,
     });
     return;
   }
@@ -329,13 +365,24 @@ const applyDialogChoice = (params: {
       enabled: true,
       channel: params.config.channel,
       muteUntil,
+      blockedDialogEnabled: params.config.blockedDialogEnabled !== false,
     });
   }
 };
 
 export const buildSystemNotificationPayload = (
-  event: PumukiCriticalNotificationEvent
+  event: PumukiCriticalNotificationEvent,
+  context?: {
+    repoRoot?: string;
+    projectLabel?: string;
+  }
 ): SystemNotificationPayload => {
+  const projectLabel = resolveProjectLabel({
+    repoRoot: context?.repoRoot,
+    projectLabel: context?.projectLabel,
+  });
+  const projectPrefix = projectLabel ? `${projectLabel} · ` : '';
+
   if (event.kind === 'audit.summary') {
     if (event.criticalViolations > 0) {
       return {
@@ -370,7 +417,7 @@ export const buildSystemNotificationPayload = (
     const remediation = resolveBlockedRemediation(event, causeCode);
     return {
       title: '🔴 Pumuki bloqueado',
-      subtitle: `${event.stage} · ${causeSummary}`,
+      subtitle: `${projectPrefix}${event.stage} · ${causeSummary}`,
       message: `Solución: ${remediation}`,
       soundName: 'Basso',
     };
@@ -418,7 +465,10 @@ export const emitSystemNotification = (params: {
   }
 
   const runner = params.runCommand ?? runSystemCommand;
-  const payload = buildSystemNotificationPayload(params.event);
+  const payload = buildSystemNotificationPayload(params.event, {
+    repoRoot: params.repoRoot,
+    projectLabel: params.env?.PUMUKI_PROJECT_LABEL,
+  });
   const script = buildDisplayNotificationScript(payload);
   const exitCode = runner('osascript', ['-e', script]);
 
@@ -427,12 +477,22 @@ export const emitSystemNotification = (params: {
   }
 
   const env = params.env ?? process.env;
-  if (params.event.kind === 'gate.blocked' && isTruthyFlag(env.PUMUKI_MACOS_BLOCKED_DIALOG)) {
+  if (
+    params.event.kind === 'gate.blocked'
+    && resolveBlockedDialogEnabled({ env, config })
+  ) {
     const causeCode = params.event.causeCode ?? 'GATE_BLOCKED';
     const cause = resolveBlockedCauseSummary(params.event, causeCode);
     const remediation = resolveBlockedRemediation(params.event, causeCode);
+    const projectLabel = resolveProjectLabel({
+      repoRoot: params.repoRoot,
+      projectLabel: env.PUMUKI_PROJECT_LABEL,
+    });
+    const dialogTitle = projectLabel
+      ? `🔴 Pumuki bloqueado · ${projectLabel}`
+      : '🔴 Pumuki bloqueado';
     const dialogScript = buildDisplayDialogScript({
-      title: '🔴 Pumuki bloqueado',
+      title: dialogTitle,
       cause,
       remediation,
     });

package/scripts/package-install-smoke-command-resolution-lib.ts

@@ -0,0 +1,64 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export type SmokeCommandResolution =
+  | 'local-bin'
+  | 'local-node-entry'
+  | 'npx-package';
+
+export type ResolvedSmokeCommand = {
+  executable: string;
+  args: string[];
+  resolution: SmokeCommandResolution;
+};
+
+const resolveLocalBinPath = (consumerRepo: string, binary: string): string | null => {
+  const candidates =
+    process.platform === 'win32'
+      ? [join(consumerRepo, 'node_modules', '.bin', `${binary}.cmd`), join(consumerRepo, 'node_modules', '.bin', binary)]
+      : [join(consumerRepo, 'node_modules', '.bin', binary)];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+};
+
+const resolveLocalNodeEntrypoint = (consumerRepo: string, binary: string): string | null => {
+  const entrypoint = join(consumerRepo, 'node_modules', 'pumuki', 'bin', `${binary}.js`);
+  return existsSync(entrypoint) ? entrypoint : null;
+};
+
+export const resolveConsumerPumukiCommand = (params: {
+  consumerRepo: string;
+  binary: string;
+  args?: ReadonlyArray<string>;
+}): ResolvedSmokeCommand => {
+  const args = [...(params.args ?? [])];
+  const localBinPath = resolveLocalBinPath(params.consumerRepo, params.binary);
+  if (localBinPath) {
+    return {
+      executable: localBinPath,
+      args,
+      resolution: 'local-bin',
+    };
+  }
+
+  const localEntrypoint = resolveLocalNodeEntrypoint(params.consumerRepo, params.binary);
+  if (localEntrypoint) {
+    return {
+      executable: 'node',
+      args: [localEntrypoint, ...args],
+      resolution: 'local-node-entry',
+    };
+  }
+
+  return {
+    executable: 'npx',
+    args: ['--yes', '--package', 'pumuki@latest', params.binary, ...args],
+    resolution: 'npx-package',
+  };
+};

package/scripts/package-install-smoke-consumer-npm-lib.ts

@@ -1,6 +1,7 @@
 import { writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import {
+  assertNoFatalOutput,
   assertSuccess,
   runCommand,
 } from './package-install-smoke-runner-common';
@@ -8,6 +9,7 @@ import {
   pushCommandLog,
   type SmokeWorkspace,
 } from './package-install-smoke-workspace-lib';
+import { resolveConsumerPumukiCommand } from './package-install-smoke-command-resolution-lib';
 import packageJson from '../package.json';
 
 const runNpmStep = (
@@ -45,3 +47,44 @@ export const verifyInstalledPackageCanBeRequired = (
   pushCommandLog(workspace.commandLog, installCheck);
   assertSuccess(installCheck, 'package require smoke');
 };
+
+export const verifyInstalledPumukiBinaryVersion = (
+  workspace: SmokeWorkspace
+): void => {
+  const noInstallVersionCheck = runCommand({
+    cwd: workspace.consumerRepo,
+    executable: 'npx',
+    args: ['--no-install', 'pumuki', '--version'],
+  });
+  pushCommandLog(workspace.commandLog, noInstallVersionCheck);
+
+  const noInstallPassed =
+    noInstallVersionCheck.exitCode === 0
+    && !/Cannot find module|ERR_MODULE_NOT_FOUND|failed to resolve tsx runtime/.test(
+      noInstallVersionCheck.combined
+    );
+  if (noInstallPassed) {
+    assertNoFatalOutput(noInstallVersionCheck, 'pumuki --version smoke');
+    return;
+  }
+
+  const fallback = resolveConsumerPumukiCommand({
+    consumerRepo: workspace.consumerRepo,
+    binary: 'pumuki',
+    args: ['--version'],
+  });
+  const fallbackCheck = runCommand({
+    cwd: workspace.consumerRepo,
+    executable: fallback.executable,
+    args: fallback.args,
+  });
+  pushCommandLog(workspace.commandLog, fallbackCheck);
+  assertSuccess(
+    fallbackCheck,
+    `pumuki --version smoke fallback (${fallback.resolution})`
+  );
+  assertNoFatalOutput(
+    fallbackCheck,
+    `pumuki --version smoke fallback (${fallback.resolution})`
+  );
+};

package/scripts/package-install-smoke-consumer-repo-setup-lib.ts

@@ -11,6 +11,7 @@ import {
 import {
   installTarballIntoConsumerRepo,
   verifyInstalledPackageCanBeRequired,
+  verifyInstalledPumukiBinaryVersion,
 } from './package-install-smoke-consumer-npm-lib';
 import type { SmokeWorkspace } from './package-install-smoke-workspace-lib';
 
@@ -23,6 +24,7 @@ export const setupConsumerRepository = (
   initializeConsumerGitRepository(workspace);
   installTarballIntoConsumerRepo(workspace);
   verifyInstalledPackageCanBeRequired(workspace);
+  verifyInstalledPumukiBinaryVersion(workspace);
   commitBaseline(workspace);
   configureRemoteAndFeatureBranch(workspace);
   writeAndCommitRangePayloadForBlockMode(workspace, mode);