kcreate-scaffolding-gcp-script 0.0.0-stage → 0.2.0

package/skill/scripts/run_tracking.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Envoltura delgada sobre github-proyect-tracking para este skill. El agente
+# nunca llama a tracking.py directamente — siempre a través de este script,
+# para no tener que recordar flags ni rutas.
+#
+# Uso:
+#   run_tracking.sh init-plan   <config_file> <plan.json>
+#   run_tracking.sh resume      <config_file>
+#   run_tracking.sh step-start  <config_file> "<nombre del paso>"
+#   run_tracking.sh step-done   <config_file> "<nombre del paso>"
+#   run_tracking.sh step-error  <config_file> "<nombre del paso>" "<detalle>"
+#   run_tracking.sh status      <config_file>
+#   run_tracking.sh finalize    <config_file>
+#
+# Si github-proyect-tracking no está instalado junto a este skill, todos los
+# subcomandos salen con error claro (código 3) en vez de fallar a medias.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+source "$SCRIPT_DIR/lib/common.sh"
+
+SUBCOMMAND="${1:-}"
+CONFIG_FILE="${2:-}"
+[[ -n "$SUBCOMMAND" && -n "$CONFIG_FILE" ]] || ksc_die \
+  "uso: run_tracking.sh <subcomando> <config_file> [args...]"
+[[ -f "$CONFIG_FILE" ]] || ksc_die "no existe el archivo de configuración: $CONFIG_FILE"
+
+REPO_ROOT="$(ksc_repo_root)"
+TRACKING_PY="$REPO_ROOT/.claude/skills/github-proyect-tracking/scripts/tracking.py"
+[[ -f "$TRACKING_PY" ]] || { ksc_err "github-proyect-tracking no está instalado en este repo ($TRACKING_PY no existe). Reinstala con install.sh de KTerragruntScaffoldingScripts (sin --skip-tracking)."; exit 3; }
+
+# shellcheck disable=SC1090
+source "$CONFIG_FILE"
+[[ -n "${TRACKING_GITHUB_PROJECT_URL:-}" ]] || ksc_die \
+  "TRACKING_GITHUB_PROJECT_URL no está definido en $CONFIG_FILE"
+
+TP() { python3 "$TRACKING_PY" "$@" --url "$TRACKING_GITHUB_PROJECT_URL"; }
+
+case "$SUBCOMMAND" in
+  init-plan)
+    PLAN_FILE="${3:-}"
+    [[ -n "$PLAN_FILE" && -f "$PLAN_FILE" ]] || ksc_die "init-plan requiere un archivo plan.json existente"
+    TP init --plan-file "$PLAN_FILE"
+    ;;
+  resume)
+    TP resume
+    ;;
+  step-start)
+    NAME="${3:-}"; [[ -n "$NAME" ]] || ksc_die "step-start requiere el nombre del paso"
+    TP step-start --name "$NAME"
+    ;;
+  step-done)
+    NAME="${3:-}"; [[ -n "$NAME" ]] || ksc_die "step-done requiere el nombre del paso"
+    TP step-done --name "$NAME"
+    ;;
+  step-error)
+    NAME="${3:-}"; DETAILS="${4:-sin detalle}"
+    [[ -n "$NAME" ]] || ksc_die "step-error requiere el nombre del paso"
+    TP step-error --name "$NAME" --details "$DETAILS"
+    ;;
+  status)
+    TP status --remote
+    ;;
+  finalize)
+    TP finalize
+    ;;
+  *)
+    ksc_die "subcomando desconocido: $SUBCOMMAND"
+    ;;
+esac

package/skill/templates/scaffolding.config.template

@@ -0,0 +1,81 @@
+# Archivo de configuración de kcreate-scaffolding-gcp-script
+# Generado automáticamente por 01_init_config.sh — no es necesario crearlo a
+# mano. Los campos marcados __PENDIENTE__ no se pudieron inferir del
+# entorno fuente y deben llenarse antes de continuar. Los demás ya vienen
+# autodetectados del entorno fuente (SOURCE_ENV) — revísalos, pero no es
+# obligatorio tocarlos salvo que alguno esté mal.
+#
+# Formato: KEY="value", una por línea. Este archivo se `source`-ea
+# directamente en bash — no agregues nada que no sea una asignación simple
+# o un comentario.
+
+# --- Identidad de la ejecución (fijos, no editar tras la primera corrida) ---
+SOURCE_ENV="__SOURCE_ENV__"
+NEW_ENV="__NEW_ENV__"
+
+# --- Requeridos: no se pueden inferir del entorno fuente ---
+
+# Nombre legible para GCP (project_name). Inferido de NEW_ENV con la
+# convención <App-Con-Mayúscula-Inicial>-<QA|Prod> — confírmalo o corrígelo
+# si el nombre de la app tiene una capitalización distinta a la obvia
+# (ej. siglas, nombres compuestos).
+PROJECT_NAME="__PENDIENTE__"
+
+# Repo(s) de GitHub (formato owner/repo) que hacen `push` de imágenes
+# Docker al Artifact Registry de este proyecto nuevo. Se asume que ya
+# existen — este skill NO valida contra GitHub. Uno solo en el caso común;
+# si la app tiene varios repos (como boletera-qa, que maneja 5), sepáralos
+# con ";" — se genera un binding de github_workload_identity por cada uno.
+APP_GITHUB_REPO="__PENDIENTE__"
+
+# URL del repo de GitHub (https://github.com/{owner}/{repo}) usado por
+# github-proyect-tracking para registrar el avance de esta ejecución como
+# Issues/comentarios. Necesario para poder reanudar si el proceso se
+# interrumpe.
+TRACKING_GITHUB_PROJECT_URL="__PENDIENTE__"
+
+# --- Autodetectados de SOURCE_ENV (verificar, normalmente no hace falta tocar) ---
+
+ORG_ID="__PENDIENTE__"
+ORG_BILLING_ACCOUNT="__PENDIENTE__"
+REGION="__PENDIENTE__"
+ZONE="__PENDIENTE__"
+LABEL_OWNER="__PENDIENTE__"
+
+# Organización de GitHub usada en github_workload_identity (local.github_organization).
+GITHUB_ORGANIZATION="__PENDIENTE__"
+
+# Entradas fijas (no "dev-<usuario>") de sql_postgres.authorized_networks en
+# SOURCE_ENV, separadas por ";" como "nombre=ip/32;nombre2=ip2/32". Se
+# copian tal cual al entorno nuevo — son IPs de oficina/admin compartidas
+# entre entornos, no específicas de SOURCE_ENV.
+FIXED_ADMIN_NETWORKS="__PENDIENTE__"
+
+# --- Opcionales, con default vacío (no bloquean CONFIG_READY) -----------
+
+# Componentes a incluir ADEMÁS de los base (la intersección real de todos
+# los entornos de live/ — ver ksc_base_components). Por defecto NO se
+# incluyen opcionales como cloud_armor/identity_platform/monitoring_alerts
+# /secrets aunque SOURCE_ENV los tenga, siguiendo la guía (§1.2: "no
+# incluir salvo pedido explícito"). Si NEW_ENV sí los necesita, lístalos
+# aquí separados por ";", ej. "secrets;cloud_armor".
+EXTRA_COMPONENTS=""
+
+# Si sql_postgres de SOURCE_ENV usa dns_domain_name, da aquí el dominio
+# real que NEW_ENV usa (ej. "xoloshop.mx."). Déjalo vacío para que el
+# skill genere un valor por patrón (<app>.ninja., copiando la convención
+# de SOURCE_ENV) marcado con [WARN] para confirmación humana — el dominio
+# real registrado puede no coincidir con ese patrón visual.
+DNS_DOMAIN=""
+
+# --- Copiados de SOURCE_ENV pero marcados para verificación humana/del ---
+# --- agente: no se puede confirmar que sigan siendo la versión más       ---
+# --- reciente sin consultar documentación externa en el momento.        ---
+
+# Versión de GKE (canal Stable). 10_build_components.sh usa este valor tal
+# cual — si quieres la versión estable más reciente real (no la que ya
+# usaba SOURCE_ENV), verifícala y corrígela aquí antes de construir.
+GKE_VERSION_NEEDS_VERIFICATION="__PENDIENTE__"
+
+# Versión mayor de Cloud SQL Postgres. Mismo criterio que GKE_VERSION.
+DATABASE_VERSION_NEEDS_VERIFICATION="__PENDIENTE__"

package/vendor/github-proyect-tracking/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: github-proyect-tracking
+description: Track process execution state in GitHub Issues with resume.
+version: 0.4.0
+author: Rommel (rommelmg), Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [github, tracking, state-machine, resume, issues]
+    category: software-development
+    related_skills: [github]
+---
+
+# github-proyect-tracking Skill
+
+Persiste el estado de ejecución de un proceso estructurado en un Issue de
+GitHub (uno por ejecución) y lo reanuda tras interrupciones leyendo el
+último comentario. No ejecuta los pasos del proceso: los instrumenta —
+el agente hace el trabajo real y reporta cada transición con este skill.
+Depende solo de Python 3.8+ (stdlib); `gh` es opcional (fuente de token).
+
+**v0.4.0**: cada transición nueva lleva metadatos HTML con `transition_id`
+UUID para reconciliar respuestas perdidas y 500/502/503/504 sin confundir
+otro emisor.
+El resultado CANCELADO se conserva en reintentos, `resume` y `adopt`; tras
+ERROR se exige una reanudación explícita. El lock tiene heartbeat automático,
+el estado usa esquema v2 con migración desde v1 y los instaladores restauran
+el respaldo exacto ante fallos.
+
+## When to Use
+
+- El usuario pide rastrear/persistir la ejecución de un proceso con estados
+  verificables en GitHub (Issues como bitácora) y reanudar tras fallos.
+- Un proceso se interrumpió (error, caída de sesión) y hay que continuar
+  exactamente donde quedó, usando el Issue como fuente de verdad.
+- Contador: "trackea este proceso en GitHub", "reanuda donde quedó",
+  "registrando el avance del proceso".
+
+Don't use for:
+- Crear issues/PRs de mantenimiento sin seguimiento de proceso
+  (usa el skill `github`).
+- Persistir secretos en el cuerpo de un Issue (los `Detalles` se
+  sanitizan por patrones, pero no guarantees absolutas: no metas
+  credenciales).
+
+## Prerequisites
+
+- `github_project_url` exacta: `https://github.com/{owner}/{repo}`
+  (obligatoria en `init`; owner/repo se normalizan a minúsculas).
+- Token de GitHub con permisos de escritura sobre Issues (classic PAT
+  scope `repo`; fine-grained: Issues → Read and write). Resolución
+  automática: `--token` → `GITHUB_TRACKING_TOKEN` → `GITHUB_TOKEN` →
+  `GH_TOKEN` → `gh auth token` → archivo de estado (solo con
+  `--store-token`). Sin token → pídelo al usuario; nunca lo inventes.
+- Python 3.8+ en PATH (`python3`).
+
+## How to Run
+
+Todo corre por `terminal` con un único JSON de respuesta por comando.
+Ruta del script relativa a este skill: `scripts/tracking.py`:
+
+```bash
+SKILL="$HOME/.hermes/profiles/<profile>/skills/software-development/github-proyect-tracking/scripts/tracking.py"
+python3 "$SKILL" doctor --url https://github.com/OWNER/REPO --token "$GITHUB_TOKEN"
+```
+
+## Quick Reference
+
+| Comando | Efecto |
+|---|---|
+| `init --url URL [--plan JSON] [--store-token]` | Valida URL+token, crea el Issue, guarda `active_process_id` |
+| `resume [--url URL]` | Lee el ÚLTIMO comentario y dicta cómo continuar |
+| `step-start --name N` | Comenta `[STATUS: INICIANDO] - Paso: N` (valida orden del plan) |
+| `step-done --name N` | Comenta `[STATUS: COMPLETADO] - Paso: N` (exige paso en vuelo) |
+| `step-error --name N --details D` | Comenta `[STATUS: ERROR]` sanitizado y detiene |
+| `finalize [--force]` | FINALIZADO, o CANCELADO con `--force`; cierra y limpia memoria |
+| `status [--remote]` | Estado local (+ veredicto remoto) |
+| `adopt --url URL --execution-id ID [--force]` | Recupera memoria desde un Issue remoto |
+| `clear [--hard]` | Limpia `active_process_id` (o borra el archivo) |
+| `doctor [--url URL]` | Diagnóstico de entorno y permisos (exit 0) |
+
+Exit codes: `0` ok · `2` validación/transición inválida · `3` token sin
+permiso · `4` sin token · `5` sin proceso activo · `6` Issue no
+encontrado/ambiguo · `7` resume requerido · `8` conflicto con el estado
+remoto (Issue cerrado externamente o finalize bloqueado). Excepciones
+documentadas al contrato JSON: `--help`/`--version` (salida humana,
+exit 0) y `KeyboardInterrupt` (130).
+
+## Procedure
+
+1. **Preparar.** `doctor --url URL`. Si `token` o `issues-write` falla,
+   pide el PAT al usuario. Criterio: JSON con `"ok": true` en checks
+   requeridos (gh es opcional y no rompe `ok`). Un rol demostrado de solo
+   lectura hace fallar `issues-write`; `UNVERIFIED` se reserva para permisos
+   granulares que la API no puede confirmar.
+2. **Init.** `init --url URL --plan '["Paso 1: ...", ...]'` (plan
+   recomendado: nombres ÚNICOS; hace la reanudación determinista). Si
+   devuelve `RESUME_REQUIRED` (exit 7), NO crees otro Issue: ve al paso 3.
+   Criterio: `execution_id` e `issue_url` en la salida.
+3. **Reanudar (si aplica).** `resume` y sigue el `verdict.action`
+   (`RERUN_STEP`, `NEXT_STEP`, `START_FIRST`, `ALL_STEPS_DONE`/
+   `FINISH_CLEANUP` → finalize, `ABORTED_EXTERNALLY` → pregunta al
+   usuario, `NEXT_STEP_AGENT_DEFINED`). `NONE` y `FINISH_CLEANUP` llevan
+   `outcome=FINALIZADO|CANCELADO`; conserva ese resultado.
+4. **Ejecutar pasos.** Por cada paso, en orden estricto: `step-start`
+   ANTES de trabajar; si el trabajo falla, `step-error` (el proceso se
+   detiene; reanudar exige `resume` y solo permite reintentar ese paso);
+   si triunfa, `step-done`. Con plan, el CLI rechaza pasos fuera de orden,
+   desconocidos, duplicados o sin `step-start` previo (exit 2). Criterio:
+   `comment_url` por transición.
+5. **Finalizar.** Con todos los pasos COMPLETADO: `finalize` — rechaza
+   cerrar procesos incompletos (exit 8 `FINALIZE_BLOCKED`) salvo
+   `--force` (que registra CANCELADO, no éxito), y nunca un Issue cerrado
+   externamente. Sin plan exige al menos un COMPLETADO para éxito; sin
+   trabajo, `--force` cancela. Criterio: `issue_state: "closed"`,
+   `active_process_id: null` y `outcome` coherente.
+6. **Fallos transitorios de red.** GET/PATCH reintentan solos. Si un POST
+   pierde la respuesta o recibe 500/502/503/504, se reconcilia por el UUID
+   del intento antes de reintentar UNA vez; otro emisor con el mismo texto
+   no lo confirma. `init` también busca el Issue por título con paginación.
+
+Memoria interna: `~/.github-proyect-tracking/{owner}__{repo}.json`
+(owner/repo en minúsculas; esquema v2, migración automática desde v1 al
+guardar, escritura atómica con tmp único + fsync y permisos 0600). El candado
+por repositorio mantiene heartbeat durante toda la operación y comprueba su
+propiedad antes de efectos remotos y escrituras. `active_process_id` (número
+de Issue; null si no hay proceso) y `github_token` (SOLO con `--store-token`;
+enmascarado en salidas). Overridable con `GITHUB_TRACKING_STATE`.
+
+## Pitfalls
+
+- **Título exacto del Issue:** `[Process Tracking] Execution ID: {ID}` —
+  no lo edites; `adopt` exige igualdad canónica (IDs parciales se
+  rechazan).
+- **Contrato de comentarios:** los formatos visibles `[STATUS: ...]` son
+  exactos. La línea HTML de metadatos no cambia ese contrato. Un comentario
+  manual que imite el formato se interpretará como evento (el modelo de
+  confianza es "cualquiera con acceso al repo puede comentar").
+- **Sanitización de secretos:** `Detalles` y nombres de paso se redactan
+  por patrones (tokens GitHub/AWS, Authorization/Bearer, passwords,
+  URLs con credenciales) ANTES de publicar — no es una garantía
+  absoluta: revisa lo que envías.
+- **`init` con proceso inconcluso** falla con exit 7 a propósito:
+  reanuda con `resume` o descarta con `clear`.
+- **`step-error` detiene el proceso** (estado `ERROR`). Continuar exige
+  `resume` → `RERUN_STEP` (no se puede hacer `step-done` directo).
+- **`finalize` exige plan completo** (o `--force`); sin plan requiere un
+  COMPLETADO para éxito. Un Issue cerrado por un humano nunca se convierte
+  en éxito (`ABORTED_EXTERNALLY`, exit 8).
+- **Planes legados duplicados** producen `PLAN_AMBIGUOUS`; asigna nombres
+  únicos en el cuerpo del Issue, sin alterar los eventos.
+- **Contexto ambiguo:** varios procesos activos exigen `--url`; `clear`
+  también lo exige con varios estados inactivos.
+- **Token en el archivo de estado** solo con `--store-token` (opt-in);
+  prefiere variables de entorno o `gh auth token`. `adopt` sí puede usarlo.
+- **Límite de comentarios:** un Issue con >10 000 comentarios produce
+  `COMMENTS_TOO_MANY` (error explícito, no veredicto truncado).
+
+## Verification
+
+- `doctor` → `"ok": true` (gh opcional no rompe el global).
+- Tras `init`: `status` muestra `active_process_id` = número del Issue.
+- Tras `finalize`: `status` → `process_state: "FINALIZED"` o `"CANCELADO"`
+  según `outcome`, `active_process_id: null`; `resume` responde `NONE` con el
+  mismo `outcome`.
+- Reanudación determinista: tras `step-error`, `resume` →
+  `verdict.action == "RERUN_STEP"` con el mismo paso; `step-done` sin
+  `step-start` previo falla con `NO_STEP_IN_FLIGHT`.
+- 141 pruebas descubiertas: `python3 tests/test_tracking.py` (140 offline;
+  la integración real opt-in se omite por defecto).

package/vendor/github-proyect-tracking/references/api.md

@@ -0,0 +1,163 @@
+# Referencia de API (CLI) — github-proyect-tracking
+
+`scripts/tracking.py` — stdlib only, Python 3.8+. Cada comando imprime
+EXACTAMENTE un objeto JSON a stdout y usa un exit code documentado. Los
+ejemplos suponen `PY="python3 <ruta-del-skill>/scripts/tracking.py"`.
+
+## Contrato de respuesta
+
+```json
+{ "ok": true, "action": "INIT", "execution_id": "exec-...", "...": "..." }
+```
+
+Error:
+
+```json
+{ "ok": false, "error": { "code": "RESUME_REQUIRED", "message": "...",
+                          "state": {...}, "next": ["resume"] } }
+```
+
+| Exit | code típico | Significado / acción del agente |
+|---|---|---|
+| 0 | — | Éxito |
+| 1 | `NETWORK_ERROR`, `RATE_LIMITED`, `STATE_CORRUPT`, `COMMENTS_TOO_MANY`, `STATE_LOCKED`, `STATE_LOCK_LOST`… | Reintentar / diagnosticar / `resume` |
+| 2 | `VALIDATION_ERROR`, `NO_STEP_IN_FLIGHT`, `STEP_OUT_OF_ORDER`, `STEP_NOT_IN_PLAN`, `STEP_ALREADY_DONE`, `STEP_IN_FLIGHT`, `CONTEXT_AMBIGUOUS` | Corregir argumentos o transición |
+| 3 | `INVALID_TOKEN`, `INSUFFICIENT_SCOPE`, `NO_REPO_ACCESS`, `REPO_NOT_FOUND`, `ISSUES_WRITE_FAILED` | Token sin `issues:write` |
+| 4 | `NO_TOKEN` | Pedir el token al usuario |
+| 5 | `NO_STATE`, `NO_ACTIVE_PROCESS` | `init` primero |
+| 6 | `ISSUE_NOT_FOUND`, `ISSUE_AMBIGUOUS` | Verificar número / `adopt` (ID EXACTO) |
+| 7 | `RESUME_REQUIRED` (proceso inconcluso, estado `ERROR`, `adopt` sobre activo) | `resume` (o `adopt --force`) |
+| 8 | `FINALIZE_BLOCKED`, `ABORTED_EXTERNALLY`, `ISSUE_CLOSED_EXTERNALLY`, `ALREADY_FINALIZED` | Conflicto con estado remoto |
+
+`finalize --force` publica `[STATUS: CANCELADO] - El proceso fue cerrado
+anticipadamente (--force).` con los pasos pendientes — distinguible del
+éxito (`FINALIZADO`). `NONE` y `FINISH_CLEANUP` incluyen `outcome:
+FINALIZADO|CANCELADO`; reintentar, reanudar o adoptar nunca reclasifica una
+cancelación como éxito.
+
+Los comentarios nuevos conservan exactamente esos formatos visibles y añaden
+una línea HTML `<!-- github-proyect-tracking: {...} -->` con `execution_id`,
+`sequence` y `transition_id` UUID. El parser ignora esos metadatos al leer el
+texto y los usa para reconciliar únicamente el intento que originó el POST.
+
+## Comandos
+
+### `init --url URL [--plan JSON | --plan-file F] [--token T] [--prompt-token] [--store-token]`
+
+- Valida la URL (regex, redactada en errores), resuelve el token, valida
+  `issues:write` ANTES de crear nada.
+- Crea el Issue `[Process Tracking] Execution ID: {exec_id}` con el cuerpo
+  estándar (metadatos + plan numerado SANITIZADO) y guarda
+  `active_process_id`.
+- `--plan` recomendado: lista JSON de cadenas (nombres únicos tras
+  normalizar: strip+sanitización; duplicados y colisiones se rechazan) →
+  `resume` determinista.
+- `--store-token`: persistencia del token OPT-IN (por defecto NO se
+  guarda; `--no-store-token` quedó obsoleto).
+
+Salida: `execution_id`, `issue_number`, `issue_url`, `state_file`, `plan`,
+`first_step`, `token_source`.
+
+### `resume [--url URL] [--token T]`
+
+- Trae Issue + TODOS los comentarios (paginación por `Link`), parsea
+  eventos, emite `verdict` (ver tabla en `references/architecture.md`).
+- `--url` opcional si hay exactamente UN proceso activo; con varios
+  activos → `CONTEXT_AMBIGUOUS` (el error lista los repos activos).
+- Registra `last_resume`: después de ERROR autoriza únicamente el reintento
+  del paso fallido. Un plan legado duplicado produce `PLAN_AMBIGUOUS` con
+  instrucciones para asignar nombres únicos en el cuerpo del Issue.
+
+Salida: `issue_state`, `comment_count`, `verdict{action, outcome?,
+resume_from_step, remaining_steps?, failed_step?, error_details?, reason}`.
+
+### `step-start --name N` / `step-done --name N`
+
+Publican exactamente:
+
+```
+[STATUS: INICIANDO] - Paso: {N}
+[STATUS: COMPLETADO] - Paso: {N}
+```
+
+### `step-error --name N (--details D | --details-file F)`
+
+Publica `[STATUS: ERROR] - Paso: {N} - Detalles: {D}` y fija
+`process_state: "ERROR"` — **el proceso se detiene aquí** (por diseño;
+reanudar exige `resume`). `--details-file` ideal para stacktraces largos
+(trunca a 60000 chars).
+
+### `finalize [--url URL] [--token T] [--force]`
+
+1. Verifica el veredicto remoto: rechaza procesos con pasos pendientes
+   (`FINALIZE_BLOCKED`, exit 8) y abortes externos. Sin plan permite éxito
+   después de un COMPLETADO; sin trabajo exige `--force`.
+2. Sin `--force`: comenta `[STATUS: FINALIZADO] - El proceso concluyó
+   exitosamente.` (idempotente). Con `--force`: `[STATUS: CANCELADO] -
+   El proceso fue cerrado anticipadamente (--force).` con los pasos
+   pendientes (cierre anticipado distinguible, nunca éxito falso).
+3. Cierra el Issue (PATCH state=closed) y **verifica re-leyendo**.
+4. Limpia `active_process_id` (estado `FINALIZED`/`CANCELADO`) + historial
+   (con `outcome`). Un CANCELADO existente conserva ese resultado aunque el
+   reintento no lleve `--force`.
+
+### `status [--url URL] [--remote]`
+
+Estado local enmascarado (nunca imprime el token) y, con `--remote`,
+veredicto fresco del Issue.
+
+### `adopt --url URL --execution-id ID [--token T] [--force]`
+
+Recuperación: busca el Issue por título canónico EXACTO (el ID completo;
+parciales rechazados, ambigüedad → `ISSUE_AMBIGUOUS`), reconstruye el
+archivo de estado local. Carga el estado candidato antes de resolver el
+token, por lo que puede usar el guardado con `--store-token`. No sustituye
+un proceso activo sin `--force` (que conserva token e historial). Si adopta
+un ERROR, guarda `process_state=ERROR` y exige `resume`; conserva CANCELADO
+y ABORTED según el Issue. Útil tras perder la máquina local o tras un
+`clear --hard` accidental.
+
+### `clear [--url URL] [--hard]`
+
+Soft: `active_process_id := null`, `process_state := "CLEARED"` (conserva
+token/historial). Hard: elimina el archivo. Si el proceso era inconcluso,
+avisa: el Issue queda abierto en GitHub (recuperable con `adopt`). Sin URL,
+varios estados locales —activos o inactivos— producen `CONTEXT_AMBIGUOUS`;
+nunca se elige un archivo destructivamente por fecha.
+
+### `doctor [--url URL] [--token T]`
+
+Checks: python ≥ 3.8, directorio de estado escribible (crea el directorio
+y un archivo de prueba — efecto de escritura declarado), token resuelto
+(incluye el guardado con `--store-token` del repo de `--url`), GitHub API
++ rate limit, `gh` CLI (opcional), archivos de estado, URL válida y
+`issues:write` (con `--url`). Siempre exit 0 — es un reporte.
+
+## Variables de entorno
+
+| Variable | Uso |
+|---|---|
+| `GITHUB_TRACKING_TOKEN` | Token (prioridad máxima de las fuentes automáticas) |
+| `GITHUB_TOKEN` / `GH_TOKEN` | Fallbacks estándar |
+| `GITHUB_TRACKING_STATE` | Directorio alternativo de archivos de estado |
+
+## Detalles de la API REST usada
+
+| Operación | Endpoint |
+|---|---|
+| Validación de repo/permisos | `GET /repos/{owner}/{repo}` |
+| Crear Issue | `POST /repos/{owner}/{repo}/issues` |
+| Leer Issue / cerrar Issue | `GET` / `PATCH /repos/{owner}/{repo}/issues/{n}` |
+| Comentarios (paginado 100/pág) | `GET /repos/{owner}/{repo}/issues/{n}/comments` |
+| Publicar comentario | `POST /repos/{owner}/{repo}/issues/{n}/comments` |
+| Buscar Issue (adopt) | `GET /search/issues?q=...` |
+| Rate limit (doctor) | `GET /rate_limit` |
+
+Cabeceras: `Authorization: Bearer`, `Accept: application/vnd.github+json`,
+`X-GitHub-Api-Version: 2022-11-28`, `User-Agent: github-proyect-tracking/{v}`.
+Reintentos: GET/PATCH/5xx con backoff. Ante respuesta perdida o
+500/502/503/504 en POST, se busca el `transition_id` UUID fuera de la línea
+base y solo entonces se reconcilia; si no aparece, hay un único reintento con
+el mismo UUID y una segunda reconciliación. La creación del Issue usa búsqueda
+paginada por título exacto. Rate limit 403/429 con `X-RateLimit-Remaining: 0`
+espera controlada (máx 90 s).

package/vendor/github-proyect-tracking/references/architecture.md

@@ -0,0 +1,171 @@
+# Arquitectura — github-proyect-tracking
+
+## Visión general
+
+El skill instrumenta procesos (no los ejecuta): convierte cada transición en
+un evento persistido en un Issue de GitHub y mantiene una memoria local para
+saber si hay un proceso inconcluso y en qué Issue vive.
+
+```
+┌──────────────┐   instrucción    ┌─────────────────────────────────────┐
+│ Agente (tú)  │ ───────────────▶ │ scripts/tracking.py (CLI, stdlib)   │
+│              │ ◀─────────────── │  · 1 JSON por comando + exit code   │
+└──────────────┘   JSON + exit    └───────────────┬─────────────────────┘
+     │ trabajo real del proceso                   │
+     ▼                                            ▼
+┌──────────────────┐   comentarios [STATUS:…]  ┌──────────────────────────┐
+│ Memoria interna  │ ◀──────────────────────── │ GitHub REST API v3       │
+│ ~/.github-       │   Issue #N (fuente de     │ /repos/{o}/{r}/issues/…  │
+│ proyect-tracking/│   verdad al reanudar)     │ Bearer token             │
+│ {owner}__{repo}. │                           └──────────────────────────┘
+│ json             │
+└──────────────────┘
+```
+
+Doble libro:
+
+1. **Remoto (autoritativo):** un Issue con título
+   `[Process Tracking] Execution ID: {id}`; cada transición es un comentario
+   con contrato visible exacto y el último evento decide la reanudación.
+2. **Local (rápido):** `~/.github-proyect-tracking/{owner}__{repo}.json` con
+   esquema v2, `active_process_id`, `github_token` opcional, plan y metadatos.
+   La carga migra v1 a v2 en memoria y el siguiente guardado la persiste.
+   Escritura atómica (tmp único + fsync + rename), permisos 0600.
+
+## Contrato de eventos y reconciliación
+
+Formatos visibles:
+
+```text
+[STATUS: INICIANDO] - Paso: {nombre}
+[STATUS: ERROR] - Paso: {nombre} - Detalles: {detalles}
+[STATUS: COMPLETADO] - Paso: {nombre}
+[STATUS: FINALIZADO] - El proceso concluyó exitosamente.
+[STATUS: CANCELADO] - El proceso fue cerrado anticipadamente (--force).
+```
+
+Los eventos nuevos añaden una línea HTML invisible:
+
+```text
+<!-- github-proyect-tracking: {"execution_id":"...","sequence":1,"transition_id":"..."} -->
+```
+
+`transition_id` es un UUID por intento y se conserva en el reintento del mismo
+comando. Ante respuesta de red perdida o HTTP 500/502/503/504, el cliente lee
+los comentarios y solo reconcilia si encuentra ese UUID fuera de la línea base.
+Un texto idéntico antiguo o nuevo de otro emisor no basta. Si no lo encuentra,
+reintenta una vez y vuelve a reconciliar. `init` recupera una creación ambigua
+buscando el título exacto con paginación; si no lo encuentra, el error incluye
+Execution ID, título y comando `adopt` sugerido.
+
+El parser elimina los metadatos antes de aplicar `COMMENT_RE`, por lo que los
+formatos visibles y los comentarios antiguos siguen siendo compatibles.
+`Detalles` admite stacktraces multilínea. `events_from_comments()` ordena por
+`(created_at, comment_id)`, sin confiar en el orden de llegada.
+
+## Máquina de estados del proceso
+
+```
+                 init (URL válida + token issues:write)
+  (sin proceso) ───────────────────────────────────────▶ RUNNING
+                                                            │
+        ┌─────────── step-start / step-done ───────────────┤
+        ▼                                                  │
+     RUNNING ── step-error ──▶ ERROR ──(resume: RERUN_STEP)─┘
+        │
+        ├──── finalize: FINALIZADO + Issue cerrado ────────▶ FINALIZED
+        └──── finalize --force: CANCELADO + Issue cerrado ─▶ CANCELADO
+              (active_process_id := null)
+```
+
+| Estado en memoria | Significado | `active_process_id` |
+|---|---|---|
+| `RUNNING` | Issue abierto, último evento INICIANDO/COMPLETADO | número |
+| `ERROR` | Último evento ERROR; proceso detenido | número |
+| `FINALIZED` | Issue cerrado con FINALIZADO | `null` |
+| `CANCELADO` | Issue cerrado anticipadamente con CANCELADO | `null` |
+| `ABORTED` | Issue cerrado sin FINALIZADO/CANCELADO | `null` |
+| `CLEARED` | Memoria descartada localmente | `null` |
+
+`is_unfinished()` exige ID activo y estado RUNNING o ERROR. `init` sobre un
+proceso inconcluso falla con exit 7 (`RESUME_REQUIRED`). El esquema valida
+tipos y estas invariantes cruzadas; un estado terminal no puede conservar ID
+activo.
+
+Después de ERROR, `resume` registra `last_resume` con Issue y comentario de
+error. `step-start` solo acepta esa autorización para reintentar el mismo paso;
+`step-done` y `step-error` también se detienen mientras el último evento remoto
+sea ERROR. `adopt` reconstruye ERROR, nunca lo sustituye por RUNNING.
+
+## Ciclo de vida de una ejecución
+
+1. **init** — valida URL y permisos, genera `exec-{timestamp}-{12 hex}`, crea
+   el Issue y guarda memoria. Un plan duplicado nuevo se rechaza.
+2. **resume** — lee Issue y todos los comentarios, deriva el veredicto y
+   sincroniza el estado. Los planes legados duplicados producen
+   `PLAN_AMBIGUOUS` con instrucciones de reparación; no se deduplican.
+3. **step-start / step-error / step-done** — una transición por comentario,
+   validada contra la misma instantánea remota.
+4. **finalize** — publica el evento terminal, cierra y verifica el Issue,
+   limpia memoria y conserva las últimas 20 entradas de historial.
+
+Con plan, el éxito exige todos los pasos completados. Sin plan, el último
+evento COMPLETADO permite FINALIZADO; sin trabajo, `finalize` se bloquea y
+`--force` registra CANCELADO. El `outcome` siempre procede del evento remoto:
+un reintento sin `--force` no convierte CANCELADO en FINALIZADO.
+
+## Veredictos de `resume`
+
+| Último evento / situación | `verdict.action` | `outcome` | Acción |
+|---|---|---|---|
+| FINALIZADO + Issue abierto | `FINISH_CLEANUP` | `FINALIZADO` | Ejecutar `finalize` |
+| CANCELADO + Issue abierto | `FINISH_CLEANUP` | `CANCELADO` | Ejecutar `finalize` |
+| FINALIZADO + Issue cerrado | `NONE` | `FINALIZADO` | Nada; memoria auto-limpia |
+| CANCELADO + Issue cerrado | `NONE` | `CANCELADO` | Nada; conservar cancelación |
+| ERROR | `RERUN_STEP` | — | Re-ejecutar ese paso tras esta autorización |
+| INICIANDO | `RERUN_STEP` | — | Re-ejecutar el paso en vuelo |
+| COMPLETADO + plan pendiente | `NEXT_STEP` | — | Ejecutar `resume_from_step` |
+| COMPLETADO + plan agotado | `ALL_STEPS_DONE` | — | Ejecutar `finalize` |
+| Sin comentarios | `START_FIRST` | — | Empezar por el paso 1 |
+| Issue cerrado sin evento terminal | `ABORTED_EXTERNALLY` | — | Preguntar al usuario |
+| Sin plan explícito | `NEXT_STEP_AGENT_DEFINED` | — | Elegir paso o finalizar tras COMPLETADO |
+
+## Módulos
+
+| Archivo | Responsabilidad |
+|---|---|
+| `scripts/tracking.py` | Parser CLI, punto de entrada y exportaciones compatibles |
+| `tracking_core/common.py` | Versión, constantes, errores y validación/redacción |
+| `tracking_core/events.py` | Contrato visible, metadatos, parser y planner |
+| `tracking_core/state.py` | Esquema v2, migración, persistencia, selección y locks |
+| `tracking_core/github.py` | Token, preflight, transporte, paginación y reconciliación |
+| `tracking_core/commands.py` | Comandos y guardas sobre instantáneas remotas |
+
+## Locks y robustez
+
+`StateLock` usa un directorio por repositorio, propietario con token y un hilo
+daemon que refresca heartbeat durante toda la operación, incluidas las llamadas
+HTTP. `ensure_owner()` se exige antes de efectos remotos y antes de guardar o
+borrar. Perder el lock produce `STATE_LOCK_LOST` y exige `resume`.
+
+- Escritura atómica, estado 0600, tokens enmascarados y persistencia opt-in.
+- Reintentos de GET/PATCH y rate limit con espera acotada.
+- Paginación completa por `Link`; más de 10 000 comentarios →
+  `COMMENTS_TOO_MANY`.
+- `adopt` usa el token almacenado antes de buscar el Issue.
+- `clear` sin URL exige contexto único también cuando solo hay estados
+  inactivos; varios candidatos → `CONTEXT_AMBIGUOUS`.
+- Preflight: un rol demostrado de solo lectura falla; `triage`, `push`,
+  `maintain` o `admin` habilitan la gestión de Issues.
+- Redacción de todo userinfo, query y fragment en URLs reflejadas.
+
+## Límites y garantías
+
+- Un proceso activo por repositorio (la memoria es por `{owner}/{repo}`).
+- Los eventos son append-only; una persona con acceso puede imitar el contrato
+  visible. Usa repositorios controlados y revisa la cronología ante anomalías.
+- No hay transacciones distribuidas: el lock protege el estado local y el
+  heartbeat evita su expiración durante una operación viva, pero dos agentes
+  independientes pueden intervenir manualmente en el mismo Issue.
+- La integración real es opt-in y requiere autorización y un repositorio
+  desechable; no se ejecuta en la suite offline por defecto.