pumuki 6.3.28 → 6.3.30

package/README.md

@@ -124,6 +124,63 @@ Rule modes:
 9. Provider-agnostic adapter scaffolding (`codex`, `claude`, `cursor`, `windsurf`, `opencode`).
 10. Optional MCP servers for evidence and enterprise context.
 
+## Policy-as-Code (Enterprise)
+
+Pumuki supports a signed and versioned stage-policy contract at:
+
+- `.pumuki/policy-as-code.json`
+
+Minimal contract:
+
+```json
+{
+  "version": "1.0",
+  "source": "default",
+  "expires_at": "2026-12-31T23:59:59.000Z",
+  "signatures": {
+    "PRE_COMMIT": "<sha256-hex>",
+    "PRE_PUSH": "<sha256-hex>",
+    "CI": "<sha256-hex>"
+  }
+}
+```
+
+Runtime behavior:
+
+- If the contract is missing, Pumuki computes deterministic local metadata and still emits `policy_version`, `policy_signature`, and `policy_source`.
+- If present, the contract is validated against active runtime policy for source/stage/signature.
+- Validation states are emitted as `valid`, `invalid`, `expired`, or `unknown-source`.
+- `PUMUKI_POLICY_STRICT=1` turns non-valid states into blocking findings (`governance.policy-as-code.invalid`).
+
+Operational fallback:
+
+- Keep strict mode disabled while bootstrapping a repo without a canonical contract.
+- Enable strict mode once contract generation/signatures are part of your baseline pipeline.
+
+## Telemetry Export (Enterprise)
+
+Pumuki can export structured gate telemetry with a stable event schema (`telemetry_event_v1`) for SIEM/observability pipelines.
+
+Default behavior remains unchanged: telemetry export is disabled unless explicitly configured.
+
+Enable one or both outputs:
+
+- `PUMUKI_TELEMETRY_JSONL_PATH`: local JSONL target (absolute or repo-relative path)
+- `PUMUKI_TELEMETRY_OTEL_ENDPOINT`: OTLP HTTP logs endpoint (`/v1/logs`)
+- `PUMUKI_TELEMETRY_OTEL_SERVICE_NAME`: optional OTel service name (default: `pumuki`)
+- `PUMUKI_TELEMETRY_OTEL_TIMEOUT_MS`: optional OTel timeout in ms (default: `1500`)
+
+Example:
+
+```bash
+export PUMUKI_TELEMETRY_JSONL_PATH=".pumuki/artifacts/gate-telemetry.jsonl"
+export PUMUKI_TELEMETRY_OTEL_ENDPOINT="https://otel.example/v1/logs"
+export PUMUKI_TELEMETRY_OTEL_SERVICE_NAME="pumuki-enterprise"
+npx --yes pumuki-pre-commit
+```
+
+Each event captures deterministic stage/outcome/policy/repo context per gate execution.
+
 ## Framework Maintainer Flow (This Repo)
 
 Use this only when working in the Pumuki framework repository itself:

package/core/gate/conditionMatches.test.ts

@@ -108,3 +108,37 @@ test('conditionMatches soporta condiciones compuestas All, Any y Not', () => {
 
   assert.equal(conditionMatches(composedCondition, facts), true);
 });
+
+test('conditionMatches respeta include glob swift y no matchea archivos no swift', () => {
+  const scopedCondition: Condition = {
+    kind: 'All',
+    conditions: [
+      {
+        kind: 'FileContent',
+        contains: ['!'],
+      },
+      {
+        kind: 'Not',
+        condition: {
+          kind: 'FileContent',
+          contains: ['IBOutlet'],
+        },
+      },
+    ],
+  };
+  const scopedFacts = [
+    {
+      kind: 'FileContent' as const,
+      path: 'apps/admin-dashboard/middleware.ts',
+      content: 'if (token != null) { return NextResponse.next(); }',
+      source: 'repo',
+    },
+  ];
+
+  assert.equal(
+    conditionMatches(scopedCondition, scopedFacts, {
+      include: ['**/*.swift'],
+    }),
+    false
+  );
+});

package/core/gate/evaluateRules.test.ts

@@ -199,3 +199,49 @@ test('evaluateRules genera un finding por cada heuristica coincidente', () => {
   );
   assert.equal(findings.every((finding) => finding.matchedBy === 'Heuristic'), true);
 });
+
+test('evaluateRules no genera finding de iOS cuando el scope es swift y el archivo es TypeScript', () => {
+  const rules: RuleSet = [
+    {
+      id: 'ios.no-force-unwrap',
+      description: 'Disallows force unwraps in iOS code.',
+      severity: 'CRITICAL',
+      scope: {
+        include: ['**/*.swift'],
+      },
+      when: {
+        kind: 'All',
+        conditions: [
+          {
+            kind: 'FileContent',
+            contains: ['!'],
+          },
+          {
+            kind: 'Not',
+            condition: {
+              kind: 'FileContent',
+              contains: ['IBOutlet'],
+            },
+          },
+        ],
+      },
+      then: {
+        kind: 'Finding',
+        message: 'Force unwraps are not allowed in iOS code.',
+        code: 'IOS_NO_FORCE_UNWRAP',
+      },
+    },
+  ];
+  const facts = [
+    {
+      kind: 'FileContent',
+      path: 'apps/admin-dashboard/middleware.ts',
+      content: 'if (token != null) { return NextResponse.next(); }',
+      source: 'repo',
+    },
+  ] as const;
+
+  const findings = evaluateRules(rules, facts);
+
+  assert.deepEqual(findings, []);
+});

package/core/gate/scopeMatcher.ts

@@ -1,68 +1,70 @@
-import type { RuleDefinition } from '../rules/RuleDefinition';
-
-type RuleScope = RuleDefinition['scope'];
-
-const SPECIAL_REGEX_CHARS = /[|\\{}()[\]^$+?.]/;
-const regexCache = new Map<string, RegExp>();
+type ScopePattern = {
+  include?: ReadonlyArray<string>;
+  exclude?: ReadonlyArray<string>;
+};
 
-const normalize = (value: string): string => {
+const normalizePath = (value: string): string => {
   return value.replace(/\\/g, '/');
 };
 
-const escapeRegexChar = (value: string): string => {
-  return SPECIAL_REGEX_CHARS.test(value) ? `\\${value}` : value;
+const escapeRegex = (value: string): string => {
+  return value.replace(/[|\\{}()[\]^$+?.]/g, '\\$&');
 };
 
 const toGlobRegex = (pattern: string): RegExp => {
-  const cached = regexCache.get(pattern);
-  if (cached) {
-    return cached;
-  }
-
   let regex = '^';
-  for (let index = 0; index < pattern.length;) {
-    if (pattern.startsWith('**/', index)) {
-      regex += '(?:.*/)?';
-      index += 3;
+  for (let index = 0; index < pattern.length; index += 1) {
+    const current = pattern[index];
+    if (current === '*') {
+      const next = pattern[index + 1];
+      if (next === '*') {
+        const nextNext = pattern[index + 2];
+        if (nextNext === '/') {
+          regex += '(?:.*/)?';
+          index += 2;
+        } else {
+          regex += '.*';
+          index += 1;
+        }
+      } else {
+        regex += '[^/]*';
+      }
       continue;
     }
-    if (pattern.startsWith('**', index)) {
-      regex += '.*';
-      index += 2;
+    if (current === '?') {
+      regex += '[^/]';
       continue;
     }
-
-    const char = pattern[index];
-    if (char === '*') {
-      regex += '[^/]*';
-      index += 1;
-      continue;
-    }
-
-    regex += escapeRegexChar(char);
-    index += 1;
+    regex += escapeRegex(current);
   }
   regex += '$';
+  return new RegExp(regex);
+};
 
-  const compiled = new RegExp(regex);
-  regexCache.set(pattern, compiled);
-  return compiled;
+const extractPrefix = (pattern: string): string => {
+  const wildcardIndex = pattern.search(/[*?]/);
+  return wildcardIndex === -1 ? pattern : pattern.slice(0, wildcardIndex);
 };
 
-const matchesPattern = (path: string, pattern: string): boolean => {
-  const normalizedPath = normalize(path);
-  const normalizedPattern = normalize(pattern);
+const isTrailingWildcardPattern = (pattern: string): boolean => {
+  const wildcardIndex = pattern.search(/[*?]/);
+  if (wildcardIndex === -1) {
+    return false;
+  }
+  const suffix = pattern.slice(wildcardIndex);
+  return /^[*?]+$/.test(suffix);
+};
 
-  const wildcardIndex = normalizedPattern.indexOf('*');
+export const matchesPattern = (path: string, pattern: string): boolean => {
+  const normalizedPath = normalizePath(path);
+  const normalizedPattern = normalizePath(pattern);
+  const wildcardIndex = normalizedPattern.search(/[*?]/);
   if (wildcardIndex === -1) {
     return normalizedPath.startsWith(normalizedPattern);
   }
-
-  const prefix = normalizedPattern.slice(0, wildcardIndex);
-  if (prefix.length > 0 && normalizedPath.startsWith(prefix)) {
-    return true;
+  if (isTrailingWildcardPattern(normalizedPattern)) {
+    return normalizedPath.startsWith(extractPrefix(normalizedPattern));
   }
-
   return toGlobRegex(normalizedPattern).test(normalizedPath);
 };
 
@@ -70,10 +72,9 @@ const matchesAnyPattern = (path: string, patterns: ReadonlyArray<string>): boole
   return patterns.some((pattern) => matchesPattern(path, pattern));
 };
 
-export const matchesScope = (path: string, scope?: RuleScope): boolean => {
+export const matchesScope = (path: string, scope?: ScopePattern): boolean => {
   const include = scope?.include;
   const exclude = scope?.exclude;
-
   if (exclude && exclude.length > 0 && matchesAnyPattern(path, exclude)) {
     return false;
   }

package/docs/API_REFERENCE.md

@@ -110,6 +110,11 @@ Contract:
   - evidence `ai_gate.status = BLOCKED`
   - protected branch use (`main/master/develop/dev` by default)
 - Returns deterministic payload: `status`, `allowed`, `violations[]`, `evidence`, `repo_state`.
+- Evidence source contract (auditability):
+  - `evidence.source.source`
+  - `evidence.source.path`
+  - `evidence.source.digest`
+  - `evidence.source.generated_at`
 
 ## PRE_WRITE JSON envelope
 

package/docs/CONFIGURATION.md

@@ -97,6 +97,26 @@ Defined in `integrations/gate/stagePolicies.ts`:
 - `PRE_PUSH`: block `ERROR`, warn from `WARN`
 - `CI`: block `ERROR`, warn from `WARN`
 
+## Gate telemetry export (optional)
+
+Structured telemetry output is disabled by default and can be enabled with environment variables:
+
+- `PUMUKI_TELEMETRY_JSONL_PATH`:
+  - JSONL file path for `telemetry_event_v1` records.
+  - Accepts absolute path or repo-relative path.
+- `PUMUKI_TELEMETRY_OTEL_ENDPOINT`:
+  - OTLP HTTP logs endpoint (`/v1/logs`).
+- `PUMUKI_TELEMETRY_OTEL_SERVICE_NAME`:
+  - Optional service name for OTel payload (`default: pumuki`).
+- `PUMUKI_TELEMETRY_OTEL_TIMEOUT_MS`:
+  - Optional timeout for OTel dispatch in milliseconds (`default: 1500`).
+
+Notes:
+
+- You can enable JSONL only, OTel only, or both.
+- If unset, no telemetry export is attempted.
+- Gate execution remains deterministic even when OTel endpoint is unavailable (best-effort dispatch).
+
 ## Heuristic pilot flag
 
 Enable semantic heuristic rules:

package/docs/README.md

@@ -2,18 +2,14 @@
 
 Canonical index for active Pumuki documentation.
 
-## Ciclo Activo (Seguimiento Temporal)
+## Seguimiento Activo (único)
 
-- Seguimiento diario (único y simplificado): `docs/EXECUTION_BOARD.md`.
-- Seguimiento simple de validación real en repo no-mock: `docs/validation/p9-ruralgo-fork-validation-tracking.md`.
-- Cierre funcional previo: `P6` (verificación exhaustiva interna real/mock, `371/371`) consolidado en `docs/REFRACTOR_PROGRESS.md`.
-- Alcance activo actual: `P9` (validación manual guiada en repo real externo `ruralgo-fork`) en `docs/validation/p9-ruralgo-fork-validation-tracking.md`.
-- Ultimo cierre oficial previo: ciclo `022` consolidado en `docs/validation/c022-phase-acceptance-contract.md`.
-- Politica: una sola tarea en construccion (`🚧`) en todo momento.
+- Maestro: `docs/registro-maestro-de-seguimiento.md`
+- Plan activo: `docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md`
+- Política: una sola tarea en construcción (`🚧`) en el plan activo.
 
 ## Product and Architecture
 
-- `docs/EXECUTION_BOARD.md`: tablero activo de seguimiento (simple).
 - `docs/ARCHITECTURE.md`: normative architecture contract.
 - `docs/HOW_IT_WORKS.md`: facts-to-gate execution flow.
 - `docs/API_REFERENCE.md`: public APIs, binaries, and command surfaces.
@@ -55,9 +51,6 @@ Canonical index for active Pumuki documentation.
 - `docs/validation/c022-phase-acceptance-contract.md`
 - `docs/validation/enterprise-consumer-isolation-policy.md`
 - `docs/validation/mock-consumer-integration-runbook.md`
-- `docs/validation/p9-ruralgo-bug-registry.md`
-- `docs/validation/p9-ruralgo-fork-validation-tracking.md`
-- `docs/validation/real-repo-manual-e2e-ruralgo-fork.md`
 - `docs/validation/detection-audit-baseline.md`
 - `docs/validation/skills-rollout-consumer-repositories.md`
 

package/docs/registro-maestro-de-seguimiento.md

@@ -0,0 +1,18 @@
+# Registro Maestro de Seguimiento
+
+## Objetivo
+- Mantener trazabilidad ejecutiva en un solo punto.
+- Referenciar un único plan activo con fases, tasks y leyenda.
+
+## Estado actual
+- Plan activo: `docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md`
+- Estado del plan: EN CURSO
+- Task activa (`🚧`): `P12.F1.T42` (sincronizar canónico RuralGO tras cierre de `#543` y actualizar refs reales en feedback/master plan).
+
+## Historial resumido
+- No se mantienen MDs históricos de seguimiento en este repositorio.
+- La trazabilidad histórica relevante debe consolidarse dentro del plan activo o en documentación oficial no temporal.
+
+## Regla de operación
+- Debe existir exactamente una task `🚧` en el plan activo.
+- No se crean nuevos MDs de seguimiento salvo instrucción explícita.