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

package/skill/scripts/run_tracking.sh

@@ -0,0 +1,93 @@
+#!/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> [archivo_de_resumen]
+#
+# `init-plan` manda siempre --process-name "/kcreate-scaffolding-gcp-script"
+# y --process-inputs con SOURCE_ENV/NEW_ENV (requiere github-proyect-tracking
+# >= 0.5.0/0.6.0 — ver vendor/VENDORED_FROM.md) — así el Issue de tracking
+# dice de entrada QUÉ skill lo está usando y CON QUÉ parámetros, sin que el
+# humano tenga que adivinarlo leyendo los comentarios de los pasos.
+#
+# `finalize` acepta opcionalmente la ruta a un archivo de texto con el
+# resumen final de la ejecución (requiere github-proyect-tracking >= 0.7.0):
+# si se da, ese resumen queda como un comentario APARTE en el Issue,
+# después del de FINALIZADO y antes de cerrarlo — el mismo resumen que el
+# agente ya le muestra al humano en pantalla, también en el Issue.
+#
+# 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"
+    PROCESS_INPUTS="$(python3 -c 'import json,sys; print(json.dumps({"SOURCE_ENV": sys.argv[1], "NEW_ENV": sys.argv[2]}))' "$SOURCE_ENV" "$NEW_ENV")"
+    TP init --plan-file "$PLAN_FILE" \
+      --process-name "/kcreate-scaffolding-gcp-script" \
+      --process-inputs "$PROCESS_INPUTS"
+    ;;
+  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)
+    SUMMARY_FILE="${3:-}"
+    if [[ -n "$SUMMARY_FILE" ]]; then
+      [[ -f "$SUMMARY_FILE" ]] || ksc_die "no existe el archivo de resumen: $SUMMARY_FILE"
+      TP finalize --summary-file "$SUMMARY_FILE"
+    else
+      TP finalize
+    fi
+    ;;
+  *)
+    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,180 @@
+---
+name: github-proyect-tracking
+description: Track process execution state in GitHub Issues with resume.
+version: 0.7.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] [--process-name N]` | Valida URL+token, crea el Issue (título `[Process Tracking][N] Execution ID: …` si se da N), guarda `active_process_id` y `process_name` |
+| `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 el proceso pertenece a un skill padre, añade
+   `--process-name "Mi Skill"`: el título del Issue pasa a
+   `[Process Tracking][Mi Skill] Execution ID: …` y el cuerpo incluye
+   `- **Proceso:** Mi Skill` — así el Issue identifica QUÉ se rastrea.
+   Para dejar constancia de CON QUÉ se ejecutó, añade `--process-inputs
+   '{"archivo":"x.csv","modo":"lint"}'` (objeto clave→valor; se publica
+   en la sección "Parámetros de entrada" del Issue, con secretos
+   redactados).
+   Si devuelve `RESUME_REQUIRED` (exit 7), NO crees otro Issue: ve al
+   paso 3. Criterio: `execution_id`, `process_name` 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,185 @@
+# 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] [--process-name N] [--process-inputs JSON]`
+
+- 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).
+- `--process-name N`: nombre del proceso/skill padre. Título resultante:
+  `[Process Tracking][N] Execution ID: {exec_id}`; el cuerpo incluye
+  `- **Proceso:** N`; estado y JSON llevan `process_name`. Sin `N`, se
+  conserva el formato legado `[Process Tracking] Execution ID: …`.
+  Un secreto en `N` se redacta; `[`/`]`/saltos → `VALIDATION_ERROR`.
+- `--process-inputs JSON`: objeto clave→valor con los parámetros de
+  entrada del proceso. Se publican en la sección "Parámetros de entrada"
+  del cuerpo del Issue (ordenados por clave, valores entre backticks) y
+  se guardan en el estado (`process_inputs`) y en la salida de `init`
+  (`process_inputs`). Secretos en claves/valores se REDACTAN; límites:
+  50 pares, valores ≤ 2000 caracteres; claves vacías, JSON inválido o no
+  objeto → `VALIDATION_ERROR`. Sin la opción, el estado queda limpio
+  (`process_inputs: null`) y el cuerpo no tiene la sección.
+- Salida de `init`: añade `process_name`, `process_inputs` e `issue_title`.
+
+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] [--summary TEXT | --summary-file F]`
+
+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. Si se dio `--summary`/`--summary-file` **y** la ruta es de éxito (no
+   `--force`): publica un comentario APARTE con ese texto (sanitizado y
+   truncado a 60000 chars, igual que `--details`), inmediatamente después
+   del de FINALIZADO. Sin marcador `[STATUS: ...]`, así que `COMMENT_RE`
+   lo ignora en lecturas futuras — no es parte de la máquina de estados,
+   solo queda como constancia legible en el Issue. `--summary`/
+   `--summary-file` vacío o en blanco no publica nada.
+4. Cierra el Issue (PATCH state=closed) y **verifica re-leyendo**.
+5. Limpia `active_process_id` (estado `FINALIZED`/`CANCELADO`) + historial
+   (con `outcome`). Un CANCELADO existente conserva ese resultado aunque el
+   reintento no lleve `--force`. La salida incluye
+   `summary_comment_posted`/`summary_comment_url`.
+
+### `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).