kcreate-scaffolding-gcp-script 0.0.0-stage → 0.2.1

package/skill/references/lessons-learned.md

@@ -0,0 +1,706 @@
+# Lecciones reales incorporadas en este skill
+
+Seis fuentes:
+
+- **A — descubiertas desplegando `xoloshop-qa` a mano** (sesión previa,
+  documentadas también en `docs/CreateScriptsNewGCPProjectInstructions.md`
+  y `docs/DeployNewGCPProjectInstructions.md` de `club-tijuana/infra-cloud`).
+- **B — descubiertas probando este skill de punta a punta** contra una
+  copia descartable de `infra-cloud` real, generando `xoloshop-prod` desde
+  `boletera-qa`, antes de considerarlo terminado. Varias de estas B
+  **nunca se habían notado** ni siquiera en el proceso manual (ej. los
+  archivos de nivel raíz, el dominio DNS) — la automatización las hizo
+  visibles por primera vez.
+- **C — encontradas por `Review_V1.md`**, una revisión independiente que
+  también ejecutó el skill de punta a punta (contra `boletera-qa` y, de
+  forma crucial, contra `xoloshop-qa` — el entorno que las pruebas B no
+  habían usado como fuente). Ver `Review_V1.md` en la raíz de este repo
+  para el texto completo de la revisión y la respuesta punto por punto.
+- **D — encontradas por `Review_V2.md`**, una re-revisión después de
+  aplicar C, con reintentos reales sobre entornos a medio construir
+  (encontró una regresión crítica del propio fix de reanudación de C1).
+  Ver `Review_V2.md`.
+- **E — encontradas por `Review_V3.md`**, una tercera revisión que
+  reprodujo la cadena crítica de N-1 paso a paso y encontró que el
+  propio fix de `artifact_registry` (una función nueva de esa misma
+  ronda) se había quedado con la misma contaminación que D1/D2 ya habían
+  corregido en las demás. Ver `Review_V3.md`.
+- **F — encontradas ejecutando el skill de punta a punta contra el repo
+  real `club-tijuana/infra-cloud`** (no una copia descartable), generando
+  `coreservices-qa` desde `xoloshop-qa`, con Issue de tracking real
+  creado y cerrado.
+
+Cada lección dice **qué pasaba**, **por qué**, y **en qué script/función
+de este skill queda resuelta**.
+
+---
+
+## A1 — Fórmula de CIDR sin validar produce octetos inválidos
+
+**Qué pasaba:** extender a mano `10.N.0.0/22` sin revisar los 4 bloques
+derivados produjo `10.335.0.0/17` (octeto `335`, inválido).
+**Resuelto en:** `lib/common.sh:ksc_cidr_pick_free` — usa
+`ipaddress.ip_network()` de Python (nunca aritmética a mano) y prueba
+`N=1..249` hasta encontrar uno sin colisión; si no hay ninguno libre,
+falla con un mensaje explícito en vez de devolver algo inválido.
+
+## A2 — Coma faltante editando `project_services` a mano
+
+**Qué pasaba:** un elemento sin coma al final de la lista rompe
+`terragrunt hcl validate` con un error de sintaxis poco claro.
+**Resuelto en:** `build_component_project_services` — el archivo se copia
+**completo, sin tocarlo**. Este skill nunca edita esa lista campo por
+campo, así que esta clase de bug queda eliminada por diseño, no detectada
+después.
+
+## A3 — Valores genéricos/org-wide en `artifact_registry`
+
+**Qué pasaba:** `repository_id`/`description` quedaron como
+`"club-tijuana-docker-repo"` / `"Official Club Tijuana docker
+repository."` en un despliegue real, sin adaptar.
+**Resuelto en:** `build_component_artifact_registry` — sustituye el
+nombre de la app si lo encuentra en el valor. **Lección B encontrada
+probando esto:** `boletera-qa`, la fuente real usada para probar este
+skill, **todavía tiene ese mismo valor genérico sin corregir**. Como no
+hay substring de la app para reemplazar, el script detecta el caso y
+emite un `[WARN]` explícito en vez de copiar el problema en silencio —
+nunca asume que "no encontré nada que sustituir" significa "está bien".
+
+## A4 — IP de `cloudadmin` transcrita mal
+
+**Qué pasaba:** `177.226.233.64` en vez de `177.226.232.136` al copiar a
+mano.
+**Resuelto en:** `01_init_config.sh` extrae las entradas fijas (no
+`dev-*`) de `authorized_networks` directo del `terragrunt.hcl` real de
+`SOURCE_ENV` con `grep`/`sed`, nunca de memoria ni de una tabla.
+
+## A5 — IP de `dev-<usuario>` vieja o reusada
+
+**Qué pasaba:** el ISP cambia; una IP de otra sesión queda obsoleta y
+deja al usuario sin acceso.
+**Resuelto en:** `lib/common.sh:ksc_fresh_public_ip`, llamada dentro de
+`build_component_sql_postgres` — siempre `curl` en el momento de
+construir, nunca cacheada entre corridas.
+
+## A6 — `gke_version`/`database_version` copiados a ciegas
+
+**Qué pasaba:** no verificar si ya existe una versión estable más
+reciente antes de copiar la de `SOURCE_ENV`.
+**Resuelto en:** el config los autodetecta con el sufijo
+`_NEEDS_VERIFICATION` en el nombre del campo — el skill los usa tal cual
+estén en el config al construir, pero el nombre del campo mismo recuerda
+que deben verificarse contra la documentación oficial antes de confiar en
+ellos ciegamente (esto sí requiere criterio humano/del agente — no es
+mecanizable sin consultar una fuente externa).
+
+## A7 — Falta `orgpolicy.googleapis.com` + sus 3 overrides
+
+**Qué pasaba:** sin esta API y sus 3 overrides en `org_policies`, el
+despliegue falla varios pasos después, con minutos de espera por
+propagación cada vez que se corrige una política a la vez.
+**Resuelto en:** `build_component_project_services` y
+`build_component_org_policies` copian ambos archivos **completos** de
+`SOURCE_ENV` — si `SOURCE_ENV` ya tiene la API y los 3 overrides (todo
+entorno desplegado después de 2026-02-17 los tiene), `NEW_ENV` los hereda
+automáticamente, sin que este skill necesite saber los nombres exactos de
+las constraints.
+
+## A8 — `roles/orgpolicy.policyAdmin` en `project_iam`
+
+**Qué pasaba:** GCP rechaza ese rol a nivel proyecto
+(`Role ... is not supported for this resource`); solo existe a nivel
+Organización/Carpeta.
+**Resuelto en:** `build_component_project_iam` hace `grep` de ese string
+después de copiar y **falla la construcción** (no solo advierte) si lo
+encuentra — a diferencia de los demás `[WARN]`, este es un error real
+conocido, no una zona gris.
+
+## A9 — Cambiar el casing de `project_name` sin que lo pidieran
+
+**Qué pasaba:** confusión real entre `"XoloShop-QA"` y `"Xoloshop-QA"` en
+el mismo PR.
+**Resuelto en:** `lib/common.sh:ksc_infer_project_name` aplica una regla
+fija y determinística (primera letra de la app en mayúscula, entorno
+`QA`/`Prod`) y la deja en el config para que el humano la confirme en la
+Etapa 1 — nunca se improvisa un casing distinto después de eso.
+
+## A10 — Bindings de `project_iam` específicos de otro equipo/app
+
+**Qué pasaba:** copiar usuarios de un dominio externo o un rol
+personalizado que no existe en el proyecto nuevo.
+**Resuelto en:** `build_component_project_iam` copia el archivo completo
+(no hay forma mecánica confiable de distinguir "binding específico de la
+app" de "binding que debería estar en todo entorno" sin entender el
+negocio) pero **siempre** emite un `[WARN]` pidiendo revisión humana
+explícita antes de confiar en el archivo. Este es, a propósito, el punto
+donde este skill deja más criterio al agente/humano — es el mismo punto
+donde la guía manual original tampoco pudo mecanizarlo del todo.
+
+---
+
+## B1 — `live/<NEW_ENV>/` nunca se crea antes de copiar `project.hcl`
+
+**Qué pasaba (encontrado probando):** la primera versión de
+`10_build_components.sh` fallaba en el primer paso (`cp: cannot create
+regular file ... No such file or directory`) porque nunca se hacía
+`mkdir -p` del directorio del entorno nuevo antes de copiar `project.hcl`
+dentro de él.
+**Resuelto en:** `mkdir -p "$NEW_DIR"` explícito justo después de
+descubrir los componentes, antes de cualquier copia.
+
+## B2 — Orden de construcción por alfabeto, no por dependencia real
+
+**Qué pasaba (encontrado probando):** los componentes se descubren y
+procesan alfabéticamente. `sql_private_access` necesita el rango CIDR que
+calcula `vpc`, pero `"sql_private_access" < "vpc"` alfabéticamente, así
+que se procesaba primero y fallaba por falta del archivo de CIDR.
+**Resuelto en:** después de descubrir los componentes, si `vpc` está
+presente se reordena al frente de la lista, antes que cualquier otro.
+
+## B3 — Variable de shell reusada como variable de loop
+
+**Qué pasaba (encontrado probando):** dentro de `build_component_vpc`, la
+variable local `f` (la ruta del `vpc/terragrunt.hcl` nuevo) se declaraba
+una vez, pero más abajo un `for f in .../sql_private_access/terragrunt.hcl`
+reusaba el mismo nombre como variable de loop — al terminar el loop, `f`
+quedaba apuntando al **último archivo de otro entorno** recorrido, no al
+`vpc/terragrunt.hcl` que se quería editar. Las siguientes llamadas
+editaban el archivo equivocado (de otro entorno ya desplegado).
+**Resuelto en:** la variable de loop se renombró a `sp_file`, y se agregó
+`local f` explícito en `ksc_copy_component_files` como defensa adicional.
+**Por qué importa documentarlo:** si agregas lógica nueva a cualquier
+`build_component_*`, nunca reuses el nombre de una variable `local` ya
+declarada en la misma función como variable de loop — bash no lo detecta
+ni avisa, simplemente sobreescribe en silencio.
+
+## B4 — `sql_private_access.address` no lleva el prefijo CIDR
+
+**Qué pasaba (encontrado probando):** el campo `address` de
+`sql_private_access/terragrunt.hcl` es una IP **sin** sufijo `/NN` (el
+prefijo va en un campo separado, `prefix_length`). El cálculo de rangos
+nuevos producía strings `ipaddress.ip_network` completos
+(`"10.0.0.0/16"`), y escribirlos tal cual en `address` genera un valor
+inválido para ese módulo. Además, la recolección de rangos *existentes*
+para evitar colisiones nunca leía estos `address`/`prefix_length`
+separados — solo los CIDR completos de `vpc/terragrunt.hcl` — así que un
+rango nuevo podía colisionar con un `sql_private_access` real sin que el
+picker lo notara.
+**Resuelto en:** `build_component_vpc` reconstruye el CIDR completo de
+cada `sql_private_access/terragrunt.hcl` existente (`address` +
+`prefix_length`) antes de buscar uno libre; `build_component_sql_private_access`
+separa el rango elegido en `address` (sin sufijo) y `prefix_length` antes
+de escribirlos.
+
+## B5 — Archivos de nivel raíz de `live/<entorno>/` (no de un componente)
+
+**Qué pasaba (encontrado probando, con `20_validate_file_parity.sh`):**
+`boletera-qa` tiene un `Makefile` (corre `terragrunt run --all ...`) y un
+`README.md` directamente en `live/boletera-qa/`, fuera de cualquier
+componente. Nada en el proceso — ni este skill en su primera versión, ni
+el proceso manual que generó `xoloshop-qa` en la sesión anterior — los
+copiaba. El propio `xoloshop-qa` real de `infra-cloud` sigue sin estos dos
+archivos hoy.
+**Resuelto en:** paso `top-level-files` dedicado en
+`10_build_components.sh`, antes del loop de componentes.
+**Por qué importa:** es la prueba de por qué existe la Etapa 3 — el
+proceso manual original nunca detectó esta falta en su momento porque
+nadie comparó cantidades de archivo a conciencia; el script de validación
+de paridad sí.
+
+## B6 — Falso positivo en la validación de "project_id pinneado"
+
+**Qué pasaba (encontrado probando):** la primera versión de
+`21_validate_project_pinning.sh` exigía que **todo** componente tuviera
+una clave `inputs.project_id = local.project_id`. Pero `org_policies` usa
+`parent = "projects/${local.project_id}"` y
+`storage_assets`/`storage_docs` usan `project = local.project_id` — nunca
+una clave llamada `project_id` en `inputs`. El check marcaba estos 3
+componentes como fallidos aunque estaban perfectamente bien pinneados.
+**Resuelto en:** el check se generalizó a "¿aparece la substring exacta
+`local.project_id` en algún lado del archivo?" — cubre cualquier forma en
+que un módulo use el project id, sin asumir un nombre de clave fijo.
+
+## B7 — `dns_record_name`/`dns_domain_name` no son un patrón de texto genérico
+
+**Qué pasaba (encontrado probando):** `sql_postgres` de varios entornos
+(no `xoloshop-qa`, que nunca los configuró) tiene
+`dns_record_name = "boletera.db"` y
+`dns_domain_name = "qa.boletera.ninja."`. A simple vista parece el mismo
+patrón `<app>.algo` que el resto de los campos, pero en realidad codifica
+un **dominio DNS real que la organización tiene registrado para esa app
+específica** (`boletera.ninja`, `cashless.ninja`) — no hay garantía de que
+la app nueva vaya a vivir bajo `<NEW_ENV_APP>.ninja`.
+**Resuelto en:** `build_component_sql_postgres` genera un valor por el
+mismo patrón visual **solo si el campo ya existía en `SOURCE_ENV`**, pero
+**siempre** lo marca con un `[WARN]` pidiendo confirmación humana — a
+diferencia de los demás campos (nombres de red, SA, CIDR), donde la
+sustitución mecánica sí es segura porque no representa una decisión de
+negocio externa al repo.
+
+## B8 — `github_workload_identity` puede manejar varios repos de la misma app
+
+**Qué pasaba (encontrado probando):** se asumió que este componente
+siempre tiene exactamente 2 bindings (`terraform` + un `github-manager`).
+`boletera-qa` real tiene **6**: el de `terraform` y 5 bindings
+`github-manager` distintos, uno por cada repo de su propia arquitectura
+multi-repo (`xbol-web-admin`, `xbol-api-client`, etc.). La primera versión
+de este skill solo corregía el *segundo* binding encontrado y dejaba los
+otros 4 con nombres de repo obsoletos de `SOURCE_ENV`, sin avisar.
+**Resuelto en (versión original):** contar los bindings; si eran
+exactamente 2 (caso simple) ajustar automáticamente, y si eran más, no
+adivinar — solo `[WARN]`. **Superado por C6** (ver sección C): ahora el
+bloque completo se reconstruye siempre, soportando una lista de repos en
+`APP_GITHUB_REPO` — ya no hace falta elegir entre "caso simple" y
+"advertir sin tocar".
+
+---
+
+## C1 — La construcción moría en el reintento (reanudación prometida pero rota)
+
+**Qué pasaba:** `mkdir -p "$NEW_DIR"` corría antes que cualquier
+componente, así que un fallo posterior dejaba `live/<NEW_ENV>/` creado —
+y una guarda previa (`[[ ! -d "$NEW_DIR" ]] || ksc_die ...`) trataba eso
+como "ya existe, no tocar" en el siguiente intento. La reanudación que
+`SKILL.md`/`IDEA.md` prometían no existía en la práctica.
+**Resuelto en:** se quitó la guarda. `10_build_components.sh` ahora
+reconstruye cada componente siempre desde `SOURCE_DIR` (nunca incrementa
+sobre `NEW_DIR`), así que el reintento es naturalmente idempotente — no
+hace falta un motor de reanudación por paso, solo que nada dependa de un
+estado parcial previo.
+
+## C2 — El picker de CIDR podía asignar un rango que se solapa consigo mismo
+
+**Qué pasaba:** la fórmula probaba un solo `N` para los 4 bloques
+(subred, pods, svc, `sql_private_access`) y solo los validaba contra los
+rangos **ya existentes**, nunca entre sí. Cuando `N` resultaba múltiplo de
+10, la subred (`10.N.0.0/22`) quedaba **contenida** en su propio
+`sql_private_access` (`10.N.0.0/16`) — un solapamiento real que solo se
+detecta desplegando. Reproducido: el primer rango libre daba `N=1`
+(válido), pero el segundo consecutivo daba `N=10` (inválido).
+**Resuelto en:** `ksc_cidr_pick_free` ahora busca por década
+(`sql_private_access = 10.<década>.0.0/16`) y, dentro de cada década, por
+un offset ≥ 1 para la subred (preferido `+3`, la convención real
+dominante del repo) — la subred nunca puede caer en la década exacta de
+su propio `/16` por construcción, no solo por un chequeo adicional (que
+también se agregó).
+
+## C3 — `boletera-qa` (el ejemplo del propio README) rompía el build
+
+**Qué pasaba:** `build_top_level_files` fallaba la construcción completa
+si `SOURCE_ENV` no tenía alguno de los 3 archivos de nivel raíz
+(`Makefile`/`README.md`/`.gitignore`) — el caso real de `xoloshop-qa`,
+que es justo el entorno más "sano" del repo (el único con
+`orgpolicy.googleapis.com` y las 6 `org_policies`).
+**Resuelto en:** copiar cada archivo de nivel raíz es ahora
+condicional-sin-fallar (`if [[ -f ... ]]; then cp ...; fi`, nunca un `&&`
+encadenado cuyo valor de verdad se propague como el de toda la función) —
+que falte uno de los 3 es normal, no un error.
+
+## C4 — Project_iam/org_policies/project_services de `SOURCE_ENV` se copiaban sin verificar que estuvieran sanos
+
+**Qué pasaba:** la estrategia "copiar tal cual" de A2/A7 asume
+implícitamente que `SOURCE_ENV` ya tiene todo lo que un entorno nuevo
+necesita. En la práctica, 4 de los 5 entornos reales de este repo NO
+tienen `orgpolicy.googleapis.com` ni las 6 `org_policies` — construir
+desde cualquiera de ellos (incluido `boletera-qa`, el ejemplo del README)
+reproduce en silencio exactamente el error #7 de
+`CreateScriptsNewGCPProjectInstructions.md`.
+**Resuelto en:** `ksc_check_source_health` (nueva, en `lib/common.sh`,
+invocada desde `02_print_config.sh` antes de confirmar) compara
+`SOURCE_ENV` contra el resto de `live/` y advierte si le falta una API o
+le faltan entradas de `org_policies` que **el entorno modificado más
+recientemente** ya tiene. Se usa "el más reciente" y no "la mayoría"
+porque un requisito nuevo de la organización, por definición, todavía NO
+lo tiene la mayoría de entornos viejos — una votación por mayoría nunca
+lo habría detectado (se probó: con mayoría, el hueco real de
+`boletera-qa` no se veía; con "más reciente" sí). La misma función
+también advierte si la IP fija de `cloudadmin` de `SOURCE_ENV` difiere de
+la mayoría del resto de `live/` (ahí sí conviene mayoría, no "más
+reciente" — una IP de oficina compartida rara vez cambia legítimamente).
+Nunca bloquea nada — solo advierte, porque un `SOURCE_ENV` minimalista a
+propósito es una posibilidad legítima que el humano puede confirmar.
+
+## C5 — Sustitución incompleta del nombre de la app fuera de `artifact_registry`
+
+**Qué pasaba:** solo se sustituía el token completo del entorno
+(`boletera-qa` → `shopdemo-qa`), nunca el nombre corto de la app
+(`boletera`) ni su capitalizado (`Boletera`), salvo en
+`artifact_registry`. Resultado real: `service_accounts` dejaba
+`display_name = "Boletera QA Node Service Account"` y `project_iam`
+dejaba namespaces/bindings con `boletera` sin tocar.
+**Resuelto en:** `ksc_copy_component_files` (la función que TODO
+`build_component_*` usa para copiar) ahora aplica, para cualquier
+componente, tres sustituciones en orden: el token completo del entorno,
+el nombre corto de la app en minúscula, y el nombre corto capitalizado —
+una sola vez, en un solo lugar, en vez de que cada componente decidiera
+por su cuenta cuáles aplicar (y se le olvidara a varios).
+
+## C6 — Editar `github_workload_identity` por posición era frágil, y no soportaba apps multi-repo
+
+**Qué pasaba:** el binding de `github-manager` se identificaba por ser
+la "2.ª coincidencia" de `principal_set_suffix` en el archivo — si
+`SOURCE_ENV` tuviera los 2 bindings en el orden inverso, se habría
+corrompido el binding de `terraform`/`infra-cloud` en vez del de la app.
+Además, cuando `SOURCE_ENV` tenía más de 2 bindings (apps multi-repo como
+`boletera-qa`, con 5), el skill solo advertía y dejaba los 5 nombres de
+repo viejos sin tocar.
+**Resuelto en:** `ksc_set_workload_identity_bindings` reconstruye el
+bloque completo: ubica el binding de `terraform` **por contenido**
+(`service_account_email` que empieza con `"terraform@"`, nunca por
+posición) y genera un binding `github-manager` por cada repo listado en
+`APP_GITHUB_REPO` (separados por `;`) — soporta tanto el caso simple (1
+repo) como el multi-repo, sin advertir-y-no-tocar.
+
+## C6b — No todo entorno real tiene un binding de terraform en `github_workload_identity`
+
+**Qué pasaba (encontrado verificando el fix de C6 con una CUARTA fuente,
+`cashless-qa`, que ninguna ronda anterior de pruebas había usado):**
+`cashless-qa` real solo tiene un binding `github-manager` — nunca tuvo
+uno de `terraform`. `ksc_set_workload_identity_bindings` (y la extracción
+previa en `build_component_github_workload_identity`) asumían que ese
+binding siempre existe y fallaban la construcción completa si no lo
+encontraban.
+**Resuelto en:** si no hay binding de `terraform@...`, no es un error —
+se usa `"infra-cloud"` como `principal_set_suffix` por defecto (el valor
+que la guía §3.15 pide siempre) y se avisa con `[WARN]`, en vez de morir.
+
+## C7 — Lecciones menores de la misma revisión
+
+- **Componentes opcionales copiados siempre:** el skill copiaba *todos*
+  los componentes que `SOURCE_ENV` tuviera, incluyendo los que la guía
+  (§1.2) pide explícitamente no incluir por defecto
+  (`cloud_armor`/`identity_platform`/`monitoring_alerts`/`secrets`).
+  Resuelto con `ksc_base_components` (intersección real de componentes en
+  TODOS los entornos de `live/`, sin lista hardcodeada — y excluyendo
+  explícitamente cualquier entorno que no siga el patrón `<app>-qa|prod>`,
+  como un proyecto de infraestructura compartida) + el campo
+  `EXTRA_COMPONENTS` del config para pedirlos de vuelta explícitamente.
+- **Tracking como dependencia dura:** si `github-proyect-tracking` no
+  podía inicializar (sin red, token, URL inválida), toda la construcción
+  moría — aunque es 100% local. Resuelto: el tracking es ahora
+  best-effort (`[WARN]` + seguir sin reanudación remota).
+- **`deletion_protection` en `*-prod`:** se copiaba de `SOURCE_ENV` sin
+  aviso; si `SOURCE_ENV` es qa (`"false"`) y `NEW_ENV` es prod, quedaba
+  `"false"` en prod en silencio. Resuelto con un `[WARN]` específico.
+- **Clave HCL duplicada heredada de `SOURCE_ENV`** (ej.
+  `boletera-qa/sql_postgres` trae `update_timeout` dos veces dentro del
+  mismo bloque `inputs`): ni `terragrunt hcl fmt` ni `hcl validate` lo
+  detectan. Resuelto con `ksc_check_duplicate_keys`, corrido al final de
+  la construcción sobre cada componente (cuidado: tiene que ser
+  consciente de bloques `{ }` — una primera versión confundía
+  `locals.project_id` con `inputs.project_id` como "duplicado" por tener
+  la misma indentación).
+- **Dos falsos positivos de los propios chequeos de este skill, encontrados
+  recién al probar con `xoloshop-qa` como fuente** (no con `boletera-qa`):
+  el comentario que el propio skill agrega en `project_iam` explicando por
+  qué no se puede usar `roles/orgpolicy.policyAdmin` ahí contiene ese
+  mismo string textualmente, y el chequeo de "¿quedó algo de SOURCE_ENV
+  sin sustituir?" no distinguía comentarios de código real. Ambos
+  chequeos ahora ignoran líneas que empiezan con `#`.
+- **`terragrunt hcl validate` por componente** (guía §3.17) no se corría,
+  solo `hcl fmt`. Se agregó al final de la construcción, tolerando el
+  falso positivo conocido de `gke_private`.
+- Bug de texto: un carácter de guion suave invisible (U+00AD) dentro de
+  "realmente" en un mensaje `[WARN]`, y la plantilla del config decía
+  "separadas por coma" cuando el formato real usa `;`. Ambos corregidos.
+
+---
+
+## D — Encontradas por `Review_V2.md` (re-revisión después de aplicar C)
+
+`Review_V2.md` volvió a ejecutar el skill de punta a punta contra las
+correcciones de la sección C, con varias fuentes y, de forma crítica,
+con reintentos reales sobre entornos a medio construir. Encontró un bug
+crítico nuevo — una regresión directa de C1 — y varios menores.
+
+## D1 (N-1) — CRÍTICO: la base de componentes se contaminaba con entornos sin comitear
+
+**Qué pasaba:** `ksc_base_components` contaba cualquier directorio de
+`live/` que pareciera un entorno (`^[a-z0-9]+-(qa|prod)$`) — incluido un
+`live/<NEW_ENV>/` a medio construir (el estado normal de un reintento
+desde C1) y, peor, cualquier OTRO entorno abandonado de una corrida
+anterior, con cualquier nombre. Reproducido en cadena: un entorno
+mutilado a 2 componentes hacía que un entorno nuevo e inocente **también**
+construyera solo 2 componentes, con `FILE_PARITY_OK`/`PROJECT_PINNING_OK`
+en verde — exactamente el defecto silencioso que este skill existe para
+eliminar.
+**Resuelto en:** `ksc_real_envs` (nueva, consolidada): un entorno solo
+cuenta si además de cumplir el patrón de nombre tiene **al menos un
+archivo comiteado en git** bajo su `live/<env>/`. Este skill nunca
+comitea nada, así que cualquier intento (parcial o completo, propio o de
+otro `NEW_ENV`) queda excluido automáticamente, sin tener que conocer su
+nombre ni asumir que "bien formado" significa "completo". Se usa en
+`ksc_base_components`, `ksc_check_source_health` y
+`ksc_majority_fixed_network` — las tres tenían el mismo filtro
+incompleto (D2).
+
+## D2 — El mismo filtro incompleto estaba duplicado en 3 funciones
+
+**Qué pasaba (encontrado aplicando el fix de D1):** el filtro
+"solo entornos reales" estaba copiado a mano en `ksc_base_components`,
+`ksc_check_source_health` y `ksc_majority_fixed_network` por separado.
+Corregirlo solo en la primera (como un primer intento de fix hizo)
+dejaba las otras dos igual de contaminables — confirmado probando: con
+dos entornos de prueba sin comitear en `live/`, el doctor reportaba "6/7
+entornos reales" en vez de "4/5".
+**Resuelto en:** las tres ahora llaman a `ksc_real_envs`, una sola
+fuente de verdad. Lección operativa: cuando un fix corrige una función,
+`grep` el resto del archivo por lógica duplicada antes de dar el fix por
+completo.
+
+## D3 — Bug de `set -e` introducido por el propio fix de N-6
+
+**Qué pasaba (encontrado probando el fix, antes de llegar a reportarlo):**
+el código nuevo para preferir la IP mayoritaria (ver D5) usaba
+`[[ condición ]] && variable=valor` como declaración suelta dentro de un
+`for`, en un script con `set -e`. Cuando la condición daba falso para
+**cualquier** entorno (ej. `live/shared/`, que no matchea
+`<app>-qa|prod>`), el script completo moría ahí mismo — y como venía
+ANTES del bloque que autodetecta `ORG_ID`/`GKE_VERSION`/etc., esos
+campos quedaban `__PENDIENTE__` sin ninguna pista de por qué.
+**Resuelto:** `if`/`fi` en vez de `&&` para cualquier asignación con
+efecto secundario que dependa de una condición que puede ser falsa,
+dentro de un script con `set -e`. Lección operativa: `A && B` es seguro
+bajo `set -e` si B puede fallar (A fallar está exento), pero mezclar
+asignaciones de esta forma invita a confundirse — mejor `if` siempre que
+el cuerpo no sea un one-liner trivial como `continue`.
+
+## D4 (N-2) — `01_init_config.sh` moría en un rescate legítimo
+
+**Qué pasaba:** después del fix de reanudación de C1, `10` ya no
+fallaba por que `live/<NEW_ENV>/` existiera — pero `01` sí, con un
+mensaje que literalmente decía "bórralo tú mismo primero", contradiciendo
+la instrucción de `SKILL.md` de simplemente re-correr `10`.
+**Resuelto en:** `01` ahora distingue "`live/<NEW_ENV>/` existe y el
+config de este skill YA existe" (reintento legítimo, no es error) de
+"existe pero no hay config" (colisión real con otra cosa, sí es error).
+
+## D5 (N-6) — El doctor avisaba del typo pero el config igual escribía el valor malo
+
+**Qué pasaba:** `ksc_check_source_health` ya sabía que la mayoría de
+`live/` usa `177.226.232.136/32` para `cloudadmin` y que `xoloshop-qa`
+tiene un valor distinto — pero solo avisaba; `01_init_config.sh` seguía
+autodetectando y escribiendo el valor de `SOURCE_ENV` tal cual.
+**Resuelto en:** `ksc_majority_fixed_network` (extraída del doctor,
+reusada) + lógica en `01_init_config.sh` que adopta el valor mayoritario
+en el config cuando hay una mayoría clara (>mitad de los entornos
+reales) y difiere del de `SOURCE_ENV`, con un `[WARN]` explicando el
+cambio (no en silencio).
+
+## D6 (N-7) — El picker de CIDR preferiría la década 0 o rellenaría huecos bajos
+
+**Qué pasaba:** el picker probaba décadas en orden `0, 10, 20, ...` —
+técnicamente sin colisión, pero `10.0.x.x` se reserva convencionalmente
+(VPN/defaults/on-prem) y rellenar huecos bajos (`10, 50, ...`) en vez de
+seguir la secuencia real (`20, 30, 40, 130, 140`) es menos predecible
+para quien revisa el PR.
+**Resuelto en:** el orden de búsqueda ahora prioriza la primera década
+libre **por encima** de la mayor ya usada, y la década 0 queda como
+último recurso, no primera opción.
+
+**Corrección posterior (Review V3, P-4):** la primera versión de esta
+lección decía "el siguiente lógico es 150" — eso es matemáticamente
+imposible con la fórmula real: `svc = 10.<década+off+106>.0.0/23`
+necesita `década+off ≤ 149` para que el segundo octeto no pase de 255,
+lo que limita la década máxima usable a **140** sin importar el offset.
+El código ya se comportaba bien (`candidate()` devuelve `None` para
+cualquier década inválida y el loop sigue), pero probaba décadas hasta
+240 sin necesidad; se acotó el rango generado a `0..140` para que el
+código y el comentario coincidan con el techo real de la fórmula.
+
+## D7 — Mejora pendiente resuelta: `artifact_registry` determinista sin hardcodear la organización
+
+Encontrada como mejora abierta en la propia `Review_V2.md` (no un bug):
+cuando `SOURCE_ENV` tiene `repository_id`/`description` genéricos (4 de
+5 entornos reales), en vez de solo advertir, `ksc_learn_artifact_registry_template`
+busca OTRO entorno de `live/` que sí tenga su propio nombre de app en su
+`artifact_registry`, extrae el patrón reemplazando ese nombre por un
+marcador, y lo aplica con el nombre de la app nueva. Nunca se hardcodea
+"club-tijuana" ni ningún otro literal de la organización en el código
+del skill — se aprende de los datos reales de `live/`, igual que el
+doctor.
+
+## D8 — Lecciones menores de la misma re-revisión
+
+- **Cobertura del leftover-check reducida (N-3):** V1 revisaba todos los
+  archivos de `live/<NEW_ENV>/`; el fix de ignorar comentarios (B-algo)
+  de la ronda anterior redujo por accidente la lista a solo
+  `terragrunt.hcl`/`project.hcl`/`README.md`, perdiendo
+  `Makefile`/`.gitignore` de cada componente. Restaurado con `find` sobre
+  todo el árbol (2 niveles), filtrando comentarios línea por línea en vez
+  de limitar por nombre de archivo.
+- **WARNs del doctor no sobrevivían a la Etapa 1 (N-5):** `KSC_WARNINGS_FILE`
+  solo se fijaba en `10_build_components.sh`; si la sesión moría entre
+  `02` y `10`, los avisos del doctor se perdían. Ahora `02` también la fija
+  (truncando, fresca cada corrida) y `10` hace *append* en vez de truncar.
+- **Código muerto (N-4):** una variable (`DUPLICATE_ISSUES`) que se
+  asignaba y nunca se leía. Eliminada.
+- **`SKILL.md` no cubría `finalize` sin tracking (N-8):** si el tracking
+  nunca se inicializó, la instrucción de cerrar con `run_tracking.sh
+  finalize` fallaría sin explicación. Se agregó la condición explícita.
+- **Cosmético (N-9):** `uninstall.sh --clean-gitignore` dejaba una línea
+  en blanco suelta al final del `.gitignore`.
+
+---
+
+## E1 (P-1) — La función nueva de D7 nació con la misma contaminación que D1/D2 ya habían corregido
+
+**Qué pasaba:** `ksc_learn_artifact_registry_template` (agregada en la
+misma ronda que D7) iteraba `live/*/` directamente, sin pasar por
+`ksc_real_envs` — exactamente el filtro incompleto que D1/D2 ya habían
+consolidado en las otras tres funciones. Reproducido: un entorno sin
+comitear (`live/aaaajunk-qa/`) con `repository_id =
+"aaaajunk-mega-custom-repo"` se "aprendía" como si fuera una plantilla
+real, con un `[OK]` que además afirmaba (incorrectamente) que era un
+"entorno real".
+**Resuelto en:** la función ahora usa `ksc_real_envs` como las demás, y
+de paso adoptó el mismo criterio de "preferir el más reciente" del
+doctor en vez de "el primero alfabético" — dos entornos específicos con
+nombres distintos ya no dependen de en qué orden los liste el
+filesystem.
+**Lección operativa, otra vez:** cada función nueva que itere `live/*/`
+tiene que pasar por `ksc_real_envs` desde el día uno — no basta con
+haberlo corregido en las funciones que ya existían (D2 ya dejó esta
+lección una vez; aquí se repitió con una función que no existía
+todavía cuando D2 se escribió).
+
+## E2 (P-2) — Rescate imposible si se perdía el config
+
+**Qué pasaba:** si `.kcreate-scaffolding/<env>.config` se perdía (ej.
+por `uninstall.sh --clean-gitignore`, que la borra a propósito) con
+`live/<NEW_ENV>/` todavía a medias, `01_init_config.sh` trataba cualquier
+`live/<NEW_ENV>/` sin config como colisión real y recomendaba borrar
+exactamente lo que se quería rescatar — sin camino automático de vuelta.
+**Resuelto en:** `01` ahora reconoce una firma mínima
+(`project.hcl` con `project_id` == `NEW_ENV`, que `build_project_hcl`
+siempre deja) para distinguir "rescate legítimo" de "colisión real", y
+regenera el config desde cero en el primer caso.
+
+## E3 (P-3) — Los warnings de la Construcción se duplicaban en cada reintento
+
+**Qué pasaba:** el fix de persistencia de D-faltante-17/N-5 usó un solo
+archivo en modo *append* para doctor + build. Correcto para que el
+doctor sobreviva entre `02` y `10`, pero cada reintento de `10` volvía a
+escribir sus propios WARN sobre los de la corrida anterior — un archivo
+que pasaba de 8 a 14 líneas con un solo retry, sin límite.
+**Resuelto en:** dos archivos separados
+(`ksc_warnings_file_path` para el doctor, `ksc_build_warnings_file_path`
+para la construcción). El del doctor se trunca en cada `02` (sigue
+fresco); el de la construcción se trunca al INICIO de cada `10` (no
+repite sus propios WARN en un retry). El reporte final combina ambos.
+
+## E4 (P-4) — Comentario/lección describía un comportamiento matemáticamente imposible
+
+**Qué pasaba:** D6 (y el comentario del código) decían que el picker de
+CIDR, al no encontrar una década libre cerca, seguiría hasta "150, 160,
+...". La fórmula real (`svc = 10.<década+off+106>.0.0/23`) hace que
+cualquier década ≥ 150 exceda 255 en el segundo octeto para todo
+offset — esas décadas nunca se usan, sin importar qué tan lejos llegue
+el rango de búsqueda. El código ya se comportaba bien (`candidate()`
+devuelve `None` y el loop sigue), solo el comentario/lección prometían
+algo que no podía pasar.
+**Resuelto en:** el rango de búsqueda ahora se acota a `0..140` (el
+techo real de la fórmula) y el comentario/D6 se corrigieron para
+describir el comportamiento real, no uno aspiracional.
+
+## E5 — Observación: repo destino sin ningún commit
+
+Si `live/` no tiene NINGÚN entorno comiteado (un repo de infra recién
+creado, sin commit inicial), `ksc_real_envs` da una lista vacía y la
+base de componentes también queda vacía — el build excluiría todo salvo
+lo que `EXTRA_COMPONENTS` pida. No ocurre en un repo de infra real (que
+siempre tiene historia), pero se agregó un `[WARN]` explícito en
+`ksc_base_components` para ese caso, en vez de dejar que "todo se
+excluye" pase sin ninguna pista de la causa.
+
+---
+
+## F — encontradas ejecutando el skill de punta a punta contra `infra-cloud` real
+
+A diferencia de B-E (copias descartables), esta corrida fue real: generó
+`coreservices-qa` desde `xoloshop-qa` en `club-tijuana/infra-cloud`, con
+Issue de tracking real (#332) creado y cerrado. El usuario revisó el
+resultado campo por campo y reportó F1 directamente.
+
+### F1 — "XoloShop" (marca estilizada) sobrevivía la sustitución, sin ser detectado
+
+**Qué pasaba:** `service_accounts/terragrunt.hcl`, generado desde
+`xoloshop-qa`, dejó `display_name`/`description` de dos service accounts
+con "XoloShop" (S interna mayúscula) sin tocar — debían decir
+"Coreservices QA ...". `ksc_copy_component_files` solo hacía dos pasadas
+de sustitución EXACTAS: `ksc_substr_replace` para `"xoloshop"` (minúsculas)
+y una para `ksc_capitalize("xoloshop")` = `"Xoloshop"` (solo la primera
+letra). Ninguna de las dos es substring de `"XoloShop"` (mayúscula
+*interna*), así que esa capitalización en particular pasaba intacta.
+Tampoco `21_validate_project_pinning.sh` lo atrapaba: busca el token
+completo `"<app>-<entorno>"` exacto, y `"XoloShop"` no es substring de
+`"xoloshop-qa"` ni de `"Xoloshop-QA"`.
+**Resuelto en:**
+- `lib/common.sh:ksc_substr_replace_app` — sustitución case-*insensitive*
+  (vía `re.IGNORECASE` en Python) con reemplazo case-*aware*: si el match
+  original era todo mayúsculas usa `APP_NEW` en mayúsculas, si era todo
+  minúsculas usa minúsculas, cualquier otro caso (incluida la "XoloShop"
+  original) usa capitalización simple (`Coreservices`). Así cualquier
+  variante de capitalización del nombre de marca queda cubierta, no solo
+  las dos que `ksc_capitalize` sabía producir.
+- `10_build_components.sh:ksc_copy_component_files` — reemplaza las dos
+  pasadas exactas por una llamada a `ksc_substr_replace_app` (solo si
+  `APP_SOURCE != APP_NEW`, evitando trabajo innecesario cuando el nombre
+  de app no cambia entre entornos).
+- `build_component_artifact_registry`'s detección de "ya es genérico" —
+  cambiada a `grep -qi` por la misma razón (consistencia: no tiene sentido
+  que la detección sea case-sensitive si la sustitución ya no lo es).
+  **Decisión explícita de NO tocar:** el check de `repository_id` en
+  `ksc_learn_artifact_registry_template` sigue siendo exacto/minúsculas —
+  GCP exige minúsculas en ese campo, así que ahí la sensibilidad a mayúsculas
+  es correcta, no un bug.
+- **Nueva validación:** `22_validate_no_app_name_leftover.sh` — un script
+  de Etapa 3 dedicado, que busca `APP_SOURCE` (cualquier capitalización)
+  en TODO archivo de `live/<NEW_ENV>/`, fuera de comentarios. Complementa
+  (no reemplaza) a `21`: ese sigue validando el token completo exacto,
+  este cubre justo el caso que `21` no puede ver por diseño. Probado
+  contra una copia descartable: pasa limpio en un build correcto, y
+  detecta correctamente un leftover reintroducido a mano, reportando
+  archivo y línea exactos.
+
+### F2 — El tracking no decía qué skill lo estaba usando ni con qué parámetros
+
+**Qué pasaba:** el Issue de GitHub que abre `github-proyect-tracking` no
+tenía forma de decir, por sí solo, que lo estaba usando
+`/kcreate-scaffolding-gcp-script`, ni con qué `SOURCE_ENV`/`NEW_ENV` —
+alguien leyendo el Issue sin contexto previo no podía saber qué se estaba
+construyendo sin preguntar aparte.
+**Resuelto:** `github-proyect-tracking` 0.7.0+ agrega `--process-name`/
+`--process-inputs` a `init` (ver `vendor/VENDORED_FROM.md`); este skill
+los manda siempre, automáticamente, desde `run_tracking.sh init-plan`
+(`--process-name "/kcreate-scaffolding-gcp-script"` y
+`--process-inputs '{"SOURCE_ENV":...,"NEW_ENV":...}'`), sin que el agente
+tenga que acordarse de pasarlos.
+
+### F3 — El resumen final solo se veía en pantalla, no quedaba en el Issue
+
+**Qué pasaba:** al terminar, el agente comentaba "FINALIZADO" en el Issue
+y lo cerraba, pero el resumen de ejecución (lo que sí le mostraba al
+humano en pantalla) nunca quedaba escrito en el Issue — quien lo leyera
+después no tenía ese resumen, solo el estado final.
+**Resuelto:** `github-proyect-tracking` 0.7.0 agrega `finalize
+--summary`/`--summary-file`, que publica un comentario aparte con el
+resumen DESPUÉS del de FINALIZADO y ANTES de cerrar el Issue (orden
+verificado con pruebas unitarias dedicadas, incluyendo que la ruta
+`--force`/CANCELADO nunca publica resumen). `run_tracking.sh finalize`
+acepta ahora un tercer argumento opcional (ruta a un archivo con el
+resumen); `SKILL.md` (Etapa 3) ya le indica al agente que construya ese
+resumen ANTES de llamar a `finalize` y lo pase como archivo.
+
+---
+
+## Qué significa esta lista para quien edite este skill después
+
+Cada vez que se agregue un `build_component_<algo>` nuevo o se modifique
+uno existente: **pruébalo contra una copia descartable de un repo real**
+(nunca contra el repo de trabajo del usuario) antes de considerarlo
+terminado, igual que se hizo para construir las lecciones B1-B8. La mitad
+de los bugs reales de este skill nunca se habrían notado solo leyendo el
+código — se encontraron ejecutándolo de punta a punta contra datos reales
+y revisando el resultado campo por campo, no solo confiando en que los
+checks automatizados pasaran.