github-proyect-tracking 0.0.0-stage → 0.4.1

package/skill/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/skill/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.

package/skill/scripts/tracking.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""CLI de github-proyect-tracking; un JSON por comando, stdlib únicamente."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+
+from tracking_core import github as _github
+from tracking_core.common import *  # noqa: F401,F403
+from tracking_core.events import *  # noqa: F401,F403
+from tracking_core.state import *  # noqa: F401,F403
+from tracking_core.commands import *  # noqa: F401,F403
+
+_raw_api = _github._raw_api
+
+
+def _sync_runtime():
+    _github._raw_api = _raw_api
+    _github.shutil = shutil
+    _github.MAX_COMMENT_PAGES = MAX_COMMENT_PAGES
+    StateLock.STALE_SECONDS = LOCK_STALE_SECONDS
+    StateLock.WAIT_SECONDS = LOCK_WAIT_SECONDS
+
+
+def api(method, path, token, body=None, retries=3):
+    _sync_runtime()
+    return _github.api(method, path, token, body, retries)
+
+
+def check_issues_write(owner, repo, token):
+    _sync_runtime()
+    return _github.check_issues_write(owner, repo, token)
+
+
+def resolve_token(cli_token=None, state=None):
+    _sync_runtime()
+    return _github.resolve_token(cli_token, state)
+
+
+def post_comment(owner, repo, number, body, token,
+                 baseline_ids=None, execution_id=None, sequence=None):
+    _sync_runtime()
+    return _github.post_comment(owner, repo, number, body, token,
+                                baseline_ids, execution_id, sequence)
+
+
+def fetch_issue(owner, repo, number, token):
+    _sync_runtime()
+    return _github.fetch_issue(owner, repo, number, token)
+
+
+def fetch_all_comments(owner, repo, number, token):
+    _sync_runtime()
+    return _github.fetch_all_comments(owner, repo, number, token)
+
+
+def close_issue(owner, repo, number, token):
+    _sync_runtime()
+    return _github.close_issue(owner, repo, number, token)
+
+
+def find_issue_by_title(owner, repo, title, token):
+    _sync_runtime()
+    return _github.find_issue_by_title(owner, repo, title, token)
+
+
+class JsonArgumentParser(argparse.ArgumentParser):
+    def error(self, message):
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         f"argumentos inválidos: {message}")
+
+
+def build_parser():
+    parser = JsonArgumentParser(
+        prog="tracking.py",
+        description="github-proyect-tracking: persiste y reanuda el estado de un "
+                    "proceso en GitHub Issues. Cada comando imprime un único JSON.")
+    parser.add_argument("--version", action="version", version=USER_AGENT)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    def common(subparser, with_url=True, url_required=False):
+        if with_url:
+            subparser.add_argument(
+                "--url", required=url_required, metavar="URL",
+                help="github_project_url (https://github.com/{owner}/{repo}); "
+                     "obligatorio si hay varios procesos activos")
+        subparser.add_argument("--token", default=None, metavar="T",
+                               help="GitHub PAT con issues:write (si se omite: "
+                                    "env/gh/estado)")
+
+    subparser = subparsers.add_parser(
+        "init", help="nueva ejecución: valida, crea el Issue y guarda memoria")
+    common(subparser, url_required=True)
+    subparser.add_argument("--plan", default=None, metavar="JSON",
+                           help='plan de pasos con nombres ÚNICOS, ej. \'["Paso 1","Paso 2"]\'')
+    subparser.add_argument("--plan-file", default=None, metavar="F",
+                           help="archivo JSON con la lista de pasos")
+    subparser.add_argument("--prompt-token", action="store_true",
+                           help="pedir el token interactivamente (TTY)")
+    subparser.add_argument("--store-token", action="store_true",
+                           help="persistir el token provisto (opt-in; por defecto NO se guarda)")
+    subparser.add_argument("--no-store-token", action="store_true",
+                           help="obsoleto (compatibilidad): ahora NO guardar es el default")
+    subparser.set_defaults(func=cmd_init)
+
+    subparser = subparsers.add_parser(
+        "resume", help="lee el último comentario del Issue y planea la reanudación")
+    common(subparser)
+    subparser.set_defaults(func=cmd_resume)
+
+    subparser = subparsers.add_parser(
+        "step-start", help="comenta [STATUS: INICIANDO] - Paso: N")
+    common(subparser)
+    subparser.add_argument("--name", required=True, metavar="N", help="nombre del paso")
+    subparser.set_defaults(func=cmd_step_start)
+
+    subparser = subparsers.add_parser(
+        "step-done", help="comenta [STATUS: COMPLETADO] - Paso: N")
+    common(subparser)
+    subparser.add_argument("--name", required=True, metavar="N", help="nombre del paso")
+    subparser.set_defaults(func=cmd_step_done)
+
+    subparser = subparsers.add_parser(
+        "step-error", help="comenta [STATUS: ERROR] y detiene el proceso")
+    common(subparser)
+    subparser.add_argument("--name", required=True, metavar="N", help="nombre del paso")
+    subparser.add_argument("--details", default=None, metavar="D",
+                           help="mensaje de error o stacktrace (se sanitiza antes de publicar)")
+    subparser.add_argument("--details-file", default=None, metavar="F",
+                           help="archivo con el error/stacktrace")
+    subparser.set_defaults(func=cmd_step_error)
+
+    subparser = subparsers.add_parser(
+        "finalize", help="cierra el Issue con resultado FINALIZADO o CANCELADO")
+    common(subparser)
+    subparser.add_argument("--force", action="store_true",
+                           help="cancelar aunque queden pasos pendientes o no haya trabajo "
+                                "(no aplica si el Issue fue cerrado externamente)")
+    subparser.set_defaults(func=cmd_finalize)
+
+    subparser = subparsers.add_parser(
+        "status", help="muestra el estado local (y remoto con --remote)")
+    common(subparser)
+    subparser.add_argument("--remote", action="store_true",
+                           help="consultar también el Issue en GitHub")
+    subparser.set_defaults(func=cmd_status)
+
+    subparser = subparsers.add_parser(
+        "adopt", help="recupera el estado local desde un Issue remoto")
+    common(subparser, url_required=True)
+    subparser.add_argument("--execution-id", required=True, metavar="ID",
+                           help="Execution ID EXACTO del título del Issue")
+    subparser.add_argument("--force", action="store_true",
+                           help="reemplazar un proceso activo existente (conserva token "
+                                "e historial)")
+    subparser.set_defaults(func=cmd_adopt)
+
+    subparser = subparsers.add_parser(
+        "clear", help="limpia la memoria interna (soft por defecto)")
+    common(subparser)
+    subparser.add_argument("--hard", action="store_true",
+                           help="eliminar el archivo de estado por completo")
+    subparser.set_defaults(func=cmd_clear)
+
+    subparser = subparsers.add_parser(
+        "doctor", help="diagnóstico del entorno (siempre exit 0)")
+    common(subparser)
+    subparser.set_defaults(func=cmd_doctor)
+    return parser
+
+
+def main(argv=None):
+    try:
+        args = build_parser().parse_args(argv)
+        _sync_runtime()
+        return args.func(args)
+    except SkillError as error:
+        emit(error.to_json())
+        return error.exit_code
+    except KeyboardInterrupt:
+        return 130
+    except SystemExit:
+        raise
+    except Exception as error:
+        emit({"ok": False, "error": {
+            "code": "UNEXPECTED",
+            "message": f"{type(error).__name__}: {error}",
+            "hint": "error no previsto; reporta el comando exacto y este JSON"}})
+        return EXIT_RUNTIME
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skill/scripts/tracking_core/__init__.py

@@ -0,0 +1 @@
+"""Componentes internos de github-proyect-tracking."""