pumuki 6.3.116 → 6.3.117

package/CHANGELOG.md

@@ -6,6 +6,14 @@ This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [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.117

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/package.json

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