release: v3.1.0 — puente desde design.md, regla sin costo ni licencias, .env.example legible

CHANGELOG.md

@@ -4,6 +4,20 @@ Formato basado en [Keep a Changelog](https://keepachangelog.com/) y [SemVer](htt
 
 ## [No publicado]
 
+## [3.1.0] - 2026-10-26
+
+### Added
+- **Del diseño al código: `/project-context <ruta>/design.md`.** Si diseñaste el sistema con [system-design-kit](https://github.com/lacasoft/system-design-kit), `project-context` traslada el diseño al proyecto sin reescribirlo: visión y "fuera de alcance (v1)", atributos de calidad con sus umbrales, modelo de dominio y contratos, arquitectura con las fallas previstas (y sus tests de regresión), supuestos pendientes, y **un ADR por decisión** con la plantilla de la skill `adr`. Lo derivable del repo (stack real, comandos, estructura) sigue saliendo del repo. Anota el diseño de origen y su fecha, así que al reimportar solo actualiza lo que vino de ahí; un ADR aceptado se reemplaza, no se edita. Mapeo completo en `skills/project-context/desde-design.md`. Probado en una sesión real: 3 ADRs desde las decisiones y 9 pendientes señalados, uno de ellos un hueco del propio diseño (validación de `long_url` frente a SSRF).
+- **Regla §6.1.7: sin costo ni ataduras.** Nada de pago, que exija API key o cuenta de un tercero, o con licencia propietaria o modificada. Está en la baseline y en la checklist que el hook `pre-bash` muestra al pedir confirmación de una instalación.
+
+### Changed
+- **Se retiran las recomendaciones que no cumplen §6.1.7** y pasan a `components.json` → `discarded` con su motivo: los plugins `security-guidance` (una llamada pagada a Opus por turno y por commit) y `claude-security` (licencia propietaria); el LSP de PHP `php-lsp`, que depende de Intelephense (licencia propietaria); y `react-doctor` (MIT modificada con restricciones, y además sugerido como `@latest`). En los overlays de React y React Native lo sustituyen `eslint-plugin-react-hooks` y los profilers de React DevTools y React Native DevTools.
+
+### Fixed
+- **El agente no podía leer `.env.example`.** `settings.json` denegaba `Read(./.env.*)`, y ese patrón atrapa también los ejemplos, que son justo la documentación versionada de las variables (y `project-context` la necesita). Las reglas de permisos no admiten excepciones, así que ahora hay denies explícitos para los `.env` reales comunes y un hook `pre-read` que bloquea cualquier `.env*` y `.envrc`, en cualquier carpeta, salvo `.example`, `.sample` y `.template`. `--update` retira el `Read(./.env.*)` viejo de los proyectos y lo informa, igual que `Bash(npx react-doctor*)`.
+- **La baseline indicaba un `.gitignore` que no funciona.** `/docs` con `!/docs/adr` no reincluye los ADRs: git no puede reincluir nada dentro de un directorio excluido. Ahora indica `/docs/*` con `!/docs/adr/`.
+- 12 tests nuevos (112 en total).
+
 ## [3.0.2] - 2026-10-18
 
 ### Fixed

CONTRIBUTING.md

@@ -85,7 +85,7 @@ Borra el archivo de `shared/.claude/` sin más: en `--update`, el instalador ret
 
 - SemVer en `package.json` + entrada en `CHANGELOG.md`.
 - Como se distribuye por `npx github:`, los proyectos toman la rama por defecto: **`master` siempre debe estar verde** (CI en cada PR). Usa ramas `feat/…`, `fix/…` y PRs.
-- Para fijar versiones en un proyecto concreto: `npx github:lacasoft/dev-starter-kit#v3.0.2`.
+- Para fijar versiones en un proyecto concreto: `npx github:lacasoft/dev-starter-kit#v3.1.0`.
 
 ## Probar localmente
 

README.md

@@ -34,7 +34,7 @@ Dentro de **cualquier proyecto** (nuevo o heredado), sin clonar nada:
 ```bash
 npx -y github:lacasoft/dev-starter-kit              # interactivo
 npx -y github:lacasoft/dev-starter-kit --yes --all  # desatendido (todo)
-npx -y github:lacasoft/dev-starter-kit#v3.0.2       # fijar una versión (recomendado)
+npx -y github:lacasoft/dev-starter-kit#v3.1.0       # fijar una versión (recomendado)
 ```
 
 Toma siempre la última versión de `master` (o el tag indicado). Repo **público (MIT)**.
@@ -146,6 +146,29 @@ comandos de build/test/lint antes de documentarlos, rellena lo derivable y te pr
 tanda lo que no se puede deducir. Mientras siga siendo la plantilla, cada sesión arranca con un
 aviso que lo sugiere.
 
+### Desde un diseño (system-design-kit)
+
+Si diseñaste el sistema con [system-design-kit](https://github.com/lacasoft/system-design-kit),
+no reescribas nada: en el proyecto de código, pasa la ruta del diseño.
+
+```bash
+claude --add-dir ../acortador-urls      # para que pueda leer la carpeta del diseño
+> /project-context ../acortador-urls/design.md
+```
+
+| Del diseño | Al proyecto |
+| --- | --- |
+| Requisitos y fuera de alcance | *Visión del producto* (con "Fuera de alcance (v1)") |
+| Requisitos no funcionales y escala | *Atributos de calidad* con sus umbrales |
+| API y modelo de datos | *Modelo / dominio* y contratos en *Arquitectura* |
+| Arquitectura inicial y escenarios de falla | *Arquitectura* (con "Fallas previstas") y tests de regresión en *Testing* |
+| Decisiones clave y tradeoffs | **Un ADR por decisión** en `docs/adr/`, con la plantilla de la skill `adr` |
+| Supuestos sin confirmar | *Pendiente de confirmar* |
+
+Lo que el repo sí sabe (stack real, comandos, estructura) sigue saliendo del repo. El archivo
+anota de qué diseño salió y su fecha, así que si el diseño cambia, volver a correrlo actualiza
+solo lo que vino de ahí; un ADR aceptado no se edita, se reemplaza por otro.
+
 ## Memoria y contexto (nativos de Claude Code)
 
 | Qué | Dónde | Quién lo escribe | Versionado |
@@ -188,6 +211,13 @@ seguridad), scripts `pre/postinstall`, y si algo del repo ya lo cubre. Si un com
 Como defensa en profundidad, `settings.json` deniega además `sudo`, `publish`, `chmod 777` y la lectura
 de `~/.ssh` y `~/.aws` por permisos, para el caso de que los hooks estén desactivados.
 
+Los archivos `.env` reales (también `.env.production`, `.env.local`, `.envrc`, en cualquier carpeta)
+no se leen: lo impide el hook `pre-read`. Los ejemplos (`.env.example`, `.env.sample`,
+`.env.template`) sí, porque documentan las variables sin valores.
+
+**Regla para cualquier externo** (§6.1.7): nada de pago, que exija API key o cuenta de un tercero,
+o con licencia propietaria o modificada.
+
 ## Estándares de seguridad
 
 | Estándar | Edición | Dónde se aplica |
@@ -225,27 +255,26 @@ cubre lo que usábamos. Si un proyecto lo tenía:
 
 **Integrados por stack** (vía `claude-code-templates`, solo los marcados `integrar`):
 - shared: `code-reviewer`, skills `clean-code`, `senior-security`; marketplace oficial de plugins.
-- seguridad (plugins oficiales, **opcionales**, revisados archivo por archivo; el instalador los
-  lista con su condición):
-  - `security-guidance`: revisión automática del diff en cada turno y revisión agéntica en cada
-    commit. Cuesta una llamada a Opus por revisión (`ENABLE_STOP_REVIEW=0` deja solo la de commit) e
-    instala `claude-agent-sdk` sin versión fijada en `~/.claude/security` al iniciar sesión.
-  - `claude-security`: escaneo profundo bajo demanda con verificación independiente y SARIF. Pesado
-    en tokens; úsalo antes de un release grande. Licencia propietaria (se usa, no se destila).
 - code intelligence (plugins oficiales LSP, se indican por stack): `typescript-lsp` (Nest, Express,
-  Angular, React, Next, React Native), `pyright-lsp` (FastAPI, Django), `php-lsp`, `jdtls-lsp`
-  (Spring), `csharp-lsp` (.NET). Sin plugin oficial para Dart ni Solidity.
+  Angular, React, Next, React Native), `pyright-lsp` (FastAPI, Django), `jdtls-lsp`
+  (Spring), `csharp-lsp` (.NET). Sin plugin oficial libre para PHP (`php-lsp` usa Intelephense,
+  de licencia propietaria), Dart ni Solidity.
 - backend: `database-architect`, `test-engineer`; skill `docker-expert`.
 - frontend/mobile: `frontend-developer`, `ui-ux-designer`; skills `frontend-design`, `ui-design-system`.
-- frontend/react + mobile/react-native: dep npm de animación (`motion` / `react-native-reanimated`)
-  + `react-doctor` (auditoría on-demand, no se cablea como hook bloqueante).
+- frontend/react + mobile/react-native: dep npm de animación (`motion` / `react-native-reanimated`).
 
 **Opcionales** (en `components.json` pero *no* se instalan solos; añádelos a mano si los quieres):
 `architect-review` (backend) y `senior-frontend` (frontend).
 
-**Descartados** (extracto; los 13 con su motivo están en `components.json` → `discarded`):
+**Regla para todo externo** (baseline §6.1.7): nada de pago, que exija API key o cuenta de un tercero,
+o con licencia propietaria o comercial.
+
+**Descartados** (extracto; los 17 con su motivo están en `components.json` → `discarded`):
 - `ruvnet/claude-flow` (Ruflo) — retirado en la 3.x; ver "Orquestación multiagente".
 - `claude-mem` — duplica la memoria nativa y registra hooks propios.
+- `php-lsp` (Intelephense) y `react-doctor` — licencia propietaria y MIT modificada con restricciones.
+- `security-guidance` y `claude-security` — el primero hace llamadas pagadas a Opus en cada turno y
+  commit; el segundo tiene licencia propietaria. Su lugar lo ocupa la skill `owasp-review`.
 - `semgrep` (Guardian) — envía cada archivo que escribe el agente a la nube de Semgrep, en todos los
   proyectos, y se autoactualiza con binarios opacos. Alternativa: `semgrep` CLI local o en CI.
 - `serena` — arranca con `uvx` desde el último commit de GitHub, sin versión fijada; los plugins LSP
@@ -307,7 +336,7 @@ recibir la copia vieja. La solución buena es la misma que exige la baseline §6
 versión** — y de paso hace la instalación reproducible:
 
 ```bash
-npx -y github:lacasoft/dev-starter-kit#v3.0.2 --update --yes    # por tag
+npx -y github:lacasoft/dev-starter-kit#v3.1.0 --update --yes    # por tag
 npx -y github:lacasoft/dev-starter-kit#<commit> --update --yes  # por commit (el SHA del tag)
 ```
 
@@ -328,4 +357,4 @@ Repo **público (MIT)** distribuido por `npx github:` → la rama **`master` deb
   (dry-run) y en un monorepo multi-stack, en cada PR. La lista sale de `scripts/stacks.cjs`, que la deriva de `install.js`.
 - **Cómo añadir** agentes, skills, stacks o externos: ver [CONTRIBUTING.md](CONTRIBUTING.md).
 - **Versionado**: SemVer en `package.json` + `CHANGELOG.md`, con tag anotado por versión
-  (`v3.0.2`). Instala siempre pineando (`#v3.0.2`): es reproducible y evita la cache de npx.
+  (`v3.1.0`). Instala siempre pineando (`#v3.1.0`): es reproducible y evita la cache de npx.

components.json

@@ -18,8 +18,6 @@
     ],
     "pluginsOptional": [
       { "id": "code-review@claude-plugins-official", "why": "review automatizado de PRs" },
-      { "id": "security-guidance@claude-plugins-official", "rec": "opcional", "short": "revisión de seguridad automática en cada turno y commit; cuesta tokens (Opus)", "why": "Revisado (v2.0.14, Apache-2.0, Anthropic). Tres capas: avisos por patrones al editar, revisión del diff con un LLM al terminar cada turno y revisión agéntica en cada commit/push que sigue el flujo de datos entre archivos (IDOR, bypass de auth, SSRF entre archivos). Complementa a owasp-review (que es bajo demanda). Condiciones: 1) cada revisión es una llamada a Opus aparte de tu sesión (su README estima ~0.19 USD por revisión del Stop): para gastar menos, ENABLE_STOP_REVIEW=0 deja solo las de commit/push, o SECURITY_REVIEW_MODEL apunta a un modelo más barato; 2) en cada SessionStart instala claude-agent-sdk desde PyPI SIN versión fijada (pip install --upgrade, en un venv en ~/.claude/security), lo que choca con la regla de versión fijada de §6.1; 3) envía el diff y los archivos relacionados al mismo endpoint de modelo que usa Claude Code. Sus hooks viven en el plugin y no tocan nuestro settings.json. Reglas propias del proyecto: .claude/claude-security-guidance.md (versionado; sin secretos, va al prompt)." },
-      { "id": "claude-security@claude-plugins-official", "rec": "opcional", "short": "escaneo profundo bajo demanda (/claude-security) con hallazgos verificados y SARIF", "why": "Revisado (v0.12.0, Anthropic, licencia PROPIETARIA: se puede usar, no destilar). Escaneo multiagente bajo demanda del repo o de un diff, con threat model, verificadores independientes que intentan refutar cada hallazgo y salida en Markdown, JSONL y SARIF; puede proponer parches como archivos que tú aplicas. Es el complemento pesado de owasp-review: úsalo antes de un release grande o tras un cambio sensible (scan de cambios a effort high). Sin instalaciones en SessionStart; sus hooks solo muestran un banner, cuentan uso y sugieren escanear tras push/PR (CLAUDE_SECURITY_SCAN_TIP=off lo apaga). Requiere Python 3.9+. Escribe CLAUDE-SECURITY-<timestamp>/ en la raíz del repo, con su propio .gitignore. Consume muchos tokens: pide confirmar el costo antes de cada scan." },
       { "id": "context7-plugin@context7-marketplace", "marketplace": "upstash/context7", "rec": "opcional", "why": "MCP remoto (https://mcp.context7.com/mcp) que inyecta docs versionadas de librerías. Sin API key obligatoria (free tier; la key gratis solo sube rate limits). No toca el .mcp.json del proyecto (servidor namespaced 'context7' dentro del plugin). Transversal a todos los stacks. Privacidad: solo viaja el nombre de librería + la pregunta, nunca metas secretos ni código propietario en la query." }
     ]
   },
@@ -72,13 +70,12 @@
     "backend/express": { "lsp": { "plugin": "typescript-lsp@claude-plugins-official", "binary": "typescript-language-server (npm i -g typescript-language-server typescript)" } },
     "backend/fastapi": { "lsp": { "plugin": "pyright-lsp@claude-plugins-official", "binary": "pyright-langserver (npm i -g pyright, o pipx install pyright)" } },
     "backend/django": { "lsp": { "plugin": "pyright-lsp@claude-plugins-official", "binary": "pyright-langserver (npm i -g pyright, o pipx install pyright)" } },
-    "backend/php": { "lsp": { "plugin": "php-lsp@claude-plugins-official", "binary": "intelephense (npm i -g intelephense)" } },
     "backend/spring": { "lsp": { "plugin": "jdtls-lsp@claude-plugins-official", "binary": "jdtls (Eclipse JDT.LS; brew install jdtls o instalación manual)" } },
     "backend/dotnet": { "lsp": { "plugin": "csharp-lsp@claude-plugins-official", "binary": "csharp-ls (dotnet tool install --global csharp-ls)" } },
     "frontend/angular": { "lsp": { "plugin": "typescript-lsp@claude-plugins-official", "binary": "typescript-language-server (npm i -g typescript-language-server typescript)" } },
-    "frontend/react": { "npm": ["motion"], "tools": ["react-doctor"], "lsp": { "plugin": "typescript-lsp@claude-plugins-official", "binary": "typescript-language-server (npm i -g typescript-language-server typescript)" } },
+    "frontend/react": { "npm": ["motion"], "lsp": { "plugin": "typescript-lsp@claude-plugins-official", "binary": "typescript-language-server (npm i -g typescript-language-server typescript)" } },
     "frontend/nextjs": { "lsp": { "plugin": "typescript-lsp@claude-plugins-official", "binary": "typescript-language-server (npm i -g typescript-language-server typescript)" } },
-    "mobile/react-native": { "npm": ["react-native-reanimated"], "tools": ["react-doctor"], "lsp": { "plugin": "typescript-lsp@claude-plugins-official", "binary": "typescript-language-server (npm i -g typescript-language-server typescript)" } }
+    "mobile/react-native": { "npm": ["react-native-reanimated"], "lsp": { "plugin": "typescript-lsp@claude-plugins-official", "binary": "typescript-language-server (npm i -g typescript-language-server typescript)" } }
   },
 
   "externalSkillCatalogs": {
@@ -132,6 +129,10 @@
     "git/git-flow-manager": "Solo si el equipo usa Git Flow (no trunk-based). Dejar a criterio por proyecto.",
     "web-development/react-best-practices": "Duplica la skill vercel:react-best-practices ya disponible en el harness.",
     "cct-hooks": "lint-on-save / security-scanner / smart-formatting / tdd-gate: su instalador hace merge shallow por evento y PISA nuestros arrays Pre/PostToolUse. Su intención (format+lint+secret-scan) ya está replicada en .claude/helpers/hook-handler.cjs.",
+    "php-lsp@claude-plugins-official (Intelephense)": "RETIRADO por la regla §6.1.7: el plugin oficial de PHP depende de Intelephense, cuya licencia es propietaria (EULA personal e intransferible; las funciones premium requieren una clave de pago). Phpactor es libre (MIT) pero no tiene plugin oficial; si se quiere, se configura a mano.",
+    "react-doctor": "RETIRADO por la regla §6.1.7: licencia 'MIT modificada' con restricciones propias (prohíbe usarlo como entrada de pipelines de IA y venderlo como servicio sin permiso escrito), no es open source estándar. Además el kit lo sugería como @latest. Alternativas libres en los overlays: eslint-plugin-react-hooks y los profilers de React DevTools / React Native DevTools.",
+    "security-guidance@claude-plugins-official": "Revisado (v2.0.14, Apache-2.0). RETIRADO de los opcionales por la regla §6.1.7 (sin costo): hace una llamada a Opus en cada turno con cambios y otra en cada commit/push, a cargo de tu cuenta, aparte de la sesión. Además instala claude-agent-sdk sin versión fijada en cada SessionStart. Su función la cubren owasp-review (bajo demanda) y el hook de secretos.",
+    "claude-security@claude-plugins-official": "Revisado (v0.12.0). RETIRADO de los opcionales por la regla §6.1.7: licencia PROPIETARIA de Anthropic (todos los derechos reservados) y escaneos que consumen muchos tokens de tu cuenta. Usa owasp-review.",
     "semgrep@claude-plugins-official (Semgrep Guardian)": "Revisado (v2.7.0). NO se recomienda por defecto: sus hooks corren en cada Write/Edit/Bash de TODOS los proyectos y envían cada archivo que escribe el agente (y su versión anterior), más lockfiles, a scanner.semgrep.ai; exige cuenta de Semgrep; ejecuta binarios precompilados que se autoactualizan en cada inicio de sesión (con manifiesto firmado, pero opacos para revisión); y el repo del plugin no trae licencia. Si tu organización ya usa Semgrep y acepta ese flujo de datos, es su decisión. La alternativa que propone el kit: semgrep CLI local o en CI (ver ci-cd y owasp-review).",
     "serena@claude-plugins-official": "Revisado. Plugin comunitario cuyo .mcp.json arranca `uvx --from git+https://github.com/oraios/serena` SIN versión fijada: cada sesión ejecuta el último commit de GitHub, lo contrario de §6.1. Lo que aporta (navegación semántica por LSP) ya lo cubren los plugins LSP oficiales que el kit indica por stack, y su propio sistema de memorias del proyecto duplicaría la memoria nativa. Si se quisiera, habría que fijarlo a un tag a mano.",
     "framer-motion (como skill)": "Es dependencia npm de proyecto, no componente .claude. Se sugiere instalar en el proyecto, no en .claude."