create-harness-btp 0.0.0-stage → 0.1.0

package/AI/AGENTS.md

@@ -0,0 +1,263 @@
+# Harness MVP SAP BTP — Reglas del proyecto
+> Nota portabilidad: verificado en Windows, adapta rutas a [TU_PC].
+
+> Flujo reutilizable especificación → despliegue en SAP BTP Cloud Foundry,
+> orquestado por OpenCode en este equipo Windows. El `AGENTS.md` global de
+> `[TU_PC]\.config\opencode` sigue cargándose; en caso de conflicto,
+> manda este archivo.
+
+## Herramientas: nombres intocables
+
+| Uso | Comando | Notas |
+|---|---|---|
+| Cloud Foundry | `sap_cf` | `sap_cf.cmd` (ruta de instalación de Cloud Foundry CLI en [TU_PC]). |
+| MTA build | `mbt` | Cloud MTA Build Tool (binario recuperado vía su propio `install.js`). |
+| Cloudflare | `cf` | **Prohibido** usar `cf` para Cloud Foundry: ese comando es el CLI de Cloudflare en [TU_PC]. |
+
+Ver skill local `sap-cf-cli` antes del primer comando CF del turno;
+ver `mta-build` antes del primer build MTAR.
+
+## Destino Cloud Foundry conocido (sin secretos)
+
+- Endpoint verificado: `[TU_ENDPOINT_CF]` (p. ej. `https://api.cf.<region>.hana.ondemand.com`;
+  registrar el valor real en la spec del MVP, nunca aquí).
+- Org y espacio objetivo (ver `sap_cf target`;
+  no se transcriben aquí por higiene). Antes de **cada despliegue**, el
+  orquestador re-verifica endpoint/org/espacio contra la especificación del
+  MVP. Si no coinciden o no pueden deducirse, se pide solo el dato
+  indispensable y no se despliega.
+- Despliegue MTA (`sap_cf deploy *.mtar`) requiere el plugin **multiapps**.
+  Antes de asumir su ausencia o instalarlo, verificar con `sap_cf plugins`
+  (lección: verificar siempre antes de asumir su ausencia).
+  Instalarlo solo cuando un MVP lo requiera (ver `mta-build`).
+- Placeholders MTA a credenciales: antes de diseñar un placeholder, verificar
+  la forma real con una key temporal borrable (se documenta solo
+  instancia/key, nunca el secreto; se borra tras extraer lo necesario). Si el
+  deploy-service rechaza placeholders a keys anidadas (p. ej.
+  `credentials.oauth`), no reintentar el mismo placeholder: fallback =
+  binding nativo (`existing-service`) o destino MANUAL en cockpit registrado
+  como pendiente conocido con su causa (cero secretos en repo).
+- No-go conocido: una instancia `integration-flow`
+  (`it-rt`) NO vale como `TokenServiceInstance` de un destino (`Invalid service
+  name [it-rt]...`); no diseñar ni reintentar destino versionado con ella.
+
+## Modelo híbrido MTA + CF CLI (regla irrestricta)
+
+> El `.mta` hace lo suyo; los agentes hacen por CLI lo que el MTA no debe
+> poseer. Objetivo: portar un MVP entre espacios/cuentas sin intervención
+> humana salvo decisiones de coste/acceso.
+
+| En MTA (`mta.yaml`) | Fuera del MTA (agentes por `sap_cf`, una vez por espacio) |
+|---|---|
+| `managed-service`: xsuaa, destination, html5-repo-host/runtime, todo lo que el deploy puede crear/actualizar | `existing-service`: bindings a instancias pre-existentes (p. ej. DIE trial, `it-rt` integration-flow), espacios, roles `SpaceDeveloper`, entitlements/cuotas |
+| Keys DECLARADAS por nombre (`service-key: name:`); el deploy reutiliza la key existente del espacio, nunca la crea con secretos | Creación idempotente de espacio/instancias/roles vía `scripts/provision-<espacio>.ps1` (ver § Paisajes); cero secretos en repo, solo nombres |
+| Destinos versionados con referencias por nombre (`TokenServiceInstanceName/KeyName`, `~{srv-api/srv-url}`); ninguna credencial literal | Lo que el deploy-service rechace (p. ej. placeholders a keys anidadas `credentials.oauth`) NO se reintenta igual: fallback = binding nativo o destino MANUAL en cockpit registrado como pendiente conocido con su causa |
+
+- `sap_cf` siempre; `cf` prohibido (es Cloudflare en [TU_PC]).
+- Keys rotadas por deploy (el deploy-service puede borrar la
+  `service-key` en cada deploy): el runtime NUNCA lee keys; solo binding/VCAP.
+  Las keys son solo de diseño (temporal borrable, solo nombre documentado).
+- Ante URL aún desconocida en paisaje nuevo (p. ej. URL del iFlow de prd antes de desplegarlo): desplegar con placeholder deja la destination inoperativa en runtime pero NO rompe el deploy; se registra como `TODO(<paisaje>)` y se fija tras conocerla.
+- `scripts/cf-safe.ps1` es el punto de entrada para toda lectura CF con secreto potencial (ver `docs/cf-safe.md`).
+
+## Paisajes .mtaext y pre-provisión idempotente
+
+- Cada paisaje = un `<paisaje>.mtaext` en la raíz del MVP (`dev.mtaext`, `prd.mtaext`): `extends: <mta-id>`, overrides SOLO por paisaje (nombres de `existing-service`, `service-key`, URL del iFlow). `mta.yaml` guarda el default (= dev vivo). Cero secretos.
+- Cadena de deploy: `sap_cf target -s <paisaje>` → `sap_cf deploy mta_archives/<mtar> -e <paisaje>.mtaext`. Sin `-e` no hay deploy multi-paisaje.
+- Puerta `/verify` (etapa 7) exige en verde: `mbt mtad-gen -e <paisaje>.mtaext` por cada `.mtaext` afectado + target coincide con spec + instancia/key esperadas existen verificadas (comando o cockpit, nunca heredadas de notas).
+- Persistencia efímera (p. ej. SQLite `:memory:` se vacía en cada redeploy/restart): la spec lo declara; el E2E resiembra tras cada deploy y ningún CA exige datos supervivientes salvo que la spec defina persistencia real.
+- Pre-provisión: `scripts/provision-<espacio>.ps1` por paisaje no-dev, idempotente (cada paso comprueba y emite `SKIP:` si existe), NO despliega nada. Plantilla obligatoria: preflight de target (endpoint+org, aborta si no coinciden) → crea espacio si falta → guardia de marketplace (aborta antes de crear si falta un offering) → crea instancias solo si faltan → asigna rol solo si falta. Allowlist cerrada: `target, spaces, space-users, services, marketplace, create-space, create-service, set-space-role`. PROHIBIDO: `delete-*`, `unbind-*`, `purge-*`, `restage-*`. Usa `sap_cf` (nunca `cf`).
+
+## Flujo por etapas (`/flow <ruta-spec>`)
+
+0. Evaluación de la especificación → 1. Investigación → 2. Plan →
+3. Preparación → 4. Desarrollo → 5. Pruebas → 6. Correcciones →
+7. Revisión de despliegue (`/verify`) → 8. Despliegue →
+9. Git → 10. Documentación (+ cosecha de lecciones: `harness-evolution`
+   propone, el orquestador aplica tras revisión).
+
+- Cada etapa tiene entregable verificable; el orquestador define el criterio
+  de avance en el plan y lo exige antes de continuar.
+- Rigor proporcional al MVP: saltar etapas irrelevantes está permitido y se
+  registra; ejecutar builds/despliegues innecesarios, no.
+- **Despliegue continuo en MVPs ya desplegados (ciclo
+  desplegar→probar→corregir, sin detenerse):** cuando se cumplan TODAS estas
+  condiciones, el orquestador NO se detiene en la etapa 7 a pedir orden de
+  despliegue, sino que encadena puerta (`/verify`) → despliegue
+  (`deploy-cf`) → E2E (`e2e-fiori`) → correcciones, con un máximo de 3
+  vueltas y presupuesto explícito por vuelta:
+  1. El MVP tiene al menos un despliegue anterior con éxito al MISMO
+     endpoint/org/espacio, registrado en la spec;
+  2. `sap_cf target` re-verificado coincide con la spec;
+  3. El cambio no puede verificarse por completo en local (integraciones
+     que solo existen en SAP: DIE, iFlow, XSUAA, HTML5 Repo…) o el usuario
+     ordenó el despliegue.
+  Si las 3 se cumplen, desplegar es parte del alcance implícito: pararse
+  deja la mejora sin probar. El bucle termina en la
+  primera vuelta con E2E en verde; si se agotan las 3 vueltas o el
+  presupuesto, se entrega lo conseguido con evidencia y pendientes.
+  **El bucle se detiene igual y se pide decisión al usuario si:** el target
+  no coincide con la spec, la sesión CF caducó y exige re-login, aparece
+  coste/cuota fuera de trial/gratuito, el destino es productivo (no
+  trial/dev), o el usuario ordena parar. Primeros despliegues (sin
+  antecedente en la spec) siguen exigiendo confirmación explícita del
+  destino antes de la etapa 8.
+- **Portar a otro espacio/cuenta (flujo estándar, sin humanos en el camino):**
+  `preflight` (target+spec+entitlements/`sap-verify` del plan en el espacio
+  nuevo) → `provision-<espacio>.ps1` (solo con orden explícita o antecedente
+  de deploy con éxito al mismo endpoint/org registrado en la spec) →
+  `/verify` (con `mtad-gen -e` del paisaje) → `deploy-cf`
+  (`-e <paisaje>.mtaext`) → `e2e-fiori`. Presupuesto: máx 15 min provision,
+  máx 3 vueltas deploy→e2e→fix como el bucle continuo. Parada con decisión
+  al usuario si: target no coincide, sesión exige re-login, falta
+  offering/entitlement, coste fuera de trial/gratuito, destino productivo, o
+  placeholder `TODO(<paisaje>)` bloquea el CA (se entrega con pendiente, no
+  se inventa la URL).
+- **Autoridad con efecto:** `deploy-cf` sigue siendo el ÚNICO agente con
+  efecto deploy. `provision-<espacio>.ps1` también tiene efecto (crea
+  espacio/instancias/roles) y exige orden explícita del usuario O antecedente
+  de deploy con éxito al mismo endpoint/org registrado en la spec; sin una de
+  las dos, el orquestador solo lo propone, no lo ejecuta. Todo `provision`
+  deja evidencia (salida `SKIP:`/`CREATE:`) y registra instancias/keys creadas
+  solo por nombre en la spec.
+- Paralelo solo en tareas realmente independientes; el orquestador integra y
+  revisa todo. No delega decisiones finales ni acepta cambios sin inspección.
+- Éxito solo con evidencia observable (salida de comandos, app en estado
+  `started`, artefacto MTAR existente). Nunca declarar éxito por haber
+  lanzado un comando.
+- Nunca imprimir tokens, contraseñas ni secretos en terminal, informes, logs
+  o prompts a subagentes. Autenticación por mecanismo interactivo/seguro.
+
+## Local frente a BAS
+
+Este harness corre en Windows local ([TU_PC]). No presuponer que una instalación local
+(`sap_cf`, `mbt`, Node, Java, Python) existe en un dev space
+remoto de BAS, ni viceversa. `cds` y `ui5` CLIs no están instalados
+globalmente: se instalan por proyecto cuando la especificación los exija.
+
+## Presupuesto anti-bloqueo (obligatorio para orquestador y subagentes)
+
+Ninguna tarea puede consumir tiempo ilimitado. Reglas:
+
+- Toda delegación con `subagent` incluye **presupuesto explícito** (minutos
+  o nº de acciones) proporcional a la tarea; p. ej. una validación en
+  navegador: 15 min.
+- **Prohibido reintentar en bucle**: si la misma acción falla 3 veces, se
+  para y se reporta como bloqueo de entorno con evidencia, no se insiste.
+- Al agotar el presupuesto: **entrega parcial + cierre limpio** (matar solo
+  procesos propios por PID, borrar perfiles temporales). El orquestador
+  sigue con la evidencia parcial; nunca se deja una sesión "trabajando" sin
+  entregable.
+- El orquestador que detecte una sesión atascada le envía UNA orden de
+  entrega inmediata; si no responde, cierra sus recursos externos por PID y
+  continúa sin ella, registrando el incidente.
+
+## Disciplina de shell y CLIs (lecciones 2026-10-29)
+
+PowerShell 5.1, no bash. Prohibidos `ver`, `head`, `tail`, `where <args>`,
+`grep` como comando: usar `Get-Command`, `Select-Object -First/-Last`,
+`Select-String`. Todo comando con sintaxis nueva se prueba aislado antes de
+encadenarlo en pipes.
+
+- `cds` CLI: solo vía `npx -p @sap/cds-dk cds ...` (el paquete del proyecto
+  no trae el CLI). Ver skill `cap-cli`. Nunca adivinar nombres de paquetes
+  npm: verificar con `context7` o `npm view` antes de `npx`/`npm i`.
+- Reparación de `mbt` verificada: `node install.js cloud-mta-build-tool`
+  en el directorio del paquete (no `mbt` a secas). Ver skill `mta-build`.
+  `mbt` exige además `make` en `%PATH%` (si falla `exec: "make": executable
+  file not found`, anteponer un `bin` con `make` al `$env:PATH` solo para
+  el comando; no persiste entre sesiones).
+- Nunca `npm audit fix --force` sin revisión: reportar vulnerabilidades a
+  `qa-review`.
+- Artefactos transitorios (regla de entorno): todo lo que
+  un agente genere y sirva solo temporalmente (capturas de pruebas, builds,
+  dumps de consola/red, perfiles CDP) va en `temp/<tarea>/`, nunca en la raíz
+  ni dentro del repo del MVP (`temp/` está ignorado). El orquestador incluye
+  la ruta `temp/<tarea>/` en cada delegación que implique tests, builds o
+  navegador; la evidencia que deba conservarse se mueve a `evidencia/` con su
+  referencia en docs. Al cerrar la tarea se borra lo transitorio.
+- El target CF puede cambiar entre sesiones: re-verificar `sap_cf target`
+  en cada puerta y registrar el cambio en la spec antes de desplegar.
+- Higiene de navegador y CDP (regla irrestricta, ver § Higiene obligatoria de
+  navegador y CDP): matar procesos solo por PID con filtro de perfil temporal
+  propio (`CommandLine -like '*<perfil>*'`); prohibido `Stop-Process -Name chrome`
+  o kills por nombre. Los subagentes llevan time-box explícito y, si lo superan,
+  se cierra su navegador y se sigue con su evidencia parcial.
+- Índices de conocimiento: `codebase-memory` local antes que lectura amplia;
+  `graphify-code` local tras cambios commiteados si está `connected`. Sin
+  reindexación redundante en ambos en el mismo turno.
+
+## Higiene obligatoria de navegador y CDP (regla irrestricta)
+
+Toda tarea que use navegador (`playwright` o `chrome-devtools`, en pruebas o
+implementación) cumple este protocolo sin excepciones. Fuente única: esta
+sección + `scripts/cdp-chrome.ps1`. Causa raíz conocida: el MCP
+`playwright` está configurado con `--cdp-endpoint http://localhost:9222` y
+**solo se conecta, no lanza navegador**; nadie levantaba el host CDP, de ahí
+el `ECONNREFUSED`. `chrome-devtools` usa canal propio y no necesita `:9222`.
+
+1. **Antes (verificación previa):** comprobar el puerto con
+   `scripts/cdp-chrome.ps1 status`. Para `playwright`, ejecutar `ensure`:
+   reutiliza el endpoint si responde; si el puerto lo ocupa un proceso
+   ajeno, **detenerse, no matarlo**, e informar; si está libre, lanza Chrome
+   headless propio con perfil temporal y verifica `/json/version` con
+   reintentos (máx 3: 1 s/2 s/4 s). Sin endpoint verificado no hay prueba
+   con navegador que dar por hecha: reportarlo y seguir con el resto.
+2. **Durante:** trabajar headless por defecto (sin ventana salvo petición
+   explícita). No abrir navegadores fuera del protocolo.
+   **Excepción — E2E con login de usuario:** si la app exige autenticación
+   interactiva (XSUAA/IdP) que solo el usuario puede completar, `e2e-fiori`
+   se invoca igual con navegador VISIBLE (`headed`, perfil temporal propio)
+   para que el usuario se autentique en su ventana y luego continúa; espera
+   acotada al login manual (máximo definido en la delegación, sin reintentos
+   en bucle) y el agente nunca pide ni registra credenciales. El orquestador
+   avisa al usuario ANTES de abrir el navegador (2026-10-31: avisar tarde
+   = 5 min perdidos). Ante muro de
+   login, `e2e-fiori` deja veredicto formal `BLOQUEADO`-con-evidencia
+   (captura + URL + punto alcanzado) salvo orden contraria del usuario;
+   nunca se omite en silencio.
+3. **Después (limpieza):** al terminar la sesión de navegador o la tarea,
+   ejecutar `scripts/cdp-chrome.ps1 cleanup` (mata **solo** procesos propios
+   verificados por PID + perfil, borra el perfil temporal) y, con
+   `chrome-devtools`, cerrar las páginas abiertas. Verificar puerto libre.
+   Sin limpieza verificada no se cierra la tarea.
+4. **Evidencia:** el cierre informa salida de `ensure`/`cleanup` (o de
+   `status` si no se usó navegador) + qué quedó pendiente.
+
+## MCP y skills: selección por fase
+
+- `context7` (`resolve-library-id` → `query-docs`): docs de CAP, UI5, CF CLI,
+  MTA y cualquier librería antes de suponer APIs. Lo usan `researcher` y los
+  especialistas. Ante un error de servicio con código (p. ej. EP003) o un
+  payload dudoso, contrastar el payload contra el tutorial oficial vigente +
+  el error real antes de asumir; las docs viejas o el scaffold no mandan.
+- `codebase-memory`: contexto del índice cuando el MVP viva en un proyecto
+  indexado (`index_status`/`detect_changes` para frescura al arrancar;
+  `index_repository` tras cambios si hay novedades); nada que asumir si
+  puede recuperarse del grafo. `graphify-code` local como complemento
+  cuando esté `connected` (ver `opencode.jsonc`); índice local por defecto,
+  sin reindexar redundante en ambos en el mismo turno.
+- `github`: solo si la especificación pide repo remoto/PR. Sin spec que lo
+  pida, trabajo local.
+- `eslint`: calidad estática en código JS/TS del MVP.
+- `playwright` / `chrome-devtools`: validación en navegador de UIs Fiori
+  cuando el MVP la incluya; `playwright` exige host CDP externo
+  (`scripts/cdp-chrome.ps1 ensure` antes, `cleanup` después; nunca dar UI
+  por hecha solo porque compila ni sin endpoint verificado).
+- Skills globales en su fase, sin cargar todas: `sapui5` con `frontend-ui5`;
+  `systematic-debugging` ante fallos; `verification-before-completion` con
+  `qa-review`; `test-driven-development` si la spec exige TDD; `git-workflow`
+  con Git. Skills externas SAP (ver `INICIO.md § Skills candidatas`) solo se
+  adoptan si la spec las necesita, tras inspección previa.
+
+## Git
+
+- Regla permanente: **ningún secreto en Git** (credenciales, tokens,
+  `.env`, `default-services` con claves, archivos de auth). Revisar diff y
+  estado de ignorados antes de cualquier operación Git.
+- No inicializar repo ni conectar remotos salvo que la especificación lo pida.
+- Commits locales solo cuando correspondan al proyecto. Nunca `push`,
+  publicar repos ni abrir PR salvo petición expresa de la especificación o
+  del usuario.
+- Si el repo del MVP tiene CI con workflows: ningún merge a `main` se da por
+  hecho sin CI en verde verificado en terminal (`gh pr checks <n> --watch`).

package/AI/INICIO.md

@@ -0,0 +1,74 @@
+# Guía de inicio — Harness MVP SAP BTP
+
+> Nota portabilidad: verificado en Windows, adapta rutas a [TU_PC].
+
+Entorno local Windows para llevar MVPs SAP de especificación a despliegue en
+Cloud Foundry, con OpenCode como orquestador.
+
+## Estado verificado (Windows, [TU_PC])
+
+| Herramienta | Resultado |
+|---|---|
+| `sap_cf --version` | CF CLI, sesión activa contra `[TU_ENDPOINT_CF]` |
+| `mbt --version` | Cloud MTA Build Tool (binario recuperado; el `install.js` del paquete npm pedía `cloud-mta-build-tool`, no `mbt`) |
+| `node` / `npm` | versión instalada en [TU_PC] |
+| `java` | versión instalada en [TU_PC] — sirve para builds MTA Java si la spec los pide |
+| `cf` | CLI de Cloudflare — no usar para Foundry |
+| OpenCode | agente `orchestrator` por defecto (este proyecto) |
+| MCP heredados (global) | `context7`, `codebase-memory`, `github`, `playwright`, `eslint`, `chrome-devtools` |
+| Skill instalada útil | `sapui5` (global) |
+| Pendiente (a propósito) | CLIs `cds`/`ui5`, skills SAP externas — se instalan solo si una spec los exige. Plugin CF `multiapps`: verificar con `sap_cf plugins` antes de asumir |
+
+## Cómo proporcionar una especificación
+
+1. Copia `specs/_template.md` a `specs/<nombre-mvp>.md` y rellénala
+   (objetivo, tipo UI5/CAP/MTA, destino BTP, servicios, criterios de
+   aceptación, fuera de alcance).
+2. El destino BTP (endpoint/org/espacio) debe figurar en la spec o
+   confirmarse cuando el orquestador lo pida. Sin destino confirmado no hay
+   despliegue.
+
+## Cómo iniciar el flujo
+
+```
+/flow specs/<nombre-mvp>.md
+```
+
+El orquestador ejecuta las etapas 0–10 de `AGENTS.md` (evaluación,
+investigación, plan, preparación, desarrollo, pruebas, correcciones,
+revisión de despliegue, despliegue, Git, documentación) con rigor
+proporcional al tamaño del MVP. Comando de apoyo:
+
+```
+/verify   — puerta de despliegue: re-verifica target, artefacto y criterios
+            sin desplegar
+```
+
+## Comandos locales de referencia
+
+```
+sap_cf target            # endpoint/org/espacio actuales (sin secretos)
+sap_cf apps              # estado observable tras desplegar
+sap_cf logs <app> --recent
+mbt build                # genera .mtar en mta_archives/ (requiere mta.yaml)
+```
+
+Nunca `cf ...` para Foundry. Nunca pegar tokens en terminal ni en specs.
+
+## Lecturas CF seguras (broker cf-safe)
+
+Toda lectura CF con secreto potencial vía `scripts/cf-safe.ps1`
+(nunca `sap_cf` directo en agentes/scripts si la salida puede traer
+credenciales). Detalle: `docs/cf-safe.md`.
+
+## Skills candidatas (no instaladas)
+
+Inspeccionadas solo por procedencia; adoptar **únicamente** si
+una spec las necesita, revisando antes su alcance y scripts de instalación:
+
+- `sap-cap-capire` (sap-ai-skills.com) — CAP/CDS.
+- `sap-btp-developer-guide` (secondsky) — fundamentos BTP/CAP.
+- AI Skills Library (`skills.cloud.sap`, SAP SE) — CF CLI v8 y despliegue.
+- Repositorio `secondsky/sap-skills` — BTP, CAP, Fiori, ABAP.
+
+La skill global `sapui5` ya cubre frontend UI5/Fiori y tiene preferencia.

package/AI/docs/cf-safe.md

@@ -0,0 +1,107 @@
+# cf-safe — broker determinista para Cloud Foundry
+
+Punto único de salida hacia `sap_cf`. Fail-closed: nada ejecuta sin pasar
+denylist → allowlist → validación de target.
+
+Fuentes: `scripts/cf-safe.ps1` (cabecera, líneas 1-34), `scripts/cf-safe-patterns.ps1`,
+`scripts/cf-safe-client.ps1`, `scripts/pre-commit-check.ps1`;
+integración: `doc-extract-lab/scripts/provision-prd.ps1` (líneas 46-50).
+Estado QA citado según brief del turno (no re-ejecutado aquí por restricción
+de no-ejecución de este turno de documentación): sintaxis 5/5, WhatIf/DENY 7/7,
+redacción 24/24. Sin E2E real contra CF todavía (pendiente).
+
+## Qué es
+
+- `scripts/cf-safe.ps1`: broker. Recibe `-CfArgs`, valida, ejecuta solo
+  `sap_cf` (`sap_cf.cmd`, ruta fija) y devuelve UNA línea JSON
+  `{ok, exit, verb, redacted, rawLog, names, output}`.
+- `scripts/cf-safe-patterns.ps1`: tabla central de redacción (6 regex +
+  marcador `***REDACTED***`, fail-closed: ante error devuelve el marcador,
+  nunca el original). Patrón de referencia: `doc-extract-lab/srv/lib/die-client.js`
+  (`redactDieSecrets`).
+- `scripts/cf-safe-client.ps1`: cliente para scripts de provisión
+  (`Invoke-SapCfSeguro`; `New-TempServiceKey` es esqueleto BLOQUEADO,
+  sin efecto en este turno).
+- `scripts/pre-commit-check.ps1`: chequeo pre-commit, bloquea secretos fuera
+  de `temp/` (whitelist: líneas con `***REDACTED***`).
+
+## Por qué (sin LLM ejecutor)
+
+Ningún agente/LLM invoca `sap_cf` directamente para lecturas con secreto
+potencial: el broker aplica las reglas de forma determinista (código, no
+criterio del modelo). El LLM solo recibe `output` ya redactado y truncado;
+el crudo nunca llega a stdout ni a prompts.
+
+## Uso
+
+Lectura (sin flags):
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts/cf-safe.ps1 -CfArgs @('services')
+# Formas equivalentes (sin comas ni @() bajo -File):
+powershell -ExecutionPolicy Bypass -File scripts/cf-safe.ps1 -CfArgs services
+powershell -ExecutionPolicy Bypass -File scripts/cf-safe.ps1 services
+```
+
+Simulación sin ejecutar (omite validación de target):
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts/cf-safe.ps1 -CfArgs @('services') -WhatIf
+```
+
+Desde un script de provisión (vía cliente, solo nombres, cero secretos):
+
+```powershell
+. (Join-Path $PSScriptRoot '..\..\scripts\cf-safe-client.ps1')
+Invoke-SapCfSeguro -CfArgs @('services') -ExpectedApi 'https://api.cf.us10-001.hana.ondemand.com'
+```
+
+Regla: **toda lectura CF con secreto potencial vía cf-safe** (nunca
+`sap_cf` directo en agentes/scripts cuando la salida pueda traer
+credenciales: `env`, `service-key` con valores, `logs --recent`).
+
+## Allowlist / denylist y códigos
+
+Orden: 1) binario fijo (`cf` de Cloudflare se rechaza) → 2) denylist →
+3) allowlist → 4) target → 5) ejecución.
+
+- Denylist (exit 1): `delete-*`, `unbind-*`, `purge-*`, `restage-*`,
+  `set-env` sin `-AllowWrite`, `create-service-key` directo,
+  `service-key` con valores sin `-NeedValues` (y sin `-AllowWrite`),
+  inyección (`|`, `>`, `;`, backtick, `$()`).
+- Allowlist lectura (sin flags): `target`, `apps`, `app`, `services`,
+  `service`, `marketplace`, `spaces`, `space-users`, `service-keys`
+  (solo nombres), `env` (redactado), `logs --recent` (redactado,
+  200 líneas), `plugins`.
+- Allowlist escritura (SOLO con `-AllowWrite`): `create-space`,
+  `create-service`, `set-space-role`, `target -o/-s`, `set-env`,
+  `service-key` con valores (exige además `-NeedValues`).
+- Códigos: `0` ok / `1` deny-denylist / `2` fuera-de-allowlist /
+  `3` validación-target (endpoint/org no coinciden; `ExpectedOrg` vacío
+  = no valida org) / `4` error-ejecución.
+
+## Dónde van los crudos
+
+- `output` (stdout JSON): redactado y truncado a 4000 caracteres.
+- Crudo SOLO en `temp/cf-safe/*.raw.log`, nunca a stdout.
+- `temp/` está ignorado (artefactos transitorios) y `pre-commit-check.ps1`
+  ignora todo bajo `temp/`; fuera de `temp/`, cualquier señal de secreto
+  sin `***REDACTED***` bloquea el commit (exit 1).
+
+## Integración provision y /verify
+
+- `doc-extract-lab/scripts/provision-prd.ps1` importa
+  `scripts/cf-safe-client.ps1`: todas sus llamadas CF pasan por
+  `Invoke-SapCfSeguro` (denylist primero). Allowlist del provision cerrada
+  (ver `AGENTS.md` § Paisajes); `New-TempServiceKey` sigue esqueleto
+  bloqueado hasta diseño final de keys temporales.
+- `/verify`: el broker valida `ExpectedApi`
+  (default `https://api.cf.us10-001.hana.ondemand.com`) y `ExpectedOrg`
+  antes de ejecutar; con `-WhatIf` la validación se omite (solo simulación).
+
+## Pendientes
+
+- [ ] E2E real contra CF (veredicto con evidencia, sin secretos en repo).
+- [ ] Instalación del hook pre-commit (`git config core.hooksPath .githooks`;
+      copiar `pre-commit-check.ps1` a `.githooks/pre-commit`).
+- [ ] Pasar PSScriptAnalyzer a los 4 scripts.

package/AI/docs/flujo-etapas.md

@@ -0,0 +1,22 @@
+# Flujo por etapas — entregables y criterios de avance
+
+> Referencia única del ciclo. `AGENTS.md` manda; este documento lo detalla.
+> El progreso de cada MVP se registra en su spec (§6) y en su informe de cierre.
+
+| Etapa | Nombre | Ejecuta | Entregable verificable | Criterio de avance |
+|---|---|---|---|---|
+| 0 | Evaluación | `analyst` | Veredicto + supuestos + CA verificables | Spec completable; bloqueos con dato mínimo pedido |
+| 1 | Investigación | `researcher` | Tabla fuente\|fecha\|evidencia (documentado/pendiente/coste) | Ninguna API/servicio supuesto sin fuente |
+| 2 | Plan/Arquitectura | `architect` | Topología + esqueleto `mta.yaml` + planes verificados | Decisiones y descartes registrados; persistencia fijada |
+| 3 | Preparación | orquestador | Scaffold + facets + deps instaladas + target CF confirmado | `cds version` OK; `sap_cf target` coincide con spec |
+| 4 | Desarrollo | `backend-cap` + `frontend-ui5` | Modelo/servicios CAP + UI + mocks DIE/iFlow corriendo en local | CA1–CA3 observables con `cds watch` |
+| 5 | Pruebas | `qa-review` | Resultado por CA (comando + salida real) | Sin rojo; vulnerabilidades del scaffold dictaminadas |
+| 6 | Correcciones | especialistas | Fixes verificados | Plan de pruebas en verde |
+| 7 | Revisión despliegue | `/verify` | Veredicto apto/no apto (target + artefacto + CA + Git limpio) | Solo "apto" permite etapa 8 |
+| 8 | Despliegue | `deploy-cf` | Apps `started` + logs + evidencia (cockpit/URL) | CA4–CA5 con evidencia observable |
+| 9 | Git | orquestador | Commits locales; remoto solo con autorización expresa | Sin secretos en diff; push/PR solo si la spec lo pide |
+| 10 | Documentación | `documentarian` | Spec, inventario e informe de cierre al día | Hechos con fuente; pendientes marcados |
+
+Rigor proporcional: en MVPs pequeños se pueden aligerar 5 (pruebas manuales
+guiadas por CA) y diferir 9; nunca se saltan 0, 2, 7 ni 8. Paralelo solo en
+tareas independientes; el orquestador integra y revisa todo cambio.

package/AI/docs/habilitacion-trial.md

@@ -0,0 +1,167 @@
+# Habilitación del trial — guía ordenada con justificación
+
+> Paso a paso de todo lo configurado para el laboratorio `doc-extract-lab`
+> el 2026-10-29. Cada sección explica **para qué sirve**, **cómo se
+> configuró**, **casos de uso** y **cuándo usarlo**. Orden cronológico real
+> de ejecución: seguirlo en este orden evita los errores que encontramos
+> (p. ej. suscribir Document AI antes de tener IAS falla con `422`).
+
+## Paso 0. Verificar el entorno Cloud Foundry (lectura, sin cambios)
+
+- **Para qué sirve.** Confirma contra qué org/espacio desplegará el MTA.
+- **Cómo.** En el equipo local: `sap_cf target` (endpoint, org, espacio).
+- **Casos de uso / cuándo.** Antes de cada despliegue y siempre que el
+  cockpit muestre un espacio con otro nombre (aquí: cockpit `dev` frente a
+  la sesión local). Si no coinciden, se ajusta el target en la puerta de
+  despliegue; nunca se despliega "a ver qué pasa".
+
+## Paso 1. Instancia HTML5 Application Repository (`HTML5_service`)
+
+- **Para qué sirve.** Repositorio central de frontends HTML5 del espacio CF:
+  versiona los bundles UI5, los sirve con caché y rutas estables, y los
+  publica en la sección **HTML5 Applications** del cockpit.
+- **Cómo se configuró.** Subcuenta `trial` → Services → Service Marketplace
+  → `HTML5 Application Repository Service` → Create → Plan **`app-host`** →
+  Runtime **Cloud Foundry** → Space **`dev`** → nombre `HTML5_service`.
+- **Casos de uso.** Cualquier frontend Fiori/UI5 que deba vivir en el
+  cockpit y servirse vía App Router.
+- **Cuándo usarlo.** Siempre que la app tenga UI propia (este MVP: CA5). Si
+  el MVP fuera solo API, se omite.
+
+## Paso 2. Instancia XSUAA (`XSUAA_service`)
+
+- **Para qué sirve.** Broker OAuth2 propio de la aplicación: emite los JWT
+  con que el App Router crea la sesión de usuario y que el backend CAP
+  valida (`xsappname`, scopes).
+- **Cómo se configuró.** Service Marketplace → `Authorization and Trust
+  Management Service` → Create → Plan **`application`** → CF → `dev` →
+  nombre `XSUAA_service`.
+- **Por qué `application`.** `broker` es para multi-tenant con tenant
+  dinámico, `apiaccess` para API sin sesión de usuario, `space` delega en el
+  espacio: ninguno sirve al App Router gestionado.
+- **Casos de uso / cuándo.** Toda app con login de usuarios o propagación de
+  identidad al backend. Se omite solo en MVPs 100 % anónimos o batch.
+
+## Paso 3. Instancia Document AI (`DAI_service`)
+
+- **Para qué sirve.** API REST de extracción de datos desde documentos
+  (PDF, imágenes): recibe el archivo y devuelve JSON con los campos del
+  esquema entrenado.
+- **Cómo se configuró.** Service Marketplace → `SAP Document AI Trial` →
+  Create → Plan **`default`** (gratuito del trial) → CF → `dev` → nombre
+  `DAI_service`. Estado final: `Usable`.
+- **Por qué `default` y no `blocks_of_100`.** `blocks_of_100` consume
+  créditos de la cuenta; `default` respeta la restricción "solo trial".
+- **Casos de uso.** Facturas, remitos, formularios: cualquier documento
+  semiestructurado del que haya que extraer campos.
+- **Cuándo usarlo.** Cuando el volumen o la variabilidad de documentos hacen
+  inviable la carga manual o plantillas fijas.
+
+## Paso 4. Suscripción a la app `SAP Document AI`
+
+- **Para qué sirve.** UI de gestión: crear/entrenar esquemas de extracción y
+  probar con documentos de ejemplo. La **instancia** (paso 3) da la API; la
+  **suscripción** da la consola.
+- **Cómo se configuró.** Service Marketplace → `SAP Document AI` →
+  suscripción directa (plan `default`). **Falló al inicio** con `422 OIDC
+  trust missing` porque no existía tenant IAS → se resolvió tras los pasos
+  6–7 y reintento.
+- **Casos de uso / cuándo.** Siempre que se usen esquemas propios o haya que
+  inspeccionar resultados fuera del código. Si solo se consume un esquema
+  estándar vía API, es opcional.
+
+## Paso 5. Suscripción a Integration Suite (plan `trial`)
+
+- **Para qué sirve.** Plataforma de integración: aquí vive el iFlow que
+  recibe el JSON extraído y simula la entrega al S/4HANA inexistente.
+- **Cómo se configuró.** Service Marketplace → `Integration Suite` → plan
+  **`trial`** → suscribir. Estado final: `Subscribed`.
+- **Casos de uso.** Conectar el MVP con sistemas SAP/no-SAP, transformar
+  mensajes, exponer APIs gestionadas.
+- **Cuándo usarlo.** Cuando el flujo sale del BTP hacia otro sistema. Si el
+  MVP fuera autocontenido, se omite (o se deja como mock documentado).
+
+## Paso 6. Suscripción a Cloud Identity Services (tenant IAS)
+
+- **Para qué sirve.** Crea el **tenant IAS propio** de la subcuenta: el
+  proveedor de identidad de los usuarios de negocio (login, grupos,
+  federación). Sin él, ninguna suscripción a aplicación con login funciona.
+- **Cómo se configuró.** Service Marketplace → `Cloud Identity Services` →
+  Create → Plan **`default` de la sección Subscriptions**
+  (`sap-identity-services-onboarding`, NO `application` de Instances) →
+  parámetro **Service type: `TEST`** → Create → **activar la cuenta con el
+  email** que llega al admin (definir contraseña) → consola admin abierta.
+- **Casos de uso.** Login de usuarios en Fiori, Work Zone y cualquier app
+  suscrita; base para federar con un IdP corporativo más adelante.
+- **Cuándo usarlo.** Antes de suscribir la primera aplicación con usuarios
+  (paso 7). Es prerrequisito, no opcional.
+
+## Paso 7. Establecer confianza (Establish Trust) y reintentar
+
+- **Para qué sirve.** Vincula la subcuenta con el tenant IAS vía **OpenID
+  Connect**, para que las apps deleguen el login en él. (SAML no vale para
+  Document AI.)
+- **Cómo.** Subcuenta → Security → Trust Configuration → **Establish
+  Trust** → Choose Tenant: ya aparece el tenant creado en el paso 6 →
+  completar el wizard → luego Instances and Subscriptions → `SAP Document
+  AI` → `...` → **Retry** hasta `Subscribed`.
+- **Cuándo.** Una vez por subcuenta, tras el paso 6 y antes de usar
+  cualquier app suscrita.
+- **Estado 2026-10-29: resuelto.** Trust `Active` (origen `sap.custom`,
+  dominio `Default`); suscripción `SAP Document AI` en `Subscribed`.
+
+## Concepto clave: usuarios de plataforma frente a usuarios de negocio
+
+El trial te da un **usuario de plataforma** (tu login, p. ej. el `HM` del
+cockpit): administra la cuenta global —cockpit, `sap_cf`, crear
+instancias— autenticado por el IdP por defecto de SAP. Ese usuario **no**
+sirve para entrar a las aplicaciones desplegadas.
+
+Los **usuarios de negocio** son quienes usan las apps (consola de Document
+AI, tu Fiori vía App Router): se autentican contra un **tenant IAS** en el
+que la subcuenta confía (pasos 6–7). Por eso hizo falta crear el tenant
+aunque ya tuvieras usuario: son dos poblaciones distintas con dos IdP
+distintos.
+
+**Cuándo es pertinente crear el tenant IAS y la confianza:**
+
+- Siempre que suscribas una **aplicación con login** (Document AI,
+  Work Zone, cualquier SaaS del marketplace).
+- Siempre que tu app propia autentique usuarios (App Router + XSUAA con
+  `application` delega el login en este trust).
+- Cuando necesites **roles y grupos de negocio** separados de los
+  administradores de plataforma.
+- En productiva, además: para **federar tu IdP corporativo** (Azure AD,
+  etc.) como fuente de usuarios sin crearlos uno a uno.
+
+**Cuándo NO hace falta:** MVPs de solo API con llaves de servicio, jobs
+batch sin usuarios, o pruebas de conectividad máquina a máquina — ahí basta
+con instancias y service keys.
+
+## Paso 8 (siguiente, aún no hecho). Role collections del usuario
+
+- **Para qué sirve.** Autorizar a tu usuario en cada servicio (DIE,
+  Integration Suite, HTML5 Repo): sin roles, el acceso da 403 aunque todo lo
+  anterior esté verde.
+- **Cómo (cuando toque).** Subcuenta → Security → Users → tu usuario →
+  asignar las role collections de cada servicio; o crear role collections a
+  medida. Se hará durante el `/flow` si algún acceso falla.
+- **Cuándo.** Después del despliegue o al primer 403.
+- **Incidencia 2026-10-29 (Integration Suite):** `Go to Application`
+  devuelve página en blanco `.../is-landing/v1.0/unauthorized` → falta
+  asignar `Integration_Provisioner` al usuario antes de `Add Capabilities`.
+  Si persiste tras asignarlo: (1) esperar 5–10 min por propagación y
+  reentrar en incógnito (token viejo en caché); (2) asignar el rol al
+  usuario de origen `sap.custom` (IAS), no solo al `sap.default` — la app
+  autentica contra el trust IAS; (3) comprobar que el usuario exista en la
+  consola IAS.
+
+## Mapa rápido decisión
+
+| Mi MVP necesita… | Habilitar |
+|---|---|
+| UI Fiori en el cockpit | Pasos 0, 1 (+ 2 para login) |
+| Login / identidad propagada | Pasos 2, 6, 7 |
+| Extraer datos de documentos | Pasos 3 (+ 4 para consola) |
+| Salir hacia otro sistema | Paso 5 |
+| Solo API sin UI ni usuarios | Solo 0 (+ 3/5 según el caso) |

package/AI/opencode.fragment.jsonc

@@ -0,0 +1,17 @@
+// Fragmento MCP para el proyecto destino. Fusionar en su `opencode.jsonc`.
+// `graphify-code` viene DESHABILITADO por defecto: el índice vive en el
+// proyecto (`AI/graphify-out/graph.json`, ruta relativa) y debe generarse
+// tras instalar. Para activarlo:
+//   1. Generar el índice del proyecto en `AI/graphify-out/graph.json`.
+//   2. Poner `"enabled": true` en el bloque `graphify-code`.
+//   3. Reiniciar OpenCode.
+{
+  "mcp": {
+    "graphify-code": {
+      "type": "local",
+      "command": ["graphify-mcp", "--graph", "AI/graphify-out/graph.json"],
+      "cwd": ".",
+      "enabled": false
+    }
+  }
+}