pumuki 6.3.96 → 6.3.98

package/integrations/mcp/preFlightCheck.ts

@@ -1,14 +1,11 @@
-import {
-  resolveGovernanceCatalogAction,
-  type GovernanceCatalogNextAction,
-} from '../gate/governanceActionCatalog';
 import { evaluateAiGate, type AiGateStage, type AiGateViolation } from '../gate/evaluateAiGate';
 import { collectWorktreeAtomicSlices } from '../git/worktreeAtomicSlices';
 import { resolveLearningContextExperimentalFeature } from '../policy/experimentalFeatures';
 import { readSddLearningContext, type SddLearningContext } from '../sdd/learningInsights';
 
 const ACTIONABLE_HINTS_BY_CODE: Readonly<Record<string, string>> = {
-  EVIDENCE_MISSING: 'Ejecuta una auditoría (1/2/3/4) para regenerar .ai_evidence.json.',
+  EVIDENCE_MISSING:
+    'Ejecuta una auditoría (1/2/3/4 u opciones de motor 11–14) para regenerar .ai_evidence.json.',
   EVIDENCE_INVALID: 'Regenera .ai_evidence.json desde una opción de auditoría.',
   EVIDENCE_INTEGRITY_MISSING: 'Refresca evidencia para regenerar metadatos de integridad.',
   EVIDENCE_ACTIVE_RULE_IDS_EMPTY_FOR_CODE_CHANGES:
@@ -42,28 +39,6 @@ const ACTIONABLE_HINTS_BY_CODE: Readonly<Record<string, string>> = {
     'Mapea todas las reglas AUTO a detectores AST antes de continuar.',
   EVIDENCE_TIMESTAMP_FUTURE: 'Corrige la hora del sistema y regenera evidencia.',
   GITFLOW_PROTECTED_BRANCH: 'Evita trabajo directo en ramas protegidas (usa feature/*).',
-  GITFLOW_BRANCH_NAMING_INVALID:
-    'La rama actual no cumple GitFlow. Usa feature/*, bugfix/*, hotfix/*, release/*, chore/*, refactor/* o docs/*.',
-  TRACKING_CANONICAL_SOURCE_CONFLICT:
-    'AGENTS.md y los README del repo no apuntan a la misma fuente canónica de tracking.',
-  TRACKING_CANONICAL_FILE_MISSING:
-    'El repo declara un MD de tracking canónico que ahora mismo no existe.',
-  TRACKING_CANONICAL_IN_PROGRESS_INVALID:
-    'El MD canónico de tracking debe dejar exactamente una task o fase en construcción.',
-};
-
-const normalizeGovernanceCatalogCode = (code: string): string => {
-  switch (code) {
-    case 'EVIDENCE_INVALID':
-    case 'EVIDENCE_CHAIN_INVALID':
-      return 'EVIDENCE_INVALID_OR_CHAIN';
-    case 'GITFLOW_PROTECTED_BRANCH':
-      return 'GITFLOW_PROTECTED_BRANCH_CONTEXT';
-    case 'GITFLOW_BRANCH_NAMING_INVALID':
-      return 'GITFLOW_BRANCH_NAMING_INVALID_CONTEXT';
-    default:
-      return code;
-  }
 };
 
 const buildPreFlightHints = (params: {
@@ -140,8 +115,6 @@ export type EnterprisePreFlightCheckResult = {
     phase: 'GREEN' | 'RED';
     message: string;
     instruction: string;
-    reason_code: string;
-    next_action: GovernanceCatalogNextAction;
     stage: ReturnType<typeof evaluateAiGate>['stage'];
     policy: ReturnType<typeof evaluateAiGate>['policy'];
     violations: ReturnType<typeof evaluateAiGate>['violations'];
@@ -181,30 +154,13 @@ export const runEnterprisePreFlightCheck = (params: {
     upstream: evaluation.repo_state.git.upstream,
     learningContext,
   });
-  const firstViolation = evaluation.violations[0];
-  const reasonCode = firstViolation?.code ?? 'READY';
-  const governanceAction = firstViolation
-    ? resolveGovernanceCatalogAction({
-      code: normalizeGovernanceCatalogCode(firstViolation.code),
-      stage: evaluation.stage,
-    })
-    : resolveGovernanceCatalogAction({
-      code: 'READY',
-      stage: evaluation.stage,
-    });
   const phase: 'GREEN' | 'RED' = evaluation.allowed ? 'GREEN' : 'RED';
   const message = evaluation.allowed
     ? '✅ Pre-flight aprobado: puedes continuar con la implementación.'
-    : `🔴 Pre-flight bloqueado: corrige ${reasonCode} y vuelve a ejecutar.`;
-  const instruction = !firstViolation && evaluation.allowed
+    : `🔴 Pre-flight bloqueado: corrige ${evaluation.violations[0]?.code ?? 'la causa'} y vuelve a ejecutar.`;
+  const instruction = evaluation.allowed
     ? 'Implementa el cambio mínimo para pasar en verde y vuelve a validar.'
-    : governanceAction.instruction;
-  const nextAction: GovernanceCatalogNextAction = evaluation.allowed
-    ? {
-      kind: 'info',
-      message: governanceAction.next_action.message,
-    }
-    : governanceAction.next_action;
+    : hints[0] ?? 'Corrige la causa bloqueante y vuelve a ejecutar el pre-flight.';
 
   return {
     tool: 'pre_flight_check',
@@ -217,8 +173,6 @@ export const runEnterprisePreFlightCheck = (params: {
       phase,
       message,
       instruction,
-      reason_code: reasonCode,
-      next_action: nextAction,
       stage: evaluation.stage,
       policy: evaluation.policy,
       violations: evaluation.violations,

package/integrations/platform/detectPlatforms.ts

@@ -51,6 +51,38 @@ const collectFilePaths = (facts: ReadonlyArray<Fact>): string[] => {
     .filter((path): path is string => typeof path === 'string');
 };
 
+const ALLOWED_PIN_KEYS = new Set(['ios', 'android', 'backend', 'frontend']);
+
+const readPinnedPlatformsFromEnv = (): ReadonlySet<keyof DetectedPlatforms> | null => {
+  const raw = process.env.PUMUKI_PIN_PLATFORMS?.trim().toLowerCase();
+  if (!raw) {
+    return null;
+  }
+  const tokens = raw
+    .split(',')
+    .map((token) => token.trim())
+    .filter((token) => token.length > 0)
+    .filter((token) => ALLOWED_PIN_KEYS.has(token)) as Array<keyof DetectedPlatforms>;
+  if (tokens.length === 0) {
+    return null;
+  }
+  return new Set(tokens);
+};
+
+const applyPinnedPlatformsFilter = (
+  detected: DetectedPlatforms,
+  pin: ReadonlySet<keyof DetectedPlatforms>
+): DetectedPlatforms => {
+  const next: DetectedPlatforms = {};
+  for (const key of pin) {
+    const state = detected[key];
+    if (state) {
+      next[key] = state;
+    }
+  }
+  return next;
+};
+
 export const detectPlatformsFromFacts = (
   facts: ReadonlyArray<Fact>
 ): DetectedPlatforms => {
@@ -102,5 +134,10 @@ export const detectPlatformsFromFacts = (
     };
   }
 
+  const pin = readPinnedPlatformsFromEnv();
+  if (pin && pin.size > 0) {
+    return applyPinnedPlatformsFilter(result, pin);
+  }
+
   return result;
 };

package/integrations/policy/experimentalFeatures.ts

@@ -40,7 +40,7 @@ type ExperimentalFeatureConfig = {
 
 const EXPERIMENTAL_FEATURES: Record<ExperimentalFeatureId, ExperimentalFeatureConfig> = {
   pre_write: {
-    defaultMode: 'strict',
+    defaultMode: 'off',
     activationVariable: 'PUMUKI_EXPERIMENTAL_PRE_WRITE',
     legacyActivationVariable: 'PUMUKI_PREWRITE_ENFORCEMENT',
   },

package/integrations/sdd/evidenceScaffold.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdirSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, relative, resolve } from 'node:path';
 import { readEvidenceResult, type EvidenceReadResult } from '../evidence/readEvidence';
 
@@ -15,7 +15,6 @@ export type SddEvidenceScaffoldResult = {
     testStatus: SddEvidenceScaffoldTestStatus;
     testOutputPath: string | null;
     fromEvidencePath: string | null;
-    traceabilityMarkdownPath: string | null;
   };
   output: {
     path: string;
@@ -45,13 +44,6 @@ export type SddEvidenceScaffoldResult = {
       source: 'pumuki-sdd-evidence';
       stack: 'sdd-evidence-scaffold';
     };
-    traceability: {
-      required: boolean;
-      path: string | null;
-      header_present: boolean;
-      rows: number;
-      status: 'valid';
-    };
     // Legacy fields kept for state-sync compatibility in existing consumers.
     scenario_id: string;
     test_run: {
@@ -73,13 +65,10 @@ export type SddEvidenceScaffoldResult = {
 const computeDigest = (value: string): string =>
   `sha256:${createHash('sha256').update(value, 'utf8').digest('hex')}`;
 
-const TRACEABILITY_HEADER = '| ARCHIVO | SKILL | REGLA | EVIDENCIA | ESTADO |';
-const TRACEABILITY_CONTRACT_MARKER = 'ARCHIVO | SKILL | REGLA | EVIDENCIA | ESTADO';
-
 const resolveRepoBoundPath = (params: {
   repoRoot: string;
   candidatePath: string;
-  flagName: '--from-evidence' | '--test-output' | '--traceability-markdown';
+  flagName: '--from-evidence' | '--test-output';
 }): string => {
   const repoRootAbsolute = resolve(params.repoRoot);
   const resolved = isAbsolute(params.candidatePath)
@@ -152,87 +141,6 @@ const resolveScenarioReference = (scenarioId: string): string => {
   return `${normalized}.feature`;
 };
 
-const repoRequiresTraceabilityMatrix = (repoRoot: string): boolean => {
-  const agentsPath = resolve(repoRoot, 'AGENTS.md');
-  if (!existsSync(agentsPath)) {
-    return false;
-  }
-  const contents = readFileSync(agentsPath, 'utf8');
-  return (
-    contents.includes('Plantilla obligatoria de trazabilidad por turno') ||
-    contents.includes(TRACEABILITY_CONTRACT_MARKER)
-  );
-};
-
-const validateTraceabilityMarkdown = (params: {
-  repoRoot: string;
-  required: boolean;
-  traceabilityMarkdownPath?: string;
-}): {
-  path: string | null;
-  header_present: boolean;
-  rows: number;
-} => {
-  if (!params.required) {
-    return {
-      path: params.traceabilityMarkdownPath?.trim() ? params.traceabilityMarkdownPath.trim() : null,
-      header_present: false,
-      rows: 0,
-    };
-  }
-  const candidate = params.traceabilityMarkdownPath?.trim() ?? '';
-  if (candidate.length === 0) {
-    throw new Error(
-      `[pumuki][sdd] evidence requires --traceability-markdown=<path> because this repository declares the contractual traceability matrix (${TRACEABILITY_HEADER}).`
-    );
-  }
-  const absolutePath = resolveRepoBoundPath({
-    repoRoot: params.repoRoot,
-    candidatePath: candidate,
-    flagName: '--traceability-markdown',
-  });
-  if (!existsSync(absolutePath)) {
-    throw new Error(
-      `[pumuki][sdd] traceability markdown file does not exist: ${candidate}. Add the contractual matrix and retry.`
-    );
-  }
-  const markdown = readFileSync(absolutePath, 'utf8');
-  const lines = markdown.split(/\r?\n/);
-  const headerIndex = lines.findIndex((line) => line.trim() === TRACEABILITY_HEADER);
-  if (headerIndex < 0) {
-    throw new Error(
-      `[pumuki][sdd] traceability markdown must include the contractual header ${TRACEABILITY_HEADER}.`
-    );
-  }
-  let rows = 0;
-  for (const line of lines.slice(headerIndex + 1)) {
-    const trimmed = line.trim();
-    if (!trimmed.startsWith('|')) {
-      if (rows > 0) {
-        break;
-      }
-      continue;
-    }
-    if (/^\|\s*-+\s*\|/.test(trimmed)) {
-      continue;
-    }
-    if (trimmed === TRACEABILITY_HEADER) {
-      continue;
-    }
-    rows += 1;
-  }
-  if (rows === 0) {
-    throw new Error(
-      '[pumuki][sdd] traceability markdown must include at least one data row under the contractual matrix header.'
-    );
-  }
-  return {
-    path: relative(params.repoRoot, absolutePath).split('\\').join('/'),
-    header_present: true,
-    rows,
-  };
-};
-
 export const runSddEvidenceScaffold = (params?: {
   repoRoot?: string;
   dryRun?: boolean;
@@ -241,7 +149,6 @@ export const runSddEvidenceScaffold = (params?: {
   testStatus?: SddEvidenceScaffoldTestStatus;
   testOutputPath?: string;
   fromEvidencePath?: string;
-  traceabilityMarkdownPath?: string;
   outputPath?: string;
   now?: () => Date;
   evidenceReader?: (repoRoot: string) => EvidenceReadResult;
@@ -288,12 +195,6 @@ export const runSddEvidenceScaffold = (params?: {
     evidenceResult: evidenceReader(repoRoot),
     fromEvidencePath,
   });
-  const traceabilityRequired = repoRequiresTraceabilityMatrix(repoRoot);
-  const traceability = validateTraceabilityMarkdown({
-    repoRoot,
-    required: traceabilityRequired,
-    traceabilityMarkdownPath: params?.traceabilityMarkdownPath,
-  });
 
   const now = params?.now ?? (() => new Date());
   const generatedAt = now().toISOString();
@@ -331,13 +232,6 @@ export const runSddEvidenceScaffold = (params?: {
       source: 'pumuki-sdd-evidence',
       stack: 'sdd-evidence-scaffold',
     },
-    traceability: {
-      required: traceabilityRequired,
-      path: traceability.path,
-      header_present: traceability.header_present,
-      rows: traceability.rows,
-      status: 'valid',
-    },
     scenario_id: scenarioId,
     test_run: {
       command: testCommand,
@@ -373,7 +267,6 @@ export const runSddEvidenceScaffold = (params?: {
       testStatus,
       testOutputPath,
       fromEvidencePath,
-      traceabilityMarkdownPath: traceability.path,
     },
     output: {
       path: outputRelativePath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pumuki",
-  "version": "6.3.96",
+  "version": "6.3.98",
   "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": {
@@ -54,6 +54,8 @@
     "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",
+    "smoke:pumuki-surface": "npx --yes tsx@4.21.0 scripts/pumuki-full-surface-smoke.ts",
+    "smoke:pumuki-surface-installed": "node scripts/pumuki-smoke-installed-wrapper.cjs",
     "test:deterministic": "npm run test:evidence && npm run test:mcp && npm run test:heuristics",
     "ast:refresh": "node bin/pumuki-pre-commit.js",
     "ast:audit": "node bin/pumuki-pre-commit.js",
@@ -144,12 +146,13 @@
     "validation:phase5-escalation:payload": "bash scripts/build-phase5-support-portal-payload.sh",
     "validation:architecture-guardrails": "npx --yes tsx@4.21.0 --test scripts/__tests__/architecture-file-size-guardrails.test.ts",
     "validation:package-manifest": "node --import tsx scripts/check-package-manifest.ts",
+    "validation:pumuki-surface-smoke": "npm run -s smoke:pumuki-surface",
+    "validation:local-merge-bar": "npm run -s typecheck && npm run -s validation:pumuki-surface-smoke && npm test",
     "validation:package-smoke": "node --import tsx scripts/package-install-smoke.ts --mode=block",
     "validation:package-smoke:minimal": "node --import tsx scripts/package-install-smoke.ts --mode=minimal",
     "validation:lifecycle-smoke": "node --import tsx scripts/package-install-smoke.ts --mode=minimal",
     "validation:contract-suite:enterprise": "node --import tsx scripts/run-enterprise-contract-suite.ts",
     "validation:consumer-matrix-baseline": "node --import tsx scripts/build-consumer-menu-matrix-baseline.ts",
-    "validation:ruralgo-s1-evidence-pack": "npx --yes tsx@4.21.0 scripts/build-ruralgo-s1-evidence-pack.ts",
     "validation:c020-benchmark": "node --import tsx scripts/run-c020-benchmark.ts",
     "validation:clean-artifacts": "npx --yes tsx@4.21.0 scripts/clean-validation-artifacts.ts",
     "skills:compile": "npx --yes tsx@4.21.0 scripts/compile-skills-lock.ts",
@@ -249,6 +252,8 @@
     "integrations/telemetry/*.ts",
     "scripts/*.ts",
     "scripts/consumer-postinstall.cjs",
+    "scripts/consumer-postinstall-resolve-args.cjs",
+    "scripts/pumuki-smoke-installed-wrapper.cjs",
     "scripts/adapters/*.ts",
     "scripts/adapters/*.md",
     "scripts/*.sh",
@@ -260,10 +265,13 @@
     "docs/product/*.md",
     "docs/rule-packs/*.md",
     "docs/validation/*.md",
+    "docs/tracking/plan-curso-pumuki-stack-my-architecture.md",
     "assets/**/*",
     "vendor/skills/**/*",
     "index.js",
     "README.md",
+    "AGENTS.md",
+    "CHANGELOG.md",
     "LICENSE",
     "VERSION",
     "tsconfig.json",

package/scripts/check-tracking-single-active.sh

@@ -31,7 +31,7 @@ for FILE in "${FILES[@]}"; do
   fi
 
   if [[ "${FILE}" == "PUMUKI-RESET-MASTER-PLAN.md" ]]; then
-    ACTIVE_PATTERN='(^- Estado:\s*🚧\b)|(^`?\[\s*🚧\s*\]\s*-`?)|(^\|\s*[^|]+\|\s*`?\[\s*🚧\s*\]\s*-`?)'
+    ACTIVE_PATTERN='^- Estado: 🚧'
   else
     ACTIVE_PATTERN='^- 🚧 (`?P[0-9A-Za-z.-]+`?)'
   fi

package/scripts/consumer-menu-matrix-baseline-report-lib.ts

@@ -4,10 +4,11 @@ import type {
   ConsumerMenuMatrixReport,
   MatrixOptionId,
 } from './framework-menu-matrix-baseline-lib';
+import { MATRIX_MENU_OPTION_IDS } from './framework-menu-matrix-evidence-lib';
 import type { DoctorDeepCheckLayer, LifecycleDoctorReport } from '../integrations/lifecycle/doctor';
 import type { LifecycleStatus } from '../integrations/lifecycle/status';
 
-const OPTION_IDS: ReadonlyArray<MatrixOptionId> = ['1', '2', '3', '4', '9'];
+const OPTION_IDS: ReadonlyArray<MatrixOptionId> = [...MATRIX_MENU_OPTION_IDS];
 const DOCTOR_LAYERS: ReadonlyArray<DoctorDeepCheckLayer> = [
   'core',
   'operational',
@@ -51,45 +52,19 @@ export type ConsumerMenuMatrixBaselineSnapshot = {
   };
 };
 
+const UNKNOWN_OPTION_REPORT = {
+  stage: 'UNKNOWN',
+  outcome: 'UNKNOWN',
+  filesScanned: 0,
+  totalViolations: 0,
+  diagnosis: 'unknown' as const,
+};
+
 const buildEmptyRound = (): ConsumerMenuMatrixReport => {
   return {
-    byOption: {
-      '1': {
-        stage: 'UNKNOWN',
-        outcome: 'UNKNOWN',
-        filesScanned: 0,
-        totalViolations: 0,
-        diagnosis: 'unknown',
-      },
-      '2': {
-        stage: 'UNKNOWN',
-        outcome: 'UNKNOWN',
-        filesScanned: 0,
-        totalViolations: 0,
-        diagnosis: 'unknown',
-      },
-      '3': {
-        stage: 'UNKNOWN',
-        outcome: 'UNKNOWN',
-        filesScanned: 0,
-        totalViolations: 0,
-        diagnosis: 'unknown',
-      },
-      '4': {
-        stage: 'UNKNOWN',
-        outcome: 'UNKNOWN',
-        filesScanned: 0,
-        totalViolations: 0,
-        diagnosis: 'unknown',
-      },
-      '9': {
-        stage: 'UNKNOWN',
-        outcome: 'UNKNOWN',
-        filesScanned: 0,
-        totalViolations: 0,
-        diagnosis: 'unknown',
-      },
-    },
+    byOption: Object.fromEntries(
+      MATRIX_MENU_OPTION_IDS.map((id) => [id, { ...UNKNOWN_OPTION_REPORT }])
+    ) as ConsumerMenuMatrixReport['byOption'],
   };
 };
 

package/scripts/consumer-postinstall-resolve-args.cjs

@@ -0,0 +1,44 @@
+'use strict';
+
+const KNOWN_MCP_AGENTS = new Set(['cursor', 'codex', 'claude', 'repo']);
+
+const normalizeExplicitAgent = (raw) => {
+  const trimmed = (raw ?? '').trim();
+  if (!trimmed) {
+    return '';
+  }
+  const lower = trimmed.toLowerCase();
+  if (lower === '0' || lower === 'none' || lower === 'false') {
+    return '';
+  }
+  if (!KNOWN_MCP_AGENTS.has(lower)) {
+    return '';
+  }
+  return lower;
+};
+
+const resolveConsumerPostinstallInstallExtras = (_consumerRoot, env = process.env) => {
+  if (env.PUMUKI_POSTINSTALL_SKIP_MCP === '1') {
+    return { extras: [], reason: 'skip_mcp' };
+  }
+  const withMcpFlag =
+    env.PUMUKI_POSTINSTALL_WITH_MCP === '1' ||
+    env.PUMUKI_POSTINSTALL_WITH_MCP?.toLowerCase() === 'true';
+  const explicit = normalizeExplicitAgent(env.PUMUKI_POSTINSTALL_MCP_AGENT);
+  if (explicit) {
+    return { extras: ['--with-mcp', `--agent=${explicit}`], reason: 'explicit_agent' };
+  }
+  if (withMcpFlag) {
+    return { extras: ['--with-mcp', '--agent=repo'], reason: 'explicit_repo_flag' };
+  }
+  return {
+    extras: [],
+    reason: 'disabled_default',
+  };
+};
+
+module.exports = {
+  KNOWN_MCP_AGENTS,
+  resolveConsumerPostinstallInstallExtras,
+  normalizeExplicitAgent,
+};

package/scripts/consumer-postinstall.cjs

@@ -4,56 +4,111 @@
 const { existsSync } = require('node:fs');
 const { join, resolve } = require('node:path');
 const { spawnSync } = require('node:child_process');
+const { resolveConsumerPostinstallInstallExtras } = require('./consumer-postinstall-resolve-args.cjs');
 
-const skipReason = () => {
-  if (process.env.PUMUKI_SKIP_POSTINSTALL === '1') {
+const skipReason = (env = process.env) => {
+  if (env.PUMUKI_SKIP_POSTINSTALL === '1') {
     return 'PUMUKI_SKIP_POSTINSTALL=1';
   }
-  if (process.env.CI === 'true' || process.env.CI === '1') {
+  if (env.CI === 'true' || env.CI === '1') {
     return 'CI';
   }
-  if (process.env.npm_config_ignore_scripts === 'true') {
+  if (env.npm_config_ignore_scripts === 'true') {
     return 'npm ignore-scripts';
   }
   return '';
 };
 
-const main = () => {
-  const reason = skipReason();
+const normalizePumukiInstallResult = (result) => {
+  if (result.error) {
+    return {
+      code: 1,
+      errorMessage: result.error.message ?? String(result.error),
+    };
+  }
+
+  return { code: typeof result.status === 'number' ? result.status : 1, errorMessage: null };
+};
+
+const runPostinstall = ({
+  spawnSyncFn = spawnSync,
+  packageRoot = resolve(__dirname, '..'),
+  consumerRoot = process.env.INIT_CWD || process.cwd(),
+  env = process.env,
+  logger = console,
+} = {}) => {
+  const reason = skipReason(env);
   if (reason) {
     return 0;
   }
 
-  const consumerRoot = process.env.INIT_CWD || process.cwd();
   if (!existsSync(join(consumerRoot, '.git'))) {
     return 0;
   }
 
-  const packageRoot = resolve(__dirname, '..');
   const pumukiCli = join(packageRoot, 'bin', 'pumuki.js');
   if (!existsSync(pumukiCli)) {
     return 0;
   }
 
-  const env = {
-    ...process.env,
+  const postinstallEnv = {
+    ...env,
     PUMUKI_AUTO_POSTINSTALL: '1',
-    PUMUKI_SKIP_OPENSPEC_BOOTSTRAP: process.env.PUMUKI_SKIP_OPENSPEC_BOOTSTRAP ?? '1',
+    PUMUKI_SKIP_OPENSPEC_BOOTSTRAP: env.PUMUKI_SKIP_OPENSPEC_BOOTSTRAP ?? '1',
   };
 
-  const result = spawnSync(process.execPath, [pumukiCli, 'install'], {
-    cwd: consumerRoot,
-    env,
-    stdio: 'inherit',
-  });
+  const { extras: installExtras, reason: mcpReason } = resolveConsumerPostinstallInstallExtras(
+    consumerRoot,
+    postinstallEnv
+  );
+  if (installExtras.length > 0 && postinstallEnv.PUMUKI_VERBOSE_INSTALL === '1') {
+    logger.debug(
+      `[pumuki] postinstall: mcp wiring (${mcpReason}): ${installExtras.join(' ')}`
+    );
+  }
+
+  if (installExtras.length === 0 && postinstallEnv.PUMUKI_VERBOSE_INSTALL === '1') {
+    logger.debug('[pumuki] postinstall: no extra args; running baseline install only.');
+  }
+
+  const result = normalizePumukiInstallResult(
+    spawnSyncFn(process.execPath, [pumukiCli, 'install', ...installExtras], {
+      cwd: consumerRoot,
+      env: postinstallEnv,
+      stdio: 'inherit',
+    })
+  );
 
-  const code = typeof result.status === 'number' ? result.status : 1;
-  if (code !== 0) {
-    console.error(
-      '[pumuki] postinstall: `pumuki install` exited non-zero; npm install will still succeed. Run `npx pumuki install` or `npx pumuki doctor` from the repo root.'
+  if (result.code !== 0) {
+    const scope = installExtras.length > 0 ? 'postinstall+extras' : 'postinstall';
+    const severityHint =
+      installExtras.length > 0
+        ? 'Run `pumuki install` manually with the desired options to investigar y resolver el fallo.'
+        : 'Run `pumuki install` o `pumuki doctor` desde la raíz del repo.';
+    logger.error(
+      `[pumuki] postinstall: install exited non-zero (scope=${scope}, reason=${mcpReason}). ${severityHint}`
     );
+    if (result.errorMessage) {
+      logger.error(`[pumuki] postinstall: ${result.errorMessage}`);
+    }
   }
-  return 0;
+
+  return result.code;
+};
+
+const main = () => {
+  return runPostinstall({
+    spawnSyncFn: spawnSync,
+    packageRoot: resolve(__dirname, '..'),
+    consumerRoot: process.env.INIT_CWD || process.cwd(),
+    env: process.env,
+    logger: console,
+  });
 };
 
 process.exitCode = main();
+
+module.exports = {
+  runPostinstall,
+  skipReason,
+};

package/scripts/framework-menu-advanced-view-lib.ts

@@ -19,14 +19,11 @@ import {
   renderActionRow,
   renderBadge,
 } from './framework-menu-ui-components-lib';
-import { buildGovernanceConsoleSummaryLines } from '../integrations/lifecycle/cliGovernanceConsole';
-import type { ConsumerPreflightResult } from './framework-menu-consumer-preflight-types';
 
 export const formatAdvancedMenuView = (
   actions: ReadonlyArray<MenuAction>,
   options?: {
     evidenceSummary?: FrameworkMenuEvidenceSummary;
-    preflight?: ConsumerPreflightResult | null;
   }
 ): string => {
   const evidenceSummary = options?.evidenceSummary ?? readEvidenceSummaryForMenu(process.cwd());
@@ -36,18 +33,6 @@ export const formatAdvancedMenuView = (
   const lines = [
     'Pumuki Framework Menu (Advanced)',
     `Status: ${statusBadge}`,
-    ...(options?.preflight
-      ? [
-        'Governance Console',
-        ...buildGovernanceConsoleSummaryLines({
-          governanceObservation: options.preflight.governanceObservation,
-          governanceNextAction: options.preflight.governanceNextAction,
-          policyValidation: options.preflight.policyValidation,
-          experimentalFeatures: options.preflight.experimentalFeatures,
-        }).map((line) => `  ${line}`),
-        '',
-      ]
-      : []),
     'C. Switch to consumer menu',
     '',
     ...groupedActions.flatMap((group, groupIndex) => [