pumuki 6.3.49 → 6.3.51

package/README.md

@@ -337,13 +337,13 @@ Important:
 
 Extended annotated walkthrough:
 
-- `docs/README_MENU_WALKTHROUGH.md`
+- `docs/operations/framework-menu-option-1-walkthrough.md`
 
 ## Enterprise Operations Baseline
 
 Pumuki production SaaS operation baseline is defined in:
 
-- `docs/OPERATIONS.md`
+- `docs/operations/OPERATIONS.md`
 
 Highlights:
 
@@ -363,29 +363,29 @@ Highlights:
 
 ## Documentation Index
 
-- Installation: `docs/INSTALLATION.md`
-- Usage: `docs/USAGE.md`
-- Backlog tooling quick nav (incluye snippet terminal): `docs/USAGE.md#backlog-tooling`
-- Backlog reasons shared module: `docs/USAGE.md#backlog-reasons`
-- Testing: `docs/TESTING.md`
-- API reference: `docs/API_REFERENCE.md`
-- Architecture: `docs/ARCHITECTURE.md`
-- Configuration: `docs/CONFIGURATION.md`
-- Code standards: `docs/CODE_STANDARDS.md`
-- Branch protection: `docs/BRANCH_PROTECTION_GUIDE.md`
-- MCP servers: `docs/MCP_SERVERS.md`
-- MCP evidence server: `docs/MCP_EVIDENCE_CONTEXT_SERVER.md`
-- MCP consumption: `docs/MCP_AGENT_CONTEXT_CONSUMPTION.md`
-- Evidence schema v2.1: `docs/evidence-v2.1.md`
-- Operations policy (SLA/SLO): `docs/OPERATIONS.md`
-- Release notes: `docs/RELEASE_NOTES.md`
+- Installation: `docs/product/INSTALLATION.md`
+- Usage: `docs/product/USAGE.md`
+- Backlog tooling quick nav (incluye snippet terminal): `docs/product/USAGE.md#backlog-tooling`
+- Backlog reasons shared module: `docs/product/USAGE.md#backlog-reasons`
+- Testing: `docs/product/TESTING.md`
+- API reference: `docs/product/API_REFERENCE.md`
+- Architecture: `docs/product/ARCHITECTURE.md`
+- Configuration: `docs/product/CONFIGURATION.md`
+- Code standards: `docs/governance/CODE_STANDARDS.md`
+- Branch protection: `docs/governance/BRANCH_PROTECTION_GUIDE.md`
+- MCP servers: `docs/mcp/MCP_SERVERS.md`
+- MCP evidence server: `docs/mcp/MCP_EVIDENCE_CONTEXT_SERVER.md`
+- MCP consumption: `docs/mcp/MCP_AGENT_CONTEXT_CONSUMPTION.md`
+- Evidence schema v2.1: `docs/mcp/ai-evidence-v2.1-contract.md`
+- Operations policy (SLA/SLO): `docs/operations/OPERATIONS.md`
+- Release notes: `docs/operations/RELEASE_NOTES.md`
 - Changelog: `CHANGELOG.md`
 
 ## Collaboration
 
 Contributions are welcome. For high-quality collaboration:
 
-1. Read `docs/CONTRIBUTING.md` and `docs/CODE_STANDARDS.md`.
+1. Read `docs/governance/CONTRIBUTING.md` and `docs/governance/CODE_STANDARDS.md`.
 2. Create a dedicated branch per change.
 3. Keep scope focused and include deterministic evidence when relevant.
 4. Before opening a PR, run at least:

package/core/facts/detectors/text/ios.test.ts

@@ -37,6 +37,19 @@ let flag = value!!
   assert.equal(hasSwiftForceUnwrap(source), false);
 });
 
+test('hasSwiftForceUnwrap excluye comparaciones seguras contra nil', () => {
+  const source = `
+if ProcessInfo.processInfo.environment["SIMULATOR_UDID"] != nil {
+  return
+}
+
+if waitersByKey[key] != nil {
+  consume()
+}
+`;
+  assert.equal(hasSwiftForceUnwrap(source), false);
+});
+
 test('hasSwiftAnyViewUsage detecta AnyView en codigo real', () => {
   const source = `
 func render() -> some View {

package/core/rules/presets/iosEnterpriseRuleSet.test.ts

@@ -1,6 +1,7 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 import { iosEnterpriseRuleSet } from './iosEnterpriseRuleSet';
+import { evaluateRules } from '../../gate/evaluateRules';
 
 test('iosEnterpriseRuleSet define reglas locked para plataforma ios', () => {
   assert.equal(iosEnterpriseRuleSet.length, 8);
@@ -23,6 +24,8 @@ test('iosEnterpriseRuleSet define reglas locked para plataforma ios', () => {
   assert.equal(byId.get('ios.no-gcd')?.severity, 'CRITICAL');
   assert.equal(byId.get('ios.tdd.domain-changes-require-tests')?.when.kind, 'All');
   assert.equal(byId.get('ios.no-completion-handlers-outside-bridges')?.when.kind, 'Any');
+  assert.equal(byId.get('ios.no-force-unwrap')?.when.kind, 'All');
+  assert.equal(byId.get('ios.no-force-unwrap')?.when.conditions[0]?.kind, 'Heuristic');
 
   for (const rule of iosEnterpriseRuleSet) {
     assert.equal(rule.platform, 'ios');
@@ -31,3 +34,46 @@ test('iosEnterpriseRuleSet define reglas locked para plataforma ios', () => {
     assert.ok(rule.scope?.include?.includes('**/*.swift'));
   }
 });
+
+test('ios.no-force-unwrap no bloquea comparaciones seguras != nil', () => {
+  const rule = iosEnterpriseRuleSet.find((candidate) => candidate.id === 'ios.no-force-unwrap');
+  assert.ok(rule);
+
+  const findings = evaluateRules([rule], [
+    {
+      kind: 'FileContent',
+      path: 'apps/ios/Sources/ListRouting/Application/UseCases/SyncShoppingListUseCase.swift',
+      content: 'if waitersByKey[key] != nil { consume() }',
+      source: 'unit-test',
+    },
+  ]);
+
+  assert.deepEqual(findings, []);
+});
+
+test('ios.no-force-unwrap bloquea cuando la heuristica detecta force unwrap real', () => {
+  const rule = iosEnterpriseRuleSet.find((candidate) => candidate.id === 'ios.no-force-unwrap');
+  assert.ok(rule);
+
+  const findings = evaluateRules([rule], [
+    {
+      kind: 'FileContent',
+      path: 'apps/ios/Sources/ListRouting/Application/UseCases/SyncShoppingListUseCase.swift',
+      content: 'let user = repository.currentUser!',
+      source: 'unit-test',
+    },
+    {
+      kind: 'Heuristic',
+      ruleId: 'heuristics.ios.force-unwrap.ast',
+      severity: 'WARN',
+      code: 'HEURISTICS_IOS_FORCE_UNWRAP_AST',
+      message: 'AST heuristic detected force unwrap usage.',
+      filePath: 'apps/ios/Sources/ListRouting/Application/UseCases/SyncShoppingListUseCase.swift',
+      source: 'heuristics:ast',
+    },
+  ]);
+
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0]?.ruleId, 'ios.no-force-unwrap');
+  assert.equal(findings[0]?.code, 'IOS_NO_FORCE_UNWRAP');
+});

package/core/rules/presets/iosEnterpriseRuleSet.ts

@@ -153,8 +153,10 @@ export const iosEnterpriseRuleSet: RuleSet = [
       kind: 'All',
       conditions: [
         {
-          kind: 'FileContent',
-          contains: ['!'],
+          kind: 'Heuristic',
+          where: {
+            ruleId: 'heuristics.ios.force-unwrap.ast',
+          },
         },
         {
           kind: 'Not',

package/docs/README.md

@@ -1,78 +1,57 @@
 # Documentation Index
 
-Canonical index for active Pumuki documentation.
+Mapa corto y humano de la documentación oficial de Pumuki.
 
-## Seguimiento Activo (único)
+## Estructura
 
-- Maestro: `docs/registro-maestro-de-seguimiento.md`
-- Plan activo: `docs/seguimiento-activo-pumuki-saas-supermercados.md`
-- Política: una sola tarea en construcción (`🚧`) en el plan activo.
+- `docs/product/`
+  - Manual funcional y técnico del producto.
+  - Archivos clave: `ARCHITECTURE.md`, `HOW_IT_WORKS.md`, `API_REFERENCE.md`, `INSTALLATION.md`, `USAGE.md`, `CONFIGURATION.md`, `DEPENDENCIES.md`, `TESTING.md`.
 
-## Product and Architecture
+- `docs/governance/`
+  - Reglas de contribución y gobierno del repo.
+  - Archivos clave: `CODE_STANDARDS.md`, `CONTRIBUTING.md`, `BRANCH_PROTECTION_GUIDE.md`.
 
-- `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.
+- `docs/mcp/`
+  - Contratos MCP, evidence y consumo por agentes.
+  - Archivos clave: `MCP_SERVERS.md`, `MCP_EVIDENCE_CONTEXT_SERVER.md`, `MCP_AGENT_CONTEXT_CONSUMPTION.md`, `ai-evidence-v2.1-contract.md`.
 
-## Setup and Usage
+- `docs/operations/`
+  - Operación diaria, walkthroughs y notas de release.
+  - Archivos clave: `OPERATIONS.md`, `framework-menu-option-1-walkthrough.md`, `RELEASE_NOTES.md`.
 
-- `docs/INSTALLATION.md`: installation and bootstrap guidance.
-- `docs/USAGE.md`: day-to-day usage.
-- `docs/OPERATIONS.md`: production operations baseline (SLA/SLO, incident severity, alerts).
-- `docs/CONFIGURATION.md`: runtime and repository configuration.
-- `docs/CODE_STANDARDS.md`: coding standards for framework contributors.
-- `docs/CONTRIBUTING.md`: contribution workflow.
-- `docs/DEPENDENCIES.md`: dependency policy and maintenance.
-- `docs/TESTING.md`: test strategy and validation commands.
-- `docs/BRANCH_PROTECTION_GUIDE.md`: branch protection baseline.
-- `docs/README_MENU_WALKTHROUGH.md`: visual walkthrough of menu Option 1 flow.
+- `docs/validation/`
+  - Runbooks y contratos estables de validación.
+  - Punto de entrada: `docs/validation/README.md`.
 
-## Evidence and MCP
+- `docs/rule-packs/`
+  - Packs de reglas oficiales por ámbito.
 
-- `docs/evidence-v2.1.md`: deterministic evidence schema.
-- `docs/MCP_EVIDENCE_CONTEXT_SERVER.md`: evidence MCP server contract.
-- `docs/MCP_SERVERS.md`: MCP integration overview.
-- `docs/MCP_AGENT_CONTEXT_CONSUMPTION.md`: deterministic MCP consumption model.
+- `docs/codex-skills/`
+  - Skills vendorizadas que el repo usa como contrato local.
 
-## Rule Packs and Skills
+- `docs/tracking/`
+  - Seguimiento permitido y solo el imprescindible.
+  - Maestro: `docs/tracking/maestro-de-seguimiento.md`
+  - Plan activo: `docs/tracking/plan-activo-pumuki.md`
+  - Históricos técnicos permitidos:
+    - `docs/tracking/historico-validacion-ruralgo-03-03-2026.md`
+    - `docs/tracking/historico-c022-contrato-aceptacion.md`
+  - Regla hard: solo puede existir una tarea `🚧` en el plan activo.
 
-- `docs/rule-packs/README.md`: rule-pack index.
-- `docs/rule-packs/engineering-baseline.md`
-- `docs/rule-packs/ios.md`
-- `docs/rule-packs/backend.md`
-- `docs/rule-packs/frontend.md`
-- `docs/rule-packs/android.md`
-- `docs/rule-packs/heuristics.md`
+## Fuera de `docs/`
 
-## Validation Runbooks
+- Gobierno raíz:
+  - `README.md`
+  - `ARCHITECTURE.md`
+  - `CHANGELOG.md`
+  - `AGENTS.md`
+  - `PUMUKI.md`
 
-- `docs/validation/README.md`: enterprise minimal validation index.
-- `docs/validation/adapter-hook-runtime-validation.md`
-- `docs/validation/ast-intelligence-roadmap.md`
-- `docs/validation/c022-phase-acceptance-contract.md`
-- `docs/validation/enterprise-consumer-isolation-policy.md`
-- `docs/validation/mock-consumer-integration-runbook.md`
-- `docs/validation/detection-audit-baseline.md`
-- `docs/validation/skills-rollout-consumer-repositories.md`
+## Lo que no se conserva
 
-## Vendored Codex Skills
-
-- `docs/codex-skills/swift-concurrency.md`
-- `docs/codex-skills/swiftui-expert-skill.md`
-- `docs/codex-skills/windsurf-rules-android.md`
-- `docs/codex-skills/windsurf-rules-backend.md`
-- `docs/codex-skills/windsurf-rules-frontend.md`
-- `docs/codex-skills/windsurf-rules-ios.md`
-
-## Releases
-
-- `docs/RELEASE_NOTES.md`
-- `CHANGELOG.md`
-
-## Root-Level Governance Docs
-
-- `README.md`
-- `ARCHITECTURE.md`
-- `CHANGELOG.md`
-- `AGENTS.md`
-- `PUMUKI.md`
+- No se guardan en `docs/` reportes ad-hoc de ejecución.
+- Los artefactos efímeros se limpian al cerrar ciclo:
+  - `.audit-reports/**`
+  - `.coverage/**`
+  - `.ai_evidence.json`

package/docs/validation/README.md

@@ -1,42 +1,36 @@
-# Validation Docs (Enterprise Minimal Set)
+# Validation Docs
 
-Este directorio contiene solo documentación oficial y estable de validación para Pumuki.
+Este directorio contiene solo documentación estable de validación y runbooks oficiales.
 
-## Documentación oficial vigente
+## Documentación vigente
 
-- `adapter-hook-runtime-validation.md`
+- `adapter-hook-runtime-runbook.md`
 - `ast-intelligence-roadmap.md`
-- `c022-phase-acceptance-contract.md`
-- `detection-audit-baseline.md`
+- `full-repo-detection-audit-baseline.md`
 - `enterprise-consumer-isolation-policy.md`
 - `mock-consumer-integration-runbook.md`
-- `skills-rollout-consumer-repositories.md`
+- `consumer-repositories-skills-rollout-validation.md`
 
-## Estado operativo actual
+## Estado de seguimiento
 
-- Master de seguimiento: `docs/registro-maestro-de-seguimiento.md`.
-- Plan activo: `docs/seguimiento-activo-pumuki-saas-supermercados.md`.
-- Suite contractual enterprise (MVP): `npm run -s validation:contract-suite:enterprise`.
-  - Perfiles activos del reporte JSON:
-    - `minimal`
-    - `block`
-    - `minimal-repeat`
-    - `telemetry-rotation`
+- Maestro: `docs/tracking/maestro-de-seguimiento.md`
+- Plan activo: `docs/tracking/plan-activo-pumuki.md`
+- Histórico permitido: `docs/tracking/historico-validacion-ruralgo-03-03-2026.md`
+
+## Histórico técnico conservado
+
+- `docs/tracking/historico-c022-contrato-aceptacion.md`
 
 ## Política de higiene
 
-- Los reportes de ejecución/cierre de ciclos se generan en `.audit_tmp` o `.audit-reports`.
-- No se versionan reportes históricos ad-hoc en `docs/validation/`.
-- Si hace falta conservar evidencia operativa de ejecución, se referencia desde el ciclo temporal activo (si existe) y/o desde reportes en `.audit_tmp` / `.audit-reports`.
-- El cierre oficial de `C022` (`D.T2` + `D.T4`) está consolidado en `c022-phase-acceptance-contract.md`.
-- El cierre de `C023` (incluyendo No-MVP SaaS ingestion diagnostics) está consolidado en documentación estable:
-  - `docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md`
-  - `docs/USAGE.md`
-  - `docs/CONFIGURATION.md`
-  - `docs/TESTING.md`
-  - `docs/API_REFERENCE.md`
-  - `docs/evidence-v2.1.md`
-- El cierre de `C025` (auditoría exhaustiva de funcionalidades + reglas) quedó consolidado en:
-  - `docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md` (estado, evidencia y cierre del bloque P5).
-- El cierre de `P6` (verificación exhaustiva real/mock) quedó consolidado en:
-  - `docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md` (checklist unificada, veredicto y transición).
+- `docs/validation/` no guarda reportes temporales.
+- Los artefactos efímeros se generan fuera de `docs/` y deben limpiarse antes de cerrar un ciclo:
+  - `.audit-reports/**`
+  - `.coverage/**`
+  - `.ai_evidence.json`
+- La evidencia histórica que sí aporta contexto se consolida en documentación estable o en el histórico permitido.
+
+## Comprobaciones útiles
+
+- Suite contractual enterprise: `npm run -s validation:contract-suite:enterprise`
+- Verificación de plan activo único: `npm run -s validation:tracking-single-active`

package/integrations/git/gitAtomicity.ts

@@ -172,6 +172,26 @@ const resolveScopeKey = (filePath: string): string => {
   return segments[0] ?? '';
 };
 
+const collectScopePaths = (
+  changedPaths: ReadonlyArray<string>
+): ReadonlyMap<string, ReadonlyArray<string>> => {
+  const buckets = new Map<string, Array<string>>();
+  for (const path of changedPaths) {
+    const scope = resolveScopeKey(path);
+    if (scope.length === 0) {
+      continue;
+    }
+    const current = buckets.get(scope) ?? [];
+    current.push(path.replace(/\\/g, '/'));
+    buckets.set(scope, current);
+  }
+  const normalized = new Map<string, ReadonlyArray<string>>();
+  for (const [scope, paths] of buckets.entries()) {
+    normalized.set(scope, [...new Set(paths)].sort());
+  }
+  return normalized;
+};
+
 const collectChangedPaths = (params: {
   git: IGitService;
   repoRoot: string;
@@ -259,25 +279,30 @@ export const evaluateGitAtomicity = (params: {
     });
   }
 
-  const scopeKeys = new Set(
-    changedPaths
-      .map((filePath) => resolveScopeKey(filePath))
-      .filter((scopeKey) => scopeKey.length > 0)
-  );
+  const scopePaths = collectScopePaths(changedPaths);
+  const scopeKeys = new Set(scopePaths.keys());
   if (scopeKeys.size > config.maxScopes) {
     const sortedScopes = [...scopeKeys].sort();
     const suggestedScopeAdds = sortedScopes
       .slice(0, Math.max(1, Math.min(config.maxScopes + 1, 3)))
       .map((scope) => `git add ${scope}/`)
       .join(' && ');
+    const scopeBreakdown = sortedScopes
+      .map((scope) => {
+        const paths = scopePaths.get(scope) ?? [];
+        const sample = paths.slice(0, 3);
+        return `${scope}{count=${paths.length}; sample=[${sample.join(', ')}]}`;
+      })
+      .join(' | ');
     violations.push({
       code: 'GIT_ATOMICITY_TOO_MANY_SCOPES',
       message:
-        `Git atomicity guard blocked at ${params.stage}: changed_scopes=${scopeKeys.size} exceeds max_scopes=${config.maxScopes}.`,
+        `Git atomicity guard blocked at ${params.stage}: changed_scopes=${scopeKeys.size} exceeds max_scopes=${config.maxScopes}. ` +
+        `scope_files=${scopeBreakdown}.`,
       remediation:
         `Agrupa cambios por ámbito funcional (máximo ${config.maxScopes} scopes por commit). ` +
         `scopes_detectados=[${sortedScopes.join(', ')}]. ` +
-        `Sugerencia: git restore --staged . && ${suggestedScopeAdds} && git commit -m "<tipo>: <scope>".`,
+        `Sugerencia split: git restore --staged . && ${suggestedScopeAdds} && git commit -m "<tipo>: <scope>".`,
     });
   }
 

package/integrations/git/runPlatformGate.ts

@@ -771,6 +771,7 @@ export async function runPlatformGate(params: {
   scope: GateScope;
   silent?: boolean;
   sddShortCircuit?: boolean;
+  sddDecisionOverride?: Pick<SddDecision, 'allowed' | 'code' | 'message'>;
   services?: Partial<GateServices>;
   dependencies?: Partial<GateDependencies>;
 }): Promise<number> {
@@ -793,10 +794,11 @@ export async function runPlatformGate(params: {
     params.policy.stage === 'PRE_PUSH' ||
     params.policy.stage === 'CI'
   ) {
-    sddDecision = dependencies.evaluateSddForStage(
-      params.policy.stage,
-      repoRoot
-    );
+    sddDecision = params.sddDecisionOverride
+      ?? dependencies.evaluateSddForStage(
+        params.policy.stage,
+        repoRoot
+      );
     if (!sddDecision.allowed) {
       if (params.silent !== true) {
         process.stdout.write(`[pumuki][sdd] ${sddDecision.code}: ${sddDecision.message}\n`);

package/integrations/git/runPlatformGateOutput.ts

@@ -2,7 +2,7 @@ import type { Finding } from '../../core/gate/Finding';
 
 const BLOCK_NEXT_ACTION_BY_CODE: Readonly<Record<string, string>> = {
   SDD_SESSION_MISSING:
-    'npx --yes --package pumuki@latest pumuki sdd session --open --change=auto',
+    'npx --yes --package pumuki@latest pumuki sdd session --open --change=<id>',
   SDD_SESSION_INVALID:
     'npx --yes --package pumuki@latest pumuki sdd session --refresh --ttl-minutes=90',
   PRE_PUSH_UPSTREAM_MISSING:
@@ -16,7 +16,7 @@ const BLOCK_NEXT_ACTION_BY_CODE: Readonly<Record<string, string>> = {
   GIT_ATOMICITY_TOO_MANY_FILES:
     'git restore --staged . && separa cambios en commits más pequeños',
   GIT_ATOMICITY_TOO_MANY_SCOPES:
-    'git restore --staged . && git add <scope>/ && git commit -m "<tipo>: <scope>"',
+    'Revisa scope_files del bloqueo y aplica: git restore --staged . && git add <scope>/ && git commit -m "<tipo>: <scope>"',
   ACTIVE_RULE_IDS_EMPTY_FOR_CODE_CHANGES_HIGH:
     'Reconcilia policy/skills y reintenta PRE_COMMIT: npx --yes --package pumuki@latest pumuki policy reconcile --strict --json && npx --yes --package pumuki@latest pumuki-pre-commit',
   SKILLS_SKILLS_FRONTEND_NO_SOLID_VIOLATIONS: