pumuki 6.3.39 → 6.3.40

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.40",
   "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/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);

package/scripts/package-install-smoke-execution-steps-lib.ts

@@ -1,5 +1,6 @@
 import type { SmokeExpectation } from './package-install-smoke-contract';
 import { runGateStep, type SmokeGateStep } from './package-install-smoke-gate-lib';
+import { resolveConsumerPumukiCommand } from './package-install-smoke-command-resolution-lib';
 import type { SmokeWorkspace } from './package-install-smoke-workspace-contract';
 
 export type SmokeStepResult = {
@@ -8,25 +9,30 @@ export type SmokeStepResult = {
   exitCode: number;
 };
 
-export const DEFAULT_SMOKE_GATE_STEPS: ReadonlyArray<SmokeGateStep> = [
+type SmokeGateStepDescriptor = {
+  label: SmokeGateStep['label'];
+  binary: string;
+  args?: ReadonlyArray<string>;
+  evidenceFile: SmokeGateStep['evidenceFile'];
+  stage: SmokeGateStep['stage'];
+};
+
+export const DEFAULT_SMOKE_GATE_STEPS: ReadonlyArray<SmokeGateStepDescriptor> = [
   {
     label: 'pre-commit',
-    command: 'npx',
-    args: ['--yes', 'pumuki-pre-commit'],
+    binary: 'pumuki-pre-commit',
     evidenceFile: 'pre-commit.ai_evidence.json',
     stage: 'PRE_COMMIT',
   },
   {
     label: 'pre-push',
-    command: 'npx',
-    args: ['--yes', 'pumuki-pre-push'],
+    binary: 'pumuki-pre-push',
     evidenceFile: 'pre-push.ai_evidence.json',
     stage: 'PRE_PUSH',
   },
   {
     label: 'ci',
-    command: 'npx',
-    args: ['--yes', 'pumuki-ci'],
+    binary: 'pumuki-ci',
     evidenceFile: 'ci.ai_evidence.json',
     stage: 'CI',
   },
@@ -36,10 +42,22 @@ export const runDefaultSmokeGateSteps = (params: {
   workspace: SmokeWorkspace;
   expectation: SmokeExpectation;
 }): ReadonlyArray<SmokeStepResult> =>
-  DEFAULT_SMOKE_GATE_STEPS.map((step) => {
+  DEFAULT_SMOKE_GATE_STEPS.map((stepDescriptor) => {
+    const resolvedCommand = resolveConsumerPumukiCommand({
+      consumerRepo: params.workspace.consumerRepo,
+      binary: stepDescriptor.binary,
+      args: stepDescriptor.args,
+    });
+    const step: SmokeGateStep = {
+      label: stepDescriptor.label,
+      command: resolvedCommand.executable,
+      args: resolvedCommand.args,
+      evidenceFile: stepDescriptor.evidenceFile,
+      stage: stepDescriptor.stage,
+    };
     const result = runGateStep(params.workspace, step, params.expectation);
     return {
-      label: step.label,
+      label: stepDescriptor.label,
       outcome: result.outcome,
       exitCode: result.exitCode,
     };

package/scripts/package-install-smoke-lifecycle-lib.ts

@@ -3,6 +3,7 @@ import {
   assertSuccess,
   runCommand,
 } from './package-install-smoke-runner-common';
+import { resolveConsumerPumukiCommand } from './package-install-smoke-command-resolution-lib';
 import { pushCommandLog, type SmokeWorkspace } from './package-install-smoke-workspace-lib';
 
 const normalizeStatus = (value: string): string =>
@@ -27,10 +28,15 @@ export const captureLifecycleStatusSnapshot = (workspace: SmokeWorkspace): strin
   getShortStatus(workspace);
 
 export const runLifecycleInstallStep = (workspace: SmokeWorkspace): void => {
+  const command = resolveConsumerPumukiCommand({
+    consumerRepo: workspace.consumerRepo,
+    binary: 'pumuki',
+    args: ['install'],
+  });
   const result = runCommand({
     cwd: workspace.consumerRepo,
-    executable: 'npx',
-    args: ['--yes', 'pumuki', 'install'],
+    executable: command.executable,
+    args: command.args,
     env: {
       PUMUKI_SKIP_OPENSPEC_BOOTSTRAP: '1',
     },
@@ -41,10 +47,15 @@ export const runLifecycleInstallStep = (workspace: SmokeWorkspace): void => {
 };
 
 export const runLifecycleUninstallStep = (workspace: SmokeWorkspace): void => {
+  const command = resolveConsumerPumukiCommand({
+    consumerRepo: workspace.consumerRepo,
+    binary: 'pumuki',
+    args: ['uninstall', '--purge-artifacts'],
+  });
   const result = runCommand({
     cwd: workspace.consumerRepo,
-    executable: 'npx',
-    args: ['--yes', 'pumuki', 'uninstall', '--purge-artifacts'],
+    executable: command.executable,
+    args: command.args,
   });
   pushCommandLog(workspace.commandLog, result);
   assertNoFatalOutput(result, 'pumuki lifecycle uninstall');

package/scripts/package-install-smoke-workspace-factory-lib.ts

@@ -15,7 +15,10 @@ export const createSmokeWorkspace = (mode: SmokeMode): SmokeWorkspace => {
   ensureDirectory(reportRoot);
 
   const tmpRoot = mkdtempSync(join(tmpdir(), 'pumuki-package-smoke-'));
-  const consumerRepo = join(tmpRoot, 'consumer');
+  const consumerRepo = join(
+    tmpRoot,
+    process.platform === 'win32' ? 'consumer' : 'consumer:repo'
+  );
   const bareRemote = join(tmpRoot, 'origin.git');
 
   return {