github-proyect-tracking 0.0.0-stage → 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kronops
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,457 @@
-# Temporary Holding Version
+# github-proyect-tracking
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Skill para agentes de IA (Hermes Agent) que **rastrea y persiste el estado de
+ejecución de un proceso estructurado, vinculándolo directamente a un proyecto
+de GitHub mediante Issues y comentarios**. Si el proceso se interrumpe (error,
+caída de sesión, reinicio), el skill reanuda exactamente donde quedó leyendo el
+último comentario del Issue.
+
+> **v0.4.0** — correcciones de `Review_V3.md`: resultados terminales derivados
+> del Issue, recuperación explícita tras `ERROR`, reconciliación por UUID ante
+> respuestas perdidas o 5xx, heartbeat durante toda la operación, esquema local
+> v2 con migración e instaladores transaccionales. El CLI se separó en módulos
+> sin cambiar su punto de entrada ni sus formatos visibles.
+
+---
+
+## 1. Descripción general
+
+`github-proyect-tracking` convierte cada ejecución de un proceso en un Issue de
+GitHub que funciona como bitácora persistente y auditable:
+
+- **Un Issue por ejecución**, titulado `[Process Tracking] Execution ID: {id}`.
+- **Cada transición del proceso es un comentario** con un contrato visible
+  cerrado y sin ambigüedades:
+
+  ```text
+  [STATUS: INICIANDO] - Paso: {nombre}
+  [STATUS: ERROR] - Paso: {nombre} - Detalles: {error o stacktrace}
+  [STATUS: COMPLETADO] - Paso: {nombre}
+  [STATUS: FINALIZADO] - El proceso concluyó exitosamente.
+  [STATUS: CANCELADO] - El proceso fue cerrado anticipadamente (--force).
+  ```
+
+  Los comentarios nuevos añaden después de ese texto una línea HTML invisible
+  con `execution_id`, `sequence` y `transition_id` (UUID). Estos metadatos
+  identifican el intento exacto al reconciliar un POST; no alteran el contrato
+  visible ni la interpretación de comentarios antiguos sin metadatos.
+
+- **Memoria interna** por repositorio (`~/.github-proyect-tracking/{owner}__{repo}.json`)
+  con `active_process_id` (número de Issue; nulo si no hay proceso) y
+  `github_token` (opcional).
+- **Reanudación determinista**: el último comentario del Issue es la fuente de
+  verdad; el parser reconstruye la cronología y dicta la acción siguiente
+  (re-ejecutar el paso con error, continuar con el siguiente, finalizar…).
+
+El skill **instrumenta procesos, no los ejecuta**: el agente (o el script
+externo que orquesta) hace el trabajo real de cada paso y reporta cada
+transición. No hay dependencias de terceros: solo Python 3.8+ (stdlib);
+`gh` CLI es opcional (fuente automática de token).
+
+| | |
+|---|---|
+| Entrada obligatoria | `github_project_url` — `https://github.com/{owner}/{repo}` |
+| Salida de cada comando | Un único objeto JSON + exit code documentado |
+| Permisos requeridos | PAT classic con scope `repo`, o fine-grained con Issues → Read and write |
+| Plataformas | Linux, macOS, Windows |
+| Licencia | MIT |
+
+---
+
+## 2. Instalación
+
+### Requisitos previos
+
+- Python 3.8 o superior (`python3` en PATH).
+- Un token de GitHub con permisos de escritura sobre Issues del repo destino.
+  Fuentes que el skill resuelve automáticamente, en orden:
+  `--token` → `GITHUB_TRACKING_TOKEN` → `GITHUB_TOKEN` → `GH_TOKEN` →
+  `gh auth token` → archivo de estado local.
+- (Opcional) `gh` CLI autenticado — sirve como fuente de token.
+
+### Instalación estándar
+
+Desde la raíz de este repositorio:
+
+```bash
+bash install.sh
+```
+
+El instalador:
+
+1. Copia `github-proyect-tracking/` a
+   `{perfil-de-hermes}/skills/software-development/github-proyect-tracking/`
+   (detecta el perfil activo; se puede forzar con `--profile NOMBRE` o
+   apuntar a cualquier ruta con `--dest RUTA`; `--user` instala en
+   `~/.hermes/skills` del perfil por defecto).
+2. Respalda cualquier versión previa con una ruta única y la restaura si el
+   reemplazo o la verificación falla.
+3. Valida el frontmatter del SKILL.md y ejecuta
+   `tracking.py --version` antes y después del reemplazo.
+4. Imprime la prueba rápida recomendada.
+
+El staging y el rename ocurren en el mismo filesystem. Retirar el directorio
+anterior y renombrar el nuevo no es una única operación atómica; esa breve
+ventana queda cubierta por rollback ante errores, pero otro proceso no debe
+usar el skill durante la instalación.
+
+> El skill aparece en el catálogo de **sesiones nuevas** de Hermes (el
+> catálogo se carga al iniciar sesión; no en la sesión en curso).
+
+### Verificación post-instalación
+
+```bash
+python3 ~/.hermes/profiles/<perfil>/skills/software-development/github-proyect-tracking/scripts/tracking.py \
+  doctor --url https://github.com/{owner}/{repo}
+```
+
+`doctor` verifica: versión de Python, directorio de estado escribible, token
+resuelto, conectividad con la API de GitHub, `gh` CLI y permisos de escritura
+sobre Issues del repo indicado. Siempre termina con exit 0 (es un reporte).
+
+### Instalación vía npx (sin clonar)
+
+Si el paquete está publicado en npm (o tienes el tarball localmente), no
+necesitas clonar el repositorio:
+
+```bash
+# instalar (mismo destino y validaciones que install.sh)
+npx --yes github-proyect-tracking
+npx --yes github-proyect-tracking install --profile kronops   # o --dest RUTA / --user
+
+# diagnóstico sin instalar (python + token + API de GitHub)
+npx --yes github-proyect-tracking doctor --url https://github.com/{owner}/{repo}
+
+# ejecutar cualquier comando del skill sin instalarlo
+npx --yes github-proyect-tracking run status --remote
+npx --yes github-proyect-tracking uninstall [--purge-state]
+```
+
+- El instalador npx (`npm/bin/cli.js`, Node ≥ 18, **cero dependencias npm**)
+  replica la resolución de destino de `install.sh`: `HERMES_HOME` → perfil
+  activo (`HERMES_PROFILE` o la línea `profile:` del `AGENT.md` del
+  directorio actual) → perfil `default`. Ambos instaladores son
+  intercambiables.
+- `install` valida el frontmatter del SKILL.md, ejecuta
+  `tracking.py --version` como verificación real y respalda la copia previa.
+- `doctor` y `run` usan la copia instalada si existe; si no, la empaquetada.
+
+**Publicar en npm** (mantenedor del paquete):
+
+```bash
+cd npm
+npm login
+npm publish        # prepack empaqueta skill/ + README + LICENSE automáticamente
+```
+
+`npm pack` genera el tarball verificable de forma idéntica
+(`npx --yes ./npm/github-proyect-tracking-0.4.0.tgz install`).
+
+### Desinstalación
+
+```bash
+bash uninstall.sh                 # quita el skill del perfil
+bash uninstall.sh --purge-state   # además borra la memoria interna local
+npx --yes github-proyect-tracking uninstall          # vía npx
+npx --yes github-proyect-tracking uninstall --purge-state
+```
+
+`--purge-state` elimina `~/.github-proyect-tracking/`; los Issues creados en
+GitHub **no** se tocan (son parte del historial del repositorio remoto).
+
+### Instalación manual
+
+```bash
+cp -R github-proyect-tracking/ ~/.hermes/profiles/<perfil>/skills/software-development/
+```
+
+### Ejecutar las pruebas
+
+```bash
+python3 tests/test_tracking.py    # 141 pruebas: 140 offline + 1 skip opt-in
+```
+
+---
+
+## 3. Arquitectura del skill
+
+### 3.1 Modelo general
+
+```
+┌──────────────┐   1 comando = 1 transición   ┌─────────────────────────────────┐
+│ Agente (tú)  │ ───────────────────────────▶ │ scripts/tracking.py (stdlib)    │
+│              │ ◀─────────────────────────── │  · valida, llama a la API,      │
+└──────────────┘   JSON + exit code           │    guarda memoria y responde    │
+     │                                        └───────────────┬─────────────────┘
+     │ ejecuta el trabajo real del proceso                   │
+     ▼ (builds, tests, despliegues…)                         ▼
+┌────────────────────────┐   comentarios     ┌────────────────────────────────┐
+│ Memoria interna local  │   [STATUS: …]     │ GitHub REST API v3             │
+│ ~/.github-proyect-     │ ◀──────────────── │ POST /repos/{o}/{r}/issues/…   │
+│ tracking/              │   Issue #N         │ (fuente de verdad al reanudar) │
+│ {owner}__{repo}.json   │                   └────────────────────────────────┘
+└────────────────────────┘
+```
+
+**Doble libro de contabilidad:**
+
+- **Remoto (autoritativo):** el Issue con su cronología de comentarios. Todo
+  evento es *append-only* y sobrevive a cualquier pérdida local.
+- **Local (rápido):** el archivo de estado evita buscar "¿qué proceso estaba
+  corriendo?" en cada comando. Escritura atómica (`tmp` + `rename`), permisos
+  `0600` (puede contener el token).
+
+### 3.2 Máquina de estados del proceso
+
+```
+                 init (URL válida + token issues:write)
+  (sin proceso) ───────────────────────────────────────▶ RUNNING
+                                                            │
+        ┌───── step-start / step-done (bucle por paso) ───┤
+        ▼                                                  │
+     RUNNING ── step-error ──▶ ERROR ── resume(RERUN_STEP)─┘
+        │
+        ├─ finalize: FINALIZADO + Issue cerrado ──────────▶ FINALIZED
+        └─ finalize --force: CANCELADO + Issue cerrado ───▶ CANCELADO
+                             (active_process_id := null)
+```
+
+| Estado | Significado | `active_process_id` |
+|---|---|---|
+| `RUNNING` | Issue abierto; último evento INICIANDO/COMPLETADO | número de Issue |
+| `ERROR` | Último evento ERROR — el proceso está detenido | número de Issue |
+| `FINALIZED` | Issue cerrado con FINALIZADO; memoria limpia | `null` |
+| `CANCELADO` | Cierre anticipado con CANCELADO; memoria limpia | `null` |
+| `ABORTED` | Issue cerrado sin evento terminal válido | `null` |
+| `CLEARED` | Memoria descartada localmente (`clear` soft) | `null` |
+
+Se considera **proceso inconcluso** aquel con `active_process_id` no nulo y
+estado `RUNNING` o `ERROR`. `init` sobre un proceso inconcluso **falla con
+exit 7** (`RESUME_REQUIRED`) a propósito: obliga a reanudar y evita Issues
+huérfanos duplicados.
+
+### 3.3 Flujo de trabajo (fases de la definición)
+
+**A. Inicialización / Reanudación**
+
+1. `init --url URL [--plan JSON]`:
+   - Valida la URL con regex (formato `https://github.com/{owner}/{repo}`).
+   - Resuelve el token y **valida permisos de escritura antes de crear nada**.
+   - Genera `exec-{UTC}-{12 hex}`, crea el Issue con título canónico y
+     cuerpo estándar (metadatos + plan numerado), guarda
+     `active_process_id` en memoria.
+2. Si ya había proceso inconcluso → exit 7 → ejecutar `resume`.
+3. `resume`: trae el Issue y **todos** sus comentarios (paginado),
+   reconstruye la cronología de eventos y emite un veredicto accionable
+   (tabla §3.4). Registra `last_resume`; después de un ERROR solo esa
+   reanudación explícita autoriza reintentar el mismo paso.
+
+**B. Ejecución de pasos** — por cada paso, en orden estricto:
+
+1. `step-start --name N` **antes** de trabajar →
+   `[STATUS: INICIANDO] - Paso: N`.
+2. Si el paso falla → `step-error --name N --details …` →
+   `[STATUS: ERROR] - Paso: N - Detalles: …` — **el proceso se detiene aquí**.
+3. Si el paso triunfa → `step-done --name N` →
+   `[STATUS: COMPLETADO] - Paso: N`.
+
+**C. Finalización**
+
+1. `finalize` comenta `[STATUS: FINALIZADO] - El proceso concluyó
+   exitosamente.` si el plan está completo. Sin plan exige al menos un
+   COMPLETADO: después del último paso permite éxito; sin ningún trabajo exige
+   `--force`. Con pasos pendientes, `--force` registra CANCELADO.
+2. Cierra el Issue (PATCH `state=closed`) y **verifica re-leyendo** el
+   estado real.
+3. Limpia `active_process_id` (estado `FINALIZED` o `CANCELADO`) y registra
+   el `outcome` en el historial (últimos 20). Reintentar conserva el evento
+   terminal remoto y no duplica el comentario.
+
+### 3.4 Parser de reanudación y veredictos
+
+Los comentarios se parsean con una regex multilinea sobre el contrato visible;
+la línea HTML de metadatos se retira antes de aplicar la regex. `Detalles`
+admite stacktraces multilínea. La cronología se ordena por
+`(created_at, comment_id)` → **el último elemento es el último evento**.
+
+| Último evento del Issue | `verdict.action` / `outcome` | El agente debe… |
+|---|---|---|
+| FINALIZADO, Issue cerrado | `NONE` / `FINALIZADO` | Nada (memoria se auto-limpia) |
+| CANCELADO, Issue cerrado | `NONE` / `CANCELADO` | Nada; conservar la cancelación |
+| FINALIZADO, Issue abierto | `FINISH_CLEANUP` / `FINALIZADO` | Ejecutar `finalize` |
+| CANCELADO, Issue abierto | `FINISH_CLEANUP` / `CANCELADO` | Ejecutar `finalize`; no cambiar el resultado |
+| ERROR | `RERUN_STEP` (+ `failed_step`, `error_details`) | Re-ejecutar ese paso y continuar |
+| INICIANDO | `RERUN_STEP` | Re-ejecutar el paso (quedó a medias) |
+| COMPLETADO, quedan pasos | `NEXT_STEP` (+ `remaining_steps`) | Ejecutar `resume_from_step` |
+| COMPLETADO, plan agotado | `ALL_STEPS_DONE` | Ejecutar `finalize` |
+| Sin comentarios | `START_FIRST` | Empezar por el paso 1 del plan |
+| Issue cerrado sin FINALIZADO/CANCELADO | `ABORTED_EXTERNALLY` | Preguntar al usuario |
+| Sin plan explícito | `NEXT_STEP_AGENT_DEFINED` | Decidir el siguiente paso / finalizar tras COMPLETADO |
+
+### 3.5 Estructura del repositorio
+
+```
+KGithubTracking/
+├── README.md / AGENT.md / CONTRIBUTING.md / CHANGELOG.md
+├── install.sh / uninstall.sh / lib/common.sh
+├── npm/                          ← paquete npx (Node ≥ 18, sin deps)
+│   ├── package.json
+│   ├── bin/cli.js / bin/build.js
+│   └── skill/                    ← copia generada (ignorada por git)
+├── tests/
+│   ├── test_tracking.py          ← carga toda la suite
+│   ├── test_more.py / test_v2.py / test_v3.py
+│   ├── test_installers.py        ← argumentos y rollback reales
+│   └── test_github_integration.py← integración real opt-in
+├── tools/check_docs.py           ← coherencia documental (CI)
+└── github-proyect-tracking/      ← skill instalable
+    ├── SKILL.md
+    ├── scripts/
+    │   ├── tracking.py           ← punto de entrada compatible
+    │   └── tracking_core/
+    │       ├── common.py         ← versión, constantes y validación
+    │       ├── events.py         ← contrato, metadatos y planner
+    │       ├── state.py          ← esquema v2, migración y locks
+    │       ├── github.py         ← token, HTTP y reconciliación
+    │       └── commands.py       ← comandos y guardas
+    └── references/
+        ├── architecture.md
+        └── api.md
+```
+
+---
+
+## 4. Documentación de funcionamiento
+
+### 4.1 Contrato de respuesta del CLI
+
+Cada comando imprime **exactamente un JSON** a stdout y termina con un exit
+code documentado:
+
+```json
+{ "ok": true, "action": "INIT", "execution_id": "exec-20261028T101500Z-ab12cd34ef56",
+  "issue_number": 42, "issue_url": "https://github.com/o/r/issues/42",
+  "state_file": "~/.github-proyect-tracking/o__r.json", "first_step": "Paso 1" }
+```
+
+```json
+{ "ok": false, "error": { "code": "RESUME_REQUIRED", "message": "...",
+                          "state": { "...": "..." }, "next": ["resume"] } }
+```
+
+| Exit | Códigos típicos | Causa / acción |
+|---|---|---|
+| 0 | — | Éxito |
+| 1 | `NETWORK_ERROR`, `RATE_LIMITED`, `STATE_CORRUPT`, `COMMENTS_TOO_MANY`, `STATE_LOCKED`… | Reintentar / diagnosticar |
+| 2 | `VALIDATION_ERROR`, `NO_STEP_IN_FLIGHT`, `STEP_OUT_OF_ORDER`, `STEP_NOT_IN_PLAN`, `STEP_ALREADY_DONE`, `STEP_IN_FLIGHT`, `CONTEXT_AMBIGUOUS`, `PLAN_AMBIGUOUS` | Argumentos o transición inválida |
+| 3 | `INVALID_TOKEN`, `INSUFFICIENT_SCOPE`, `NO_REPO_ACCESS`, `REPO_NOT_FOUND`, `ISSUES_WRITE_FAILED` | El token no puede escribir Issues |
+| 4 | `NO_TOKEN` | No hay token: pedirlo al usuario |
+| 5 | `NO_STATE`, `NO_ACTIVE_PROCESS` | No hay proceso activo: `init` primero |
+| 6 | `ISSUE_NOT_FOUND`, `ISSUE_AMBIGUOUS` | El Issue no existe o es ambiguo |
+| 7 | `RESUME_REQUIRED` (proceso inconcluso, estado `ERROR`, `adopt` sobre activo) | Ejecutar `resume` |
+| 8 | `FINALIZE_BLOCKED`, `ABORTED_EXTERNALLY`, `ISSUE_CLOSED_EXTERNALLY`, `ALREADY_FINALIZED` | Conflicto con el estado remoto |
+
+Excepciones documentadas al contrato "un JSON por comando": `--help`/
+`--version` (salida humana, exit 0) y `KeyboardInterrupt` (exit 130).
+
+### 4.2 Referencia de comandos
+
+| Comando | Efecto | Efectos secundarios |
+|---|---|---|
+| `init --url URL [--plan JSON \| --plan-file F] [--token T] [--store-token]` | Crea el Issue y la memoria (plan sanitizado) | Issue nuevo en GitHub + archivo local |
+| `resume [--url URL]` | Veredicto de reanudación | Actualiza memoria local |
+| `step-start --name N` | Comenta INICIANDO | Comentario + memoria |
+| `step-done --name N` | Comenta COMPLETADO | Comentario + memoria |
+| `step-error --name N (--details D \| --details-file F)` | Comenta ERROR y detiene | Comentario + memoria (`ERROR`) |
+| `finalize [--force]` | FINALIZADO (o CANCELADO con `--force`) + cierre + limpieza | Comentario + Issue cerrado |
+| `status [--remote]` | Estado local (y remoto) | Solo lectura |
+| `adopt --url URL --execution-id ID [--force]` | Recupera memoria desde un Issue | Archivo local nuevo |
+| `clear [--hard]` | Limpia la memoria | Archivo local (soft/hard) |
+| `doctor [--url URL]` | Diagnóstico (crea el dir. de estado y un archivo de prueba como efecto declarado) | Efecto de escritura intencional y documentado |
+
+`--url` es opcional cuando hay exactamente UN proceso activo (ese es el
+contexto); con varios procesos activos el comando exige `--url`
+(`CONTEXT_AMBIGUOUS` lista los activos). `--plan` es opcional pero
+recomendado — hace la reanudación 100% determinista; los nombres se
+normalizan (validar+strip+sanitizar) y los duplicados tras normalizar se
+rechazan.
+
+### 4.3 Variables de entorno
+
+| Variable | Uso |
+|---|---|
+| `GITHUB_TRACKING_TOKEN` | Token preferido (máxima prioridad de las fuentes automáticas) |
+| `GITHUB_TOKEN` / `GH_TOKEN` | Fallbacks estándar de la comunidad |
+| `GITHUB_TRACKING_STATE` | Directorio alternativo para los archivos de estado |
+
+### 4.4 Seguridad del token
+
+- Nunca se imprime en stdout (`status` lo enmascara como `<stored>`).
+- Se persiste en el archivo de estado **solo** con `--store-token`
+  (opt-in explícito desde v0.2.0; `--token` solo ya NO guarda; el flag
+  `--no-store-token` quedó obsoleto y se acepta por compatibilidad); el
+  archivo queda con permisos `0600`.
+- Vía preferida: variables de entorno o `gh auth token`.
+- Nunca debe viajar en el cuerpo de un Issue o comentario (solo van
+  mensajes de error/stacktrace del proceso, sin credenciales).
+
+### 4.5 Robustez implementada
+
+| Requisito | Implementación |
+|---|---|
+| URL y credenciales | `REPO_URL_RE`; redacción completa de userinfo/query/fragment |
+| Permisos antes de `init` | Scopes y permisos efectivos; rol de solo lectura demostrado falla; `triage` permite gestionar Issues |
+| Reanudación | Regex del contrato visible, cronología completa y veredictos con `outcome` |
+| Memoria | Esquema v2 con validación/invariantes y migración automática v1→v2 al guardar; escritura atómica, 0600 |
+| Exclusión | Lock con dueño y heartbeat automático durante red; `ensure_owner()` antes de efectos remotos y escrituras |
+| `ERROR` | `resume` registra autorización y solo permite reintentar el paso fallido |
+| Red | Respuesta perdida o 500/502/503/504 en POST → reconciliación por UUID y un reintento |
+| Recuperación | `adopt` usa token almacenado y conserva ERROR/CANCELADO/ABORTED; `init` recupera por título paginado |
+| Contexto | Varios activos o varios estados para `clear` → `CONTEXT_AMBIGUOUS` |
+
+### 4.6 Pruebas
+
+La suite descubre **141 pruebas**: **140 offline** y una integración real
+omitida por defecto. Las pruebas offline usan stdlib, `FakeGateway`, inyección
+de fallos, subprocesos CLI e instaladores reales en directorios temporales.
+Cubren los formatos visibles, máquina de estados, reconciliación con UUID y
+5xx, cancelaciones, procesos sin plan, heartbeat, migración v1→v2, esquema,
+contexto ambiguo, seguridad, rollback y contrato JSON.
+
+```bash
+python3 tests/test_tracking.py
+# Ran 141 tests ... OK (skipped=1)
+python3 tools/check_docs.py
+```
+
+La integración real es opt-in, crea un Issue y 105 notas para ejercitar
+paginación, pérdida/recuperación con `adopt` y cierre. Requiere autorización
+explícita y un repositorio desechable:
+
+```bash
+GITHUB_TRACKING_INTEGRATION=1 \
+GITHUB_TRACKING_INTEGRATION_URL=https://github.com/owner/repo-desechable \
+GITHUB_TRACKING_TOKEN=... python3 tests/test_github_integration.py
+```
+
+También acepta `GITHUB_TOKEN` o `GH_TOKEN`. No se ejecuta con la suite normal.
+
+### 4.7 Límites operativos conocidos
+
+- **Concurrencia:** el lock protege escrituras locales y mantiene heartbeat;
+  no hay transacciones distribuidas. Otro actor con acceso puede intervenir
+  manualmente en el Issue.
+- **Comentarios de terceros:** el contrato visible puede imitarse manualmente
+  y se interpreta como evento. Los metadatos UUID solo autentican la
+  reconciliación del intento, no convierten comentarios en eventos firmados.
+- **Paginación:** Issues con >10 000 comentarios → `COMMENTS_TOO_MANY`.
+- **Token en archivo:** opt-in (`--store-token`), 0600 y enmascarado; prefiere
+  variables de entorno o `gh`.
+- **Idempotencia:** `finalize` no duplica su evento terminal. Cada invocación
+  nueva de paso tiene otro UUID; la reconciliación automática solo deduplica
+  los reintentos internos de esa invocación. Consulta `status --remote` antes
+  de repetir manualmente un comando cuyo resultado sea incierto.
+- **CANCELADO vs FINALIZADO:** ambos resultados se preservan en reintentos,
+  `resume`, `adopt`, estado e historial.
+- **Múltiples repos:** usa `--url` cuando haya varios procesos activos o varios
+  estados candidatos para `clear`.

package/bin/build.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * Empaqueta el skill dentro de npm/ para su distribución (prepack):
+ *   github-proyect-tracking/ → npm/skill/   (sin __pycache__/bytecode)
+ *   README.md, LICENSE       → npm/
+ * Se ejecuta automáticamente con `npm pack` / `npm publish` (script prepack).
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const root = path.join(__dirname, '..', '..');
+const src = path.join(root, 'github-proyect-tracking');
+const here = path.join(__dirname, '..');
+const dst = path.join(here, 'skill');
+
+if (!fs.existsSync(path.join(src, 'SKILL.md'))) {
+  console.error(`ERROR: no se encontró ${src}/SKILL.md`);
+  process.exit(1);
+}
+
+fs.rmSync(dst, { recursive: true, force: true });
+fs.cpSync(src, dst, { recursive: true });
+
+(function clean(dir) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (e.name === '__pycache__') fs.rmSync(p, { recursive: true, force: true });
+      else clean(p);
+    } else if (/\.py[co]$/.test(e.name)) {
+      fs.rmSync(p, { force: true });
+    }
+  }
+})(dst);
+
+fs.copyFileSync(path.join(root, 'README.md'), path.join(here, 'README.md'));
+fs.copyFileSync(path.join(root, 'LICENSE'), path.join(here, 'LICENSE'));
+
+console.log(`skill → ${dst}`);
+console.log('README.md + LICENSE → npm/');