ozali 0.1.0

package/skill/references/knowledge-blueprint.md

@@ -0,0 +1,143 @@
+# Blueprint de la base de conocimiento (AI.md + carpeta dotted)
+
+Se usa en la **ruta GENERATE** (Fase 2 de `ozali`), cuando el repo **no** tiene ya
+`AI.md`/`.ai` ni `IA.md`/`.ia`. La fuente de verdad **no se descarga de ningún lado**:
+se **genera evaluando el proyecto real**. Este documento define la estructura canónica,
+las reglas de generación y las diferencias frontend/backend.
+
+> **Regla anti-invención:** todo el contenido se deriva del código, los manifiestos y la
+> configuración REALES del repo. Lo que no se pueda derivar se marca como
+> `<!-- PROVISIONAL: confirmar con el usuario -->` o se pregunta. Nunca inventes reglas de
+> negocio, módulos, comandos ni versiones.
+
+---
+
+## 1. Detección frontend vs backend
+
+Evalúa señales en la raíz del repo (la primera categoría con coincidencias gana; si hay
+ambigüedad —p. ej. monorepo full-stack— **pregunta al usuario**):
+
+**Frontend**
+- `angular.json`, `package.json` con `@angular/*`, `react`, `next`, `vue`, `vite`, `svelte`
+- carpeta `src/app` (Angular) o `src/pages`/`src/components`
+
+**Backend**
+- `pom.xml`, `build.gradle` (Java/Spring)
+- `requirements.txt`, `pyproject.toml`, `manage.py` (Python)
+- `go.mod` (Go), `Cargo.toml` (Rust)
+- `package.json` con `express`/`nestjs`/`fastify` y sin framework de UI
+
+---
+
+## 2. Qué inspeccionar del proyecto antes de generar
+
+| Aspecto | Dónde leerlo |
+|---|---|
+| Nombre real del proyecto | manifiesto (`pom.xml` `<artifactId>`, `package.json` `name`), README |
+| Stack y versiones | `pom.xml`/`package.json`/`build.gradle` — versiones EXACTAS, no supuestas |
+| Estructura de capas/módulos | árbol real de `src/` (paquetes Java, carpetas Angular, etc.) |
+| Comandos build/test/run | scripts del manifiesto, wrappers (`mvnw`, `gradlew`), CI (`.github/`, pipelines) |
+| Patrones de arquitectura | leer 3-5 clases/componentes representativos por capa |
+| Convenciones de código | observar nombres, inyección, manejo de errores, estilo en el código real |
+| Configuración por entorno | `application*.yml`/`.properties`, `environments/`, `.env*` |
+| Estado de pruebas | contar archivos en `src/test`/`*.spec.ts` — reportar cobertura real |
+
+---
+
+## 3. Estructura canónica de la carpeta dotted
+
+Por defecto genera `.ai/` + `AI.md` (usa `.ia/` + `IA.md` solo si el usuario lo pide o el
+ecosistema del equipo ya usa esa variante).
+
+```
+.ai/
+  agents/        → identidades por rol (difieren según front/back, ver §5)
+  context/
+    architecture.md       → capas/módulos REALES + diagrama de flujo (mermaid)
+    coding-standards.md   → convenciones OBSERVADAS en el código + reglas de oro
+    tech-stack.md         → stack, versiones exactas y comandos de build/test/run
+  knowledge/
+    README.md             → qué es esta carpeta y cómo se alimenta
+    learning-notes.md     → memoria técnica: gotchas, lecciones, decisiones (inicia con
+                            los hallazgos de la propia inspección)
+  workflows/
+    feature.md   → proceso para nueva funcionalidad
+    bugfix.md    → proceso para corrección no crítica
+    hotfix.md    → proceso express para incidente de producción (gate humano intacto)
+    refactor.md  → proceso para mejora interna sin cambio de comportamiento
+```
+
+---
+
+## 4. Estructura canónica de `AI.md` (documento guía / "Project Brain")
+
+Modelo: punto de entrada corto; el detalle vive en `.ai/`. Secciones obligatorias:
+
+```markdown
+# <Proyecto> - Project Brain (AI.md)
+
+Este archivo sirve como el "cerebro" del proyecto para asistir a agentes de IA y
+desarrolladores en la comprensión de la arquitectura, flujos y estándares de <Proyecto>.
+
+## 🚀 Descripción del Proyecto
+<2-4 frases: qué es, qué resuelve, integraciones clave — derivado del código real>
+
+Para detalles sobre el comportamiento de la IA en este proyecto, consulta:
+- **[<Rol 1>](.ai/agents/<rol1>.md)**
+- **[<Rol 2>](.ai/agents/<rol2>.md)**
+- ...
+
+## 📚 Contexto Global
+| Documento | Alcance / Contenido |
+|-----------|--------------------|
+| **[Arquitectura](.ai/context/architecture.md)** | <resumen de una línea> |
+| **[Stack Tecnológico](.ai/context/tech-stack.md)** | <resumen> |
+| **[Estándares de Código](.ai/context/coding-standards.md)** | <resumen> |
+| **[Log de Conocimiento](.ai/knowledge/learning-notes.md)** | Memoria técnica de la IA. |
+
+## ⚙️ Workflow & Comandos
+| Comando | Descripción |
+|---------|-------------|
+| <comando real 1> | <qué hace> |
+| <comando real 2> | <qué hace> |
+
+### Workflows de Agentes
+- **[Desarrollo de Feature](.ai/workflows/feature.md)**
+- **[Bugfix](.ai/workflows/bugfix.md)**
+- **[Hotfix](.ai/workflows/hotfix.md)**
+- **[Refactor](.ai/workflows/refactor.md)**
+
+---
+*Este documento es el punto de entrada. Las definiciones técnicas detalladas residen en `.ai/`.*
+```
+
+---
+
+## 5. Diferencias frontend vs backend
+
+| Aspecto | Frontend | Backend |
+|---|---|---|
+| `agents/` | `frontend.md`, `designer.md`, `reviewer.md`, `tester.md` | `architect.md`, `backend.md`, `dao-specialist.md` (si hay BD), `reviewer.md`, `tester.md` |
+| `architecture.md` | estructura `src/app` (módulos, componentes, servicios, rutas, guards), flujo de datos UI ⇄ servicios ⇄ API | capas `Controller → Service → DAO/Repository → Entity` (+ DTO/Projection/Strategy según el repo), paquetes reales |
+| `tech-stack.md` | framework UI + Node + tooling (versiones de `package.json`), comandos `npm ...` | lenguaje + framework + BD (versiones de `pom.xml`/etc.), comandos `mvn ...`/wrapper |
+| `coding-standards.md` | reactividad, manejo de estado, i18n, accesibilidad, testing (Karma/Jest/Cypress) | inyección por constructor, DTO vs Entity, wrapper de respuesta, manejo de excepciones, transaccionalidad, testing (JUnit/mocks) |
+| Comandos típicos | `npm start`, `npm run build`, `npm run test`, deploy (Firebase/CDN) | `mvn spring-boot:run`, `mvn test`, `mvn package`, perfiles por entorno |
+| Zonas sensibles típicas | guards/auth, interceptores, modelos compartidos, config de entornos | config de datasource, clientes externos, exception handlers, DTOs de contrato público, ymls de uat/producción |
+
+Los `workflows/` son comunes en estructura (feature/bugfix/hotfix/refactor) pero sus pasos
+de validación usan los comandos reales del proyecto (npm vs mvn).
+
+---
+
+## 6. Reglas de generación
+
+1. **Nomenclatura del repo:** nombres, títulos y rutas reales del proyecto; nada de
+   placeholders genéricos de plantilla.
+2. **Versiones leídas, no recordadas:** copia las versiones de los manifiestos.
+3. **Convenciones observadas:** un estándar solo entra a `coding-standards.md` si se
+   observa de forma consistente en el código (o el usuario lo confirma).
+4. **Estado real de pruebas:** si `src/test` está casi vacío, dilo en `tech-stack.md` y en
+   `learning-notes.md` — no asumas cobertura.
+5. **Siembra `learning-notes.md`** con los hallazgos de la inspección (typos en nombres de
+   clases, paquetes con nombre inesperado, módulos sin uso aparente, etc.).
+6. **Todo lo generado es provisional** hasta pasar la validación de la Fase 3 de `ozali`.

package/skill/references/permissions-bypass.md

@@ -0,0 +1,232 @@
+# Perfiles de permiso de `cdk` (modo normal y `--auto`)
+
+Plantillas y mecanismos de permisos para `cdk`, en **dos perfiles**, para **Claude Code** y
+**opencode**.
+
+> [!IMPORTANT]
+> Una **skill no puede** otorgarse permisos ni cambiar el modo en caliente: el harness lee la
+> configuración de los **archivos de settings** y de los **flags de lanzamiento**. Por eso
+> esto es **configuración de entorno**, no algo que el `SKILL.md` ejecute. `cdk` solo
+> **verifica/recuerda** que esté activa al iniciar.
+>
+> El **GATE es comportamiento de la skill**, no un prompt de permisos: liberar permisos y
+> parar en el plan **no se contradicen**.
+
+## Perfiles
+
+| Capacidad | **Modo normal** (sin `--auto`) | **Modo `--auto`** |
+| :-- | :-- | :-- |
+| Lectura dentro del proyecto | ✅ sin prompt | ✅ sin prompt |
+| Lectura de rutas **fuera** del proyecto | ❓ pregunta | ✅ sin prompt |
+| Líneas de comando (Bash/PowerShell) | ✅ sin prompt | ✅ sin prompt |
+| Scripts de Python | ✅ sin prompt | ✅ sin prompt |
+| Fetch de sitios externos (lectura) | ✅ sin prompt | ✅ sin prompt |
+| **Ediciones/escrituras de código** | ❓ **pregunta** | ✅ auto-aplica |
+| Comandos destructivos (`rm -rf`, `git push`) | ❓ pregunta | ⚠ circuit breakers / `ask` |
+| 🛑 GATE del plan | siempre para | siempre para |
+
+> En **modo normal** `cdk` puede analizar y ejecutar libremente, pero **confirma los cambios de
+> código**. En **`--auto`** además auto-aplica los cambios y el **único alto es el GATE**.
+
+---
+
+## 1. Claude Code
+
+### 1.0 Modo normal (base) — lectura + comandos + Python + fetch
+Perfil para el flujo **sin `--auto`**: libera análisis y ejecución, pero **las ediciones de
+código siguen pidiendo confirmación**. Archivo `.claude/settings.json` (compartible) o
+`.claude/settings.local.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash",
+      "PowerShell",
+      "WebFetch",
+      "WebSearch"
+    ],
+    "deny": [
+      "Bash(rm -rf *)",
+      "Bash(git push *)",
+      "PowerShell(Remove-Item *)"
+    ]
+  }
+}
+```
+
+- **Lectura dentro del proyecto** ya es libre (ver §1.1), por eso no hace falta `Read` en el
+  `allow`; se mantiene **`ask` por defecto** para rutas fuera del proyecto (no se abre
+  `additionalDirectories` en este perfil).
+- **Líneas de comando** y **Python** quedan cubiertos por `Bash`/`PowerShell` (p. ej.
+  `python script.py`, `python3 -m ...`, `mvn`, `node`).
+- **Fetch externo de lectura** vía `WebFetch` (cualquier dominio) + `WebSearch`.
+- **Ediciones/escrituras** (`Edit`/`Write`) **NO** están en `allow` → siguen preguntando.
+- `deny` deja como red de seguridad los comandos destructivos más comunes (gana sobre `allow`).
+
+> Variante **más acotada** (en vez de `Bash`/`PowerShell` completos): lista solo los comandos
+> que usa el análisis, p. ej. `"Bash(python *)"`, `"Bash(python3 *)"`, `"Bash(node *)"`,
+> `"Bash(mvn *)"`, `"Bash(git status*)"`, `"Bash(node .claude/skills/cdk/verify-structure.mjs*)"`.
+
+### 1.1 Qué ya NO pide permiso (no necesitas hacer nada)
+- **Lecturas dentro del working dir** y herramientas read-only: `Read`, `Grep`, `Glob`.
+- **Comandos Bash read-only**: `ls`, `cat`, `echo`, `pwd`, `head`, `tail`, `grep`, `find`,
+  `wc`, `which`, `diff`, `stat`, `du`, `cd` y formas read-only de `git`.
+
+→ La fricción real del análisis son **rutas FUERA del working dir** (otro repo, `~`, etc.).
+
+### 1.2 Opción A — Scoped (recomendada por seguridad)
+Lecturas libres en el análisis + ediciones automáticas en la ejecución, sin abrir todo.
+Archivo `.claude/settings.local.json` (o `.claude/settings.json` para compartir):
+
+```json
+{
+  "permissions": {
+    "defaultMode": "acceptEdits",
+    "allow": [
+      "Read",
+      "Grep",
+      "Glob",
+      "Bash(node .claude/skills/cdk/verify-structure.mjs*)"
+    ],
+    "additionalDirectories": [
+      "../",
+      "//c/Users/<usuario>/ruta/a/otros/repos"
+    ]
+  }
+}
+```
+
+- `additionalDirectories` habilita **leer/editar rutas fuera del proyecto** sin prompt (úsalo
+  para las rutas no contempladas que el análisis pueda necesitar).
+- `defaultMode: "acceptEdits"` auto-acepta ediciones y `mkdir/touch/mv/cp` en el working dir y
+  en `additionalDirectories` (cubre la ejecución post-GATE).
+- Mantienes control sobre comandos Bash de escritura (siguen preguntando salvo los `allow`).
+
+### 1.3 Opción B — Bypass total (lo que pediste: solo parar en el plan)
+Forma **fiable**: lanzar la sesión con el flag (NO depende de settings):
+
+```bash
+claude --dangerously-skip-permissions
+```
+
+- Salta **todos** los prompts; el único alto será el GATE de `cdk`.
+- `defaultMode: "bypassPermissions"` en settings **puede no surtir efecto** (bug conocido); por
+  eso se prefiere el flag.
+- **Circuit breakers que SIEMPRE preguntan** aunque el bypass esté activo: `rm -rf /`,
+  `rm -rf ~` y cualquier regla `ask` explícita.
+- Escrituras a directorios protegidos (`.git`, `.claude`, `.vscode`, `.idea`, `.husky`, …)
+  pueden seguir avisando; excepciones: `.claude/commands`, `.claude/agents`, `.claude/skills`.
+- ⚠ Úsalo solo en entornos aislados/confiables (contenedor, VM o repo controlado).
+
+### 1.4 Opción C — PreToolUse hook (avanzado)
+Orden de evaluación: **PreToolUse hook → deny → ask → allow → modo**. Un hook puede
+**auto-aprobar** llamadas (no puede saltarse `deny`/`ask`). Patrón típico: `allow` de `Bash` +
+un hook que **rechace** solo los comandos peligrosos. Ver docs de hooks de Claude Code.
+
+> Precedencia de settings: managed > flags CLI > `.claude/settings.local.json` >
+> `.claude/settings.json` > `~/.claude/settings.json`. Un `deny` en cualquier nivel gana.
+
+---
+
+## 2. opencode
+
+Config en `opencode.json` (raíz del proyecto) o `~/.config/opencode/opencode.json`. Valores:
+`"allow"` | `"ask"` | `"deny"`. **Gana la última regla que coincide** → pon el catch-all `*`
+primero y luego las excepciones.
+
+### 2.0 Modo normal (base) — lectura + comandos + Python + fetch
+Perfil para el flujo **sin `--auto`**: libera análisis y ejecución, **confirma ediciones**.
+`opencode.json` en la raíz del proyecto:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "read": "allow",
+    "grep": "allow",
+    "glob": "allow",
+    "webfetch": "allow",
+    "external_directory": "ask",
+    "edit": "ask",
+    "bash": {
+      "*": "allow",
+      "rm -rf *": "ask",
+      "git push *": "ask"
+    }
+  }
+}
+```
+
+- `bash: "*": "allow"` cubre **líneas de comando y Python** (`python ...`, `mvn`, `node`).
+- `webfetch: "allow"` → **fetch externo de lectura**.
+- `external_directory: "ask"` mantiene la confirmación para **rutas fuera del proyecto**
+  (en `--auto` pasa a `"allow"`, ver §2.1/§2.2).
+- `edit: "ask"` → los **cambios de código siguen confirmándose**.
+
+### 2.1 Opción A — Scoped (recomendada)
+La clave para "rutas fuera del scope" es **`external_directory`** (por defecto `"ask"`):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "read": "allow",
+    "grep": "allow",
+    "glob": "allow",
+    "external_directory": "allow",
+    "edit": "allow",
+    "bash": {
+      "*": "allow",
+      "rm -rf *": "ask",
+      "git push *": "ask"
+    }
+  }
+}
+```
+
+### 2.2 Opción B — Bypass total
+```json
+{ "$schema": "https://opencode.ai/config.json", "permission": "allow" }
+```
+(equivale a `{ "*": "allow" }`). Nota: los archivos `.env` están **denegados por defecto**.
+
+### 2.3 Opción C — Acotado solo al agente `cdk`
+Deja el resto en `"ask"` y abre el bypass únicamente cuando corre `cdk`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": { "*": "ask" },
+  "agent": {
+    "cdk": {
+      "permission": {
+        "read": "allow",
+        "grep": "allow",
+        "glob": "allow",
+        "external_directory": "allow",
+        "edit": "allow",
+        "bash": { "*": "allow", "rm -rf *": "deny", "git push *": "ask" }
+      }
+    }
+  }
+}
+```
+
+Las reglas del agente **se fusionan** con las globales y **tienen prioridad**.
+
+---
+
+## 3. Resumen rápido
+
+| Necesidad | Claude Code | opencode |
+| :-- | :-- | :-- |
+| **Base modo normal** (lectura proyecto + comandos + Python + fetch, edita con confirmación) | `allow: [Bash, PowerShell, WebFetch, WebSearch]` (§1.0) | `read/grep/glob/webfetch/bash: allow`, `edit: ask` (§2.0) |
+| Leer rutas fuera del scope en análisis | `permissions.additionalDirectories` | `external_directory: "allow"` |
+| Auto-aceptar ediciones (post-GATE) | `defaultMode: "acceptEdits"` o Shift+Tab | `edit: "allow"` |
+| Bypass total (solo parar en el plan) | `claude --dangerously-skip-permissions` | `"permission": "allow"` |
+| Acotar el bypass a un solo flujo | `allow` por patrón + hook | `agent.cdk.permission` |
+| Siempre pregunta (no bypasseable) | `rm -rf /`, `rm -rf ~`, reglas `ask` | `.env` (deny por defecto) |
+
+> El **GATE del plan no se configura aquí**: lo impone el `SKILL.md` de `cdk`. Esta config solo
+> elimina los **prompts de permiso** alrededor de él.