pumuki 6.3.13 → 6.3.14

package/docs/MCP_SERVERS.md

@@ -1,114 +1,207 @@
 # MCP Servers (v2.x)
 
-This repository currently exposes a single active MCP-oriented server implementation:
+Pumuki expone dos servidores MCP HTTP opcionales:
 
-- **Evidence Context Server** (read-only)
+- `pumuki-mcp-evidence`: API read-only para `.ai_evidence.json`.
+- `pumuki-mcp-enterprise`: superficie enterprise consolidada (resources + tools) con guardrails fail-safe.
 
-## Evidence Context Server
+El enforcement de gates (`pre-commit`, `pre-push`, `ci`) no depende de MCP.
 
-### Source files
+## Arranque rápido
+
+### Desde el repositorio framework
+
+```bash
+npm run mcp:evidence
+npm run mcp:enterprise
+```
+
+### Desde un repositorio consumidor
+
+```bash
+npx --yes pumuki-mcp-evidence
+npx --yes pumuki-mcp-enterprise
+```
+
+## 1) Evidence Context Server (`pumuki-mcp-evidence`)
+
+### Implementación
 
 - `integrations/mcp/evidenceContextServer.ts`
 - `integrations/mcp/evidenceContextServer.cli.ts`
-- `integrations/mcp/index.ts`
 
 ### Purpose
 
-Expose deterministic evidence (`.ai_evidence.json`) to external agents without allowing writes.
+Exponer evidencia v2.1 de forma determinista y solo lectura.
 
-### Contract
+### Configuración runtime
 
-- Serves evidence only when file exists and `version === "2.1"`.
-- Returns deterministic JSON payload from local repo root.
+- Host default: `127.0.0.1`
+- Port default: `7341`
+- Route default: `/ai-evidence`
 
-### Default runtime
+Variables de entorno:
 
-- Host: `127.0.0.1`
-- Port: `7341`
-- Route: `/ai-evidence`
+- `PUMUKI_EVIDENCE_HOST`
+- `PUMUKI_EVIDENCE_PORT`
+- `PUMUKI_EVIDENCE_ROUTE`
 
 ### Endpoints
 
 - `GET /health`
-  - `200 { "status": "ok" }`
 - `GET /status`
-  - `200` with evidence health summary and `context_api` filter/pagination capabilities (including `present`, `valid`, `version`, `stage`, `outcome`, `has_findings`, `tracked_platforms_count`, `detected_platforms_count`, `non_detected_platforms_count`, `suppressed_findings_count`, `suppressed_replacement_rule_platform_pairs_ratio_pct`, `suppressed_non_replacement_rule_platform_pairs_ratio_pct`, and related suppression facets)
-- `GET /ai-evidence`
-  - `200` with evidence payload when valid
-  - `404` when missing or invalid
-- `GET /ai-evidence/summary`
-  - `200` with compact deterministic summary (including `snapshot.has_findings`, `snapshot.findings_files_count`, `snapshot.findings_rules_count`, `snapshot.findings_with_lines_count`, `snapshot.findings_without_lines_count`, `snapshot.severity_counts`, `snapshot.findings_by_platform`, `snapshot.highest_severity`, `snapshot.blocking_findings_count`, `ledger_count`, `ledger_files_count`, `ledger_rules_count`, `ledger_by_platform`, `rulesets_count`, `rulesets_platforms_count`, `rulesets_bundles_count`, `rulesets_hashes_count`, `rulesets_by_platform`, `rulesets_fingerprint`, `platform_confidence_counts`, `suppressed_findings_count`, `suppressed_replacement_rules_count`, `suppressed_platforms_count`, `suppressed_files_count`, `suppressed_rules_count`, `tracked_platforms_count`, `detected_platforms_count`, `non_detected_platforms_count`, `suppressed_replacement_rule_platform_pairs_ratio_pct`, `suppressed_non_replacement_rule_platform_pairs_ratio_pct`)
-  - `404` when missing or invalid
-- `GET /ai-evidence/snapshot`
-  - `200` with deterministic snapshot + findings
-  - `404` when missing or invalid
-- `GET /ai-evidence/findings`
-  - `200` with deterministic findings list
-  - supports `?severity=...&ruleId=...&platform=...`
-  - supports `?limit=...&offset=...` for deterministic pagination
-  - applies deterministic `maxLimit=100` bound
-  - paginated responses include `pagination.has_more`
-  - `404` when missing or invalid
-- `GET /ai-evidence/rulesets`
-  - `200` with deterministic sorted rulesets
-  - supports `?platform=...&bundle=...` for deterministic filtered slices
-  - supports `?limit=...&offset=...` for deterministic pagination (`maxLimit=100`)
-  - paginated responses include `pagination.has_more`
-  - `404` when missing or invalid
-- `GET /ai-evidence/platforms`
-  - `200` with detected platforms only
-  - supports `?detectedOnly=false` for full platform state
-  - supports `?confidence=HIGH|MEDIUM|LOW` for deterministic filtered slices
-  - supports `?limit=...&offset=...` for deterministic pagination (`maxLimit=100`)
-  - paginated responses include `pagination.has_more`
-  - `404` when missing or invalid
-- `GET /ai-evidence/ledger`
-  - `200` with deterministic sorted open-ledger entries
-  - supports `?lastSeenAfter=...&lastSeenBefore=...` for deterministic time-window slices
-  - supports `?limit=...&offset=...` for deterministic pagination (`maxLimit=100`)
-  - paginated responses include `pagination.has_more`
-  - `404` when missing or invalid
-
-### Run locally
+- `GET /<route>` (default: `/ai-evidence`)
+- `GET /<route>/summary`
+- `GET /<route>/snapshot`
+- `GET /<route>/findings`
+- `GET /<route>/rulesets`
+- `GET /<route>/platforms`
+- `GET /<route>/ledger`
 
-```bash
-npm run mcp:evidence
-```
+Comportamiento:
 
-Or directly:
+- Si falta evidencia o no cumple `version = "2.1"`, los endpoints de evidencia devuelven `404`.
+- `findings`, `rulesets`, `platforms` y `ledger` soportan filtrado/paginación deterministas.
 
-```bash
-npx tsx integrations/mcp/evidenceContextServer.cli.ts
+## 2) Enterprise MCP Server (`pumuki-mcp-enterprise`)
+
+### Implementación
+
+- `integrations/mcp/enterpriseServer.ts`
+- `integrations/mcp/enterpriseServer.cli.ts`
+
+### Purpose
+
+Expose enterprise operational state for the active repository:
+
+- estado de evidencia,
+- estado gitflow,
+- estado lifecycle,
+- estado SDD/OpenSpec,
+- toolset legacy-style en modo seguro.
+
+### Configuración runtime
+
+- Host default: `127.0.0.1`
+- Port default: `7391`
+
+Variables de entorno:
+
+- `PUMUKI_ENTERPRISE_MCP_HOST`
+- `PUMUKI_ENTERPRISE_MCP_PORT`
+
+### Endpoints
+
+- `GET /health`
+- `GET /status`
+- `GET /resources`
+- `GET /resource?uri=<resource-uri>`
+- `GET /tools`
+- `POST /tool`
+
+`GET /status` devuelve:
+
+- `capabilities.resources`
+- `capabilities.tools`
+- `capabilities.mode = "baseline"`
+- `lifecycle` (o `null` si no aplica)
+- `sdd` (o `null` si no aplica)
+- `evidence` (status payload)
+
+### Catálogo de resources
+
+- `evidence://status`
+- `gitflow://state`
+- `context://active`
+- `sdd://status`
+- `sdd://active-change`
+
+`GET /resource` responde:
+
+```json
+{
+  "uri": "sdd://status",
+  "payload": {}
+}
 ```
 
-### Environment variables
+URI no soportada devuelve `404`.
 
-- `PUMUKI_EVIDENCE_HOST`
-- `PUMUKI_EVIDENCE_PORT`
-- `PUMUKI_EVIDENCE_ROUTE`
+### Catálogo de tools
 
-Example:
+- `ai_gate_check`
+- `check_sdd_status`
+- `validate_and_fix`
+- `sync_branches`
+- `cleanup_stale_branches`
 
-```bash
-PUMUKI_EVIDENCE_PORT=7342 npm run mcp:evidence
+`GET /tools` incluye metadatos por tool (`name`, `description`, `mutating`, `safeByDefault`).
+
+`POST /tool` acepta:
+
+```json
+{
+  "name": "sync_branches",
+  "dryRun": false,
+  "args": {
+    "stage": "PRE_PUSH"
+  }
+}
+```
+
+`POST /tool` responde siempre con envelope estable:
+
+```json
+{
+  "tool": "sync_branches",
+  "dryRun": true,
+  "executed": false,
+  "success": true,
+  "warnings": [],
+  "result": {}
+}
 ```
 
-## Testing
+### Guardrails enterprise (baseline fail-safe)
+
+- Tools mutating (`validate_and_fix`, `sync_branches`, `cleanup_stale_branches`) fuerzan `dryRun=true` aunque se solicite `dryRun=false`.
+- Tools críticos (`validate_and_fix`, `sync_branches`, `cleanup_stale_branches`) pasan por guardia SDD/session.
+- Si SDD bloquea, `/tool` devuelve `success=false`, `executed=false` y `result.guard.decision`.
+- Errores de ejecución se manejan fail-safe (`success=false`, sin mutaciones).
+
+Códigos SDD frecuentes en bloqueo:
 
-Server behavior is covered in:
+- `OPENSPEC_MISSING`
+- `OPENSPEC_PROJECT_MISSING`
+- `SDD_SESSION_MISSING`
+- `SDD_SESSION_INVALID`
+- `SDD_CHANGE_MISSING`
+- `SDD_CHANGE_ARCHIVED`
+- `SDD_VALIDATION_FAILED`
+- `SDD_VALIDATION_ERROR`
 
-- `integrations/mcp/__tests__/evidenceContextServer.test.ts`
+## Comportamiento HTTP
 
-Run:
+- Endpoint desconocido: `404`
+- Método no permitido: `405`
+- JSON inválido en `POST /tool`: `400`
+- Body inválido en `POST /tool`: `400`
+
+## Validación
+
+Suites MCP:
+
+- `integrations/mcp/__tests__/evidenceContextServer-*.test.ts`
+- `integrations/mcp/__tests__/enterpriseServer.test.ts`
+
+Comando:
 
 ```bash
 npm run test:mcp
 ```
 
-## Scope note
-
-Legacy MCP references (older automation/watcher services) are not part of the active v2.x documentation surface.
-
-Consumption pattern reference:
+## Referencias
 
+- `docs/MCP_EVIDENCE_CONTEXT_SERVER.md`
 - `docs/MCP_AGENT_CONTEXT_CONSUMPTION.md`
+- `docs/evidence-v2.1.md`

package/docs/PUMUKI_FULL_VALIDATION_CHECKLIST.md

@@ -14,6 +14,7 @@ Checklist maestro para validar el ciclo completo de Pumuki de forma secuencial a
 - Cerrar una tarea cada vez.
 - Guardar evidencia de cada tarea (salida de comandos + resultado esperado).
 - Cualquier warning/error detectado durante la ejecución debe corregirse de inmediato antes de continuar.
+- Todas las pruebas de validación de runtime se ejecutan únicamente en `pumuki-mock-consumer` (no en el repo de framework `ast-intelligence-hooks`).
 
 ## Orden de ejecución recomendado
 
@@ -53,13 +54,13 @@ Checklist maestro para validar el ciclo completo de Pumuki de forma secuencial a
 
 ### 3) Lifecycle de Pumuki
 
-- 🚧 3.1 Ejecutar y validar `npx pumuki doctor` tras instalación en baseline limpia.
-- ⏳ 3.2 Ejecutar y validar `npx pumuki status` tras instalación.
-- ⏳ 3.3 Validar `npx pumuki update --latest` (idempotencia y salud de hooks).
-- ⏳ 3.4 Validar `npx pumuki uninstall --purge-artifacts` (solo hooks + artifacts gestionados).
+- ✅ 3.1 Ejecutar y validar `npx pumuki doctor` tras instalación en baseline limpia.
+- ✅ 3.2 Ejecutar y validar `npx pumuki status` tras instalación.
+- ✅ 3.3 Validar `npx pumuki update --latest` (idempotencia y salud de hooks).
+- ✅ 3.4 Validar `npx pumuki uninstall --purge-artifacts` (solo hooks + artifacts gestionados).
 - ✅ 3.5 Validar `npx --yes pumuki remove` (limpieza total de rastro Pumuki sin tocar terceros).
 - ✅ 3.6 Validar idempotencia lifecycle (ciclo install/remove repetido).
-- ⏳ 3.7 Validar guardrail: install/update falla si hay `node_modules` tracked.
+- ✅ 3.7 Validar guardrail: install/update falla si hay `node_modules` tracked.
 
 ### 4) Stage gates runtime
 
@@ -67,65 +68,65 @@ Checklist maestro para validar el ciclo completo de Pumuki de forma secuencial a
 - ✅ 4.2 `pumuki-pre-push` evalúa `upstream..HEAD`.
 - ✅ 4.3 `pumuki-ci` evalúa `baseRef..HEAD` (`GITHUB_BASE_REF` o fallback).
 - ✅ 4.4 Exit codes deterministas (`0` allow, `1` block).
-- ⏳ 4.5 Consistencia entre ejecución directa de binarios y ejecución vía hooks.
+- ✅ 4.5 Consistencia entre ejecución directa de binarios y ejecución vía hooks.
 
 ### 5) Detección multi-plataforma y evaluación combinada
 
-- ⏳ 5.1 Cobertura iOS (`*.swift`) en repos mixtos.
-- ⏳ 5.2 Cobertura backend (`apps/backend/**/*.ts`) en repos mixtos.
-- ⏳ 5.3 Cobertura frontend (`apps/frontend|apps/web`) en repos mixtos.
-- ⏳ 5.4 Cobertura android (`*.kt`, `*.kts`) en repos mixtos.
-- ⏳ 5.5 Commits/rangos multi-plataforma cargan rulesets combinados y salida combinada.
-- ⏳ 5.6 No hay falsos positivos de plataforma fuera de selectores.
+- ✅ 5.1 Cobertura iOS (`*.swift`) en repos mixtos.
+- ✅ 5.2 Cobertura backend (`apps/backend/**/*.ts`) en repos mixtos.
+- ✅ 5.3 Cobertura frontend (`apps/frontend|apps/web`) en repos mixtos.
+- ✅ 5.4 Cobertura android (`*.kt`, `*.kts`) en repos mixtos.
+- ✅ 5.5 Commits/rangos multi-plataforma cargan rulesets combinados y salida combinada.
+- ✅ 5.6 No hay falsos positivos de plataforma fuera de selectores.
 
 ### 6) Rulesets, políticas y overrides
 
-- ⏳ 6.1 Verificar carga de baseline packs:
+- ✅ 6.1 Verificar carga de baseline packs:
   - `iosEnterpriseRuleSet`
   - `backendRuleSet`
   - `frontendRuleSet`
   - `androidRuleSet`
-- ⏳ 6.2 Verificar políticas por stage:
+- ✅ 6.2 Verificar políticas por stage:
   - PRE_COMMIT: block `CRITICAL`, warn `ERROR`
   - PRE_PUSH: block `ERROR`, warn `WARN`
   - CI: block `ERROR`, warn `WARN`
-- ⏳ 6.3 Verificar aplicación de overrides de proyecto.
-- ⏳ 6.4 Verificar enforcement de locked rules sin override explícito permitido.
+- ✅ 6.3 Verificar aplicación de overrides de proyecto.
+- ✅ 6.4 Verificar enforcement de locked rules sin override explícito permitido.
 
 ### 7) Contrato de evidencia v2.1
 
-- ⏳ 7.1 Se genera `.ai_evidence.json` en cada stage.
-- ⏳ 7.2 Campos de esquema válidos (`version`, `snapshot`, `ledger`).
-- ⏳ 7.3 Evidencia incluye plataformas activas y rulesets cargados.
-- ⏳ 7.4 Orden determinista entre ejecuciones equivalentes.
-- ⏳ 7.5 Suppressions/ledger se mantienen estables y machine-readable.
+- ✅ 7.1 Se genera `.ai_evidence.json` en cada stage.
+- ✅ 7.2 Campos de esquema válidos (`version`, `snapshot`, `ledger`).
+- ✅ 7.3 Evidencia incluye plataformas activas y rulesets cargados.
+- ✅ 7.4 Orden determinista entre ejecuciones equivalentes.
+- ✅ 7.5 Suppressions/ledger se mantienen estables y machine-readable.
 
 ### 8) MCP evidence context server
 
-- ⏳ 8.1 Arrancar `pumuki-mcp-evidence` desde contexto de repositorio consumidor.
-- ⏳ 8.2 Validar endpoints/facetas MCP con payload shape válido.
-- ⏳ 8.3 Validar lectura determinista del último `.ai_evidence.json`.
-- ⏳ 8.4 Validar comportamiento cuando falta/corrompe evidencia.
+- ✅ 8.1 Arrancar `pumuki-mcp-evidence` desde contexto de repositorio consumidor.
+- ✅ 8.2 Validar endpoints/facetas MCP con payload shape válido.
+- ✅ 8.3 Validar lectura determinista del último `.ai_evidence.json`.
+- ✅ 8.4 Validar comportamiento cuando falta/corrompe evidencia.
 
 ### 9) UX operativa (framework menu)
 
-- ⏳ 9.1 `npm run framework:menu` abre y ejecuta acciones esperadas.
-- ⏳ 9.2 Acciones mapeadas a lifecycle/gates producen salidas esperadas.
-- ⏳ 9.3 Acciones de reportes generan archivos en rutas esperadas.
+- ✅ 9.1 `npx pumuki-framework` (en repositorio consumidor) abre y ejecuta acciones esperadas.
+- ✅ 9.2 Acciones mapeadas a lifecycle/gates producen salidas esperadas.
+- ✅ 9.3 Acciones de reportes generan archivos en rutas esperadas.
 
 ### 10) Suites deterministas y validaciones
 
 - ✅ 10.1 `npm run typecheck` pasa.
-- ⏳ 10.2 `npm run test` pasa.
-- ⏳ 10.3 `npm run test:deterministic` pasa.
-- ⏳ 10.4 `npm run test:heuristics` pasa.
-- ⏳ 10.5 `npm run test:mcp` pasa.
-- ⏳ 10.6 `npm run test:stage-gates` pasa.
-- ⏳ 10.7 `npm run validation:package-manifest` pasa.
-- ⏳ 10.8 `npm run validation:lifecycle-smoke` pasa.
-- ⏳ 10.9 `npm run validation:package-smoke` pasa.
-- ⏳ 10.10 `npm run validation:package-smoke:minimal` pasa.
-- ⏳ 10.11 `npm run validation:docs-hygiene` pasa.
+- ✅ 10.2 `npm run test` pasa.
+- ✅ 10.3 `npm run test:deterministic` pasa.
+- ✅ 10.4 `npm run test:heuristics` pasa.
+- ✅ 10.5 `npm run test:mcp` pasa.
+- ✅ 10.6 `npm run test:stage-gates` pasa.
+- ✅ 10.7 `npm run validation:package-manifest` pasa.
+- ✅ 10.8 `npm run validation:lifecycle-smoke` pasa.
+- ✅ 10.9 `npm run validation:package-smoke` pasa.
+- ✅ 10.10 `npm run validation:package-smoke:minimal` pasa.
+- ✅ 10.11 `npm run validation:docs-hygiene` pasa.
 
 ### 11) Mock consumer: ciclo funcional completo
 
@@ -133,18 +134,18 @@ Checklist maestro para validar el ciclo completo de Pumuki de forma secuencial a
 - ✅ 11.2 Escenario violations: pre-commit/pre-push/ci => `1` esperado.
 - ✅ 11.3 Escenario mixed: comportamiento determinista combinado.
 - ✅ 11.4 Cleanup lifecycle tras cada escenario deja baseline limpio.
-- ⏳ 11.5 Repetir matriz completa para confirmar repetibilidad exacta.
+- ✅ 11.5 Repetir matriz completa para confirmar repetibilidad exacta.
 
 ### 12) Fallos, recuperación y cierre de release
 
-- ⏳ 12.1 PRE_PUSH sin upstream: guía clara y fallo seguro.
-- ⏳ 12.2 CI sin `GITHUB_BASE_REF`: fallback correcto.
-- ⏳ 12.3 Hook drift: `doctor` detecta y `install/update` restaura.
-- ⏳ 12.4 Mismatch parcial lifecycle: detectado y recuperable.
-- ⏳ 12.5 README/USAGE/INSTALLATION alineados con runtime actual.
+- ✅ 12.1 PRE_PUSH sin upstream: guía clara y fallo seguro.
+- ✅ 12.2 CI sin `GITHUB_BASE_REF`: fallback correcto.
+- ✅ 12.3 Hook drift: `doctor` detecta y `install/update` restaura.
+- ✅ 12.4 Mismatch parcial lifecycle: detectado y recuperable.
+- ✅ 12.5 README/USAGE/INSTALLATION alineados con runtime actual.
 - ✅ 12.6 CHANGELOG incluye cambios visibles para usuario.
 - ✅ 12.7 Release probada en mock desde npm (no ruta local).
-- ⏳ 12.8 Informe final go/no-go con enlaces a artifacts y logs.
+- ✅ 12.8 Informe final go/no-go con enlaces a artifacts y logs.
 
 ## Criterio de salida
 

package/docs/PUMUKI_OPENSPEC_SDD_ROADMAP.md

@@ -0,0 +1,55 @@
+# PUMUKI + OpenSpec SDD Roadmap
+
+## Leyenda
+- ✅ Completada
+- 🚧 En construcción
+- ⏳ Pendiente
+
+## Fase 1 — Núcleo SDD
+- ✅ Implementar módulo `integrations/sdd/` (cliente OpenSpec + policy + sesión SDD).
+- ✅ Añadir comandos `pumuki sdd status|session|validate`.
+- ✅ Definir contrato de salida JSON para decisiones SDD.
+- ✅ Añadir persistencia de sesión SDD por repositorio.
+
+## Fase 2 — Enforcement en Gates
+- ✅ Integrar SDD gate en `PRE_COMMIT`.
+- ✅ Integrar SDD gate en `PRE_PUSH`.
+- ✅ Integrar SDD gate en `CI`.
+- ✅ Integrar enforcement ligero en `pre-write`.
+- ✅ Añadir bypass de emergencia auditado (`PUMUKI_SDD_BYPASS=1`).
+
+## Fase 3 — Lifecycle y Auto-Bootstrap OpenSpec
+- ✅ Extender `pumuki install` para auto-bootstrap OpenSpec.
+- ✅ Extender `pumuki update` para compat/migración OpenSpec.
+- ✅ Extender `pumuki uninstall/remove` para limpieza segura de artefactos gestionados.
+- ✅ Añadir matriz de compatibilidad de versión mínima OpenSpec.
+
+## Fase 4 — MCP Enterprise (Legacy válido + guardrails)
+- ✅ Crear `pumuki-mcp-enterprise`.
+- ✅ Exponer recursos `evidence://status`, `gitflow://state`, `context://active`, `sdd://status`, `sdd://active-change`.
+- ✅ Exponer tools legacy-style con seguridad (`ai_gate_check`, `check_sdd_status`, `validate_and_fix`, `sync_branches`, `cleanup_stale_branches`).
+- ✅ Enforzar gate/session para tools críticas.
+- ✅ Aplicar `dry-run` por defecto en operaciones sensibles.
+
+## Fase 5 — Evidencia, Telemetría y Contratos
+- ✅ Añadir `sdd_metrics` en `.ai_evidence.json`.
+- ✅ Añadir findings `source: "sdd-policy"` en bloqueos SDD.
+- ✅ Garantizar orden determinista de payload/evidencia.
+- ✅ Añadir tests de contrato de esquema SDD + evidencia.
+
+## Fase 6 — QA Técnica en Pumuki
+- ✅ Añadir tests unitarios `integrations/sdd/*`.
+- ✅ Añadir tests unitarios/integración `integrations/mcp-enterprise/*`.
+- ✅ Reforzar tests lifecycle (install/update/remove) con OpenSpec bootstrap.
+- ✅ Revalidar `test:deterministic` + nuevas suites.
+
+## Fase 7 — Documentación y Release
+- ✅ Actualizar `README.md` para SDD obligatorio con OpenSpec.
+- ✅ Actualizar `docs/USAGE.md` (flujo diario y comandos SDD).
+- ✅ Actualizar `docs/INSTALLATION.md` (bootstrap + compat).
+- ✅ Actualizar `docs/MCP_SERVERS.md` (MCP enterprise).
+- ✅ Actualizar `CHANGELOG.md` y preparar release.
+
+## Fase 8 — Cierre Operativo
+- 🚧 Ejecutar checklist final de aceptación enterprise.
+- ⏳ Cerrar fase con evidencia de no regresión.

package/docs/README.md

@@ -55,6 +55,8 @@ Language baseline: active repository documentation is maintained in English.
 - `validation/mock-consumer-integration-runbook.md`
 - `validation/github-support-ticket-template-startup-failure.md`
 - `validation/skills-rollout-consumer-repositories.md`
+- `validation/phase12-go-no-go-report.md`
+- `validation/post-phase12-next-lot-decision.md`
 - `validation/archive/README.md`: historical validation reports.
 
 ## Vendored Codex Skills
@@ -75,6 +77,8 @@ Language baseline: active repository documentation is maintained in English.
 - `RELEASE_NOTES.md`: v2.x release notes and rollout checkpoints.
 - `TODO.md`: active operational work tracking.
 - `REFRACTOR_PROGRESS.md`: linear phase-by-phase status (done/in-progress/pending).
+- `PUMUKI_FULL_VALIDATION_CHECKLIST.md`: sequential full validation matrix for enterprise readiness.
+- `PUMUKI_OPENSPEC_SDD_ROADMAP.md`: phased rollout roadmap for OpenSpec+SDD integration.
 
 ## Root-Level Pointers
 
@@ -83,3 +87,4 @@ Language baseline: active repository documentation is maintained in English.
 - `CHANGELOG.md` (repository root) tracks top-level package changes for the active baseline.
 - `AGENTS.md` (repository root) defines repository execution constraints for coding agents.
 - `CLAUDE.md` (repository root) provides a concise agent profile aligned with repository policies.
+- `PUMUKI.md` (repository root) is the framework-facing manual entrypoint.