github-proyect-tracking 0.0.0-stage → 0.4.1

package/bin/cli.js

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+/**
+ * github-proyect-tracking — instalador tipo npx del skill para Hermes Agent.
+ *
+ *   npx --yes github-proyect-tracking                          (install)
+ *   npx --yes github-proyect-tracking doctor --url https://github.com/{owner}/{repo}
+ *   npx --yes github-proyect-tracking uninstall [--purge-state]
+ *
+ * Comandos: install (por defecto) · doctor · uninstall · run (paso a tracking.py)
+ * Flags:    --dest RUTA · --profile PERFIL · --user · --purge-state · -h/-v
+ *
+ * Sin dependencias npm (Node >= 18). El skill en sí es Python 3.8+ stdlib.
+ * La resolución de destino replica install.sh: HERMES_HOME → perfil activo
+ * (HERMES_PROFILE o la línea "profile:" del AGENT.md del directorio actual)
+ * → perfil default. install.sh y este instalador son intercambiables.
+ */
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const SKILL_NAME = 'github-proyect-tracking';
+const CATEGORY = 'software-development';
+const VERSION = require('../package.json').version;
+const SKILL_SRC = path.join(__dirname, '..', 'skill'); // copia empaquetada
+
+// ---------------------------------------------------------------------------
+// utilidades
+// ---------------------------------------------------------------------------
+
+const log = (m = '') => console.log(m);
+const die = (msg, code = 1) => { console.error(`ERROR: ${msg}`); process.exit(code); };
+
+function pythonCmd() {
+  for (const c of ['python3', 'python']) {
+    const r = spawnSync(c, ['-c', ''], { stdio: 'ignore' });
+    if (!r.error) return c;
+  }
+  return null;
+}
+
+function parseArgs(argv) {
+  const out = { command: null, flags: {}, rest: [] };
+  const valueFlags = new Set(['--dest', '--profile']); // V2-E-12
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') out.flags.help = true;
+    else if (a === '-v' || a === '--version') out.flags.version = true;
+    else if (valueFlags.has(a)) {
+      // V2-E-12: flag que exige valor — sin valor → error de uso (exit 2)
+      const v = argv[i + 1];
+      if (v === undefined || !v.trim() || v.startsWith('-')) {
+        die(`el flag ${a} requiere un valor no vacío (ej. ${a} RUTA)`, 2);
+      }
+      out.flags[a === '--dest' ? 'dest' : 'profile'] = v;
+      i++;
+    }
+    else if (a === '--user') out.flags.user = true;
+    else if (a === '--purge-state') out.flags.purgeState = true;
+    else if (a === '--') { out.rest.push(...argv.slice(i + 1)); break; }
+    else if (a.startsWith('-')) out.rest.push(a);        // p.ej. --url (doctor/run)
+    else if (out.command === null) out.command = a;
+    else out.rest.push(a);
+  }
+  if (out.command === null) out.command = 'install';
+  return out;
+}
+
+function mostRecentProfile(hermesHome) {
+  // último recurso: el perfil con actividad más reciente (Hermes no
+  // persiste "perfil activo" global; en su terminal no hay HERMES_*).
+  const dir = path.join(hermesHome, 'profiles');
+  try {
+    let best = null, bestT = -1;
+    for (const name of fs.readdirSync(dir)) {
+      const p = path.join(dir, name);
+      if (!fs.statSync(p).isDirectory()) continue;
+      const t = fs.statSync(p).mtimeMs;
+      if (t > bestT) { bestT = t; best = name; }
+    }
+    return best;
+  } catch { return null; }
+}
+
+function profileFromAgentMd(cwd) {
+  for (const f of ['AGENT.md', 'AGENTS.md']) {
+    const p = path.join(cwd, f);
+    if (fs.existsSync(p)) {
+      const m = fs.readFileSync(p, 'utf8').match(/^profile\s*[:=]\s*(\S+)/m);
+      if (m) return m[1];
+    }
+  }
+  return null;
+}
+
+function resolveDest(flags) {
+  if (flags.dest) return flags.dest;
+  const hermesHome = process.env.HERMES_HOME || path.join(os.homedir(), '.hermes');
+  if (flags.user || !fs.existsSync(path.join(hermesHome, 'profiles'))) {
+    return path.join(hermesHome, 'skills');
+  }
+  const explicit = Boolean(flags.profile);
+  let profile = flags.profile || process.env.HERMES_PROFILE
+    || profileFromAgentMd(process.cwd());
+  const exists = (p) => fs.existsSync(path.join(hermesHome, 'profiles', p));
+  const available = () => fs.readdirSync(path.join(hermesHome, 'profiles'))
+    .filter((n) => fs.statSync(path.join(hermesHome, 'profiles', n)).isDirectory());
+  // --profile EXPLÍCITO inexistente → error claro (nunca fallback silencioso)
+  if (explicit && !exists(profile)) {
+    die(`el perfil '${profile}' no existe en ${hermesHome}/profiles/ ` +
+        `(disponibles: ${available().join(', ') || 'ninguno'})`, 2);
+  }
+  // Automático inexistente → elegir uno sensato en vez de abortar:
+  // 1) 'default' si existe, 2) el ÚNICO perfil si solo hay uno.
+  if (!profile || !exists(profile)) {
+    const sugerido = profile;
+    const perfs = available();
+    if (exists('default')) {
+      if (sugerido) {
+        console.error(`ADVERTENCIA: el perfil automático '${sugerido}' no existe; ` +
+                      "usando 'default'");
+      }
+      profile = 'default';
+    } else if (perfs.length === 1) {
+      profile = perfs[0];
+      console.error(`ADVERTENCIA: perfil automático '${sugerido || "(no detectado)"}' ` +
+                    `no disponible; usando el único perfil existente '${profile}'`);
+    } else if (perfs.length > 1) {
+      const recent = mostRecentProfile(hermesHome);
+      if (recent) {
+        profile = recent;
+        console.error(`ADVERTENCIA: no se detectó perfil ` +
+                      `(${sugerido ? `'${sugerido}' no existe` : 'sin HERMES_PROFILE ni AGENT.md'}); ` +
+                      `usando el de actividad más reciente '${profile}'. ` +
+                      'Usa --profile PERFIL para elegirlo explícitamente');
+      } else {
+        die(`no se pudo determinar el perfil: ${sugerido
+          ? `'${sugerido}' no existe` : 'no se detectó (ejecuta desde el repo o define HERMES_PROFILE)'}. ` +
+          `Perfiles disponibles: ${perfs.join(', ')}. ` +
+          'Usa --profile PERFIL o --dest RUTA', 2);
+      }
+    } else {
+      die(`no hay perfiles de Hermes en ${hermesHome}/profiles/; ` +
+          'usa --dest RUTA para indicar el destino', 2);
+    }
+  }
+  return path.join(hermesHome, 'profiles', profile, 'skills');
+}
+
+function cleanCaches(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 cleanCaches(p);
+    } else if (/\.py[co]$/.test(e.name)) {
+      fs.rmSync(p, { force: true });
+    }
+  }
+}
+
+function validateFrontmatter(skillDir) {
+  const md = fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf8');
+  if (!md.startsWith('---')) throw new Error('SKILL.md: falta "---" inicial');
+  const rel = md.slice(3).search(/\n---\s*\n/);
+  if (rel < 0) throw new Error('SKILL.md: falta cierre "---"');
+  const fm = md.slice(3, 3 + rel);
+  const name = (fm.match(/^name:\s*(.+?)\s*$/m) || [])[1];
+  let desc = (fm.match(/^description:\s*(.+?)\s*$/m) || [])[1] || '';
+  if (desc.startsWith('"') && desc.endsWith('"')) desc = desc.slice(1, -1);
+  if (name !== SKILL_NAME) throw new Error(`name=${name} (esperado ${SKILL_NAME})`);
+  if (!desc || desc.length > 60) {
+    throw new Error(`description (${desc.length} chars) vacía o > 60`);
+  }
+}
+
+function verifyTrackingPy(target) {
+  // E-23: la verificación del script es OBLIGATORIA (exit != 0 si falla)
+  const py = pythonCmd();
+  if (!py) throw new Error('python3 no está en PATH; el skill lo requiere');
+  const r = spawnSync(py, [path.join(target, 'scripts', 'tracking.py'), '--version'],
+                      { encoding: 'utf8' });
+  if (r.status !== 0) {
+    throw new Error(`tracking.py --version falló (exit ${r.status}); ` +
+                    'instalación abortada');
+  }
+  return r.stdout.trim();
+}
+
+// ---------------------------------------------------------------------------
+// comandos
+// ---------------------------------------------------------------------------
+
+function install(flags) {
+  if (!fs.existsSync(path.join(SKILL_SRC, 'SKILL.md'))) {
+    die(`paquete corrupto: falta ${SKILL_SRC}/SKILL.md`, 2);
+  }
+  const dest = resolveDest(flags);
+  const target = path.join(dest, CATEGORY, SKILL_NAME);
+  log(`Origen : ${SKILL_SRC}`);
+  log(`Destino: ${target}`);
+
+  const stage = fs.mkdtempSync(path.join(os.tmpdir(), 'gpt-npx-'));
+  const stageSkill = path.join(stage, SKILL_NAME);
+  const unique = `${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}`;
+  const staged = `${target}.new.${unique}`;
+  const bak = `${target}.bak.${unique}`;
+  let swapStarted = false;
+  try {
+    fs.cpSync(SKILL_SRC, stageSkill, { recursive: true });
+    cleanCaches(stageSkill);
+    validateFrontmatter(stageSkill);
+    log('frontmatter: OK (name + description <= 60)');
+    const preVer = verifyTrackingPy(stageSkill);
+    if (preVer) log(preVer);
+
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.cpSync(stageSkill, staged, { recursive: true });
+    if (fs.existsSync(target)) {
+      fs.cpSync(target, bak, { recursive: true });
+      log(`Copia previa respaldada en: ${bak}`);
+    }
+    swapStarted = true;
+    fs.rmSync(target, { recursive: true, force: true });
+    fs.renameSync(staged, target);
+    const ver = verifyTrackingPy(target);
+    if (ver) log(ver);
+  } catch (error) {
+    if (swapStarted) {
+      fs.rmSync(target, { recursive: true, force: true });
+      if (fs.existsSync(bak)) {
+        fs.cpSync(bak, target, { recursive: true });
+        log(`Rollback: restaurado ${bak}`);
+      } else {
+        log('Sin respaldo previo: la copia no usable fue eliminada');
+      }
+    }
+    throw error;
+  } finally {
+    fs.rmSync(stage, { recursive: true, force: true });
+    fs.rmSync(staged, { recursive: true, force: true });
+  }
+
+  const py = pythonCmd();
+  if (!py) {
+    log('ADVERTENCIA: python3 no está en PATH; el skill lo requiere.');
+  } else {
+    const r = spawnSync(py, [path.join(target, 'scripts', 'tracking.py'), '--version'],
+                        { encoding: 'utf8' });
+    if (r.status === 0 && r.stdout) log(r.stdout.trim());
+    else log(`ADVERTENCIA: verificación de tracking.py falló (exit ${r.status})`);
+  }
+
+  log();
+  log('Instalado. Prueba rápida:');
+  log(`  ${py || 'python3'} "${path.join(target, 'scripts', 'tracking.py')}" doctor --url https://github.com/{owner}/{repo}`);
+  log();
+  log('Nota: el skill estará visible para sesiones NUEVAS de Hermes (el catálogo');
+  log('se carga al iniciar sesión). La memoria interna vive en');
+  log('~/.github-proyect-tracking/ (override: $GITHUB_TRACKING_STATE).');
+}
+
+function uninstall(flags) {
+  const dest = resolveDest(flags);
+  const target = path.join(dest, CATEGORY, SKILL_NAME);
+  if (fs.existsSync(target)) {
+    fs.rmSync(target, { recursive: true, force: true });
+    log(`Eliminado: ${target}`);
+    try { fs.rmdirSync(path.dirname(target)); } catch { /* categoría no vacía */ }
+  } else {
+    log(`No hay instalación en: ${target} (nada que desinstalar)`);
+  }
+  if (flags.purgeState) {
+    const stateDir = process.env.GITHUB_TRACKING_STATE
+      || path.join(os.homedir(), '.github-proyect-tracking');
+    if (fs.existsSync(stateDir)) {
+      fs.rmSync(stateDir, { recursive: true, force: true });
+      log(`Memoria interna eliminada: ${stateDir}`);
+    }
+    log('Nota: los Issues creados en GitHub NO se eliminan (permanecen en el repo).');
+  }
+  log('Listo.');
+}
+
+function doctor(flags, rest) {
+  const py = pythonCmd();
+  if (!py) die('python3 no está en PATH (requerido por el skill)');
+  const candidates = [
+    path.join(resolveDest(flags), CATEGORY, SKILL_NAME, 'scripts', 'tracking.py'),
+    path.join(SKILL_SRC, 'scripts', 'tracking.py'),
+  ];
+  const script = candidates.find((p) => fs.existsSync(p));
+  if (!script) die('no se encontró tracking.py (¿paquete corrupto?)', 2);
+  const r = spawnSync(py, [script, 'doctor', ...rest], { stdio: 'inherit' });
+  process.exit(r.status === null ? 1 : r.status);
+}
+
+function run(flags, rest) {
+  const py = pythonCmd();
+  if (!py) die('python3 no está en PATH (requerido por el skill)');
+  const candidates = [
+    path.join(resolveDest(flags), CATEGORY, SKILL_NAME, 'scripts', 'tracking.py'),
+    path.join(SKILL_SRC, 'scripts', 'tracking.py'),
+  ];
+  const script = candidates.find((p) => fs.existsSync(p));
+  if (!script) die('no se encontró tracking.py (¿paquete corrupto?)', 2);
+  const r = spawnSync(py, [script, ...rest], { stdio: 'inherit' });
+  process.exit(r.status === null ? 1 : r.status);
+}
+
+// ---------------------------------------------------------------------------
+// ayuda y main
+// ---------------------------------------------------------------------------
+
+function help() {
+  log(`github-proyect-tracking v${VERSION} — instalador npx del skill para Hermes Agent`);
+  log();
+  log('Uso:');
+  log('  npx --yes github-proyect-tracking [install] [flags]     instalar el skill');
+  log('  npx --yes github-proyect-tracking doctor [args…]        diagnóstico (sin instalar)');
+  log('  npx --yes github-proyect-tracking run <cmd> [args…]     ejecutar un comando del skill');
+  log('  npx --yes github-proyect-tracking uninstall [flags]     desinstalar');
+  log();
+  log('Flags:');
+  log('  --dest RUTA       destino explícito (directorio padre de skills)');
+  log('  --profile PERFIL  perfil de Hermes (~/.hermes/profiles/<p>/skills)');
+  log('  --user            ~/.hermes/skills del perfil por defecto');
+  log('  --purge-state     (uninstall) borra también ~/.github-proyect-tracking/');
+  log('  -h, --help        esta ayuda');
+  log('  -v, --version     versión del paquete');
+  log();
+  log('El destino por defecto se resuelve igual que install.sh: HERMES_HOME,');
+  log('perfil activo (HERMES_PROFILE o la línea "profile:" del AGENT.md del');
+  log('directorio actual) y, si no, el perfil default. Requisitos: Node >= 18');
+  log('para este instalador; Python 3.8+ (stdlib) para el skill.');
+}
+
+function main() {
+  const { command, flags, rest } = parseArgs(process.argv.slice(2));
+  if (flags.version) { log(`github-proyect-tracking/${VERSION} (instalador npx)`); return; }
+  if (flags.help) { help(); return; }
+  if (!['doctor', 'run'].includes(command) && rest.length) {
+    die(`argumentos no reconocidos para ${command}: ${rest.join(' ')}`, 2);
+  }
+  if (command === 'install' && flags.purgeState) {
+    die('--purge-state solo es válido con uninstall', 2);
+  }
+  switch (command) {
+    case 'install': install(flags); break;
+    case 'uninstall': uninstall(flags); break;
+    case 'doctor': doctor(flags, rest); break;
+    case 'run': run(flags, rest); break;
+    default: die(`comando desconocido: ${command} (usa --help)`, 2);
+  }
+}
+
+main();

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "github-proyect-tracking",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.1",
+  "description": "Instalador npx del skill github-proyect-tracking para Hermes Agent: rastrea el estado de procesos en GitHub Issues con reanudacion.",
+  "bin": {
+    "github-proyect-tracking": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "skill/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node bin/build.js",
+    "prepack": "node bin/build.js"
+  },
+  "keywords": [
+    "hermes-agent",
+    "skill",
+    "github",
+    "issues",
+    "tracking",
+    "state-machine",
+    "resume"
+  ],
+  "author": "Rommel (https://github.com/rommelmg)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rommelmg/KGithubTracking.git"
+  },
+  "private": false
+}

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