pumuki 6.3.71 → 6.3.73

package/integrations/sdd/openSpecCli.ts

@@ -17,20 +17,29 @@ type OpenSpecCommandResult = {
   stderr: string;
 };
 
-const resolveOpenSpecBinary = (repoRoot: string): string => {
+const resolveOpenSpecBinary = (repoRoot: string): string | undefined => {
   const binaryName = process.platform === 'win32' ? 'openspec.cmd' : 'openspec';
   const localBinaryPath = join(repoRoot, 'node_modules', '.bin', binaryName);
   if (existsSync(localBinaryPath)) {
     return localBinaryPath;
   }
-  return 'openspec';
+  return undefined;
 };
 
 const runOpenSpecCommand = (
   args: ReadonlyArray<string>,
   cwd: string
 ): OpenSpecCommandResult => {
-  const result = runSpawnSync(resolveOpenSpecBinary(cwd), [...args], {
+  const binary = resolveOpenSpecBinary(cwd);
+  if (!binary) {
+    return {
+      exitCode: 127,
+      stdout: '',
+      stderr:
+        'OpenSpec CLI not found under repo node_modules/.bin (add @fission-ai/openspec to this repository).',
+    };
+  }
+  const result = runSpawnSync(binary, [...args], {
     cwd,
     encoding: 'utf8',
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pumuki",
-  "version": "6.3.71",
+  "version": "6.3.73",
   "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,11 +146,14 @@
     "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",
@@ -248,6 +253,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",
@@ -259,10 +266,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/build-ruralgo-s1-evidence-pack.ts

@@ -0,0 +1,85 @@
+import {
+  buildRuralGoS1EvidencePackMarkdown,
+  writeRuralGoS1EvidencePack,
+} from './ruralgo-s1-evidence-pack-lib';
+
+type CliOptions = {
+  consumerRoot: string;
+  outFile: string;
+  packageVersion: string;
+  generatedAt: string;
+};
+
+const parseArgs = (argv: ReadonlyArray<string>): CliOptions => {
+  const options: CliOptions = {
+    consumerRoot: '<RURALGO_REPO_ROOT>',
+    outFile: '.audit-reports/ruralgo-s1/ruralgo-s1-evidence-pack.md',
+    packageVersion: 'unknown',
+    generatedAt: new Date().toISOString(),
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    const next = argv[index + 1];
+    switch (token) {
+      case '--consumer-root':
+        if (!next) {
+          throw new Error('missing value for --consumer-root');
+        }
+        options.consumerRoot = next;
+        index += 1;
+        break;
+      case '--out':
+        if (!next) {
+          throw new Error('missing value for --out');
+        }
+        options.outFile = next;
+        index += 1;
+        break;
+      case '--package-version':
+        if (!next) {
+          throw new Error('missing value for --package-version');
+        }
+        options.packageVersion = next;
+        index += 1;
+        break;
+      case '--generated-at':
+        if (!next) {
+          throw new Error('missing value for --generated-at');
+        }
+        options.generatedAt = next;
+        index += 1;
+        break;
+      default:
+        throw new Error(`unknown argument: ${token}`);
+    }
+  }
+
+  return options;
+};
+
+const main = (): number => {
+  const cwd = process.cwd();
+  const options = parseArgs(process.argv.slice(2));
+  const markdown = buildRuralGoS1EvidencePackMarkdown({
+    cwd,
+    consumerRoot: options.consumerRoot,
+    packageVersion: options.packageVersion,
+    generatedAt: options.generatedAt,
+  });
+  const outputPath = writeRuralGoS1EvidencePack({
+    cwd,
+    outFile: options.outFile,
+    markdown,
+  });
+  process.stdout.write(`ruralgo s1 evidence pack generated at ${outputPath}\n`);
+  return 0;
+};
+
+try {
+  process.exitCode = main();
+} catch (error) {
+  const message = error instanceof Error ? error.message : 'unknown error';
+  process.stderr.write(`ruralgo s1 evidence pack failed: ${message}\n`);
+  process.exitCode = 1;
+}

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

@@ -0,0 +1,38 @@
+'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 explicit = normalizeExplicitAgent(env.PUMUKI_POSTINSTALL_MCP_AGENT);
+  if (explicit) {
+    return { extras: ['--with-mcp', `--agent=${explicit}`], reason: 'explicit_agent' };
+  }
+  return {
+    extras: ['--with-mcp', '--agent=repo'],
+    reason: 'default_repo_adapter',
+  };
+};
+
+module.exports = {
+  KNOWN_MCP_AGENTS,
+  resolveConsumerPostinstallInstallExtras,
+  normalizeExplicitAgent,
+};

package/scripts/consumer-postinstall.cjs

@@ -4,6 +4,7 @@
 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') {
@@ -41,7 +42,15 @@ const main = () => {
     PUMUKI_SKIP_OPENSPEC_BOOTSTRAP: process.env.PUMUKI_SKIP_OPENSPEC_BOOTSTRAP ?? '1',
   };
 
-  const result = spawnSync(process.execPath, [pumukiCli, 'install'], {
+  const { extras: installExtras, reason: mcpReason } = resolveConsumerPostinstallInstallExtras(
+    consumerRoot,
+    env
+  );
+  if (installExtras.length > 0 && env.PUMUKI_VERBOSE_INSTALL === '1') {
+    console.debug(`[pumuki] postinstall: mcp wiring (${mcpReason}): ${installExtras.join(' ')}`);
+  }
+
+  const result = spawnSync(process.execPath, [pumukiCli, 'install', ...installExtras], {
     cwd: consumerRoot,
     env,
     stdio: 'inherit',

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

@@ -1,5 +1,7 @@
 import { renderLegacyPanel, resolveLegacyPanelOuterWidth } from './framework-menu-legacy-audit-lib';
 import { buildConsumerPreflightBlockingCauseLines } from './framework-menu-consumer-preflight-hints';
+import { buildGovernanceNextActionSummaryLines } from '../integrations/lifecycle/governanceNextAction';
+import { buildGovernanceObservationSummaryLines } from '../integrations/lifecycle/governanceObservationSnapshot';
 import type {
   ConsumerPreflightRenderOptions,
   ConsumerPreflightResult,
@@ -19,6 +21,10 @@ const buildConsumerPreflightPanelLines = (
     `Evidence source: source=${evidence.source.source} path=${evidence.source.path} digest=${evidence.source.digest ?? 'null'} generated_at=${evidence.source.generated_at ?? 'null'}`,
     `Gate: ${preflight.status} (${preflight.result.violations.length} violations)`,
   ];
+  lines.push('', 'Governance truth:');
+  lines.push(...buildGovernanceObservationSummaryLines(preflight.governanceObservation));
+  lines.push('', 'Governance next action:');
+  lines.push(...buildGovernanceNextActionSummaryLines(preflight.governanceNextAction));
   lines.push(...buildConsumerPreflightBlockingCauseLines(preflight));
 
   if (preflight.hints.length > 0) {

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

@@ -2,6 +2,11 @@ import {
   evaluateAiGate,
   type AiGateCheckResult,
 } from '../integrations/gate/evaluateAiGate';
+import { readLifecycleExperimentalFeaturesSnapshot } from '../integrations/lifecycle/experimentalFeaturesSnapshot';
+import { LifecycleGitService } from '../integrations/lifecycle/gitService';
+import { readGovernanceObservationSnapshot } from '../integrations/lifecycle/governanceObservationSnapshot';
+import { readGovernanceNextAction } from '../integrations/lifecycle/governanceNextAction';
+import { readLifecyclePolicyValidationSnapshot } from '../integrations/lifecycle/policyValidationSnapshot';
 import {
   emitSystemNotification,
   type PumukiCriticalNotificationEvent,
@@ -28,6 +33,7 @@ const defaultDependencies: ConsumerPreflightDependencies = {
       event: params.event,
       repoRoot: params.repoRoot,
     }),
+  readGovernanceNextAction,
 };
 
 const buildNotificationEvents = (
@@ -86,6 +92,17 @@ export const runConsumerPreflight = (
     repoRoot,
     stage: params.stage,
   });
+  const governanceObservation = readGovernanceObservationSnapshot({
+    repoRoot,
+    experimentalFeatures: readLifecycleExperimentalFeaturesSnapshot(),
+    policyValidation: readLifecyclePolicyValidationSnapshot(repoRoot),
+    git: new LifecycleGitService(),
+  });
+  const governanceNextAction = activeDependencies.readGovernanceNextAction({
+    repoRoot,
+    stage: params.stage,
+    governanceObservation,
+  });
   const hints = buildConsumerPreflightHints(result, params.stage);
   const notificationEvents = buildNotificationEvents(result);
   const notificationResults = notificationEvents.map((event) =>
@@ -99,6 +116,8 @@ export const runConsumerPreflight = (
     stage: params.stage,
     status: result.status,
     result,
+    governanceObservation,
+    governanceNextAction,
     hints,
     notificationResults,
   };

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

@@ -2,6 +2,11 @@ import type {
   AiGateCheckResult,
   AiGateViolation,
 } from '../integrations/gate/evaluateAiGate';
+import type {
+  GovernanceNextActionReader,
+  GovernanceNextActionSummary,
+} from '../integrations/lifecycle/governanceNextAction';
+import type { GovernanceObservationSnapshot } from '../integrations/lifecycle/governanceObservationSnapshot';
 import type {
   PumukiCriticalNotificationEvent,
   SystemNotificationEmitResult,
@@ -13,6 +18,8 @@ export type ConsumerPreflightResult = {
   stage: ConsumerPreflightStage;
   status: AiGateCheckResult['status'];
   result: AiGateCheckResult;
+  governanceObservation: GovernanceObservationSnapshot;
+  governanceNextAction: GovernanceNextActionSummary;
   hints: ReadonlyArray<string>;
   notificationResults: ReadonlyArray<SystemNotificationEmitResult>;
 };
@@ -26,6 +33,7 @@ export type ConsumerPreflightDependencies = {
     event: PumukiCriticalNotificationEvent;
     repoRoot: string;
   }) => SystemNotificationEmitResult;
+  readGovernanceNextAction: GovernanceNextActionReader;
 };
 
 export type ConsumerPreflightRenderOptions = {

package/scripts/pumuki-full-surface-smoke-lib.ts

@@ -0,0 +1,37 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export type SmokeBinStrategy = 'source' | 'installed';
+
+export const resolveBinStrategy = (raw: string | undefined): SmokeBinStrategy => {
+  const normalized = (raw ?? 'source').trim().toLowerCase();
+  if (normalized === 'installed' || normalized === 'consumer') {
+    return 'installed';
+  }
+  return 'source';
+};
+
+export type SmokeLayout = {
+  pumukiPackageRoot: string;
+  smokeCwd: string;
+  binStrategy: SmokeBinStrategy;
+  binRoot: string;
+};
+
+export const resolveSmokeLayout = (params: {
+  scriptFileUrl: string;
+  env: NodeJS.ProcessEnv;
+}): SmokeLayout => {
+  const pumukiPackageRoot = join(dirname(fileURLToPath(params.scriptFileUrl)), '..');
+  const smokeCwd =
+    (params.env.PUMUKI_SMOKE_REPO_ROOT ?? pumukiPackageRoot).trim() || pumukiPackageRoot;
+  const binStrategy = resolveBinStrategy(params.env.PUMUKI_SMOKE_BIN_STRATEGY);
+  const binRoot =
+    binStrategy === 'installed'
+      ? join(smokeCwd, 'node_modules', 'pumuki')
+      : pumukiPackageRoot;
+  return { pumukiPackageRoot, smokeCwd, binStrategy, binRoot };
+};
+
+export const installedBinMarkerPath = (layout: SmokeLayout): string =>
+  join(layout.binRoot, 'bin', 'pumuki.js');

package/scripts/pumuki-full-surface-smoke.ts

@@ -0,0 +1,261 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  installedBinMarkerPath,
+  resolveSmokeLayout,
+} from './pumuki-full-surface-smoke-lib';
+
+type SmokeRow = {
+  id: string;
+  bin: string;
+  args: ReadonlyArray<string>;
+  timeoutMs: number;
+  allowNonZero?: boolean;
+};
+
+const layout = resolveSmokeLayout({
+  scriptFileUrl: import.meta.url,
+  env: process.env,
+});
+
+const { pumukiPackageRoot, smokeCwd, binStrategy, binRoot } = layout;
+const node = process.execPath;
+const binPath = (name: string): string => join(binRoot, 'bin', name);
+
+const run = (row: SmokeRow): { code: number | null; signal: NodeJS.Signals | null; ms: number } => {
+  const started = Date.now();
+  const r = spawnSync(node, [binPath(row.bin), ...row.args], {
+    cwd: smokeCwd,
+    encoding: 'utf8',
+    timeout: row.timeoutMs,
+    maxBuffer: 50 * 1024 * 1024,
+    env: { ...process.env, FORCE_COLOR: '0' },
+  });
+  return { code: r.status, signal: r.signal, ms: Date.now() - started };
+};
+
+const rows: ReadonlyArray<SmokeRow> = [
+  { id: 'cli.help_implicit', bin: 'pumuki.js', args: [], timeoutMs: 15_000, allowNonZero: true },
+  { id: 'cli.help_explicit', bin: 'pumuki.js', args: ['--help'], timeoutMs: 15_000 },
+  {
+    id: 'cli.unknown_subcommand',
+    bin: 'pumuki.js',
+    args: ['__no_such_lifecycle_command__'],
+    timeoutMs: 15_000,
+    allowNonZero: true,
+  },
+  { id: 'doctor.json', bin: 'pumuki.js', args: ['doctor', '--json'], timeoutMs: 60_000 },
+  {
+    id: 'doctor.deep_json',
+    bin: 'pumuki.js',
+    args: ['doctor', '--deep', '--json'],
+    timeoutMs: 180_000,
+    allowNonZero: true,
+  },
+  { id: 'doctor.parity_json', bin: 'pumuki.js', args: ['doctor', '--parity', '--json'], timeoutMs: 120_000 },
+  { id: 'status.json', bin: 'pumuki.js', args: ['status', '--json'], timeoutMs: 90_000 },
+  {
+    id: 'audit.default_json',
+    bin: 'pumuki.js',
+    args: ['audit', '--json'],
+    timeoutMs: 300_000,
+    allowNonZero: true,
+  },
+  {
+    id: 'audit.pre_push_json',
+    bin: 'pumuki.js',
+    args: ['audit', '--stage=PRE_PUSH', '--json'],
+    timeoutMs: 300_000,
+    allowNonZero: true,
+  },
+  {
+    id: 'audit.ci_engine_json',
+    bin: 'pumuki.js',
+    args: ['audit', '--stage=CI', '--engine', '--json'],
+    timeoutMs: 300_000,
+    allowNonZero: true,
+  },
+  {
+    id: 'watch.once_json',
+    bin: 'pumuki.js',
+    args: [
+      'watch',
+      '--once',
+      '--json',
+      '--stage=PRE_COMMIT',
+      '--scope=repo',
+      '--interval-ms=200',
+      '--no-notify',
+    ],
+    timeoutMs: 180_000,
+  },
+  {
+    id: 'watch.once_staged_json',
+    bin: 'pumuki.js',
+    args: [
+      'watch',
+      '--once',
+      '--json',
+      '--stage=PRE_COMMIT',
+      '--scope=staged',
+      '--interval-ms=200',
+      '--no-notify',
+    ],
+    timeoutMs: 180_000,
+    allowNonZero: true,
+  },
+  { id: 'loop.list_json', bin: 'pumuki.js', args: ['loop', 'list', '--json'], timeoutMs: 30_000 },
+  {
+    id: 'loop.run_smoke',
+    bin: 'pumuki.js',
+    args: ['loop', 'run', '--objective=smoke-surface', '--max-attempts=1', '--json'],
+    timeoutMs: 300_000,
+    allowNonZero: true,
+  },
+  {
+    id: 'adapter.install_dry_repo_json',
+    bin: 'pumuki.js',
+    args: ['adapter', 'install', '--agent=repo', '--dry-run', '--json'],
+    timeoutMs: 30_000,
+  },
+  {
+    id: 'adapter.install_dry_codex_json',
+    bin: 'pumuki.js',
+    args: ['adapter', 'install', '--agent=codex', '--dry-run', '--json'],
+    timeoutMs: 30_000,
+  },
+  {
+    id: 'analytics.hotspots_report',
+    bin: 'pumuki.js',
+    args: ['analytics', 'hotspots', 'report', '--top=3', '--since-days=30', '--json'],
+    timeoutMs: 120_000,
+    allowNonZero: true,
+  },
+  {
+    id: 'analytics.hotspots_diagnose',
+    bin: 'pumuki.js',
+    args: ['analytics', 'hotspots', 'diagnose', '--json'],
+    timeoutMs: 120_000,
+    allowNonZero: true,
+  },
+  {
+    id: 'policy.reconcile_json',
+    bin: 'pumuki.js',
+    args: ['policy', 'reconcile', '--json'],
+    timeoutMs: 120_000,
+    allowNonZero: true,
+  },
+  {
+    id: 'policy.reconcile_strict_json',
+    bin: 'pumuki.js',
+    args: ['policy', 'reconcile', '--strict', '--json'],
+    timeoutMs: 120_000,
+    allowNonZero: true,
+  },
+  { id: 'sdd.status_json', bin: 'pumuki.js', args: ['sdd', 'status', '--json'], timeoutMs: 60_000 },
+  {
+    id: 'sdd.validate_pre_write_json',
+    bin: 'pumuki.js',
+    args: ['sdd', 'validate', '--stage=PRE_WRITE', '--json'],
+    timeoutMs: 120_000,
+    allowNonZero: true,
+  },
+  {
+    id: 'sdd.validate_precommit_json',
+    bin: 'pumuki.js',
+    args: ['sdd', 'validate', '--stage=PRE_COMMIT', '--json'],
+    timeoutMs: 120_000,
+    allowNonZero: true,
+  },
+  {
+    id: 'sdd.validate_prepush_json',
+    bin: 'pumuki.js',
+    args: ['sdd', 'validate', '--stage=PRE_PUSH', '--json'],
+    timeoutMs: 120_000,
+    allowNonZero: true,
+  },
+  {
+    id: 'sdd.validate_ci_json',
+    bin: 'pumuki.js',
+    args: ['sdd', 'validate', '--stage=CI', '--json'],
+    timeoutMs: 120_000,
+    allowNonZero: true,
+  },
+  { id: 'hook.pre_write', bin: 'pumuki-pre-write.js', args: [], timeoutMs: 300_000, allowNonZero: true },
+  { id: 'hook.pre_commit', bin: 'pumuki-pre-commit.js', args: [], timeoutMs: 300_000, allowNonZero: true },
+  { id: 'hook.pre_push', bin: 'pumuki-pre-push.js', args: [], timeoutMs: 300_000, allowNonZero: true },
+  { id: 'hook.ci', bin: 'pumuki-ci.js', args: [], timeoutMs: 300_000, allowNonZero: true },
+];
+
+const main = (): number => {
+  if (binStrategy === 'installed') {
+    const marker = installedBinMarkerPath(layout);
+    if (!existsSync(marker)) {
+      process.stderr.write(
+        `[pumuki] smoke: PUMUKI_SMOKE_BIN_STRATEGY=installed pero no existe ${marker}. ` +
+          'Ejecuta npm install en el consumidor o revisa PUMUKI_SMOKE_REPO_ROOT.\n'
+      );
+      return 2;
+    }
+  }
+
+  const lines: string[] = [];
+  lines.push('# Pumuki superficie — smoke');
+  lines.push('');
+  lines.push(`- binStrategy: \`${binStrategy}\` (PUMUKI_SMOKE_BIN_STRATEGY=source|installed)`);
+  lines.push(`- binRoot: \`${binRoot}\``);
+  lines.push(`- pumukiPackageRoot (script host): \`${pumukiPackageRoot}\``);
+  lines.push(`- smokeCwd (gate/doctor cwd): \`${smokeCwd}\``);
+  lines.push(`- node: \`${node}\``);
+  lines.push(`- filas: **${rows.length}** (incluye CLI, doctor/status, audit×3, watch×2, loop, adapter×2, analytics×2, policy×2, sdd×5, hooks×4)`);
+  lines.push('');
+  lines.push('| id | exit | ms | ok |');
+  lines.push('|----|------|----|----|');
+  let failed = 0;
+  for (const row of rows) {
+    const { code, signal, ms } = run(row);
+    const exit = signal ? `signal:${signal}` : String(code ?? 'null');
+    const ok =
+      signal !== null
+        ? false
+        : row.allowNonZero
+          ? true
+          : code === 0;
+    if (!ok) {
+      failed += 1;
+    }
+    lines.push(`| ${row.id} | ${exit} | ${ms} | ${ok ? 'yes' : 'no'} |`);
+  }
+  lines.push('');
+  lines.push('## Interpretación de exit codes');
+  lines.push('');
+  lines.push('- `audit` devuelve el **mismo código que el gate** del alcance auditado (p. ej. 1 si hay `BLOCK` en el repo). Eso es correcto, no indica CLI roto.');
+  lines.push('- `doctor --deep` puede devolver **1** si `doctorHasBlockingIssues` (issues `error` o `deep.blocking`) o mismatch de parity esperado.');
+  lines.push('- Los **hooks** (`pre-commit`, etc.) reflejan el gate sobre el estado actual del worktree; 1 con cambios locales o rama protegida es esperable.');
+  lines.push('- `sdd validate` y `policy reconcile --strict` pueden devolver **1** según política del repo; el smoke los marca con `allowNonZero`.');
+  lines.push('');
+  lines.push('## No cubierto aquí (manual o destructivo)');
+  lines.push('');
+  lines.push('- `pumuki install|uninstall|remove|update|bootstrap` (mutan hooks/artefactos).');
+  lines.push('- `pumuki framework` / menú interactivo (`pumuki-framework.js`).');
+  lines.push('- Servidores MCP stdio (`pumuki-mcp-*-stdio.js`): esperan JSON-RPC por stdin; probar con cliente MCP.');
+  lines.push('- `pumuki sdd session|sync|learn|evidence|state-sync|auto-sync`: requieren ids / evidencia / cambios reales.');
+  lines.push('- `pumuki doctor|status --remote-checks`: dependen de red / GitHub.');
+  lines.push('');
+  lines.push('## Otro repo (consumidor)');
+  lines.push('');
+  lines.push(
+    '- **Bins del tree pumuki (desarrollo):** `PUMUKI_SMOKE_REPO_ROOT=/ruta/al/repo npm run -s smoke:pumuki-surface` desde la raíz de **pumuki** (`PUMUKI_SMOKE_BIN_STRATEGY=source` por defecto).'
+  );
+  lines.push(
+    '- **Bins instalados en el consumidor (`node_modules/pumuki`):** `PUMUKI_SMOKE_REPO_ROOT=/ruta/al/repo PUMUKI_SMOKE_BIN_STRATEGY=installed npm run -s smoke:pumuki-surface` o `npm run -s smoke:pumuki-surface-installed` (exige `PUMUKI_SMOKE_REPO_ROOT`).'
+  );
+  lines.push('');
+  lines.push(`**Resumen:** ${failed} filas con fallo estricto (sin allowNonZero).`);
+  process.stdout.write(lines.join('\n'));
+  process.stdout.write('\n');
+  return failed > 0 ? 1 : 0;
+};
+
+process.exitCode = main();

package/scripts/pumuki-smoke-installed-wrapper.cjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const { join } = require('node:path');
+
+if (!process.env.PUMUKI_SMOKE_REPO_ROOT || !String(process.env.PUMUKI_SMOKE_REPO_ROOT).trim()) {
+  console.error(
+    '[pumuki] smoke:pumuki-surface-installed requires PUMUKI_SMOKE_REPO_ROOT (absolute path to consumer repo).'
+  );
+  process.exit(1);
+}
+
+const root = join(__dirname, '..');
+const env = {
+  ...process.env,
+  PUMUKI_SMOKE_BIN_STRATEGY: 'installed',
+};
+
+const result = spawnSync(
+  'npx',
+  ['--yes', 'tsx@4.21.0', 'scripts/pumuki-full-surface-smoke.ts'],
+  {
+    cwd: root,
+    env,
+    stdio: 'inherit',
+  }
+);
+
+const code = typeof result.status === 'number' ? result.status : 1;
+process.exitCode = code;