github-proyect-tracking 0.4.1 → 0.5.0

package/README.md

@@ -6,11 +6,14 @@ 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.
+> **v0.5.0** — el Issue ahora identifica el proceso rastreado:
+> `init --process-name "Mi Skill"` produce el título
+> `[Process Tracking][Mi Skill] Execution ID: …` y el cuerpo incluye
+> `- **Proceso:** Mi Skill` (compatibilidad total con Issues anteriores).
+> Conserva las correcciones de `Review_V3.md` (v0.4.x): resultados
+> terminales derivados del Issue, recuperación explícita tras `ERROR`,
+> reconciliación por UUID, heartbeat, esquema v2 con migración e
+> instaladores transaccionales.
 
 ---
 
@@ -145,7 +148,7 @@ npm publish        # prepack empaqueta skill/ + README + LICENSE automáticament
 ```
 
 `npm pack` genera el tarball verificable de forma idéntica
-(`npx --yes ./npm/github-proyect-tracking-0.4.0.tgz install`).
+(`npx --yes ./npm/github-proyect-tracking-0.5.0.tgz install`).
 
 ### Desinstalación
 
@@ -168,7 +171,7 @@ cp -R github-proyect-tracking/ ~/.hermes/profiles/<perfil>/skills/software-devel
 ### Ejecutar las pruebas
 
 ```bash
-python3 tests/test_tracking.py    # 141 pruebas: 140 offline + 1 skip opt-in
+python3 tests/test_tracking.py    # 157 pruebas: 140 offline + 1 skip opt-in
 ```
 
 ---
@@ -358,7 +361,7 @@ Excepciones documentadas al contrato "un JSON por comando": `--help`/
 
 | 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 |
+| `init --url URL [--plan JSON \| --plan-file F] [--token T] [--store-token] [--process-name N]` | Crea el Issue y la memoria (plan sanitizado; `N` = skill padre, aparece en título/cuerpo del Issue) | 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 |
@@ -411,7 +414,7 @@ rechazan.
 
 ### 4.6 Pruebas
 
-La suite descubre **141 pruebas**: **140 offline** y una integración real
+La suite descubre **157 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
@@ -420,7 +423,7 @@ contexto ambiguo, seguridad, rollback y contrato JSON.
 
 ```bash
 python3 tests/test_tracking.py
-# Ran 141 tests ... OK (skipped=1)
+# Ran 157 tests ... OK (skipped=1)
 python3 tools/check_docs.py
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-proyect-tracking",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "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"

package/skill/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: github-proyect-tracking
 description: Track process execution state in GitHub Issues with resume.
-version: 0.4.0
+version: 0.5.0
 author: Rommel (rommelmg), Hermes Agent
 license: MIT
 platforms: [linux, macos, windows]
@@ -69,7 +69,7 @@ python3 "$SKILL" doctor --url https://github.com/OWNER/REPO --token "$GITHUB_TOK
 
 | Comando | Efecto |
 |---|---|
-| `init --url URL [--plan JSON] [--store-token]` | Valida URL+token, crea el Issue, guarda `active_process_id` |
+| `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) |
@@ -95,9 +95,14 @@ exit 0) y `KeyboardInterrupt` (130).
    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.
+   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.
+   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

package/skill/references/api.md

@@ -42,7 +42,7 @@ 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]`
+### `init --url URL [--plan JSON | --plan-file F] [--token T] [--prompt-token] [--store-token] [--process-name N]`
 
 - Valida la URL (regex, redactada en errores), resuelve el token, valida
   `issues:write` ANTES de crear nada.
@@ -54,6 +54,12 @@ texto y los usa para reconciliar únicamente el intento que originó el POST.
   `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`.
+- Salida de `init`: añade `process_name` e `issue_title`.
 
 Salida: `execution_id`, `issue_number`, `issue_url`, `state_file`, `plan`,
 `first_step`, `token_source`.

package/skill/scripts/tracking.py

@@ -95,9 +95,12 @@ def build_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"]\'')
+                           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("--process-name", default=None, metavar="N",
+                           help="nombre del proceso/skill padre que se rastrea "
+                                "(aparece en el título y cuerpo del Issue)")
     subparser.add_argument("--prompt-token", action="store_true",
                            help="pedir el token interactivamente (TTY)")
     subparser.add_argument("--store-token", action="store_true",
@@ -153,6 +156,9 @@ def build_parser():
     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("--process-name", default=None, metavar="N",
+                           help="nombre del proceso a adoptar (filtro adicional "
+                                "opcional si hay ambigüedad)")
     subparser.add_argument("--force", action="store_true",
                            help="reemplazar un proceso activo existente (conserva token "
                                 "e historial)")

package/skill/scripts/tracking_core/commands.py

@@ -14,8 +14,9 @@ from .common import (
     EXIT_RESUME_REQUIRED, EXIT_RUNTIME, EXIT_TOKEN_INSUFFICIENT,
     EXIT_VALIDATION, MAX_DETAILS_LEN, MAX_PLAN_STEPS, SCHEMA_VERSION,
     STATUS_CANCELADO, STATUS_COMPLETADO, STATUS_ERROR, STATUS_FINALIZADO,
-    STATUS_INICIANDO, SkillError, emit, new_execution_id, normalize_step_name,
-    now_iso, ordered_unique, redact_url, sanitize_text, validate_repo_url,
+    STATUS_INICIANDO, TITLE_RE, SkillError, emit, new_execution_id,
+    normalize_process_name, normalize_step_name, now_iso, ordered_unique,
+    issue_title, redact_url, sanitize_text, validate_repo_url,
 )
 from .events import (
     build_issue_body, events_from_comments, fmt_cancelado, fmt_completado,
@@ -125,6 +126,7 @@ def cmd_init(args):
     owner, repo = target
     path = state_file_for(owner, repo)
     plan = load_plan(args)
+    process_name = normalize_process_name(getattr(args, "process_name", None))
 
     lock = StateLock(path)
     with lock:
@@ -154,8 +156,9 @@ def cmd_init(args):
         store = bool(args.store_token) and source in ("cli", "prompt")
 
         execution_id = new_execution_id()
-        title = f"[Process Tracking] Execution ID: {execution_id}"
-        body = build_issue_body(args.url.strip(), execution_id, plan)
+        title = issue_title(execution_id, process_name)
+        body = build_issue_body(args.url.strip(), execution_id, plan,
+                                process_name=process_name)
         recovered = False
         create_error = None
         lock.ensure_owner()
@@ -202,6 +205,7 @@ def cmd_init(args):
             "owner": owner, "repo": repo,
             "active_process_id": number,
             "execution_id": execution_id,
+            "process_name": process_name,
             "issue_url": data.get("html_url"),
             "process_state": "RUNNING",
             "current_step": None,
@@ -224,6 +228,7 @@ def cmd_init(args):
             "ok": True, "action": "INIT",
             "execution_id": execution_id, "issue_number": number,
             "issue_url": data.get("html_url"), "state_file": str(path),
+            "process_name": process_name, "issue_title": title,
             "plan": plan, "first_step": plan[0] if plan else None,
             "recovered": recovered,
             "token_source": source, "token_stored": bool(state["github_token"]),
@@ -653,8 +658,9 @@ def cmd_adopt(args):
     existing = load_state(path)
     token, _ = need_token(args, existing)
 
-    query = (f'repo:{owner}/{repo} "[Process Tracking] Execution ID: {execution_id}" '
-             f'in:title is:issue')
+    # v0.5.0: el título puede incluir [Nombre]; se busca por el execution_id
+    # (único) y el filtrado canónico exacto lo hace canonical_title_match.
+    query = f'repo:{owner}/{repo} "{execution_id}" in:title is:issue'
     status, data, _ = github.api(
         "GET", "/search/issues?" + urllib.parse.urlencode({"q": query, "per_page": 30}),
         token)
@@ -662,8 +668,10 @@ def cmd_adopt(args):
         raise SkillError(EXIT_RUNTIME, "SEARCH_FAILED",
                          f"búsqueda de Issues devolvió {status}: "
                          f"{data.get('message', '')}")
+    process_name = normalize_process_name(getattr(args, "process_name", None))
     matches = [issue for issue in (data.get("items") or [])
-               if github.canonical_title_match(issue, execution_id)]
+               if github.canonical_title_match(issue, execution_id,
+                                               process_name=process_name)]
     if not matches:
         raise SkillError(EXIT_NOT_FOUND, "ISSUE_NOT_FOUND",
                          f"no se encontró un Issue con título canónico para "
@@ -691,6 +699,10 @@ def cmd_adopt(args):
         plan = parse_plan_from_body(issue.get("body") or "")
         verdict = plan_resume(events, plan, issue.get("state", "open"))
         action = verdict["action"]
+        title_match = TITLE_RE.match((issue.get("title") or "").strip())
+        adopted_name = (title_match.group("process_name")
+                        if title_match and title_match.group("process_name")
+                        else None)
         if issue.get("state") == "open":
             active = number
             process_state = ("ERROR" if events and events[-1]["status"] == STATUS_ERROR
@@ -708,6 +720,7 @@ def cmd_adopt(args):
             "owner": owner, "repo": repo,
             "active_process_id": active,
             "execution_id": execution_id,
+            "process_name": process_name or adopted_name,
             "issue_url": issue.get("html_url"),
             "process_state": process_state,
             "current_step": verdict.get("resume_from_step"),
@@ -727,7 +740,9 @@ def cmd_adopt(args):
             "ok": True, "action": "ADOPT", "execution_id": execution_id,
             "issue_number": number, "issue_url": issue.get("html_url"),
             "issue_state": issue.get("state"), "verdict": verdict,
-            "process_state": process_state, "state_file": str(path),
+            "process_state": process_state,
+            "process_name": process_name or adopted_name,
+            "state_file": str(path),
         })
     return EXIT_OK
 

package/skill/scripts/tracking_core/common.py

@@ -7,7 +7,7 @@ import re
 import uuid
 from datetime import datetime, timezone
 
-VERSION = "0.4.0"
+VERSION = "0.5.0"
 API_BASE = "https://api.github.com"
 USER_AGENT = f"github-proyect-tracking/{VERSION}"
 
@@ -47,10 +47,18 @@ REPO_URL_RE = re.compile(
     r"(?P<repo>[A-Za-z0-9._-]+?)(?:\.git)?/?$",
     re.IGNORECASE,
 )
+# Título dual (v0.5.0): con o sin nombre de proceso.
+#   [Process Tracking][Mi Skill] Execution ID: exec-...
+#   [Process Tracking] Execution ID: exec-...           (formato <=0.4.x)
 TITLE_RE = re.compile(
-    r"^\[Process Tracking\]\s*(?:-\s*)?Execution ID:\s*(?P<exec_id>\S+?)\s*$",
+    r"^\[Process Tracking\]"
+    r"(?:\[(?P<process_name>"
+    r"(?:[^\[\]\r\n]|\[RED[Aa]ctado:[^\[\]]*\]){1,200}"
+    r")\])?"
+    r"\s*(?:-\s*)?Execution ID:\s*(?P<exec_id>\S+?)\s*$",
     re.IGNORECASE,
 )
+MAX_PROCESS_NAME_LEN = 100
 
 SECRET_REDACTIONS = [
     (re.compile(r"(?i)\b(authorization|proxy-authorization)\s*[:=]\s*"
@@ -68,6 +76,43 @@ SECRET_REDACTIONS = [
 ]
 
 
+def normalize_process_name(name):
+    """Normaliza el nombre del proceso (skill padre) para título y cuerpo
+    del Issue. Orden V2-aprendido: validar la entrada CRUDA (longitud y
+    corchetes) ANTES de sanitizar — los marcadores [REDactado:...] que
+    introduce la sanitización son legítimos y TITLE_RE los acepta."""
+    if name is None:
+        return None
+    text = str(name).strip()
+    if not text:
+        return None
+    if len(text) > MAX_PROCESS_NAME_LEN:
+        raise SkillError(
+            EXIT_VALIDATION, "VALIDATION_ERROR",
+            f"el nombre del proceso no puede exceder {MAX_PROCESS_NAME_LEN} "
+            f"caracteres (recibido: {len(text)})")
+    if any(ch in text for ch in "[]\r\n"):
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         "el nombre del proceso no puede contener '[', ']' "
+                         "ni saltos de línea (rompe el título canónico)")
+    clean, _ = sanitize_text(text)
+    clean = clean.strip()
+    if not clean:
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         "el nombre del proceso quedó vacío tras sanitizar")
+    return clean
+
+
+def issue_title(execution_id, process_name=None):
+    """Título canónico del Issue con el nombre del proceso (v0.5.0).
+    El nombre debe venir YA normalizado (normalize_process_name); aquí no
+    se re-valida porque los marcadores [REDactado:...] son legítimos."""
+    if process_name:
+        return f"[Process Tracking][{process_name}] Execution ID: {execution_id}"
+    return f"[Process Tracking] Execution ID: {execution_id}"
+
+
+
 class SkillError(Exception):
     """Error operativo que se serializa como un único objeto JSON."""
 

package/skill/scripts/tracking_core/events.py

@@ -98,11 +98,15 @@ def events_from_comments(comments):
     return events
 
 
-def build_issue_body(url, execution_id, plan):
+def build_issue_body(url, execution_id, plan, process_name=None):
     lines = [
         "Proceso rastreado por el skill `github-proyect-tracking`.",
         "",
         f"- **Execution ID:** `{execution_id}`",
+    ]
+    if process_name:
+        lines.append(f"- **Proceso:** {process_name}")
+    lines += [
         f"- **Proyecto:** {url}",
         f"- **Iniciado (UTC):** {now_iso()}",
         "",

package/skill/scripts/tracking_core/github.py

@@ -14,7 +14,7 @@ import uuid
 from .common import (
     AMBIGUOUS_HTTP_STATUSES, API_BASE, EXIT_NOT_FOUND, EXIT_NO_TOKEN,
     EXIT_RUNTIME, EXIT_TOKEN_INSUFFICIENT, MAX_COMMENT_PAGES, TITLE_RE,
-    USER_AGENT, SkillError,
+    USER_AGENT, SkillError, issue_title,
 )
 from .events import events_from_comments, transition_metadata, with_transition_metadata
 
@@ -295,6 +295,7 @@ def close_issue(owner, repo, number, token):
 
 
 def find_issue_by_title(owner, repo, title, token):
+    # v0.5.0: title ya viene construido con issue_title()
     url = (f"{API_BASE}/repos/{owner}/{repo}/issues?state=all&sort=created"
            "&direction=desc&per_page=100")
     seen = set()
@@ -310,6 +311,14 @@ def find_issue_by_title(owner, repo, title, token):
     return None
 
 
-def canonical_title_match(issue, execution_id):
+def canonical_title_match(issue, execution_id, process_name=None):
+    """v0.5.0: casa el título canónico con o sin nombre de proceso; el
+    exec_id debe coincidir EXACTO y, si se indica process_name, también."""
     match = TITLE_RE.match((issue.get("title") or "").strip())
-    return bool(match and match.group("exec_id").lower() == execution_id.lower())
+    if not match or match.group("exec_id").lower() != execution_id.lower():
+        return False
+    if process_name:
+        found = match.group("process_name")
+        if (found or "").strip().lower() != str(process_name).strip().lower():
+            return False
+    return True