github-proyect-tracking 0.5.0 → 0.6.0

package/README.md

@@ -6,6 +6,12 @@ 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.6.0** — el Issue documenta QUÉ y CON QUÉ: `--process-name` nombra
+> el proceso (título `[Process Tracking][N] …`) y `--process-inputs
+> '{"k":"v",…}` publica los parámetros de entrada del proceso en una
+> sección del cuerpo (secretos redactados) — la única forma de saber
+> exactamente qué tarea estaba realizando la ejecución.
+>
 > **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
@@ -22,7 +28,14 @@ caída de sesión, reinicio), el skill reanuda exactamente donde quedó leyendo
 `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}`.
+- **Un Issue por ejecución**, titulado
+  `[Process Tracking][{proceso}] Execution ID: {id}` — el nombre del proceso
+  (skill padre) se declara con `--process-name` y deja claro **qué** se
+  rastrea; sin él se conserva el formato legado
+  `[Process Tracking] Execution ID: {id}`.
+- **Parámetros de entrada del proceso** (`--process-inputs '{"k":"v",…}`): se
+  publican en la sección "Parámetros de entrada" del cuerpo del Issue — la
+  constancia de **con qué** se ejecutó la tarea (secretos redactados).
 - **Cada transición del proceso es un comentario** con un contrato visible
   cerrado y sin ambigüedades:
 
@@ -54,6 +67,7 @@ transición. No hay dependencias de terceros: solo Python 3.8+ (stdlib);
 | | |
 |---|---|
 | Entrada obligatoria | `github_project_url` — `https://github.com/{owner}/{repo}` |
+| Identificación del proceso | `--process-name N` (skill padre; título del Issue) y `--process-inputs JSON` (parámetros de entrada, sección del cuerpo) — ambos opcionales pero recomendados |
 | 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 |
@@ -171,7 +185,7 @@ cp -R github-proyect-tracking/ ~/.hermes/profiles/<perfil>/skills/software-devel
 ### Ejecutar las pruebas
 
 ```bash
-python3 tests/test_tracking.py    # 157 pruebas: 140 offline + 1 skip opt-in
+python3 tests/test_tracking.py    # 172 pruebas: 140 offline + 1 skip opt-in
 ```
 
 ---
@@ -334,9 +348,48 @@ code documentado:
 ```json
 { "ok": true, "action": "INIT", "execution_id": "exec-20261028T101500Z-ab12cd34ef56",
   "issue_number": 42, "issue_url": "https://github.com/o/r/issues/42",
+  "process_name": "Mi Skill", "issue_title": "[Process Tracking][Mi Skill] Execution ID: exec-20261028T101500Z-ab12cd34ef56",
+  "process_inputs": { "archivo": "datos.csv", "modo": "lint" },
   "state_file": "~/.github-proyect-tracking/o__r.json", "first_step": "Paso 1" }
 ```
 
+`process_name` y `process_inputs` son `null` cuando no se pasaron las
+opciones correspondientes.
+
+### Ejemplo del Issue generado
+
+Con `init --url … --process-name "Mi Skill" --process-inputs
+'{"archivo":"datos.csv","modo":"lint"}' --plan '["Paso 1","Paso 2"]'`:
+
+```markdown
+[Process Tracking][Mi Skill] Execution ID: exec-20261030T153448Z-9071da2dae76
+```
+*(título)* — y el cuerpo:
+
+```markdown
+Proceso rastreado por el skill `github-proyect-tracking`.
+
+- **Execution ID:** `exec-20261030T153448Z-9071da2dae76`
+- **Proceso:** Mi Skill
+- **Proyecto:** https://github.com/o/r
+- **Iniciado (UTC):** 2026-10-30T15:34:48+00:00
+
+## Parámetros de entrada
+
+- **archivo:** `datos.csv`
+- **modo:** `lint`
+
+## Plan de pasos
+
+1. Paso 1
+2. Paso 2
+
+> El avance se registra como comentarios con el contrato `[STATUS: ...]`.
+> El ÚLTIMO comentario es la fuente de verdad para reanudar.
+```
+
+Ejemplo de error (JSON con `ok: false` + exit code documentado):
+
 ```json
 { "ok": false, "error": { "code": "RESUME_REQUIRED", "message": "...",
                           "state": { "...": "..." }, "next": ["resume"] } }
@@ -361,7 +414,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] [--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 |
+| `init --url URL [--plan JSON \| --plan-file F] [--token T] [--store-token] [--process-name N] [--process-inputs JSON]` | Crea el Issue y la memoria (plan sanitizado; `N` = skill padre en título/cuerpo; JSON = parámetros de entrada del proceso, publicados en el Issue con secretos redactados) | 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 |
@@ -414,7 +467,7 @@ rechazan.
 
 ### 4.6 Pruebas
 
-La suite descubre **157 pruebas**: **140 offline** y una integración real
+La suite descubre **172 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
@@ -423,7 +476,7 @@ contexto ambiguo, seguridad, rollback y contrato JSON.
 
 ```bash
 python3 tests/test_tracking.py
-# Ran 157 tests ... OK (skipped=1)
+# Ran 172 tests ... OK (skipped=1)
 python3 tools/check_docs.py
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-proyect-tracking",
-  "version": "0.5.0",
+  "version": "0.6.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.5.0
+version: 0.6.0
 author: Rommel (rommelmg), Hermes Agent
 license: MIT
 platforms: [linux, macos, windows]
@@ -100,6 +100,10 @@ exit 0) y `KeyboardInterrupt` (130).
    `--process-name "Mi Skill"`: el título del Issue pasa a
    `[Process Tracking][Mi Skill] Execution ID: …` y el cuerpo incluye
    `- **Proceso:** Mi Skill` — así el Issue identifica QUÉ se rastrea.
+   Para dejar constancia de CON QUÉ se ejecutó, añade `--process-inputs
+   '{"archivo":"x.csv","modo":"lint"}'` (objeto clave→valor; se publica
+   en la sección "Parámetros de entrada" del Issue, con secretos
+   redactados).
    Si devuelve `RESUME_REQUIRED` (exit 7), NO crees otro Issue: ve al
    paso 3. Criterio: `execution_id`, `process_name` e `issue_url` en la
    salida.

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] [--process-name N]`
+### `init --url URL [--plan JSON | --plan-file F] [--token T] [--prompt-token] [--store-token] [--process-name N] [--process-inputs JSON]`
 
 - Valida la URL (regex, redactada en errores), resuelve el token, valida
   `issues:write` ANTES de crear nada.
@@ -59,7 +59,15 @@ texto y los usa para reconciliar únicamente el intento que originó el POST.
   `- **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`.
+- `--process-inputs JSON`: objeto clave→valor con los parámetros de
+  entrada del proceso. Se publican en la sección "Parámetros de entrada"
+  del cuerpo del Issue (ordenados por clave, valores entre backticks) y
+  se guardan en el estado (`process_inputs`) y en la salida de `init`
+  (`process_inputs`). Secretos en claves/valores se REDACTAN; límites:
+  50 pares, valores ≤ 2000 caracteres; claves vacías, JSON inválido o no
+  objeto → `VALIDATION_ERROR`. Sin la opción, el estado queda limpio
+  (`process_inputs: null`) y el cuerpo no tiene la sección.
+- Salida de `init`: añade `process_name`, `process_inputs` e `issue_title`.
 
 Salida: `execution_id`, `issue_number`, `issue_url`, `state_file`, `plan`,
 `first_step`, `token_source`.

package/skill/scripts/tracking.py

@@ -101,6 +101,11 @@ def build_parser():
     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("--process-inputs", default=None, metavar="JSON",
+                           help='parámetros de entrada del proceso (objeto '
+                                "clave→valor, se publican en el Issue; los "
+                                "secretos se redactan), ej. \'{\"archivo\": "
+                                '\"datos.csv\"}\'')
     subparser.add_argument("--prompt-token", action="store_true",
                            help="pedir el token interactivamente (TTY)")
     subparser.add_argument("--store-token", action="store_true",

package/skill/scripts/tracking_core/commands.py

@@ -97,6 +97,47 @@ def load_plan(args):
     return plan
 
 
+MAX_INPUTS_COUNT = 50
+MAX_INPUT_VALUE_LEN = 2000
+
+
+def load_process_inputs(args):
+    """Valida y normaliza --process-inputs (objeto JSON clave→valor).
+
+    - claves y valores se convierten a cadena; claves vacías se rechazan
+    - secretos en valores (y claves) se REDACTAN antes de guardar/publicar
+    - valores se truncan a MAX_INPUT_VALUE_LEN; máx MAX_INPUTS_COUNT pares
+    - devuelve None cuando no se pasó la opción (mantiene el estado limpio)
+    """
+    raw = getattr(args, "process_inputs", None)
+    if raw is None:
+        return None
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as error:
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         f"--process-inputs no es JSON válido: {error}")
+    if not isinstance(data, dict):
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         "--process-inputs debe ser un objeto JSON "
+                         "clave→valor, ej. '{\"archivo\": \"x.csv\", "
+                         "\"modo\": \"lint\"}'")
+    if len(data) > MAX_INPUTS_COUNT:
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         f"--process-inputs no puede exceder "
+                         f"{MAX_INPUTS_COUNT} pares")
+    inputs = {}
+    for key, value in data.items():
+        clean_key, _ = sanitize_text(str(key).strip())
+        clean_key = clean_key.strip()
+        if not clean_key:
+            raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                             "--process-inputs: las claves no pueden ser vacías")
+        clean_value, _ = sanitize_text(str(value))
+        inputs[clean_key] = clean_value[:MAX_INPUT_VALUE_LEN]
+    return inputs or None
+
+
 def _remote_snapshot(owner, repo, number, token):
     issue = github.fetch_issue(owner, repo, number, token)
     comments = github.fetch_all_comments(owner, repo, number, token)
@@ -127,6 +168,7 @@ def cmd_init(args):
     path = state_file_for(owner, repo)
     plan = load_plan(args)
     process_name = normalize_process_name(getattr(args, "process_name", None))
+    process_inputs = load_process_inputs(args)
 
     lock = StateLock(path)
     with lock:
@@ -158,7 +200,8 @@ def cmd_init(args):
         execution_id = new_execution_id()
         title = issue_title(execution_id, process_name)
         body = build_issue_body(args.url.strip(), execution_id, plan,
-                                process_name=process_name)
+                                process_name=process_name,
+                                process_inputs=process_inputs)
         recovered = False
         create_error = None
         lock.ensure_owner()
@@ -206,6 +249,7 @@ def cmd_init(args):
             "active_process_id": number,
             "execution_id": execution_id,
             "process_name": process_name,
+            "process_inputs": process_inputs or None,
             "issue_url": data.get("html_url"),
             "process_state": "RUNNING",
             "current_step": None,
@@ -229,6 +273,7 @@ def cmd_init(args):
             "execution_id": execution_id, "issue_number": number,
             "issue_url": data.get("html_url"), "state_file": str(path),
             "process_name": process_name, "issue_title": title,
+            "process_inputs": process_inputs or None,
             "plan": plan, "first_step": plan[0] if plan else None,
             "recovered": recovered,
             "token_source": source, "token_stored": bool(state["github_token"]),

package/skill/scripts/tracking_core/common.py

@@ -7,7 +7,7 @@ import re
 import uuid
 from datetime import datetime, timezone
 
-VERSION = "0.5.0"
+VERSION = "0.6.0"
 API_BASE = "https://api.github.com"
 USER_AGENT = f"github-proyect-tracking/{VERSION}"
 

package/skill/scripts/tracking_core/events.py

@@ -98,7 +98,22 @@ def events_from_comments(comments):
     return events
 
 
-def build_issue_body(url, execution_id, plan, process_name=None):
+def _normalized_inputs(process_inputs):
+    """Normaliza los parámetros de entrada a pares (clave, valor) ordenados,
+    con ambos convertidos a cadena. Devuelve [] si no hay inputs."""
+    if not process_inputs:
+        return []
+    if not isinstance(process_inputs, dict):
+        return []
+    entries = []
+    for key in sorted(process_inputs, key=str):
+        value = process_inputs[key]
+        entries.append((str(key).strip(), str(value)))
+    return [(k, v) for k, v in entries if k]
+
+
+def build_issue_body(url, execution_id, plan, process_name=None,
+                     process_inputs=None):
     lines = [
         "Proceso rastreado por el skill `github-proyect-tracking`.",
         "",
@@ -109,6 +124,16 @@ def build_issue_body(url, execution_id, plan, process_name=None):
     lines += [
         f"- **Proyecto:** {url}",
         f"- **Iniciado (UTC):** {now_iso()}",
+    ]
+
+    # v0.6.0: parámetros de entrada del proceso — la única forma de saber
+    # exactamente qué tarea estaba realizando esta ejecución.
+    entries = _normalized_inputs(process_inputs)
+    if entries:
+        lines += ["", "## Parámetros de entrada", ""]
+        lines += [f"- **{key}:** `{value}`" for key, value in entries]
+
+    lines += [
         "",
         "## Plan de pasos",
     ]