pumuki 6.3.116 → 6.3.118

package/CHANGELOG.md

@@ -6,6 +6,21 @@ This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [6.3.118] - 2026-04-28
+
+### Fixed
+
+- **Guard PRE_WRITE para editores/agentes vía MCP:** el catálogo enterprise expone `pre_write_guard`, una tool no mutante que ejecuta `audit --stage=PRE_WRITE --json` y devuelve `findings` accionables antes de permitir continuar una edición/restauración de ficheros.
+- **Cierre operativo de `PUMUKI-INC-109`:** RuralGo ya tiene una ruta MCP explícita para bloquear antes de escribir, no sólo en commit/gate posterior.
+
+## [6.3.117] - 2026-04-28
+
+### Fixed
+
+- **`pumuki audit --json` queda accionable cuando bloquea:** la salida ahora expone `findings_count`, `blocking_findings_count` y `findings`; si el gate bloquea sin findings persistidos, emite un blocker sintético `AUDIT_BLOCKED_WITHOUT_FINDINGS` para evitar JSON no accionable.
+- **Auditoría previa a edición:** `pumuki audit --stage=PRE_WRITE --json` queda soportado para dar a consumers como RuralGo un contrato machine-friendly antes de continuar feature work.
+- **Tracking externo prioritario:** el reset interno queda alineado con el bloqueo vivo de RuralGo `PUMUKI-INC-109`/`PUMUKI-INC-110`.
+
 ## [6.3.116] - 2026-04-25
 
 ### Fixed

package/VERSION

@@ -1 +1 @@
-v6.3.116
+v6.3.118

package/integrations/lifecycle/audit.ts

@@ -1,12 +1,23 @@
 import { readEvidence } from '../evidence/readEvidence';
-import { GitService } from '../git/GitService';
+import type { AiEvidenceV2_1, SnapshotFinding } from '../evidence/schema';
+import { GitService, type IGitService } from '../git/GitService';
 import { hasAllowedExtension } from '../git/gitDiffUtils';
 import { runPlatformGate } from '../git/runPlatformGate';
 import { evaluatePlatformGateFindings } from '../git/runPlatformGateEvaluation';
 import { DEFAULT_FACT_FILE_EXTENSIONS } from '../git/runPlatformGateFacts';
-import { resolvePolicyForStage } from '../gate/stagePolicies';
+import { resolvePolicyForStage, type ResolvedStagePolicy } from '../gate/stagePolicies';
 
-export type LifecycleAuditStage = 'PRE_COMMIT' | 'PRE_PUSH' | 'CI';
+export type LifecycleAuditStage = 'PRE_WRITE' | 'PRE_COMMIT' | 'PRE_PUSH' | 'CI';
+
+export type LifecycleAuditFinding = {
+  ruleId: string;
+  severity: string;
+  code: string;
+  message: string;
+  file: string;
+  lines?: SnapshotFinding['lines'];
+  blocking: boolean;
+};
 
 export type LifecycleAuditResult = {
   command: 'pumuki audit';
@@ -18,14 +29,24 @@ export type LifecycleAuditResult = {
   files_scanned: number | null;
   untracked_matching_extensions_count: number;
   snapshot_outcome: string | null;
+  findings_count: number;
+  blocking_findings_count: number;
+  findings: ReadonlyArray<LifecycleAuditFinding>;
   policy_reconcile_hint: string;
 };
 
+type LifecycleAuditDependencies = {
+  git: IGitService;
+  readEvidence: typeof readEvidence;
+  resolvePolicyForStage: typeof resolvePolicyForStage;
+  runPlatformGate: typeof runPlatformGate;
+};
+
 const POLICY_RECONCILE_HINT =
   'If .pumuki/policy-as-code.json signatures drift after a pumuki upgrade, run: pumuki policy reconcile --apply';
 
 const countUntrackedMatchingExtensions = (
-  git: GitService,
+  git: Pick<IGitService, 'resolveRepoRoot' | 'runGit'>,
   extensions: ReadonlyArray<string>
 ): number => {
   const repoRoot = git.resolveRepoRoot();
@@ -37,13 +58,80 @@ const countUntrackedMatchingExtensions = (
     .filter((path) => hasAllowedExtension(path, extensions)).length;
 };
 
+const isFindingBlocking = (finding: SnapshotFinding): boolean => {
+  if (typeof finding.blocking === 'boolean') {
+    return finding.blocking;
+  }
+  return finding.severity === 'CRITICAL' || finding.severity === 'ERROR';
+};
+
+const toLifecycleAuditFinding = (finding: SnapshotFinding): LifecycleAuditFinding => ({
+  ruleId: finding.ruleId,
+  severity: finding.severity,
+  code: finding.code,
+  message: finding.message,
+  file: finding.file,
+  ...(typeof finding.lines !== 'undefined' ? { lines: finding.lines } : {}),
+  blocking: isFindingBlocking(finding),
+});
+
+const buildBlockedWithoutFindingsFallback = (params: {
+  stage: LifecycleAuditStage;
+  gateExitCode: number;
+  snapshotOutcome: string | null;
+}): LifecycleAuditFinding => ({
+  ruleId: 'audit.gate.blocked-without-findings',
+  severity: 'ERROR',
+  code: 'AUDIT_BLOCKED_WITHOUT_FINDINGS',
+  message:
+    `Audit ${params.stage} exited ${params.gateExitCode} with outcome=${params.snapshotOutcome ?? 'unknown'} ` +
+    'but produced no machine-readable findings. Re-run with this Pumuki version and inspect policy/SDD output; this fallback keeps JSON actionable.',
+  file: '.ai_evidence.json',
+  blocking: true,
+});
+
+const extractAuditFindings = (params: {
+  evidence: AiEvidenceV2_1 | undefined;
+  gateExitCode: number;
+  stage: LifecycleAuditStage;
+  snapshotOutcome: string | null;
+}): ReadonlyArray<LifecycleAuditFinding> => {
+  const findings = Array.isArray(params.evidence?.snapshot.findings)
+    ? params.evidence.snapshot.findings.map(toLifecycleAuditFinding)
+    : [];
+  if (findings.length > 0) {
+    return findings;
+  }
+  if (params.gateExitCode !== 0 || params.snapshotOutcome === 'BLOCK') {
+    return [
+      buildBlockedWithoutFindingsFallback({
+        stage: params.stage,
+        gateExitCode: params.gateExitCode,
+        snapshotOutcome: params.snapshotOutcome,
+      }),
+    ];
+  }
+  return [];
+};
+
 export const runLifecycleAudit = async (params: {
   stage: LifecycleAuditStage;
   auditMode: 'gate' | 'engine';
+  dependencies?: Partial<LifecycleAuditDependencies>;
 }): Promise<LifecycleAuditResult> => {
-  const git = new GitService();
+  const activeDependencies: LifecycleAuditDependencies = {
+    git: new GitService(),
+    readEvidence,
+    resolvePolicyForStage,
+    runPlatformGate,
+    ...params.dependencies,
+  };
+  const git = activeDependencies.git;
   const repoRoot = git.resolveRepoRoot();
-  const resolved = resolvePolicyForStage(params.stage, repoRoot);
+  const resolved: ResolvedStagePolicy = activeDependencies.resolvePolicyForStage(
+    params.stage,
+    repoRoot
+  );
   const extensions = DEFAULT_FACT_FILE_EXTENSIONS;
   const untrackedMatchingExtensionsCount = countUntrackedMatchingExtensions(git, extensions);
 
@@ -76,8 +164,8 @@ export const runLifecycleAudit = async (params: {
           auditMode: 'gate' as const,
         };
 
-  const gateExitCode = await runPlatformGate(gateParams);
-  const evidence = readEvidence(repoRoot);
+  const gateExitCode = await activeDependencies.runPlatformGate(gateParams);
+  const evidence = activeDependencies.readEvidence(repoRoot);
   const filesScanned =
     typeof evidence?.snapshot.files_scanned === 'number' &&
     Number.isFinite(evidence.snapshot.files_scanned)
@@ -85,6 +173,12 @@ export const runLifecycleAudit = async (params: {
       : null;
   const snapshotOutcome =
     typeof evidence?.snapshot.outcome === 'string' ? evidence.snapshot.outcome : null;
+  const findings = extractAuditFindings({
+    evidence,
+    gateExitCode,
+    stage: params.stage,
+    snapshotOutcome,
+  });
 
   return {
     command: 'pumuki audit',
@@ -96,6 +190,9 @@ export const runLifecycleAudit = async (params: {
     files_scanned: filesScanned,
     untracked_matching_extensions_count: untrackedMatchingExtensionsCount,
     snapshot_outcome: snapshotOutcome,
+    findings_count: findings.length,
+    blocking_findings_count: findings.filter((finding) => finding.blocking).length,
+    findings,
     policy_reconcile_hint: POLICY_RECONCILE_HINT,
   };
 };

package/integrations/lifecycle/cli.ts

@@ -188,7 +188,7 @@ Pumuki lifecycle commands:
   pumuki remove
   pumuki update [--latest|--spec=<package-spec>]
   pumuki doctor [--remote-checks] [--deep] [--parity] [--json]
-  pumuki audit [--stage=PRE_COMMIT|PRE_PUSH|CI] [--engine] [--json]
+  pumuki audit [--stage=PRE_WRITE|PRE_COMMIT|PRE_PUSH|CI] [--engine] [--json]
   pumuki status [--json] [--remote-checks]
   pumuki watch [--stage=PRE_COMMIT|PRE_PUSH|CI] [--scope=workingTree|staged|repoAndStaged|repo] [--severity=critical|high|medium|low] [--interval-ms=<n>] [--notify-cooldown-ms=<n>] [--no-notify] [--once|--iterations=<n>] [--json]
   pumuki loop run --objective=<text> [--max-attempts=<n>] [--json]
@@ -266,13 +266,7 @@ const parseSddStage = (value?: string): SddStage => {
 };
 
 const parseAuditStage = (value?: string): LifecycleAuditStage => {
-  const stage = parseSddStage(value);
-  if (stage === 'PRE_WRITE') {
-    throw new Error(
-      'PRE_WRITE is not supported for "pumuki audit". Use PRE_COMMIT, PRE_PUSH or CI (aliases GREEN, REFACTOR, CLOSE).'
-    );
-  }
-  return stage;
+  return parseSddStage(value);
 };
 
 const parseSddEvidencePath = (value: string): string => {

package/integrations/mcp/enterpriseServer.ts

@@ -4,7 +4,7 @@ import type { Server } from 'node:http';
 import { execFileSync as runBinarySync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { readLifecycleStatus } from '../lifecycle';
+import { readLifecycleStatus, runLifecycleAudit } from '../lifecycle';
 import { resolveMcpEnterpriseExperimentalFeature } from '../policy/experimentalFeatures';
 import { evaluateSddPolicy, readSddStatus } from '../sdd';
 import type { SddStage } from '../sdd';
@@ -75,6 +75,7 @@ const ENTERPRISE_RESOURCE_DESCRIPTORS: ReadonlyArray<{
 ];
 
 const ENTERPRISE_TOOLS = [
+  'pre_write_guard',
   'ai_gate_check',
   'pre_flight_check',
   'auto_execute_ai_start',
@@ -91,6 +92,12 @@ const ENTERPRISE_TOOL_DESCRIPTORS: ReadonlyArray<{
   mutating: boolean;
   safeByDefault: boolean;
 }> = [
+  {
+    name: 'pre_write_guard',
+    description: 'Runs the PRE_WRITE audit gate and returns actionable findings before an editor/agent writes code.',
+    mutating: false,
+    safeByDefault: true,
+  },
   {
     name: 'ai_gate_check',
     description: 'Reads .ai_evidence.json and reports AI gate compatibility status.',
@@ -382,13 +389,41 @@ const evaluateCriticalToolGuard = (
   }
 };
 
-const executeEnterpriseTool = (
+const executeEnterpriseTool = async (
   repoRoot: string,
   toolName: EnterpriseToolName,
   args: Record<string, string | number | boolean | bigint | symbol | null | Date | object>,
   dryRun: boolean
-): EnterpriseToolExecution => {
+): Promise<EnterpriseToolExecution> => {
   switch (toolName) {
+    case 'pre_write_guard': {
+      const audit = await runLifecycleAudit({
+        repoRoot,
+        stage: 'PRE_WRITE',
+        auditMode: 'gate',
+      });
+      return {
+        name: toolName,
+        success: audit.gate_exit_code === 0 && audit.blocking_findings_count === 0,
+        dryRun: true,
+        executed: true,
+        warnings: audit.blocking_findings_count > 0
+          ? ['PRE_WRITE guard blocked before editor write; inspect result.findings.']
+          : [],
+        data: {
+          ...audit,
+          next_action: audit.blocking_findings_count > 0
+            ? {
+                kind: 'inspect_findings',
+                message: 'Corrige los findings bloqueantes antes de escribir o restaurar ficheros.',
+              }
+            : {
+                kind: 'continue',
+                message: 'PRE_WRITE guard passed.',
+              },
+        },
+      };
+    }
     case 'ai_gate_check': {
       const stage = toSddStage(args.stage, 'PRE_COMMIT');
       const execution = runEnterpriseAiGateCheck({
@@ -741,7 +776,7 @@ export const startEnterpriseMcpServer = (
         return;
       }
       void readJsonBody(req)
-        .then((body) => {
+        .then(async (body) => {
           if (typeof body !== 'object' || body === null) {
             sendJson(res, 400, {
               error: 'Invalid request body.',
@@ -814,7 +849,7 @@ export const startEnterpriseMcpServer = (
           }
           let result: EnterpriseToolExecution;
           try {
-            result = executeEnterpriseTool(
+            result = await executeEnterpriseTool(
               repoRoot,
               toolName,
               args,

package/package.json

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