pumuki 6.3.97 → 6.3.99

package/integrations/mcp/enterpriseStdioServer.cli.ts

@@ -1,6 +1,5 @@
 import { Socket, createServer } from 'node:net';
 import { startEnterpriseMcpServer } from './enterpriseServer';
-import { resolveMcpEnterpriseExperimentalFeature } from '../policy/experimentalFeatures';
 
 type JsonRpcId = string | number | null;
 
@@ -99,32 +98,11 @@ const fetchJson = async (url: string, options?: RequestInit): Promise<unknown> =
   }
 };
 
-type EnterpriseHealthPayload = {
-  status?: string;
-  repoRoot?: string;
-  experimentalFeatures?: {
-    mcp_enterprise?: {
-      mode?: string;
-    };
-  };
-};
-
-const canReuseEnterpriseHttp = (
-  health: EnterpriseHealthPayload,
-  repoRoot: string,
-  expectedMcpMode: string
-): boolean =>
-  health.status === 'ok'
-  && health.repoRoot === repoRoot
-  && health.experimentalFeatures?.mcp_enterprise?.mode === expectedMcpMode;
-
 const startOrReuseEnterpriseHttp = async (): Promise<{
   host: string;
   port: number;
   startedByThisProcess: boolean;
 }> => {
-  const repoRoot = process.cwd();
-  const expectedMcpMode = resolveMcpEnterpriseExperimentalFeature().mode;
   const host = process.env.PUMUKI_ENTERPRISE_MCP_HOST ?? '127.0.0.1';
   const parsedPort = Number.parseInt(process.env.PUMUKI_ENTERPRISE_MCP_PORT ?? '', 10);
   const preferredPort = Number.isFinite(parsedPort) ? parsedPort : 7391;
@@ -132,8 +110,8 @@ const startOrReuseEnterpriseHttp = async (): Promise<{
 
   const healthUrl = `http://${host}:${requestedPort}/health`;
   try {
-    const health = (await fetchJson(healthUrl)) as EnterpriseHealthPayload;
-    if (canReuseEnterpriseHttp(health, repoRoot, expectedMcpMode)) {
+    const health = (await fetchJson(healthUrl)) as { status?: string };
+    if (health.status === 'ok') {
       return {
         host,
         port: requestedPort,
@@ -141,12 +119,7 @@ const startOrReuseEnterpriseHttp = async (): Promise<{
       };
     }
   } catch (error) {
-    if (process.env.PUMUKI_DEBUG_MCP === '1') {
-      const message = error instanceof Error ? error.message : String(error);
-      process.stderr.write(
-        `[pumuki-mcp-enterprise-stdio] health probe reuse skipped: ${message}\n`
-      );
-    }
+    void error;
   }
 
   const portInUse = await isPortInUse(host, requestedPort);
@@ -154,7 +127,7 @@ const startOrReuseEnterpriseHttp = async (): Promise<{
   startEnterpriseMcpServer({
     host,
     port: resolvedPort,
-    repoRoot,
+    repoRoot: process.cwd(),
   });
 
   return {

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.97",
+  "version": "6.3.99",
   "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,
+};