pumuki 6.3.13 → 6.3.14

package/integrations/evidence/buildEvidence.ts

@@ -11,6 +11,7 @@ import type {
   LedgerEntry,
   PlatformState,
   RulesetState,
+  SddMetrics,
   SnapshotFinding,
 } from './schema';
 import { resolveHumanIntent } from './humanIntent';
@@ -28,6 +29,7 @@ export type BuildEvidenceParams = {
   humanIntent?: HumanIntentState | null;
   detectedPlatforms: Record<string, PlatformState>;
   loadedRulesets: ReadonlyArray<RulesetState>;
+  sddMetrics?: SddMetrics;
 };
 
 const normalizeLines = (lines?: EvidenceLines): EvidenceLines | undefined => {
@@ -96,6 +98,30 @@ const normalizeFinding = (finding: BuildFindingInput): SnapshotFinding => {
   };
 };
 
+const pickDeterministicDuplicateFinding = (
+  current: SnapshotFinding,
+  candidate: SnapshotFinding
+): SnapshotFinding => {
+  const bySeverity = severityRank[candidate.severity] - severityRank[current.severity];
+  if (bySeverity > 0) {
+    return candidate;
+  }
+  if (bySeverity < 0) {
+    return current;
+  }
+
+  const tuple = (finding: SnapshotFinding): string => {
+    return [
+      finding.code,
+      finding.message,
+      finding.matchedBy ?? '',
+      finding.source ?? '',
+    ].join('\u0000');
+  };
+
+  return tuple(candidate).localeCompare(tuple(current)) < 0 ? candidate : current;
+};
+
 const severityRank: Record<Severity, number> = {
   INFO: 0,
   WARN: 1,
@@ -228,9 +254,11 @@ const normalizeAndDedupeFindings = (
   for (const finding of findings) {
     const normalized = normalizeFinding(finding);
     const key = findingKey(normalized);
-    if (!unique.has(key)) {
-      unique.set(key, normalized);
-    }
+    const current = unique.get(key);
+    unique.set(
+      key,
+      current ? pickDeterministicDuplicateFinding(current, normalized) : normalized
+    );
   }
   const deduped = Array.from(unique.values()).sort(compareFindingEntries);
   const consolidated = consolidateEquivalentFindings(deduped);
@@ -371,6 +399,17 @@ export function buildEvidence(params: BuildEvidenceParams): AiEvidenceV2_1 {
       total_violations: normalizedFindings.length,
       by_severity: severity,
     },
+    sdd_metrics: params.sddMetrics
+      ? {
+        enforced: params.sddMetrics.enforced,
+        stage: params.sddMetrics.stage,
+        decision: {
+          allowed: params.sddMetrics.decision.allowed,
+          code: params.sddMetrics.decision.code,
+          message: params.sddMetrics.decision.message,
+        },
+      }
+      : undefined,
     consolidation:
       consolidatedFindings.suppressed.length > 0
         ? { suppressed: consolidatedFindings.suppressed }

package/integrations/evidence/generateEvidence.test.ts

@@ -121,3 +121,62 @@ test('generateEvidence respeta gateOutcome explícito al componer build + write'
     });
   });
 });
+
+test('generateEvidence persiste contrato SDD cuando se informa bloqueo de policy', async () => {
+  await withTempDir('pumuki-generate-evidence-sdd-contract-', async (tempRoot) => {
+    initGitRepo(tempRoot);
+    await withCwd(tempRoot, async () => {
+      const result = generateEvidence({
+        stage: 'PRE_PUSH',
+        gateOutcome: 'BLOCK',
+        findings: [
+          {
+            ruleId: 'sdd.policy.blocked',
+            severity: 'ERROR',
+            code: 'SDD_VALIDATION_FAILED',
+            message: 'OpenSpec validation failed',
+            filePath: 'openspec/changes',
+            matchedBy: 'SddPolicy',
+            source: 'sdd-policy',
+          },
+        ],
+        detectedPlatforms: {},
+        loadedRulesets: [{ platform: 'policy', bundle: 'gate-policy.default.PRE_PUSH', hash: 'hash-policy' }],
+        sddMetrics: {
+          enforced: true,
+          stage: 'PRE_PUSH',
+          decision: {
+            allowed: false,
+            code: 'SDD_VALIDATION_FAILED',
+            message: 'OpenSpec validation failed',
+          },
+        },
+      });
+
+      assert.equal(result.evidence.snapshot.findings[0]?.source, 'sdd-policy');
+      assert.deepEqual(result.evidence.sdd_metrics, {
+        enforced: true,
+        stage: 'PRE_PUSH',
+        decision: {
+          allowed: false,
+          code: 'SDD_VALIDATION_FAILED',
+          message: 'OpenSpec validation failed',
+        },
+      });
+      assert.equal(result.write.ok, true);
+
+      const persisted = JSON.parse(readFileSync(join(tempRoot, '.ai_evidence.json'), 'utf8')) as AiEvidenceV2_1;
+      assert.equal(persisted.snapshot.findings[0]?.source, 'sdd-policy');
+      assert.equal(persisted.ai_gate.violations[0]?.source, 'sdd-policy');
+      assert.deepEqual(persisted.sdd_metrics, {
+        enforced: true,
+        stage: 'PRE_PUSH',
+        decision: {
+          allowed: false,
+          code: 'SDD_VALIDATION_FAILED',
+          message: 'OpenSpec validation failed',
+        },
+      });
+    });
+  });
+});

package/integrations/evidence/readEvidence.test.ts

@@ -57,6 +57,67 @@ test('readEvidenceResult devuelve valid cuando el archivo tiene version 2.1', as
   });
 });
 
+test('readEvidenceResult preserva contrato SDD (sdd_metrics + source sdd-policy)', async () => {
+  await withTempDir('pumuki-read-evidence-sdd-contract-', async (tempRoot) => {
+    const evidence = sampleEvidence();
+    evidence.snapshot.stage = 'PRE_PUSH';
+    evidence.snapshot.outcome = 'BLOCK';
+    evidence.snapshot.findings = [
+      {
+        ruleId: 'sdd.policy.blocked',
+        severity: 'ERROR',
+        code: 'SDD_VALIDATION_FAILED',
+        message: 'OpenSpec validation failed',
+        file: 'openspec/changes',
+        matchedBy: 'SddPolicy',
+        source: 'sdd-policy',
+      },
+    ];
+    evidence.ledger = [
+      {
+        ruleId: 'sdd.policy.blocked',
+        file: 'openspec/changes',
+        firstSeen: '2026-02-18T10:00:00.000Z',
+        lastSeen: '2026-02-18T10:01:00.000Z',
+      },
+    ];
+    evidence.ai_gate.status = 'BLOCKED';
+    evidence.ai_gate.violations = [
+      {
+        ruleId: 'sdd.policy.blocked',
+        level: 'ERROR',
+        code: 'SDD_VALIDATION_FAILED',
+        message: 'OpenSpec validation failed',
+        file: 'openspec/changes',
+        matchedBy: 'SddPolicy',
+        source: 'sdd-policy',
+      },
+    ];
+    evidence.severity_metrics.gate_status = 'BLOCKED';
+    evidence.severity_metrics.total_violations = 1;
+    evidence.severity_metrics.by_severity.ERROR = 1;
+    evidence.sdd_metrics = {
+      enforced: true,
+      stage: 'PRE_PUSH',
+      decision: {
+        allowed: false,
+        code: 'SDD_VALIDATION_FAILED',
+        message: 'OpenSpec validation failed',
+      },
+    };
+
+    writeFileSync(join(tempRoot, '.ai_evidence.json'), JSON.stringify(evidence, null, 2), 'utf8');
+
+    const result = readEvidenceResult(tempRoot);
+    assert.equal(result.kind, 'valid');
+    if (result.kind === 'valid') {
+      assert.equal(result.evidence.snapshot.findings[0]?.source, 'sdd-policy');
+      assert.equal(result.evidence.ai_gate.violations[0]?.source, 'sdd-policy');
+      assert.deepEqual(result.evidence.sdd_metrics, evidence.sdd_metrics);
+    }
+  });
+});
+
 test('readEvidenceResult devuelve invalid y versión cuando el schema es de otra versión', async () => {
   await withTempDir('pumuki-read-evidence-invalid-version-', async (tempRoot) => {
     writeFileSync(

package/integrations/evidence/schema.test.ts

@@ -81,6 +81,87 @@ test('AiEvidenceV2_1 soporta snapshot/ledger/platforms/rulesets con contrato 2.1
   assert.equal(evidence.ai_gate.violations[0]?.level, 'ERROR');
 });
 
+test('AiEvidenceV2_1 soporta contrato SDD en evidencia (sdd_metrics + source sdd-policy)', () => {
+  const evidence: AiEvidenceV2_1 = {
+    version: '2.1',
+    timestamp: '2026-02-18T10:00:00.000Z',
+    snapshot: {
+      stage: 'PRE_PUSH',
+      outcome: 'BLOCK',
+      findings: [
+        sampleFinding({
+          ruleId: 'sdd.policy.blocked',
+          severity: 'ERROR',
+          code: 'SDD_VALIDATION_FAILED',
+          message: 'OpenSpec validation failed',
+          file: 'openspec/changes',
+          lines: undefined,
+          matchedBy: 'SddPolicy',
+          source: 'sdd-policy',
+        }),
+      ],
+    },
+    ledger: [
+      {
+        ruleId: 'sdd.policy.blocked',
+        file: 'openspec/changes',
+        firstSeen: '2026-02-18T09:58:00.000Z',
+        lastSeen: '2026-02-18T10:00:00.000Z',
+      },
+    ],
+    platforms: {},
+    rulesets: [{ platform: 'policy', bundle: 'gate-policy.default.PRE_PUSH', hash: 'hash-policy' }],
+    human_intent: null,
+    ai_gate: {
+      status: 'BLOCKED',
+      violations: [
+        sampleViolation({
+          ruleId: 'sdd.policy.blocked',
+          code: 'SDD_VALIDATION_FAILED',
+          message: 'OpenSpec validation failed',
+          file: 'openspec/changes',
+          lines: undefined,
+          matchedBy: 'SddPolicy',
+          source: 'sdd-policy',
+        }),
+      ],
+      human_intent: null,
+    },
+    severity_metrics: {
+      gate_status: 'BLOCKED',
+      total_violations: 1,
+      by_severity: {
+        INFO: 0,
+        WARN: 0,
+        ERROR: 1,
+        CRITICAL: 0,
+      },
+    },
+    sdd_metrics: {
+      enforced: true,
+      stage: 'PRE_PUSH',
+      decision: {
+        allowed: false,
+        code: 'SDD_VALIDATION_FAILED',
+        message: 'OpenSpec validation failed',
+      },
+    },
+  };
+
+  assert.equal(evidence.snapshot.findings[0]?.source, 'sdd-policy');
+  assert.equal(evidence.snapshot.findings[0]?.matchedBy, 'SddPolicy');
+  assert.equal(evidence.ai_gate.violations[0]?.source, 'sdd-policy');
+  assert.deepEqual(evidence.sdd_metrics, {
+    enforced: true,
+    stage: 'PRE_PUSH',
+    decision: {
+      allowed: false,
+      code: 'SDD_VALIDATION_FAILED',
+      message: 'OpenSpec validation failed',
+    },
+  });
+});
+
 test('EvidenceLines acepta string, number y array numérico según contrato', () => {
   const stringLines = sampleFinding({ lines: 'L12-L14' });
   const numberLines = sampleFinding({ lines: 12 });

package/integrations/evidence/schema.ts

@@ -67,6 +67,16 @@ export type CompatibilityViolation = {
   source?: string;
 };
 
+export type SddMetrics = {
+  enforced: boolean;
+  stage: GateStage;
+  decision: {
+    allowed: boolean;
+    code: string;
+    message: string;
+  };
+};
+
 export type ConsolidationSuppressedFinding = {
   ruleId: string;
   file: string;
@@ -95,6 +105,7 @@ export type AiEvidenceV2_1 = {
     total_violations: number;
     by_severity: Record<Severity, number>;
   };
+  sdd_metrics?: SddMetrics;
   consolidation?: {
     suppressed: ConsolidationSuppressedFinding[];
   };

package/integrations/evidence/writeEvidence.test.ts

@@ -93,6 +93,15 @@ const sampleEvidence = (repoRoot: string): AiEvidenceV2_1 => ({
       INFO: 0,
     },
   },
+  sdd_metrics: {
+    enforced: true,
+    stage: 'PRE_PUSH',
+    decision: {
+      allowed: true,
+      code: 'ALLOWED',
+      message: 'sdd policy passed',
+    },
+  },
 });
 
 test('writeEvidence escribe archivo estable y normaliza paths/orden/lineas', async () => {
@@ -137,6 +146,15 @@ test('writeEvidence escribe archivo estable y normaliza paths/orden/lineas', asy
           ['z.rule', 'FileContent', 'git:staged'],
         ]
       );
+      assert.deepEqual(written.sdd_metrics, {
+        enforced: true,
+        stage: 'PRE_PUSH',
+        decision: {
+          allowed: true,
+          code: 'ALLOWED',
+          message: 'sdd policy passed',
+        },
+      });
     });
   });
 });

package/integrations/evidence/writeEvidence.ts

@@ -169,6 +169,17 @@ const toStableEvidence = (
       total_violations: evidence.severity_metrics.total_violations,
       by_severity: bySeverity,
     },
+    sdd_metrics: evidence.sdd_metrics
+      ? {
+        enforced: evidence.sdd_metrics.enforced,
+        stage: evidence.sdd_metrics.stage,
+        decision: {
+          allowed: evidence.sdd_metrics.decision.allowed,
+          code: evidence.sdd_metrics.decision.code,
+          message: evidence.sdd_metrics.decision.message,
+        },
+      }
+      : undefined,
   };
 };
 

package/integrations/git/resolveGitRefs.ts

@@ -26,11 +26,11 @@ const resolveDefaultCiBaseRef = (): string => {
   return 'HEAD';
 };
 
-export const resolveUpstreamRef = (): string => {
+export const resolveUpstreamRef = (): string | null => {
   try {
     return runGit(['rev-parse', '@{u}']);
   } catch {
-    return 'HEAD';
+    return null;
   }
 };
 

package/integrations/git/runPlatformGate.ts

@@ -1,12 +1,17 @@
 import { evaluateGate } from '../../core/gate/evaluateGate';
+import type { Finding } from '../../core/gate/Finding';
 import type { GatePolicy } from '../../core/gate/GatePolicy';
+import type { RuleSet } from '../../core/rules/RuleSet';
+import type { SkillsRuleSetLoadResult } from '../config/skillsRuleSet';
 import type { ResolvedStagePolicy } from '../gate/stagePolicies';
+import type { DetectedPlatforms } from '../platform/detectPlatforms';
 import { GitService, type IGitService } from './GitService';
 import { EvidenceService, type IEvidenceService } from './EvidenceService';
 import { evaluatePlatformGateFindings } from './runPlatformGateEvaluation';
 import { resolveFactsForGateScope, type GateScope } from './runPlatformGateFacts';
 import { emitPlatformGateEvidence } from './runPlatformGateEvidence';
 import { printGateFindings } from './runPlatformGateOutput';
+import { evaluateSddPolicy, type SddDecision } from '../sdd';
 
 export type GateServices = {
   git: IGitService;
@@ -19,6 +24,10 @@ export type GateDependencies = {
   resolveFactsForGateScope: typeof resolveFactsForGateScope;
   emitPlatformGateEvidence: typeof emitPlatformGateEvidence;
   printGateFindings: typeof printGateFindings;
+  evaluateSddForStage: (
+    stage: 'PRE_COMMIT' | 'PRE_PUSH' | 'CI',
+    repoRoot: string
+  ) => Pick<SddDecision, 'allowed' | 'code' | 'message'>;
 };
 
 const defaultServices: GateServices = {
@@ -32,8 +41,23 @@ const defaultDependencies: GateDependencies = {
   resolveFactsForGateScope,
   emitPlatformGateEvidence,
   printGateFindings,
+  evaluateSddForStage: (stage, repoRoot) =>
+    evaluateSddPolicy({
+      stage,
+      repoRoot,
+    }).decision,
 };
 
+const toSddBlockingFinding = (decision: Pick<SddDecision, 'code' | 'message'>): Finding => ({
+  ruleId: 'sdd.policy.blocked',
+  severity: 'ERROR',
+  code: decision.code,
+  message: decision.message,
+  filePath: 'openspec/changes',
+  matchedBy: 'SddPolicy',
+  source: 'sdd-policy',
+});
+
 export async function runPlatformGate(params: {
   policy: GatePolicy;
   policyTrace?: ResolvedStagePolicy['trace'];
@@ -48,6 +72,45 @@ export async function runPlatformGate(params: {
     ...params.dependencies,
   };
   const repoRoot = git.resolveRepoRoot();
+  let sddDecision:
+    | Pick<SddDecision, 'allowed' | 'code' | 'message'>
+    | undefined;
+
+  if (
+    params.policy.stage === 'PRE_COMMIT' ||
+    params.policy.stage === 'PRE_PUSH' ||
+    params.policy.stage === 'CI'
+  ) {
+    sddDecision = dependencies.evaluateSddForStage(
+      params.policy.stage,
+      repoRoot
+    );
+    if (!sddDecision.allowed) {
+      console.log(`[pumuki][sdd] ${sddDecision.code}: ${sddDecision.message}`);
+      const emptyDetectedPlatforms: DetectedPlatforms = {};
+      const emptySkillsRuleSet: SkillsRuleSetLoadResult = {
+        rules: [],
+        activeBundles: [],
+        mappedHeuristicRuleIds: new Set<string>(),
+        requiresHeuristicFacts: false,
+      };
+      const emptyRuleSet: RuleSet = [];
+      dependencies.emitPlatformGateEvidence({
+        stage: params.policy.stage,
+        policyTrace: params.policyTrace,
+        findings: [toSddBlockingFinding(sddDecision)],
+        gateOutcome: 'BLOCK',
+        repoRoot,
+        detectedPlatforms: emptyDetectedPlatforms,
+        skillsRuleSet: emptySkillsRuleSet,
+        projectRules: emptyRuleSet,
+        heuristicRules: emptyRuleSet,
+        evidenceService: evidence,
+        sddDecision,
+      });
+      return 1;
+    }
+  }
 
   const facts = await dependencies.resolveFactsForGateScope({
     scope: params.scope,
@@ -78,6 +141,7 @@ export async function runPlatformGate(params: {
     projectRules,
     heuristicRules,
     evidenceService: evidence,
+    sddDecision,
   });
 
   if (decision.outcome === 'BLOCK') {

package/integrations/git/runPlatformGateEvidence.ts

@@ -9,6 +9,7 @@ import type { ResolvedStagePolicy } from '../gate/stagePolicies';
 import type { DetectedPlatforms } from '../platform/detectPlatforms';
 import { buildBaselineRuleSetEntries } from './baselineRuleSets';
 import type { IEvidenceService } from './EvidenceService';
+import type { SddDecision } from '../sdd';
 
 export type PlatformGateEvidenceDependencies = {
   generateEvidence: typeof generateEvidence;
@@ -29,6 +30,7 @@ export const emitPlatformGateEvidence = (params: {
   projectRules: RuleSet;
   heuristicRules: RuleSet;
   evidenceService: IEvidenceService;
+  sddDecision?: Pick<SddDecision, 'allowed' | 'code' | 'message'>;
 }, dependencies: Partial<PlatformGateEvidenceDependencies> = {}): void => {
   const activeDependencies: PlatformGateEvidenceDependencies = {
     ...defaultDependencies,
@@ -50,5 +52,16 @@ export const emitPlatformGateEvidence = (params: {
       policyTrace: params.policyTrace,
       stage: params.stage,
     }),
+    sddMetrics: params.sddDecision
+      ? {
+        enforced: true,
+        stage: params.stage,
+        decision: {
+          allowed: params.sddDecision.allowed,
+          code: params.sddDecision.code,
+          message: params.sddDecision.message,
+        },
+      }
+      : undefined,
   });
 };

package/integrations/git/stageRunners.ts

@@ -2,6 +2,9 @@ import { resolvePolicyForStage } from '../gate/stagePolicies';
 import { resolveCiBaseRef, resolveUpstreamRef } from './resolveGitRefs';
 import { runPlatformGate } from './runPlatformGate';
 
+const PRE_PUSH_UPSTREAM_REQUIRED_MESSAGE =
+  'pumuki pre-push blocked: branch has no upstream tracking reference. Configure upstream first (for example: git push --set-upstream origin <branch>) and retry.';
+
 export async function runPreCommitStage(): Promise<number> {
   const resolved = resolvePolicyForStage('PRE_COMMIT');
   return runPlatformGate({
@@ -14,13 +17,19 @@ export async function runPreCommitStage(): Promise<number> {
 }
 
 export async function runPrePushStage(): Promise<number> {
+  const upstreamRef = resolveUpstreamRef();
+  if (!upstreamRef) {
+    console.error(PRE_PUSH_UPSTREAM_REQUIRED_MESSAGE);
+    return 1;
+  }
+
   const resolved = resolvePolicyForStage('PRE_PUSH');
   return runPlatformGate({
     policy: resolved.policy,
     policyTrace: resolved.trace,
     scope: {
       kind: 'range',
-      fromRef: resolveUpstreamRef(),
+      fromRef: upstreamRef,
       toRef: 'HEAD',
     },
   });

package/integrations/lifecycle/artifacts.ts

@@ -1,5 +1,5 @@
-import { existsSync, unlinkSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, lstatSync, readdirSync, rmdirSync, unlinkSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import type { ILifecycleGitService } from './gitService';
 
 const PUMUKI_ARTIFACTS = ['.ai_evidence.json', '.AI_EVIDENCE.json'] as const;
@@ -21,9 +21,46 @@ const isTrackedArtifactAlias = (params: {
 export const purgeUntrackedPumukiArtifacts = (params: {
   git: ILifecycleGitService;
   repoRoot: string;
+  managedOpenSpecArtifacts?: ReadonlyArray<string>;
 }): ReadonlyArray<string> => {
   const removed: string[] = [];
 
+  const pruneEmptyAncestors = (relativePath: string): void => {
+    let current = dirname(relativePath);
+    while (current !== '.' && current !== '') {
+      const absolute = join(params.repoRoot, current);
+      if (!existsSync(absolute)) {
+        break;
+      }
+      if (params.git.isPathTracked(params.repoRoot, current)) {
+        break;
+      }
+      if (readdirSync(absolute).length > 0) {
+        break;
+      }
+      rmdirSync(absolute);
+      current = dirname(current);
+    }
+  };
+
+  const removeUntrackedFile = (relativePath: string): boolean => {
+    const absolutePath = join(params.repoRoot, relativePath);
+    if (!existsSync(absolutePath)) {
+      return false;
+    }
+    if (params.git.isPathTracked(params.repoRoot, relativePath)) {
+      return false;
+    }
+    const stat = lstatSync(absolutePath);
+    if (!stat.isFile() && !stat.isSymbolicLink()) {
+      return false;
+    }
+    unlinkSync(absolutePath);
+    removed.push(relativePath);
+    pruneEmptyAncestors(relativePath);
+    return true;
+  };
+
   for (const relativePath of PUMUKI_ARTIFACTS) {
     const absolutePath = join(params.repoRoot, relativePath);
     if (!existsSync(absolutePath)) {
@@ -38,8 +75,24 @@ export const purgeUntrackedPumukiArtifacts = (params: {
     ) {
       continue;
     }
-    unlinkSync(absolutePath);
-    removed.push(relativePath);
+    removeUntrackedFile(relativePath);
+  }
+
+  const managedArtifacts = Array.from(
+    new Set((params.managedOpenSpecArtifacts ?? []).map((value) => value.trim()))
+  );
+  for (const rawPath of managedArtifacts) {
+    const normalized = rawPath.replace(/\\/g, '/');
+    if (normalized.length === 0) {
+      continue;
+    }
+    if (normalized.startsWith('/') || normalized.startsWith('../') || normalized.includes('/../')) {
+      continue;
+    }
+    if (PUMUKI_ARTIFACTS.includes(normalized as (typeof PUMUKI_ARTIFACTS)[number])) {
+      continue;
+    }
+    removeUntrackedFile(normalized);
   }
 
   return removed;