gherkin-ai 2.6.3 → 2.6.4

package/README.md

@@ -4,7 +4,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 > **The Closed-Loop Agentic Testing & Orchestration Engine for Full-Stack Applications.**
-> Turn product requirements into verifiable Gherkin specifications, execute dual-stack implementations (React + Java / PHP / .NET / Python), and experiment with self-healing agent loops.
+> Turn product requirements into verifiable Gherkin specifications, execute 15+ multi-stack implementations (React/Vue/Angular + Java / Kotlin / Go / Elixir / PHP / Ruby / Python / .NET / Flutter / React Native, plus gRPC & GraphQL contracts), and experiment with self-healing agent loops.
 > 
 > [![CI](https://github.com/FennerEduardo/gherkin-ai-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/FennerEduardo/gherkin-ai-cli/actions/workflows/ci.yml)
 > [![Coverage Status](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)]()
@@ -15,10 +15,10 @@
 
 While basic AI spec tools only generate text prompts, `gherkin-ai` acts as an **executable contract and verification harness** between Product Intent, AI Agents (Cursor, Antigravity, Claude Code, Windsurf, Copilot), Code Implementation, and CI/CD Quality Gates:
 
-- 🤖 **AI Agent Implementation Orchestration (`ghk implement`)**: Compiles `.ghkgovernance.yaml`, domain contracts (`*.contract.php`, `.ts`, `.py`, `.java`), ADRs, and Gherkin features into a copy-pasteable Master Agent Implementation Prompt.
-- 🐳 **Docker Container Sandbox & Host Protection (`--docker`)**: Generates stack-specific dev container environments (`mcr.microsoft.com/dotnet/sdk:8.0`, `eclipse-temurin:21-jdk-alpine`, `php:8.3-cli-alpine`, `python:3.11-slim`, `node:20-alpine`, `golang:1.22-alpine`, `ruby:3.3-alpine`) so AI agents run tests inside isolated Docker containers without polluting host OS.
+- 🤖 **AI Agent Implementation Orchestration (`ghk implement`)**: Compiles `.ghkgovernance.yaml`, domain contracts (`*.contract.php`, `.ts`, `.py`, `.java`, `.go`, `.ex`, `.kt`, `.proto`, `.graphql`), ADRs, and Gherkin features into a copy-pasteable Master Agent Implementation Prompt.
+- 🐳 **Docker Container Sandbox & Host Protection (`--docker`)**: Generates stack-specific dev container environments (`mcr.microsoft.com/dotnet/sdk`, `eclipse-temurin:21`, `elixir:1.16`, `golang:1.22`, `php:8.3`, `python:3.12`, `ruby:3.3`, `node:20`) so AI agents run tests inside isolated Docker containers without polluting host OS.
 - 📋 **Feature Inventory & Developer Audit Trail (`ghk audit`)**: Auto-detects developer identity (`git config user.name`/`email`), SHA-256 spec & prompt hashes, timestamps, and execution records stored in `.ghe/inventory.json` with LRU retention limit (`maxEntries: 50`) and `--json` export for CI/CD audit pipelines.
-- ⚡ **Token Efficiency & Ultra-Compact Mode (`-C, --compact`)**: Uses direct `@` file pointers for on-demand context resolution (70–85% token savings vs code dumping) and provides a dense ~90-token compact prompt mode for cost-sensitive LLMs.
+- ⚡ **Token Efficiency & Ultra-Compact Mode (`-C, --compact`)**: Uses direct `@` context pointers (`@.ghkgovernance.yaml`, `@features/*.feature`) for on-demand resolution to radically reduce token footprint vs. code dumping, providing an ultra-compact prompt mode for cost-sensitive LLMs.
 - 🌐 **Multilingual CLI & English Prompt Rationale (`ghk lang`)**: Full interactive CLI support in Spanish (`es`) and English (`en`). Master AI Prompts are intentionally generated in **English** for maximum BPE token density (~30% cheaper) and LLM reasoning accuracy.
 - 🤖 **True Agentic Engine & Self-Healing (EXPERIMENTAL - `ghk verify --auto-fix` & `ghk autopilot`)**: Connects natively with LLMs (OpenAI, Anthropic, Ollama), modifies source code, intercepts test failures, and recursively applies repairs in a true **Closed-Loop**. *Note: Agentic execution is currently experimental and should be run with human supervision.*
 - 🌐 **Web Studio UI (`ghk web`)**: Launch a premium local graphical interface to interactively generate your Gherkin specifications, detect your stack, and orchestrate agent prompts visually.
@@ -41,11 +41,11 @@ npx -y gherkin-ai implement --feature ./features/01-customer-management.feature
 ## 🚀 Quick Start Commands
 
 ```bash
-# 1. Generate Master AI Agent Implementation Prompt & Context Package
-ghk implement --feature ./features/01-customer-management.feature
+# 1. Initialize Stack Architecture (Supports 14+ Stacks)
+ghk init --stack=java-springboot_vue-pinia
 
-# 2. Generate Ultra-Compact Prompt for Low-Cost LLMs (~90 tokens)
-ghk implement --feature ./features/01-customer-management.feature --compact
+# 2. Generate Master Agent Implementation Prompt (Docker Sandbox & Compact Mode)
+ghk implement --docker -C --feature ./features/01-customer-management.feature --contract ./contracts/customer.contract.java
 
 # 3. View Feature Inventory & Developer Audit Trail History
 ghk audit
@@ -54,16 +54,17 @@ ghk audit
 ghk audit --json
 
 # 5. Configure CLI Language (English or Spanish)
-ghk lang --set es
+ghk lang --set en
 
 # 6. Run Closed-Loop Test Verification with Auto-Fix Loop
-ghk verify --auto-fix
+ghk verify --docker --auto-fix
 ```
 
 ---
 
 ## 📖 Comprehensive Documentation
 
+- [Multi-Stack Evaluation Report (15 Projects)](docs/EVALUATION_REPORT.md)
 - [CLI Commands Reference Guide](docs/COMMANDS.md)
 - [Model Context Protocol (MCP) Integration Guide](docs/MCP_GUIDE.md)
 - [Closed-Loop Verification & Auto-Repair Guide](docs/USAGE_GUIDE.md)

package/docs/COMMANDS.md

@@ -7,7 +7,7 @@ This document provides a comprehensive list of all commands available in the `gh
 ## 🤖 Agent Orchestration & Implementation
 
 ### `ghk implement` (alias: `impl`)
-Generate the **AI Agent Master Implementation Prompt & Context Package** for a feature. This command compiles `.ghkgovernance.yaml`, domain contracts (`*.contract.php`, `.ts`, `.py`, `.java`), ADRs, OpenAPI specs, and docker-compose configurations into an executable AI agent package saved at `generated-specs/prompts/implement-master-prompt.md`.
+Generate the **AI Agent Master Implementation Prompt & Context Package** for a feature. This command compiles `.ghkgovernance.yaml`, domain contracts (`*.contract.php`, `.ts`, `.py`, `.java`, `.go`, `.ex`, `.kt`, `.proto`, `.graphql`), ADRs, OpenAPI specs, and docker-compose configurations into an executable AI agent package saved at `generated-specs/prompts/implement-master-prompt.md`.
 
 - `-f, --feature <file>`: Path to Gherkin `.feature` file (auto-selects first feature if omitted).
 - `--docker`: Include Docker container sandbox execution instructions in the master prompt.
@@ -65,11 +65,13 @@ ghk lang --set es
 | :--- | :--- | :--- |
 | **C# / .NET** | `mcr.microsoft.com/dotnet/sdk:8.0` | `docker compose run --rm app dotnet test` |
 | **Java / Spring Boot** | `eclipse-temurin:21-jdk-alpine` | `docker compose run --rm app ./gradlew test` |
-| **PHP** | `php:8.3-cli-alpine` | `docker compose run --rm app vendor/bin/phpunit` |
-| **Python** | `python:3.11-slim` | `docker compose run --rm app pytest` |
+| **Kotlin / Spring Boot**| `eclipse-temurin:21-jdk-alpine` | `docker compose run --rm app ./gradlew test` |
+| **PHP / Laravel** | `php:8.3-cli-alpine` | `docker compose run --rm app vendor/bin/phpunit` |
+| **Python / Django** | `python:3.12-alpine` | `docker compose run --rm app pytest` |
 | **Node / TypeScript** | `node:20-alpine` | `docker compose run --rm app npm test` |
-| **Go** | `golang:1.22-alpine` | `docker compose run --rm app go test ./...` |
-| **Ruby** | `ruby:3.3-alpine` | `docker compose run --rm app bundle exec rspec` |
+| **Go / chi** | `golang:1.22-alpine` | `docker compose run --rm app go test -race ./...` |
+| **Ruby / Rails** | `ruby:3.3-alpine` | `docker compose run --rm app bundle exec rspec` |
+| **Elixir / Phoenix** | `elixir:1.16-alpine` | `docker compose run --rm app mix test` |
 
 ---
 

package/docs/EVALUATION_REPORT.md

@@ -0,0 +1,91 @@
+# Multi-Stack Evaluation Report & GitHub Repositories — `gherkin-ai` v2.6.3
+
+**GitHub User:** `FennerEduardo`  
+**Total Evaluated & Published Projects:** 15 Repositories  
+**Frozen CLI Version:** `gherkin-ai` v2.6.3 (WSL / Windows)  
+
+---
+
+## 1. Consolidated Matrix with GitHub Repositories
+
+| Phase / ID | Project Name / Stack | GitHub Repository | Rubric Average | `ghk verify` Status |
+|---|---|---|:---:|:---:|
+| **Phase 0** | Baseline .NET 8 / C# Angular | [transactional-system](https://github.com/FennerEduardo/transactional-system) | **9.7 / 10** | ✅ PASSED |
+| **Phase 1 (TS-01)** | Java 21 Spring Boot + Vue 3 Pinia | [ts01-java-springboot-vue](https://github.com/FennerEduardo/ts01-java-springboot-vue) | **9.5 / 10** | ✅ PASSED |
+| **Phase 2 (TS-02)** | NestJS 10 + Next.js 14 App Router | [ts02-nestjs-react-nextjs](https://github.com/FennerEduardo/ts02-nestjs-react-nextjs) | **9.3 / 10** | ✅ PASSED |
+| **Phase 3 (TS-03)** | .NET 8 + Angular 17 Signals | [ts03-dotnet-angular](https://github.com/FennerEduardo/ts03-dotnet-angular) | **9.7 / 10** | ✅ PASSED |
+| **Phase 4 (API-03)** | Python 3.12 Django DRF + React | [ts04-django-react-auth](https://github.com/FennerEduardo/ts04-django-react-auth) | **9.2 / 10** | ✅ PASSED |
+| **Phase 5 (API-04)** | Express.js 4 + Angular 17 | [ts05-express-angular-auth](https://github.com/FennerEduardo/ts05-express-angular-auth) | **9.0 / 10** | ✅ PASSED |
+| **Phase 6 (TS-07)** | Go 1.22 chi router + React | [ts06-go-chi-react](https://github.com/FennerEduardo/ts06-go-chi-react) | **9.2 / 10** | ✅ PASSED |
+| **Phase 7 (TS-09)** | Kotlin 1.9 Spring Boot + Vue | [ts07-kotlin-springboot-vue](https://github.com/FennerEduardo/ts07-kotlin-springboot-vue) | **9.7 / 10** | ✅ PASSED |
+| **Phase 8 (API-01)** | Laravel 11 + Inertia.js Vue | [ts08-laravel-inertia-vue](https://github.com/FennerEduardo/ts08-laravel-inertia-vue) | **9.0 / 10** | ✅ PASSED |
+| **Phase 9 (API-02)** | Ruby 3.3 Rails 7.1 + React | [ts09-rails-react-auth](https://github.com/FennerEduardo/ts09-rails-react-auth) | **8.7 / 10** | ✅ PASSED |
+| **Phase 10 (TS-08)** | Elixir 1.16 Phoenix LiveView | [ts10-elixir-phoenix-liveview](https://github.com/FennerEduardo/ts10-elixir-phoenix-liveview) | **9.3 / 10** | ✅ PASSED |
+| **Phase 11 (TS-05)** | Java Spring WebFlux + React Native Expo | [ts11-java-springboot-reactnative](https://github.com/FennerEduardo/ts11-java-springboot-reactnative) | **9.2 / 10** | ✅ PASSED |
+| **Phase 12 (API-05)** | gRPC Protobuf v3 & GraphQL SDL | [ts12-grpc-graphql-contracts](https://github.com/FennerEduardo/ts12-grpc-graphql-contracts) | **9.7 / 10** | ✅ PASSED |
+| **Phase 13 (TS-06)** | RabbitMQ Real + Postgres Outbox | [ts13-real-broker-saga-outbox](https://github.com/FennerEduardo/ts13-real-broker-saga-outbox) | **9.8 / 10** | ✅ PASSED |
+| **Phase 14 (HARNESS)**| Security & Determinism Test Harness | [ts14-adversarial-security-harness](https://github.com/FennerEduardo/ts14-adversarial-security-harness) | **10.0 / 10** | ✅ PASSED |
+
+---
+
+## 2. Direct Links to GitHub Repositories
+
+1. 📦 **Baseline .NET/Angular:** [FennerEduardo/transactional-system](https://github.com/FennerEduardo/transactional-system)
+2. ☕ **TS-01 Java / Vue 3:** [FennerEduardo/ts01-java-springboot-vue](https://github.com/FennerEduardo/ts01-java-springboot-vue)
+3. 💚 **TS-02 NestJS / Next.js:** [FennerEduardo/ts02-nestjs-react-nextjs](https://github.com/FennerEduardo/ts02-nestjs-react-nextjs)
+4. 🔷 **TS-03 .NET 8 / Angular 17:** [FennerEduardo/ts03-dotnet-angular](https://github.com/FennerEduardo/ts03-dotnet-angular)
+5. 🐍 **TS-04 Django DRF / React:** [FennerEduardo/ts04-django-react-auth](https://github.com/FennerEduardo/ts04-django-react-auth)
+6. 🚀 **TS-05 Express / Angular:** [FennerEduardo/ts05-express-angular-auth](https://github.com/FennerEduardo/ts05-express-angular-auth)
+7. 🐹 **TS-06 Go chi / React:** [FennerEduardo/ts06-go-chi-react](https://github.com/FennerEduardo/ts06-go-chi-react)
+8. 🟣 **TS-07 Kotlin / Vue:** [FennerEduardo/ts07-kotlin-springboot-vue](https://github.com/FennerEduardo/ts07-kotlin-springboot-vue)
+9. 🔴 **TS-08 Laravel Inertia:** [FennerEduardo/ts08-laravel-inertia-vue](https://github.com/FennerEduardo/ts08-laravel-inertia-vue)
+10. 💎 **TS-09 Rails API / React:** [FennerEduardo/ts09-rails-react-auth](https://github.com/FennerEduardo/ts09-rails-react-auth)
+11. 💧 **TS-10 Elixir Phoenix:** [FennerEduardo/ts10-elixir-phoenix-liveview](https://github.com/FennerEduardo/ts10-elixir-phoenix-liveview)
+12. 📱 **TS-11 WebFlux / React Native:** [FennerEduardo/ts11-java-springboot-reactnative](https://github.com/FennerEduardo/ts11-java-springboot-reactnative)
+13. ⚡ **TS-12 gRPC / GraphQL:** [FennerEduardo/ts12-grpc-graphql-contracts](https://github.com/FennerEduardo/ts12-grpc-graphql-contracts)
+14. 🐰 **TS-13 Real Broker Outbox:** [FennerEduardo/ts13-real-broker-saga-outbox](https://github.com/FennerEduardo/ts13-real-broker-saga-outbox)
+15. 🛡️ **TS-14 Security Harness:** [FennerEduardo/ts14-adversarial-security-harness](https://github.com/FennerEduardo/ts14-adversarial-security-harness)
+
+---
+
+## 3. Evaluation Findings and SDD Alignment
+
+The evaluation of these 15 projects demonstrates significant findings regarding the CLI's role in Spec-Driven Development (SDD):
+
+### State-of-the-Art Architecture Alignment
+The pipeline architecture (`spec → contract → master prompt → sandbox verification → audit`) is highly coherent with the state-of-the-art in spec-driven development. It closely mirrors the **Specify → Plan → Implement → Validate** flow described in recent literature for SDD with AI agents. The core philosophy that the specification must act as the shared "source of truth" between the human developer and the AI aligns with leading conceptual frameworks (e.g., GitHub Spec Kit).
+
+### Broad Multi-Stack Coverage
+The 14+ stack coverage is unusually ambitious for an SDD tool. While most SDD CLIs implicitly assume JS/Python ecosystems, `gherkin-ai` successfully evaluates complex and diverse paradigms, including:
+- Reactive WebFlux (Java)
+- OTP GenServers (Elixir / Phoenix)
+- Goroutines with `chi` (Go)
+- Form Requests (Laravel / PHP)
+- Non-REST domain contracts (gRPC Protobuf & GraphQL SDL)
+
+### Accurate Stack-Specific Validation Criteria
+The validation criteria enforced per stack target the exact architectural boundaries where LLMs typically hallucinate. Examples include enforcing Java Records for events, ensuring non-blocking R2DBC, verifying Elixir `defmodule` usage over `class`, and strictly requiring `go test -race`.
+
+### Validity of Compact Mode (`-C`)
+The compact mode successfully mitigates the real-world problem of context window bloat when feeding agents. The use of context pointers (`@.ghkgovernance.yaml`, `@features/*.feature`) rather than inlining full specs is a highly valid and effective prompt engineering technique for cost-sensitive environments.
+
+---
+
+## 4. Ecosystem Positioning
+
+`gherkin-ai` competes conceptually with **GitHub Spec Kit, Kiro, and Tessl** in the SDD layer, and with **Specmatic/Pact** in the contract verification layer. 
+
+Its declared differentiators—executable seeds, pinned versions, and role-specialized prompts—fill the exact gap identified in "spec + TDD" workflows: specifications provide the *"what"*, while the test suite provides the *"proof that it works"*. 
+
+Within Martin Fowler's SDD classification, `gherkin-ai` is positioned as **"spec-first with verification"**: the spec guides the initial generation, but the generated artifacts (code/tests) remain the long-term source of truth. This is a highly pragmatic approach for today's AI coding landscape.
+
+---
+
+## 5. Recommendations for Future Hardening
+
+To elevate this proof-of-concept into a fully verifiable benchmark, the following methodological improvements are recommended for future evaluations:
+
+1. **Publish Verification Logs**: Define the `PASSED` status explicitly by publishing the raw test suite execution logs (`gradle test`, `go test -race ./...`, `mix test`, `rspec`) and coverage counts per repository, moving beyond binary assertions.
+2. **Establish Control Groups**: Introduce a control group for the same `.feature` and contract implemented (a) with raw prompting, (b) with `ghk` without `-C`, and (c) with alternative tools like Spec Kit to measure the baseline impact accurately.
+3. **Refine Token Metrics**: Provide exact token counts per stack for the base prompt vs. the `-C` compact mode, rather than aggregated percentages.
+4. **Blind Evaluation**: Separate the author from the evaluator to eliminate self-referential bias in qualitative rubric scoring (Idiomatic Quality and Architectural Veracity).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gherkin-ai",
-  "version": "2.6.3",
+  "version": "2.6.4",
   "description": "Enterprise-Grade Closed-Loop Agentic Orchestration Engine & Spec-Driven Verification Framework for AI Coding Agents.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",