pumuki 6.3.89 → 6.3.91

package/docs/operations/RELEASE_NOTES.md

@@ -1,3 +1,7 @@
+## 2026-04-20 (v6.3.91)
+- **Observabilidad de skills alineada**: `status --json` y `doctor --json` dejan visible `governanceObservation.skills_contract` cuando la evidencia y el lock efectivo de skills muestran un contrato activo; el lifecycle ya no aparenta `NOT_APPLICABLE` mientras el gate real bloquea violaciones frontend/backend.
+- **Rollout recomendado**: publicar `pumuki@6.3.91`, repin inmediato en `Flux_training` y repetir la repro con rojo frontend staged para confirmar `skills_contract.enforced=true`, `skills_contract.status=FAIL` y `attention_codes` con `SKILLS_CONTRACT_INCOMPLETE`.
+
 ## 2026-04-20 (v6.3.89)
 - **Aislamiento por worktree**: `pumuki install` detecta worktrees sin `core.hooksPath` explícito y fija un `core.hooksPath` local a `.pumuki/git-hooks`, evitando que los hooks gestionados se escriban en `.git/hooks` del checkout principal compartido.
 - **Rollback limpio**: `pumuki uninstall` retira ese `core.hooksPath` solo si fue creado por Pumuki para el worktree.

package/integrations/lifecycle/governanceObservationSnapshot.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { readEvidenceResult } from '../evidence/readEvidence';
 import { readRepoTrackingState } from '../evidence/trackingContract';
 import type { RepoTrackingState } from '../evidence/schema';
+import { loadRequiredSkillsLock } from '../config/skillsEffectiveLock';
 import { readSddStatus } from '../sdd';
 import type { SddStatusPayload } from '../sdd/types';
 import type { LifecycleExperimentalFeaturesSnapshot } from './experimentalFeaturesSnapshot';
@@ -25,6 +26,37 @@ export type GovernanceEvidenceSummary = {
   human_summary_preview: string[];
 };
 
+type GovernanceSkillsContractPlatform = 'ios' | 'android' | 'backend' | 'frontend';
+
+type GovernanceSkillsContractViolation = {
+  code: string;
+  message: string;
+  severity: 'ERROR' | 'WARN';
+};
+
+type GovernanceSkillsContractPlatformRequirement = {
+  platform: GovernanceSkillsContractPlatform;
+  required_rule_prefix: string;
+  required_bundles: ReadonlyArray<string>;
+  required_critical_rule_ids: ReadonlyArray<string>;
+  required_any_transversal_critical_rule_ids: ReadonlyArray<string>;
+  active_prefix_covered: boolean;
+  evaluated_prefix_covered: boolean;
+  missing_bundles: ReadonlyArray<string>;
+  missing_critical_rule_ids: ReadonlyArray<string>;
+  transversal_critical_covered: boolean;
+  missing_any_transversal_critical_rule_ids: ReadonlyArray<string>;
+};
+
+export type GovernanceSkillsContractSummary = {
+  stage: 'PRE_WRITE';
+  enforced: boolean;
+  status: 'PASS' | 'FAIL' | 'NOT_APPLICABLE';
+  detected_platforms: ReadonlyArray<GovernanceSkillsContractPlatform>;
+  requirements: ReadonlyArray<GovernanceSkillsContractPlatformRequirement>;
+  violations: ReadonlyArray<GovernanceSkillsContractViolation>;
+};
+
 export type GovernanceContractSurface = {
   agents_md: boolean;
   skills_lock_json: boolean;
@@ -54,6 +86,7 @@ export type GovernanceObservationSnapshot = {
   };
   enterprise_warn_as_block_env: boolean;
   evidence: GovernanceEvidenceSummary;
+  skills_contract: GovernanceSkillsContractSummary;
   git: {
     current_branch: string | null;
     on_protected_branch_hint: boolean;
@@ -65,6 +98,40 @@ export type GovernanceObservationSnapshot = {
   agent_bootstrap_hints: ReadonlyArray<string>;
 };
 
+const GOVERNANCE_SKILLS_PLATFORMS = ['ios', 'android', 'backend', 'frontend'] as const;
+const GOVERNANCE_SKILLS_RULE_PREFIXES: Readonly<
+  Record<GovernanceSkillsContractPlatform, string>
+> = {
+  ios: 'skills.ios.',
+  android: 'skills.android.',
+  backend: 'skills.backend.',
+  frontend: 'skills.frontend.',
+};
+const GOVERNANCE_REQUIRED_SKILLS_BUNDLES: Readonly<
+  Record<GovernanceSkillsContractPlatform, ReadonlyArray<string>>
+> = {
+  ios: ['ios-guidelines', 'ios-concurrency-guidelines', 'ios-swiftui-expert-guidelines'],
+  android: ['android-guidelines'],
+  backend: ['backend-guidelines'],
+  frontend: ['frontend-guidelines'],
+};
+const GOVERNANCE_CRITICAL_SKILLS_RULES: Readonly<
+  Record<GovernanceSkillsContractPlatform, ReadonlyArray<string>>
+> = {
+  ios: ['skills.ios.critical-test-quality'],
+  android: [],
+  backend: [],
+  frontend: [],
+};
+const GOVERNANCE_TRANSVERSAL_CRITICAL_SKILLS_RULES: Readonly<
+  Record<GovernanceSkillsContractPlatform, ReadonlyArray<string>>
+> = {
+  ios: [],
+  android: ['skills.android.no-runblocking', 'skills.android.no-thread-sleep'],
+  backend: ['skills.backend.no-empty-catch', 'skills.backend.avoid-explicit-any'],
+  frontend: ['skills.frontend.no-empty-catch', 'skills.frontend.avoid-explicit-any'],
+};
+
 const truthyEnv = (value: string | undefined): boolean => {
   if (typeof value !== 'string') {
     return false;
@@ -112,6 +179,186 @@ const buildContractSurface = (repoRoot: string): GovernanceContractSurface => ({
   pumuki_adapter_json: existsSync(join(repoRoot, '.pumuki', 'adapter.json')),
 });
 
+const toRequiredSkillsPlatforms = (repoRoot: string): GovernanceSkillsContractPlatform[] => {
+  const requiredLock = loadRequiredSkillsLock(repoRoot);
+  if (!requiredLock) {
+    return [];
+  }
+  const detected = new Set<GovernanceSkillsContractPlatform>();
+  for (const bundle of requiredLock.bundles) {
+    for (const rule of bundle.rules) {
+      if (
+        rule.platform === 'ios'
+        || rule.platform === 'android'
+        || rule.platform === 'backend'
+        || rule.platform === 'frontend'
+      ) {
+        detected.add(rule.platform);
+      }
+    }
+  }
+  return GOVERNANCE_SKILLS_PLATFORMS.filter((platform) => detected.has(platform));
+};
+
+const toCoverageDetectedPlatforms = (
+  evidenceResult: ReturnType<typeof readEvidenceResult>
+): GovernanceSkillsContractPlatform[] => {
+  if (evidenceResult.kind !== 'valid') {
+    return [];
+  }
+  const explicit = GOVERNANCE_SKILLS_PLATFORMS.filter((platform) => {
+    const candidate = evidenceResult.evidence.platforms?.[platform];
+    return candidate?.detected === true;
+  });
+  if (explicit.length > 0) {
+    return explicit;
+  }
+  const coverage = evidenceResult.evidence.snapshot.rules_coverage;
+  if (!coverage) {
+    return [];
+  }
+  return GOVERNANCE_SKILLS_PLATFORMS.filter((platform) => {
+    const prefix = GOVERNANCE_SKILLS_RULE_PREFIXES[platform];
+    return (
+      coverage.active_rule_ids.some((ruleId) => ruleId.startsWith(prefix))
+      || coverage.evaluated_rule_ids.some((ruleId) => ruleId.startsWith(prefix))
+    );
+  });
+};
+
+const summarizeSkillsContract = (repoRoot: string): GovernanceSkillsContractSummary => {
+  const requiredPlatforms = toRequiredSkillsPlatforms(repoRoot);
+  const evidenceResult = readEvidenceResult(repoRoot);
+  if (evidenceResult.kind !== 'valid') {
+    return {
+      stage: 'PRE_WRITE',
+      enforced: false,
+      status: 'NOT_APPLICABLE',
+      detected_platforms: [],
+      requirements: [],
+      violations: [],
+    };
+  }
+
+  const coverage = evidenceResult.evidence.snapshot.rules_coverage;
+  const detectedPlatforms = toCoverageDetectedPlatforms(evidenceResult);
+  const assessmentPlatforms = requiredPlatforms.length > 0 ? requiredPlatforms : detectedPlatforms;
+  if (assessmentPlatforms.length === 0) {
+    return {
+      stage: 'PRE_WRITE',
+      enforced: false,
+      status: 'NOT_APPLICABLE',
+      detected_platforms: [],
+      requirements: [],
+      violations: [],
+    };
+  }
+
+  const activeSkillsBundles = new Set(
+    (evidenceResult.evidence.rulesets ?? [])
+      .filter((ruleset) => ruleset.platform === 'skills')
+      .map((ruleset) => {
+        const [bundleName] = ruleset.bundle.split('@');
+        return bundleName?.trim().toLowerCase() ?? '';
+      })
+      .filter((bundle) => bundle.length > 0)
+  );
+
+  const requirements: GovernanceSkillsContractPlatformRequirement[] = [];
+  const violations: GovernanceSkillsContractViolation[] = [];
+  for (const platform of assessmentPlatforms) {
+    const requiredRulePrefix = GOVERNANCE_SKILLS_RULE_PREFIXES[platform];
+    const requiredBundles = [...GOVERNANCE_REQUIRED_SKILLS_BUNDLES[platform]];
+    const requiredCriticalRuleIds = [...GOVERNANCE_CRITICAL_SKILLS_RULES[platform]];
+    const requiredAnyTransversalCriticalRuleIds = [
+      ...GOVERNANCE_TRANSVERSAL_CRITICAL_SKILLS_RULES[platform],
+    ];
+    const activePrefixCovered = coverage
+      ? coverage.active_rule_ids.some((ruleId) => ruleId.startsWith(requiredRulePrefix))
+      : false;
+    const evaluatedPrefixCovered = coverage
+      ? coverage.evaluated_rule_ids.some((ruleId) => ruleId.startsWith(requiredRulePrefix))
+      : false;
+    const missingBundles = requiredBundles.filter(
+      (bundleName) => !activeSkillsBundles.has(bundleName.toLowerCase())
+    );
+    const missingCriticalRuleIds = coverage
+      ? requiredCriticalRuleIds.filter((ruleId) => {
+          const hasActive = coverage.active_rule_ids.includes(ruleId);
+          const hasEvaluated = coverage.evaluated_rule_ids.includes(ruleId);
+          return !hasActive || !hasEvaluated;
+        })
+      : [...requiredCriticalRuleIds];
+    const transversalCriticalCovered =
+      requiredAnyTransversalCriticalRuleIds.length === 0
+        ? true
+        : Boolean(
+            coverage
+            && requiredAnyTransversalCriticalRuleIds.some((ruleId) =>
+              coverage.active_rule_ids.includes(ruleId)
+              && coverage.evaluated_rule_ids.includes(ruleId)
+            )
+          );
+    const missingAnyTransversalCriticalRuleIds = transversalCriticalCovered
+      ? []
+      : [...requiredAnyTransversalCriticalRuleIds];
+
+    requirements.push({
+      platform,
+      required_rule_prefix: requiredRulePrefix,
+      required_bundles: requiredBundles,
+      required_critical_rule_ids: requiredCriticalRuleIds,
+      required_any_transversal_critical_rule_ids: requiredAnyTransversalCriticalRuleIds,
+      active_prefix_covered: activePrefixCovered,
+      evaluated_prefix_covered: evaluatedPrefixCovered,
+      missing_bundles: missingBundles,
+      missing_critical_rule_ids: missingCriticalRuleIds,
+      transversal_critical_covered: transversalCriticalCovered,
+      missing_any_transversal_critical_rule_ids: missingAnyTransversalCriticalRuleIds,
+    });
+
+    if (!activePrefixCovered || !evaluatedPrefixCovered) {
+      violations.push({
+        severity: 'ERROR',
+        code: 'EVIDENCE_PLATFORM_SKILLS_SCOPE_INCOMPLETE',
+        message: `Skills contract scope coverage missing for ${platform}.`,
+      });
+    }
+    if (missingBundles.length > 0) {
+      violations.push({
+        severity: 'ERROR',
+        code: 'EVIDENCE_PLATFORM_SKILLS_BUNDLES_MISSING',
+        message: `Skills contract missing bundles for ${platform}: [${missingBundles.join(', ')}].`,
+      });
+    }
+    if (missingCriticalRuleIds.length > 0) {
+      violations.push({
+        severity: 'ERROR',
+        code: 'EVIDENCE_PLATFORM_CRITICAL_SKILLS_RULES_MISSING',
+        message: `Skills contract missing critical rule coverage for ${platform}: [${missingCriticalRuleIds.join(', ')}].`,
+      });
+    }
+    if (!transversalCriticalCovered && requiredAnyTransversalCriticalRuleIds.length > 0) {
+      violations.push({
+        severity: 'ERROR',
+        code: 'EVIDENCE_CROSS_PLATFORM_CRITICAL_ENFORCEMENT_INCOMPLETE',
+        message:
+          `Skills contract missing transversal critical coverage for ${platform}: ` +
+          `[${requiredAnyTransversalCriticalRuleIds.join(', ')}].`,
+      });
+    }
+  }
+
+  return {
+    stage: 'PRE_WRITE',
+    enforced: true,
+    status: violations.length === 0 ? 'PASS' : 'FAIL',
+    detected_platforms: detectedPlatforms,
+    requirements,
+    violations,
+  };
+};
+
 const summarizeEvidence = (repoRoot: string): GovernanceEvidenceSummary => {
   const evidenceResult = readEvidenceResult(repoRoot);
   const path = evidenceResult.source_descriptor.path;
@@ -193,6 +440,7 @@ export const readGovernanceObservationSnapshot = (params: {
   const surface = buildContractSurface(repoRoot);
   const tracking = readRepoTrackingState(repoRoot);
   const warnAsBlock = truthyEnv(process.env.PUMUKI_ENTERPRISE_STRICT_WARN_AS_BLOCK);
+  const skillsContract = summarizeSkillsContract(repoRoot);
 
   const attention: string[] = [];
   if (evidence.readable === 'invalid') {
@@ -234,6 +482,9 @@ export const readGovernanceObservationSnapshot = (params: {
   if (tracking.enforced && tracking.single_in_progress_valid === false) {
     attention.push('TRACKING_CANONICAL_IN_PROGRESS_INVALID');
   }
+  if (skillsContract.status === 'FAIL') {
+    attention.push('SKILLS_CONTRACT_INCOMPLETE');
+  }
 
   let governanceEffective: GovernanceObservationSnapshot['governance_effective'] = 'green';
   if (
@@ -268,6 +519,7 @@ export const readGovernanceObservationSnapshot = (params: {
     },
     enterprise_warn_as_block_env: warnAsBlock,
     evidence,
+    skills_contract: skillsContract,
     git: {
       current_branch: branch,
       on_protected_branch_hint: onProtected,

package/integrations/lifecycle/npmService.ts

@@ -1,21 +1,173 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { spawnSync as runSpawnSync } from 'node:child_process';
 
 export interface ILifecycleNpmService {
   runNpm(args: ReadonlyArray<string>, cwd: string): void;
 }
 
+type LifecyclePackageManager = 'npm' | 'pnpm' | 'yarn';
+
+type PackageManagerManifest = {
+  packageManager?: string;
+  workspaces?: unknown;
+};
+
+const resolvePackageManagerFromManifest = (cwd: string): LifecyclePackageManager | undefined => {
+  const packageJsonPath = join(cwd, 'package.json');
+  if (!existsSync(packageJsonPath)) {
+    return undefined;
+  }
+
+  try {
+    const raw = readFileSync(packageJsonPath, 'utf8');
+    const manifest = JSON.parse(raw) as PackageManagerManifest;
+    const packageManager = manifest.packageManager?.trim().toLowerCase();
+    if (!packageManager) {
+      return undefined;
+    }
+    if (packageManager.startsWith('pnpm@')) {
+      return 'pnpm';
+    }
+    if (packageManager.startsWith('yarn@')) {
+      return 'yarn';
+    }
+    if (packageManager.startsWith('npm@')) {
+      return 'npm';
+    }
+  } catch {
+    return undefined;
+  }
+
+  return undefined;
+};
+
+export const resolveLifecyclePackageManager = (cwd: string): LifecyclePackageManager => {
+  const fromManifest = resolvePackageManagerFromManifest(cwd);
+  if (fromManifest) {
+    return fromManifest;
+  }
+  if (existsSync(join(cwd, 'pnpm-lock.yaml'))) {
+    return 'pnpm';
+  }
+  if (existsSync(join(cwd, 'yarn.lock'))) {
+    return 'yarn';
+  }
+  return 'npm';
+};
+
+const isWorkspaceRoot = (cwd: string): boolean => {
+  if (existsSync(join(cwd, 'pnpm-workspace.yaml'))) {
+    return true;
+  }
+  const packageJsonPath = join(cwd, 'package.json');
+  if (!existsSync(packageJsonPath)) {
+    return false;
+  }
+  try {
+    const raw = readFileSync(packageJsonPath, 'utf8');
+    const manifest = JSON.parse(raw) as PackageManagerManifest;
+    return Array.isArray(manifest.workspaces) || typeof manifest.workspaces === 'object';
+  } catch {
+    return false;
+  }
+};
+
+const translateInstallLikeArgs = (
+  packageManager: Exclude<LifecyclePackageManager, 'npm'>,
+  args: ReadonlyArray<string>,
+  cwd: string
+): ReadonlyArray<string> => {
+  const packageSpecs = args.filter((arg) => !arg.startsWith('-')).slice(1);
+  if (packageSpecs.length === 0) {
+    return args;
+  }
+
+  const useExact = args.includes('--save-exact');
+  const useDev = args.includes('--save-dev');
+
+  if (packageManager === 'pnpm') {
+    return [
+      'add',
+      ...(isWorkspaceRoot(cwd) ? ['-w'] : []),
+      ...(useDev ? ['-D'] : []),
+      ...(useExact ? ['-E'] : []),
+      ...packageSpecs,
+    ];
+  }
+
+  return [
+    'add',
+    ...(useDev ? ['--dev'] : []),
+    ...(useExact ? ['--exact'] : []),
+    ...packageSpecs,
+  ];
+};
+
+const translateUninstallLikeArgs = (
+  packageManager: Exclude<LifecyclePackageManager, 'npm'>,
+  args: ReadonlyArray<string>,
+  cwd: string
+): ReadonlyArray<string> => {
+  const packageSpecs = args.filter((arg) => !arg.startsWith('-')).slice(1);
+  if (packageSpecs.length === 0) {
+    return args;
+  }
+  if (packageManager === 'pnpm') {
+    return ['remove', ...(isWorkspaceRoot(cwd) ? ['-w'] : []), ...packageSpecs];
+  }
+  return ['remove', ...packageSpecs];
+};
+
+export const resolveLifecyclePackageManagerCommand = (
+  args: ReadonlyArray<string>,
+  cwd: string
+): {
+  command: LifecyclePackageManager;
+  args: ReadonlyArray<string>;
+} => {
+  const packageManager = resolveLifecyclePackageManager(cwd);
+  if (packageManager === 'npm') {
+    return {
+      command: 'npm',
+      args,
+    };
+  }
+
+  const primaryCommand = args[0];
+  if (primaryCommand === 'install') {
+    return {
+      command: packageManager,
+      args: translateInstallLikeArgs(packageManager, args, cwd),
+    };
+  }
+  if (primaryCommand === 'uninstall') {
+    return {
+      command: packageManager,
+      args: translateUninstallLikeArgs(packageManager, args, cwd),
+    };
+  }
+
+  return {
+    command: packageManager,
+    args,
+  };
+};
+
 export class LifecycleNpmService implements ILifecycleNpmService {
   runNpm(args: ReadonlyArray<string>, cwd: string): void {
-    const result = runSpawnSync('npm', args, {
+    const execution = resolveLifecyclePackageManagerCommand(args, cwd);
+    const renderedCommand = `${execution.command} ${execution.args.join(' ')}`.trim();
+    const result = runSpawnSync(execution.command, execution.args, {
       cwd,
       stdio: 'inherit',
       env: process.env,
     });
     if (result.error) {
-      throw new Error(`npm ${args.join(' ')} failed: ${result.error.message}`);
+      throw new Error(`${renderedCommand} failed: ${result.error.message}`);
     }
     if (typeof result.status !== 'number' || result.status !== 0) {
-      throw new Error(`npm ${args.join(' ')} failed with exit code ${result.status ?? 'unknown'}`);
+      throw new Error(`${renderedCommand} failed with exit code ${result.status ?? 'unknown'}`);
     }
   }
 }

package/package.json

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