specleap-framework 2.1.6 → 2.1.8

package/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.8] - 2026-04-26
+
+### Fixed
+
+- **`setup.sh` token validation no longer aborts on the first wrong input.** Both the GitHub and the Asana token prompts now retry up to 3 times before asking the user whether to retry the round again or cancel the installation. Empty input doesn't consume an attempt (it's almost always a paste/typo, not a real failure). Reported by Styng during a manual test where pasting a partial Asana token killed the installer outright with no recovery path.
+
+#### Behavioural details
+
+- 3 attempts per round, then the installer prints the actual count and asks `[R]eintentar / [C]ancelar` (Spanish) or `[R]etry / [C]ancel` (English) depending on the chosen language.
+- Choosing `R` (default) resets the attempt counter and lets the user try 3 more times — useful when they realise mid-prompt that they grabbed the wrong token.
+- Choosing `C` exits cleanly with code 1 and the message `Instalación cancelada por el usuario` / `Installation cancelled by user`.
+- After every invalid token, a tip is printed reminding the user about required scopes (GitHub: `repo`, `workflow`) or token format (Asana: Personal Access Token).
+- Empty token input prints a localised reminder of the expected format and re-prompts without spending an attempt.
+
+No changes to the validation logic itself (still calls `https://api.github.com/user` and `https://app.asana.com/api/1.0/workspaces`), so behaviour with valid tokens is unchanged.
+
+## [2.1.7] - 2026-04-25
+
+### Added
+
+- **Bilingual setup questionnaire** (Phase 1 of i18n rollout) — `scripts/lib/questions.json` was split into `questions.es.json` and `questions.en.json`, both with all 58 questions. `generate-contrato.sh` now resolves the file at runtime from `SPECLEAP_LANG` (set by `setup.sh` from the user's choice or by `.specleap/config.json`), falling back to Spanish if the requested locale file is missing. Question IDs, numbers, options, validations and conditional logic (`skip_if`, `auto_suggest`) are preserved verbatim across both files for behavioural parity.
+- **Bilingual openspec CLI `--help` output** (Phase 2 of i18n rollout) — the `usage()` function in all nine subcommands (`apply`, `archive`, `code-review`, `enrich`, `ff`, `new`, `report`, `status`, `verify`) now prints English when `SPECLEAP_LANG=en`. A new `cli_lang()` helper in `openspec/cli/common.sh` resolves the active language from the env var, then `.specleap/config.json`, then falls back to `es`. Spanish output is byte-identical to the previous version, so existing users see no change.
+- **Bilingual FAQ** documenting the eight most common questions (vendor lock-in, SDD vs vibe coding, project size threshold, working without Claude Code, switching AI providers mid-project, Asana requirement, team scaling, relation to TDD/Agile/Scrum). Lives at `docs/faq.es.md` and `docs/faq.en.md`, linked from the README. Same content also rendered as a public section on `specleap.com/#faq` and `specleap.com/en/#faq`.
+- **Branch protection workflow** — new `pre-push` git hook installed alongside `pre-commit` by `scripts/install-git-hooks.sh`. The hook blocks direct pushes to `main` and `stage`, redirecting contributors to the documented `feature → stage → main` flow. Bypassable with `--no-verify` for emergencies. Companion document `CONTRIBUTING.md` describes the workflow, commit conventions and hook setup.
+
+### Notes
+
+- The `.specleap/i18n/{es,en}.json` runtime catalog and the `t()` helper in `.specleap/i18n.sh` continue to be used for short labels and runtime messages. The bilingual files added in this release (`questions.<lang>.json`) follow the project's separate-files convention for larger localised content.
+- The repository now has a `stage` branch as a permanent integration target; release tags are cut from `main` after a `stage → main` merge.
+- This release is the first to ship the openspec CLI with English `--help` to npm. Local i18n catalog (`.specleap/i18n/`) was already in the v2.1.5 tarball.
+
 ## [2.1.6] - 2026-04-24
 
 ### Changed

package/README.md

@@ -20,7 +20,7 @@
 
 SpecLeap convierte cualquier IDE con asistente de IA en un entorno de desarrollo spec-first. Combina un contrato de proyecto inmutable, agentes conversacionales especializados, 34 Agent Skills profesionales y un pipeline de validación en tres capas para entregar código consistente y probado sin improvisación.
 
-**Versión actual:** 2.1.6 · **Licencia:** MIT · **Autor:** Styng Arias ([ConceptualCreative](https://conceptualcreative.com))
+**Versión actual:** 2.1.8 · **Licencia:** MIT · **Autor:** Styng Arias ([ConceptualCreative](https://conceptualcreative.com))
 
 ---
 
@@ -37,6 +37,7 @@ SpecLeap convierte cualquier IDE con asistente de IA en un entorno de desarrollo
 - [IDEs Compatibles](#ides-compatibles)
 - [Dos Modos de Trabajo](#dos-modos-de-trabajo)
 - [Documentación](#documentación)
+- [Preguntas Frecuentes (FAQ)](#preguntas-frecuentes-faq)
 - [Licencia y Contribución](#licencia-y-contribución)
 
 ---
@@ -244,6 +245,19 @@ Ambos modos coexisten. Lo habitual es trabajar conversacionalmente en el día a
 
 ---
 
+## Preguntas Frecuentes (FAQ)
+
+Las preguntas habituales están respondidas en archivos dedicados:
+
+- **Español:** [docs/faq.es.md](docs/faq.es.md)
+- **English:** [docs/faq.en.md](docs/faq.en.md)
+
+Cubren temas como vendor lock-in, cuándo SDD se rentabiliza, compatibilidad con asistentes que no son Claude Code, escalado en equipo, y cómo SDD complementa (no reemplaza) a TDD/Agile/Scrum.
+
+Si tu pregunta no está cubierta, abre un issue en GitHub o escribe a `info@specleap.com`.
+
+---
+
 ## Licencia y Contribución
 
 Distribuido bajo licencia MIT. Ver [LICENSE](LICENSE).

package/openspec/cli/apply.sh

@@ -8,7 +8,42 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 source "$SCRIPT_DIR/common.sh"
 
 usage() {
-    cat <<EOF
+    if [ "$(cli_lang)" = "en" ]; then
+        cat <<EOF
+openspec apply — Implement an approved proposal
+
+USAGE:
+    openspec apply <CHANGE-ID> [options]
+
+OPTIONS:
+    --no-branch         Do not create a Git branch
+    --base <branch>     Base branch (default: develop)
+    --dry-run           Simulate without making changes
+    -h, --help          Show help
+
+DESCRIPTION:
+    Implements an approved proposal:
+    1. Creates a Git branch (feat/CHANGE-ID-name)
+    2. Applies delta specs (if any)
+    3. Generates scaffolding from design.md
+    4. Updates status to "in_progress"
+
+    NOTE: Does not generate code automatically.
+          Use an AI assistant (Continue, Copilot) to implement against specs.
+
+EXAMPLES:
+    openspec apply CHANGE-001
+    openspec apply CHANGE-002 --base main
+    openspec apply CHANGE-003 --dry-run
+
+PREREQUISITES:
+    - Proposal completed and reviewed
+    - Git repository initialised
+    - Base branch already exists
+
+EOF
+    else
+        cat <<EOF
 openspec apply — Implementar propuesta aprobada
 
 USAGE:
@@ -41,6 +76,7 @@ PREREQUISITES:
     - Base branch existente
 
 EOF
+    fi
 }
 
 # Parse arguments

package/openspec/cli/archive.sh

@@ -8,7 +8,37 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 source "$SCRIPT_DIR/common.sh"
 
 usage() {
-    cat <<EOF
+    if [ "$(cli_lang)" = "en" ]; then
+        cat <<EOF
+openspec archive — Archive a completed proposal
+
+USAGE:
+    openspec archive <CHANGE-ID> [options]
+
+OPTIONS:
+    --keep-branch       Do not delete the feature branch
+    --no-merge          Skip merge check (useful if already merged manually)
+    -h, --help          Show help
+
+DESCRIPTION:
+    Archives a completed and merged proposal:
+    1. Verifies the PR is merged
+    2. Updates status to "completed"
+    3. Deletes the feature branch (optional)
+    4. Generates a final report
+
+EXAMPLES:
+    openspec archive CHANGE-001
+    openspec archive CHANGE-002 --keep-branch
+    openspec archive CHANGE-003 --no-merge
+
+PREREQUISITES:
+    - PR merged into the base branch
+    - Code review approved
+
+EOF
+    else
+        cat <<EOF
 openspec archive — Archivar propuesta completada
 
 USAGE:
@@ -36,6 +66,7 @@ PREREQUISITES:
     - Code review aprobado
 
 EOF
+    fi
 }
 
 # Parse arguments

package/openspec/cli/code-review.sh

@@ -8,7 +8,40 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 source "$SCRIPT_DIR/common.sh"
 
 usage() {
-    cat <<EOF
+    if [ "$(cli_lang)" = "en" ]; then
+        cat <<EOF
+openspec code-review — Request a CodeRabbit review
+
+USAGE:
+    openspec code-review <CHANGE-ID> [options]
+
+OPTIONS:
+    --create-pr         Create the Pull Request automatically
+    --base <branch>     Base branch for the PR (default: develop)
+    --draft             Create the PR as draft
+    -h, --help          Show help
+
+DESCRIPTION:
+    Requests a code review for a proposal:
+    1. Verifies tests pass (openspec verify)
+    2. Creates PR on GitHub (if --create-pr)
+    3. CodeRabbit reviews automatically
+    4. Generates a review report
+
+EXAMPLES:
+    openspec code-review CHANGE-001
+    openspec code-review CHANGE-002 --create-pr
+    openspec code-review CHANGE-003 --create-pr --draft
+
+PREREQUISITES:
+    - Feature branch created
+    - Tests passing
+    - GitHub CLI configured (gh)
+    - CodeRabbit active in the repo
+
+EOF
+    else
+        cat <<EOF
 openspec code-review — Solicitar review de CodeRabbit
 
 USAGE:
@@ -39,6 +72,7 @@ PREREQUISITES:
     - CodeRabbit activo en el repo
 
 EOF
+    fi
 }
 
 # Parse arguments

package/openspec/cli/common.sh

@@ -16,6 +16,29 @@ warning() { echo -e "${YELLOW}⚠${NC} $*"; }
 error() { echo -e "${RED}✗${NC} $*" >&2; }
 step() { echo -e "${CYAN}→${NC} $*"; }
 
+# Detectar idioma activo del usuario.
+# Orden de precedencia:
+#   1. Variable de entorno SPECLEAP_LANG (export SPECLEAP_LANG=en)
+#   2. Campo "language" en .specleap/config.json (escrito por setup.sh)
+#   3. Fallback: "es"
+# Devuelve por stdout el código de idioma ("es" o "en"). Pensado para usarse
+# como `if [ "$(cli_lang)" = "en" ]; then ... else ... fi` en heredocs largos.
+cli_lang() {
+    if [ -n "${SPECLEAP_LANG:-}" ]; then
+        echo "$SPECLEAP_LANG"
+        return
+    fi
+    if [ -f "${PROJECT_ROOT:-.}/.specleap/config.json" ]; then
+        local lang
+        lang=$(grep -o '"language": "[^"]*"' "${PROJECT_ROOT}/.specleap/config.json" 2>/dev/null | cut -d'"' -f4)
+        if [ -n "$lang" ]; then
+            echo "$lang"
+            return
+        fi
+    fi
+    echo "es"
+}
+
 # Validate project structure
 validate_project() {
     if [[ ! -f "$PROJECT_ROOT/openspec/config.yaml" ]]; then

package/openspec/cli/enrich.sh

@@ -8,7 +8,42 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 source "$SCRIPT_DIR/common.sh"
 
 usage() {
-    cat <<EOF
+    if [ "$(cli_lang)" = "en" ]; then
+        cat <<EOF
+openspec enrich — Refine a user story with AI
+
+USAGE:
+    openspec enrich <user-story> [options]
+    openspec enrich --file <path>
+
+OPTIONS:
+    --file <path>       Read user story from file
+    --output <path>     Save the result (default: STDOUT)
+    --model <model>     AI model to use (default: auto)
+    -h, --help          Show help
+
+DESCRIPTION:
+    Takes a plain user story and enriches it with:
+    - Technical context
+    - Detailed acceptance criteria
+    - Identified edge cases
+    - Complexity estimate
+
+EXAMPLE:
+    openspec enrich "As a user I want to log in"
+    openspec enrich --file stories/US-123.md --output stories/US-123-refined.md
+
+OUTPUT:
+    Refined user story in markdown with:
+    - Title and description
+    - Business context
+    - Acceptance criteria (GIVEN/WHEN/THEN)
+    - Additional use cases
+    - Initial estimate
+
+EOF
+    else
+        cat <<EOF
 openspec enrich — Refinar user story con AI
 
 USAGE:
@@ -41,6 +76,7 @@ OUTPUT:
     - Estimación inicial
 
 EOF
+    fi
 }
 
 # Parse arguments

package/openspec/cli/ff.sh

@@ -8,7 +8,40 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 source "$SCRIPT_DIR/common.sh"
 
 usage() {
-    cat <<EOF
+    if [ "$(cli_lang)" = "en" ]; then
+        cat <<EOF
+openspec ff — Fast-forward: generate the complete proposal with AI
+
+USAGE:
+    openspec ff <CHANGE-ID> [options]
+
+OPTIONS:
+    --model <model>     AI model to use (default: auto)
+    --skip-proposal     Skip proposal.md generation
+    --skip-design       Skip design.md generation
+    --skip-tasks        Skip tasks.md generation
+    -h, --help          Show help
+
+DESCRIPTION:
+    Automatically generates with AI:
+    - Full proposal.md (if a base user story is available)
+    - Technical design.md (architecture, API, data)
+    - Broken-down tasks.md (tasks + estimates)
+
+    IMPORTANT: Review and adjust the AI output before applying.
+
+EXAMPLES:
+    openspec ff CHANGE-001
+    openspec ff CHANGE-002 --model anthropic/claude-sonnet-4
+    openspec ff CHANGE-003 --skip-tasks
+
+PREREQUISITES:
+    - Proposal created via: openspec new
+    - At least a proposal.md with basic context
+
+EOF
+    else
+        cat <<EOF
 openspec ff — Fast-forward: generar propuesta completa con AI
 
 USAGE:
@@ -39,6 +72,7 @@ PREREQUISITES:
     - Al menos proposal.md con contexto básico
 
 EOF
+    fi
 }
 
 # Parse arguments

package/openspec/cli/new.sh

@@ -8,7 +8,44 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 source "$SCRIPT_DIR/common.sh"
 
 usage() {
-    cat <<EOF
+    if [ "$(cli_lang)" = "en" ]; then
+        cat <<EOF
+openspec new — Create a new change proposal
+
+USAGE:
+    openspec new [CHANGE-ID] <title> [options]
+    openspec new --auto <title>
+
+OPTIONS:
+    --auto              Generate ID automatically
+    --from <file>       Create from a refined user story
+    --ticket <id>       Associate with a ticket ID (e.g. app-tienda-23)
+    --priority <level>  Priority (critical/high/medium/low)
+    --author <name>     Author (default: git user)
+    -h, --help          Show help
+
+DESCRIPTION:
+    Creates a new change proposal with the full structure:
+    - proposal.md (WHAT and WHY)
+    - design.md (HOW — technical)
+    - tasks.md (Tasks and Testing Report)
+    - specs/ (Delta specs if applicable)
+
+EXAMPLES:
+    openspec new CHANGE-001 "Implement JWT authentication"
+    openspec new --auto "Notification system" --ticket app-tienda-23
+    openspec new CHANGE-002 --from stories/auth-refined.md
+
+OUTPUT:
+    openspec/changes/CHANGE-XXX-name/
+    ├── proposal.md
+    ├── design.md
+    ├── tasks.md
+    └── specs/  (if applicable)
+
+EOF
+    else
+        cat <<EOF
 openspec new — Crear nueva propuesta de cambio
 
 USAGE:
@@ -43,6 +80,7 @@ OUTPUT:
     └── specs/  (si aplica)
 
 EOF
+    fi
 }
 
 # Parse arguments

package/openspec/cli/report.sh

@@ -8,7 +8,40 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 source "$SCRIPT_DIR/common.sh"
 
 usage() {
-    cat <<EOF
+    if [ "$(cli_lang)" = "en" ]; then
+        cat <<EOF
+openspec report — Generate testing report
+
+USAGE:
+    openspec report [CHANGE-ID] [options]
+
+OPTIONS:
+    --format <fmt>      Output format (markdown|json|text)
+    --output <file>     Output file (default: STDOUT)
+    -h, --help          Show help
+
+DESCRIPTION:
+    Generates a Testing Report automatically from test results:
+    - Runs the test suite
+    - Parses results (PHPUnit, Jest, etc.)
+    - Generates the report in the specified format
+    - Updates tasks.md if a CHANGE-ID is provided
+
+EXAMPLES:
+    openspec report
+    openspec report CHANGE-001
+    openspec report --format json --output report.json
+    openspec report CHANGE-002 --format markdown
+
+OUTPUT (markdown):
+    ## Testing Report
+    | Suite | Tests | Passed | Failed | Coverage |
+    |-------|-------|--------|--------|----------|
+    | Unit | X | X | 0 | XX% |
+
+EOF
+    else
+        cat <<EOF
 openspec report — Generar testing report
 
 USAGE:
@@ -39,6 +72,7 @@ OUTPUT (markdown):
     | Unit | X | X | 0 | XX% |
 
 EOF
+    fi
 }
 
 # Parse arguments

package/openspec/cli/status.sh

@@ -8,7 +8,34 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 source "$SCRIPT_DIR/common.sh"
 
 usage() {
-    cat <<EOF
+    if [ "$(cli_lang)" = "en" ]; then
+        cat <<EOF
+openspec status — View proposal status
+
+USAGE:
+    openspec status [options]
+
+OPTIONS:
+    --all               Show all (including completed)
+    --state <state>     Filter by state
+    --format <fmt>      Format (table|json|list)
+    -h, --help          Show help
+
+DESCRIPTION:
+    Shows the current status of all active proposals.
+
+EXAMPLES:
+    openspec status
+    openspec status --all
+    openspec status --state in_progress
+    openspec status --format json
+
+STATES:
+    draft, review, approved, in_progress, testing, completed, archived, rejected
+
+EOF
+    else
+        cat <<EOF
 openspec status — Ver estado de propuestas
 
 USAGE:
@@ -33,6 +60,7 @@ STATES:
     draft, review, approved, in_progress, testing, completed, archived, rejected
 
 EOF
+    fi
 }
 
 # Parse arguments

package/openspec/cli/verify.sh

@@ -8,7 +8,39 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 source "$SCRIPT_DIR/common.sh"
 
 usage() {
-    cat <<EOF
+    if [ "$(cli_lang)" = "en" ]; then
+        cat <<EOF
+openspec verify — Verify tests and specs
+
+USAGE:
+    openspec verify <CHANGE-ID> [options]
+
+OPTIONS:
+    --skip-tests        Skip test execution
+    --skip-specs        Skip spec validation
+    --coverage <min>    Minimum required coverage (default: 80)
+    -h, --help          Show help
+
+DESCRIPTION:
+    Verifies a proposal meets requirements before PR:
+    1. Runs the test suite (unit + integration)
+    2. Validates minimum coverage
+    3. Checks that specs are up to date
+    4. Generates Testing Report
+
+EXAMPLES:
+    openspec verify CHANGE-001
+    openspec verify CHANGE-002 --skip-specs
+    openspec verify CHANGE-003 --coverage 90
+
+OUTPUT:
+    - Testing Report updated in tasks.md
+    - Verification summary on STDOUT
+    - Exit code 0 if all OK, 1 if failures
+
+EOF
+    else
+        cat <<EOF
 openspec verify — Verificar tests y specs
 
 USAGE:
@@ -38,6 +70,7 @@ OUTPUT:
     - Exit code 0 si todo OK, 1 si hay fallos
 
 EOF
+    fi
 }
 
 # Parse arguments

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specleap-framework",
-  "version": "2.1.6",
+  "version": "2.1.8",
   "description": "Spec-Driven Development Framework — Transform VSCode, Cursor, JetBrains into spec-first development machines",
   "keywords": [
     "spec-driven-development",

package/scripts/generate-contrato.sh

@@ -10,16 +10,21 @@ set -euo pipefail
 # ============================================================================
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-QUESTIONS_FILE="$SCRIPT_DIR/lib/questions.json"
 SESSIONS_DIR="$SCRIPT_DIR/.sessions"
 TEMPLATE_FILE="$SCRIPT_DIR/../proyectos/_template/CONTRATO.md"
 TEMPLATE_LEGACY_FILE="$SCRIPT_DIR/../proyectos/_template/CONTRATO-LEGACY.md"
 VALIDATE_LIB="$SCRIPT_DIR/lib/validate.sh"
 ANALYZE_SCRIPT="$SCRIPT_DIR/analyze-project.sh"
 
-# Cargar sistema i18n
+# Cargar sistema i18n (define SPECLEAP_LANG y la función t())
 source "$SCRIPT_DIR/../.specleap/i18n.sh"
 
+# Cuestionario localizado: questions.<lang>.json (es por defecto, fallback si EN no existe)
+QUESTIONS_FILE="$SCRIPT_DIR/lib/questions.${SPECLEAP_LANG}.json"
+if [ ! -f "$QUESTIONS_FILE" ]; then
+    QUESTIONS_FILE="$SCRIPT_DIR/lib/questions.es.json"
+fi
+
 # Cargar funciones de validación
 source "$VALIDATE_LIB"
 

package/scripts/install-git-hooks.sh

@@ -132,10 +132,74 @@ EOF
 
 chmod +x "$HOOKS_DIR/pre-commit"
 
+# Crear pre-push hook (bloquea push directo a main/stage)
+cat > "$HOOKS_DIR/pre-push" << 'EOF'
+#!/bin/bash
+# SpecLeap Pre-Push Hook
+# Bloquea pushes directos a las ramas protegidas (main, stage).
+# Defensa local — equivalente a un Branch Protection Rule, mientras
+# el repo sea privado en plan free (los Rulesets de GitHub solo están
+# disponibles con Pro o repo público).
+
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+PROTECTED_BRANCHES=("main" "stage")
+
+# git pre-push hooks reciben argumentos: <remote> <url>
+# y por stdin líneas: <local_ref> <local_sha> <remote_ref> <remote_sha>
+remote="$1"
+url="$2"
+
+while read -r local_ref local_sha remote_ref remote_sha; do
+    # remote_ref es del estilo refs/heads/main, refs/heads/stage, refs/heads/feature/...
+    branch_name="${remote_ref#refs/heads/}"
+
+    for protected in "${PROTECTED_BRANCHES[@]}"; do
+        if [ "$branch_name" = "$protected" ]; then
+            echo ""
+            echo -e "${RED}╔═════════════════════════════════════════════════════════╗${NC}"
+            echo -e "${RED}║ SpecLeap: push directo a rama protegida BLOQUEADO       ║${NC}"
+            echo -e "${RED}╚═════════════════════════════════════════════════════════╝${NC}"
+            echo ""
+            echo -e "  Rama destino: ${YELLOW}$branch_name${NC}"
+            echo -e "  Remote:       ${YELLOW}$remote${NC} ($url)"
+            echo ""
+            echo "  El flujo SpecLeap requiere pull requests para integrar cambios:"
+            echo "    feature/<proyecto>-<ticket>-<desc>  →  stage  →  main"
+            echo ""
+            echo "  Pasos:"
+            echo "    1. Crea una feature branch:"
+            echo -e "       ${GREEN}git checkout -b feature/[proyecto]-[ticket]-[desc]${NC}"
+            echo ""
+            echo "    2. Haz tus commits ahí y pushea esa branch:"
+            echo -e "       ${GREEN}git push -u origin feature/[proyecto]-[ticket]-[desc]${NC}"
+            echo ""
+            echo "    3. Abre PR contra ${YELLOW}stage${NC} en GitHub."
+            echo ""
+            echo "  Si necesitas saltarte esto (emergencia, NO recomendado):"
+            echo "    git push --no-verify"
+            echo ""
+            echo "  Más info: CONTRIBUTING.md"
+            echo ""
+            exit 1
+        fi
+    done
+done
+
+exit 0
+EOF
+
+chmod +x "$HOOKS_DIR/pre-push"
+
 echo "✅ Git hooks instalados exitosamente"
 echo ""
-echo "📝 Hook instalado: pre-commit"
-echo "   → Valida linters, formatters y specs antes de cada commit"
+echo "📝 Hooks instalados:"
+echo "   • pre-commit  — valida linters, formatters y specs antes de cada commit"
+echo "   • pre-push    — bloquea pushes directos a main y stage (flujo feature → stage → main)"
 echo ""
-echo "💡 Para saltarte la validación (NO recomendado):"
-echo "   git commit --no-verify -m \"mensaje\""
+echo "💡 Para saltarte una validación (NO recomendado):"
+echo "   git commit --no-verify -m \"mensaje\"   # bypassea pre-commit"
+echo "   git push --no-verify                  # bypassea pre-push"