github-proyect-tracking 0.0.0-stage → 0.4.1

package/skill/scripts/tracking_core/commands.py

@@ -0,0 +1,846 @@
+"""Implementación de comandos sobre una instantánea remota coherente."""
+
+from __future__ import annotations
+
+import getpass
+import json
+import sys
+import urllib.parse
+from pathlib import Path
+
+from . import github
+from .common import (
+    EXIT_CONFLICT, EXIT_NO_PROCESS, EXIT_NO_TOKEN, EXIT_NOT_FOUND, EXIT_OK,
+    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,
+)
+from .events import (
+    build_issue_body, events_from_comments, fmt_cancelado, fmt_completado,
+    fmt_error, fmt_finalizado, fmt_iniciando, parse_plan_from_body, plan_resume,
+    _validate_resume_plan,
+)
+from .state import (
+    StateLock, is_unfinished, list_state_files, load_state, public_state,
+    save_state, select_state_path, state_dir, state_file_for,
+)
+
+
+def resolve_target(args):
+    url = getattr(args, "url", None)
+    if url:
+        target = validate_repo_url(url)
+        if not target:
+            raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                             f"github_project_url inválido: {redact_url(url)} "
+                             "(se requiere https://github.com/{owner}/{repo})")
+        owner, repo = target
+        return owner, repo, state_file_for(owner, repo)
+    path = select_state_path()
+    probe = load_state(path)
+    return probe["owner"], probe["repo"], path
+
+
+def load_active_state(path):
+    state = load_state(path)
+    if not (state and state.get("active_process_id")):
+        raise SkillError(EXIT_NO_PROCESS, "NO_ACTIVE_PROCESS",
+                         f"no hay proceso activo en {path}; ejecuta init primero")
+    return state
+
+
+def need_token(args, state=None):
+    token, source = github.resolve_token(getattr(args, "token", None), state)
+    if not token:
+        raise SkillError(EXIT_NO_TOKEN, "NO_TOKEN",
+                         "no hay token de GitHub disponible. Fuentes aceptadas: "
+                         "--token, $GITHUB_TRACKING_TOKEN, $GITHUB_TOKEN, $GH_TOKEN, "
+                         "'gh auth token' o el archivo de estado (--store-token).",
+                         {"how_to_fix": "pide al usuario un PAT con issues:write y "
+                                        "reintenta con --token o GITHUB_TOKEN"})
+    return token, source
+
+
+def load_plan(args):
+    raw = None
+    if getattr(args, "plan", None):
+        raw = args.plan
+    elif getattr(args, "plan_file", None):
+        try:
+            raw = Path(args.plan_file).read_text(encoding="utf-8")
+        except OSError as error:
+            raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                             f"no se pudo leer --plan-file: {error}")
+    if raw is None:
+        return []
+    try:
+        plan = json.loads(raw)
+    except json.JSONDecodeError as error:
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         f"--plan no es JSON válido: {error}")
+    if not isinstance(plan, list) or not all(isinstance(step, str) for step in plan):
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         '--plan debe ser una lista JSON de cadenas, '
+                         'ej. \'["Paso 1: análisis", "Paso 2: build"]\'')
+    if len(plan) > MAX_PLAN_STEPS:
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         f"el plan no puede exceder {MAX_PLAN_STEPS} pasos")
+    plan = [normalize_step_name(step) for step in plan]
+    if len(plan) != len(set(plan)):
+        duplicates = sorted({step for step in plan if plan.count(step) > 1})
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         f"el plan contiene pasos duplicados (tras normalizar): "
+                         f"{duplicates}; usa nombres únicos")
+    return plan
+
+
+def _remote_snapshot(owner, repo, number, token):
+    issue = github.fetch_issue(owner, repo, number, token)
+    comments = github.fetch_all_comments(owner, repo, number, token)
+    events = events_from_comments(comments)
+    return issue, events, comments
+
+
+def _plan_from_any(state, issue):
+    plan = state.get("plan")
+    if plan is None:
+        plan = parse_plan_from_body(issue.get("body") or "")
+    return _validate_resume_plan(plan)
+
+
+def _completed_from_events(events):
+    return ordered_unique(
+        event["step"] for event in events
+        if event["status"] == STATUS_COMPLETADO and event.get("step"))
+
+
+def cmd_init(args):
+    target = validate_repo_url(args.url)
+    if not target:
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         f"github_project_url inválido: {redact_url(args.url)} "
+                         "(se requiere https://github.com/{owner}/{repo})")
+    owner, repo = target
+    path = state_file_for(owner, repo)
+    plan = load_plan(args)
+
+    lock = StateLock(path)
+    with lock:
+        existing = load_state(path)
+        if is_unfinished(existing):
+            raise SkillError(EXIT_RESUME_REQUIRED, "RESUME_REQUIRED",
+                             f"ya existe un proceso inconcluso (Issue "
+                             f"#{existing['active_process_id']}, estado "
+                             f"{existing['process_state']}) en la memoria interna "
+                             f"para {owner}/{repo}. Ejecuta 'resume' para reanudarlo.",
+                             {"state": public_state(existing), "next": ["resume"]})
+
+        token, source = github.resolve_token(args.token, existing)
+        if not token:
+            if args.prompt_token and sys.stdin.isatty():
+                token = getpass.getpass("GitHub token (issues:write): ")
+                source = "prompt"
+            else:
+                raise SkillError(EXIT_NO_TOKEN, "NO_TOKEN",
+                                 "no hay token de GitHub disponible para crear el Issue.",
+                                 {"how_to_fix": "pide al usuario un PAT con permisos "
+                                                "issues:write y reintenta con --token "
+                                                "o GITHUB_TOKEN"})
+        ok, code, detail = github.check_issues_write(owner, repo, token)
+        if not ok:
+            raise SkillError(EXIT_TOKEN_INSUFFICIENT, code, detail)
+        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)
+        recovered = False
+        create_error = None
+        lock.ensure_owner()
+        try:
+            status, data, _ = github.api(
+                "POST", f"/repos/{owner}/{repo}/issues", token,
+                {"title": title, "body": body})
+            if status in github.AMBIGUOUS_HTTP_STATUSES:
+                create_error = SkillError(
+                    EXIT_RUNTIME, "ISSUE_CREATE_AMBIGUOUS",
+                    f"el servidor devolvió {status}; el Issue pudo haberse creado")
+            elif status not in (200, 201):
+                if status == 403:
+                    raise SkillError(EXIT_TOKEN_INSUFFICIENT, "ISSUES_WRITE_FAILED",
+                                     f"no se pudo crear el Issue (403): "
+                                     f"{data.get('message', '')} — el token no puede "
+                                     "escribir Issues en este repositorio")
+                raise SkillError(EXIT_RUNTIME, "ISSUE_CREATE_FAILED",
+                                 f"no se pudo crear el Issue ({status}): "
+                                 f"{data.get('message', '')}")
+        except SkillError as error:
+            if error.code != "NETWORK_ERROR":
+                raise
+            create_error = error
+        if create_error is not None:
+            issue = github.find_issue_by_title(owner, repo, title, token)
+            if issue is None:
+                extra = dict(create_error.extra)
+                extra.update({
+                    "execution_id": execution_id,
+                    "issue_title": title,
+                    "hint": f"si el Issue existe, recupéralo con: adopt --url "
+                            f"{args.url} --execution-id {execution_id}; no repitas init "
+                            "hasta comprobarlo",
+                })
+                raise SkillError(create_error.exit_code, create_error.code,
+                                 create_error.message, extra)
+            data, recovered = issue, True
+        number = data["number"]
+
+        state = {
+            "schema_version": SCHEMA_VERSION,
+            "github_project_url": f"https://github.com/{owner}/{repo}",
+            "owner": owner, "repo": repo,
+            "active_process_id": number,
+            "execution_id": execution_id,
+            "issue_url": data.get("html_url"),
+            "process_state": "RUNNING",
+            "current_step": None,
+            "completed_steps": [],
+            "plan": plan,
+            "github_token": token if store else (existing or {}).get("github_token"),
+            "created_at": now_iso(),
+            "history": (existing or {}).get("history", []),
+        }
+        lock.ensure_owner()
+        try:
+            save_state(path, state)
+        except SkillError as error:
+            raise SkillError(EXIT_RUNTIME, "STATE_SAVE_FAILED", error.message, {
+                "execution_id": execution_id, "issue_number": number,
+                "issue_url": data.get("html_url"),
+                "hint": f"el Issue se creó pero la memoria local no se guardó; "
+                        f"recupera con: adopt --url {args.url} --execution-id {execution_id}"})
+        emit({
+            "ok": True, "action": "INIT",
+            "execution_id": execution_id, "issue_number": number,
+            "issue_url": data.get("html_url"), "state_file": str(path),
+            "plan": plan, "first_step": plan[0] if plan else None,
+            "recovered": recovered,
+            "token_source": source, "token_stored": bool(state["github_token"]),
+        })
+    return EXIT_OK
+
+
+def cmd_resume(args):
+    owner, repo, path = resolve_target(args)
+    lock = StateLock(path)
+    with lock:
+        state = load_active_state(path)
+        number = state["active_process_id"]
+        token, _ = need_token(args, state)
+        issue, events, comments = _remote_snapshot(owner, repo, number, token)
+        plan = state.get("plan") or parse_plan_from_body(issue.get("body") or "")
+        verdict = plan_resume(events, plan, issue.get("state", "open"))
+
+        action = verdict["action"]
+        if action == "NONE":
+            state["active_process_id"] = None
+            state["process_state"] = (
+                "CANCELADO" if verdict.get("outcome") == "CANCELADO"
+                else "FINALIZED")
+        elif action == "ABORTED_EXTERNALLY":
+            state["active_process_id"] = None
+            state["process_state"] = "ABORTED"
+            state["aborted"] = {"issue_number": number,
+                                "issue_url": issue.get("html_url"),
+                                "at": now_iso()}
+        else:
+            last_event = events[-1] if events else None
+            state["process_state"] = (
+                "ERROR" if last_event and last_event["status"] == STATUS_ERROR
+                else "RUNNING")
+        state["completed_steps"] = verdict.get("completed_steps", [])
+        state["current_step"] = verdict.get("resume_from_step")
+        last_event = events[-1] if events else None
+        state["last_resume"] = {
+            "verdict": action,
+            "at": now_iso(),
+            "issue_number": number,
+            "event_comment_id": last_event.get("comment_id") if last_event else None,
+            "event_transition_id": last_event.get("transition_id") if last_event else None,
+            "failed_step": verdict.get("failed_step"),
+        }
+        lock.ensure_owner()
+        save_state(path, state)
+        emit({
+            "ok": True, "action": "RESUME",
+            "owner": owner, "repo": repo, "issue_number": number,
+            "issue_url": issue.get("html_url"),
+            "issue_state": issue.get("state"),
+            "comment_count": len(comments), "verdict": verdict,
+            "state_file": str(path),
+        })
+    return EXIT_OK
+
+
+def cmd_step_start(args):
+    step = normalize_step_name(args.name)
+    owner, repo, path = resolve_target(args)
+    lock = StateLock(path)
+    with lock:
+        state = load_active_state(path)
+        token, _ = need_token(args, state)
+        number = state["active_process_id"]
+        issue, events, comments = _remote_snapshot(owner, repo, number, token)
+        if issue.get("state") != "open":
+            raise SkillError(EXIT_CONFLICT, "ISSUE_CLOSED_EXTERNALLY",
+                             f"el Issue #{number} fue cerrado externamente",
+                             {"issue_url": issue.get("html_url")})
+        last = events[-1] if events else None
+        if last and last["status"] in (STATUS_FINALIZADO, STATUS_CANCELADO):
+            raise SkillError(EXIT_CONFLICT, "ALREADY_FINALIZED",
+                             f"el último evento remoto es {last['status']}; "
+                             "usa finalize para cerrar y limpiar memoria")
+
+        completed = _completed_from_events(events)
+        plan = _plan_from_any(state, issue)
+        if last and last["status"] == STATUS_ERROR:
+            resumed = state.get("last_resume") or {}
+            authorized = (
+                resumed.get("verdict") == "RERUN_STEP"
+                and resumed.get("issue_number") == number
+                and resumed.get("event_comment_id") == last.get("comment_id")
+                and resumed.get("failed_step") == last.get("step"))
+            if not authorized:
+                raise SkillError(EXIT_RESUME_REQUIRED, "RESUME_REQUIRED",
+                                 "el último evento remoto es ERROR; ejecuta "
+                                 "'resume' antes de reintentar el paso")
+            if step != last.get("step"):
+                raise SkillError(EXIT_VALIDATION, "STEP_OUT_OF_ORDER",
+                                 f"después de ERROR debes reintentar '{last.get('step')}', "
+                                 f"no '{step}'")
+        if last and last["status"] == STATUS_INICIANDO \
+                and last.get("step") and last["step"] != step:
+            raise SkillError(EXIT_VALIDATION, "STEP_IN_FLIGHT",
+                             f"el paso '{last['step']}' está en curso; completa "
+                             "o erra ese paso antes de iniciar otro")
+        if plan:
+            if step in completed:
+                raise SkillError(EXIT_VALIDATION, "STEP_ALREADY_DONE",
+                                 f"el paso '{step}' ya está COMPLETADO",
+                                 {"completed_steps": completed})
+            if step not in plan:
+                raise SkillError(EXIT_VALIDATION, "STEP_NOT_IN_PLAN",
+                                 f"el paso '{step}' no pertenece al plan",
+                                 {"plan": plan})
+            expected = next((item for item in plan if item not in completed), None)
+            if expected and step != expected:
+                raise SkillError(EXIT_VALIDATION, "STEP_OUT_OF_ORDER",
+                                 f"el siguiente paso del plan es '{expected}', "
+                                 f"no '{step}'",
+                                 {"expected_step": expected,
+                                  "completed_steps": completed})
+
+        baseline = frozenset(comment.get("id") for comment in comments)
+        lock.ensure_owner()
+        comment = github.post_comment(
+            owner, repo, number, fmt_iniciando(step), token,
+            baseline_ids=baseline, execution_id=state.get("execution_id"),
+            sequence=len(events) + 1)
+        state["current_step"] = step
+        state["process_state"] = "RUNNING"
+        state["completed_steps"] = completed
+        state["plan"] = plan
+        lock.ensure_owner()
+        try:
+            save_state(path, state)
+        except SkillError as error:
+            raise SkillError(EXIT_RUNTIME, "STATE_SAVE_FAILED", error.message, {
+                "comment_url": comment["comment_url"],
+                "hint": "el comentario se publicó; ejecuta resume para "
+                        "re-sincronizar la memoria desde el Issue"})
+        emit({"ok": True, "action": "STEP_START", "step": step,
+              "issue_number": number,
+              "comment_url": comment["comment_url"],
+              "reconciled": comment["reconciled"],
+              "process_state": "RUNNING", "state_file": str(path)})
+    return EXIT_OK
+
+
+def _step_guard_check(issue, events, number):
+    if issue.get("state") != "open":
+        raise SkillError(EXIT_CONFLICT, "ISSUE_CLOSED_EXTERNALLY",
+                         f"el Issue #{number} fue cerrado externamente",
+                         {"issue_url": issue.get("html_url")})
+    last = events[-1] if events else None
+    if last and last["status"] == STATUS_ERROR:
+        raise SkillError(EXIT_RESUME_REQUIRED, "RESUME_REQUIRED",
+                         "el último evento remoto es ERROR; ejecuta 'resume' "
+                         "antes de cualquier otra transición")
+    if last and last["status"] in (STATUS_FINALIZADO, STATUS_CANCELADO):
+        raise SkillError(EXIT_CONFLICT, "ALREADY_FINALIZED",
+                         f"el último evento remoto es {last['status']}; usa "
+                         "finalize para cerrar y limpiar memoria")
+
+
+def _require_in_flight(last, step, what):
+    if not last or last["status"] != STATUS_INICIANDO \
+            or last.get("step") != step:
+        got = (f"{last['status']} - Paso: {last.get('step')}" if last
+               else "sin eventos")
+        raise SkillError(EXIT_VALIDATION, "NO_STEP_IN_FLIGHT",
+                         f"{what} requiere que el último evento remoto sea "
+                         f"'[STATUS: INICIANDO] - Paso: {step}'; el actual es: {got}. "
+                         "Ejecuta step-start primero (o resume si el estado es incierto)")
+
+
+def _save_after_comment(lock, path, state, comment):
+    lock.ensure_owner()
+    try:
+        save_state(path, state)
+    except SkillError as error:
+        raise SkillError(EXIT_RUNTIME, "STATE_SAVE_FAILED", error.message, {
+            "comment_url": comment["comment_url"],
+            "hint": "el comentario se publicó; ejecuta resume para "
+                    "re-sincronizar la memoria desde el Issue"})
+
+
+def cmd_step_done(args):
+    step = normalize_step_name(args.name)
+    owner, repo, path = resolve_target(args)
+    lock = StateLock(path)
+    with lock:
+        state = load_active_state(path)
+        token, _ = need_token(args, state)
+        number = state["active_process_id"]
+        issue, events, comments = _remote_snapshot(owner, repo, number, token)
+        _step_guard_check(issue, events, number)
+        last = events[-1] if events else None
+        _require_in_flight(last, step, "step-done")
+        baseline = frozenset(comment.get("id") for comment in comments)
+        lock.ensure_owner()
+        comment = github.post_comment(
+            owner, repo, number, fmt_completado(step), token,
+            baseline_ids=baseline, execution_id=state.get("execution_id"),
+            sequence=len(events) + 1)
+        state["current_step"] = None
+        state["process_state"] = "RUNNING"
+        state["completed_steps"] = ordered_unique(
+            _completed_from_events(events) + [step])
+        _save_after_comment(lock, path, state, comment)
+        emit({"ok": True, "action": "STEP_DONE", "step": step,
+              "issue_number": number, "comment_url": comment["comment_url"],
+              "reconciled": comment["reconciled"], "process_state": "RUNNING",
+              "state_file": str(path)})
+    return EXIT_OK
+
+
+def cmd_step_error(args):
+    step = normalize_step_name(args.name)
+    if getattr(args, "details", None):
+        details = args.details
+    elif getattr(args, "details_file", None):
+        try:
+            details = Path(args.details_file).read_text(encoding="utf-8",
+                                                        errors="replace")
+        except OSError as error:
+            raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                             f"no se pudo leer --details-file: {error}")
+    else:
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         "step-error requiere --details o --details-file "
+                         "(mensaje de error o stacktrace)")
+    details = details.strip()
+    if not details:
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         "los detalles del error no pueden estar vacíos")
+    details, redacted = sanitize_text(details)
+    details = details[:MAX_DETAILS_LEN]
+
+    owner, repo, path = resolve_target(args)
+    lock = StateLock(path)
+    with lock:
+        state = load_active_state(path)
+        token, _ = need_token(args, state)
+        number = state["active_process_id"]
+        issue, events, comments = _remote_snapshot(owner, repo, number, token)
+        _step_guard_check(issue, events, number)
+        last = events[-1] if events else None
+        _require_in_flight(last, step, "step-error")
+        baseline = frozenset(comment.get("id") for comment in comments)
+        lock.ensure_owner()
+        comment = github.post_comment(
+            owner, repo, number, fmt_error(step, details), token,
+            baseline_ids=baseline, execution_id=state.get("execution_id"),
+            sequence=len(events) + 1)
+        state["current_step"] = step
+        state["process_state"] = "ERROR"
+        state["last_error"] = {"step": step, "at": now_iso()}
+        _save_after_comment(lock, path, state, comment)
+        output = {"ok": True, "action": "STEP_ERROR", "step": step,
+                  "issue_number": number, "comment_url": comment["comment_url"],
+                  "reconciled": comment["reconciled"],
+                  "process_state": "ERROR", "stopped": True,
+                  "state_file": str(path)}
+        if redacted:
+            output["redacted_secrets"] = redacted
+        emit(output)
+    return EXIT_OK
+
+
+_PENDING_VERDICTS = ("RERUN_STEP", "NEXT_STEP", "START_FIRST",
+                     "NEXT_STEP_AGENT_DEFINED")
+
+
+def cmd_finalize(args):
+    owner, repo, path = resolve_target(args)
+    lock = StateLock(path)
+    with lock:
+        state = load_active_state(path)
+        number = state["active_process_id"]
+        token, _ = need_token(args, state)
+        issue, events, comments = _remote_snapshot(owner, repo, number, token)
+        plan = _plan_from_any(state, issue)
+        verdict = plan_resume(events, plan, issue.get("state", "open"))
+        action = verdict["action"]
+        completed = verdict.get("completed_steps", [])
+        if action == "ABORTED_EXTERNALLY":
+            raise SkillError(EXIT_CONFLICT, "ABORTED_EXTERNALLY",
+                             "el Issue fue cerrado sin comentario de cierre; no "
+                             "se marca como exitoso. Decide con el usuario: "
+                             "reabrir y continuar, o clear --hard para descartar",
+                             {"issue_url": issue.get("html_url"),
+                              "verdict": verdict})
+        last = events[-1] if events else None
+        already_done = bool(last) and last["status"] == STATUS_FINALIZADO
+        already_cancel = bool(last) and last["status"] == STATUS_CANCELADO
+        if last and last["status"] == STATUS_ERROR and not args.force:
+            raise SkillError(EXIT_RESUME_REQUIRED, "RESUME_REQUIRED",
+                             "el último evento remoto es ERROR; ejecuta 'resume' "
+                             "y completa el paso fallido antes de finalizar "
+                             "(o --force para cancelar)")
+
+        no_plan_complete = (not plan and action == "NEXT_STEP_AGENT_DEFINED"
+                            and last and last["status"] == STATUS_COMPLETADO)
+        pending_action = action in _PENDING_VERDICTS and not no_plan_complete
+        if pending_action and not args.force:
+            raise SkillError(EXIT_CONFLICT, "FINALIZE_BLOCKED",
+                             "el proceso no ha completado todos los pasos",
+                             {"verdict": verdict,
+                              "hint": "completa los pasos pendientes, o usa "
+                                      "--force para cancelar ahora "
+                                      "(se registrará CANCELADO, no éxito)"})
+        forced = pending_action and args.force
+        outcome = "CANCELADO" if (forced or already_cancel) else "FINALIZADO"
+
+        lock.ensure_owner()
+        comment = None
+        if forced and not already_cancel:
+            pending = verdict.get("remaining_steps") or (
+                [step for step in plan if step not in completed] if plan else [])
+            comment = github.post_comment(
+                owner, repo, number, fmt_cancelado(pending), token,
+                baseline_ids=frozenset(item.get("id") for item in comments),
+                execution_id=state.get("execution_id"), sequence=len(events) + 1)
+        elif not already_done and not already_cancel and not forced:
+            comment = github.post_comment(
+                owner, repo, number, fmt_finalizado(), token,
+                baseline_ids=frozenset(item.get("id") for item in comments),
+                execution_id=state.get("execution_id"), sequence=len(events) + 1)
+        github.close_issue(owner, repo, number, token)
+        issue = github.fetch_issue(owner, repo, number, token)
+        if issue.get("state") != "closed":
+            raise SkillError(EXIT_RUNTIME, "CLOSE_FAILED",
+                             f"el Issue #{number} no quedó cerrado tras el PATCH "
+                             f"(state={issue.get('state')})")
+
+        history = state.get("history") or []
+        history.append({
+            "execution_id": state.get("execution_id"),
+            "issue_number": number,
+            "issue_url": state.get("issue_url") or issue.get("html_url"),
+            "finished_at": now_iso(),
+            "forced": outcome == "CANCELADO",
+            "outcome": outcome,
+        })
+        state.update({
+            "active_process_id": None,
+            "process_state": "CANCELADO" if outcome == "CANCELADO" else "FINALIZED",
+            "current_step": None,
+            "completed_steps": completed,
+            "github_token": state.get("github_token"),
+            "history": history[-20:],
+        })
+        lock.ensure_owner()
+        try:
+            save_state(path, state)
+        except SkillError as error:
+            raise SkillError(EXIT_RUNTIME, "STATE_SAVE_FAILED", error.message, {
+                "issue_url": issue.get("html_url"),
+                "hint": "el Issue está cerrado y finalizado/cancelado; ejecuta "
+                        "clear para limpiar la memoria local"})
+        emit({
+            "ok": True, "action": "FINALIZE", "issue_number": number,
+            "issue_url": issue.get("html_url"), "issue_state": "closed",
+            "outcome": outcome,
+            "forced": outcome == "CANCELADO",
+            "comment_posted": bool(comment),
+            "comment_url": comment["comment_url"] if comment else None,
+            "completed_steps": completed,
+            "active_process_id": None,
+            "state_file": str(path),
+        })
+    return EXIT_OK
+
+
+def cmd_status(args):
+    url = getattr(args, "url", None)
+    if url:
+        target = validate_repo_url(url)
+        if not target:
+            raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                             f"github_project_url inválido: {redact_url(url)}")
+        owner, repo = target
+        path = state_file_for(owner, repo)
+        state = load_state(path)
+    else:
+        try:
+            path = select_state_path()
+        except SkillError as error:
+            if error.code == "CONTEXT_AMBIGUOUS":
+                emit({"ok": True, "action": "STATUS",
+                      "state": None, "state_files": [
+                          item.name for item in list_state_files()],
+                      "error_hint": {"code": error.code,
+                                     "message": error.message,
+                                     "active_repos": error.extra.get("active_repos")}})
+                return EXIT_OK
+            raise
+        state = load_state(path)
+        owner = state.get("owner") if state else None
+        repo = state.get("repo") if state else None
+
+    output = {"ok": True, "action": "STATUS",
+              "state_file": str(path) if path else None,
+              "state": public_state(state),
+              "state_files": [item.name for item in list_state_files()]}
+    if args.remote and state and state.get("active_process_id"):
+        token, _ = need_token(args, state)
+        number = state["active_process_id"]
+        issue = github.fetch_issue(owner, repo, number, token)
+        events = events_from_comments(
+            github.fetch_all_comments(owner, repo, number, token))
+        plan = state.get("plan") or parse_plan_from_body(issue.get("body") or "")
+        output["remote"] = {
+            "issue_number": number, "issue_state": issue.get("state"),
+            "verdict": plan_resume(events, plan, issue.get("state", "open")),
+        }
+    emit(output)
+    return EXIT_OK
+
+
+def cmd_adopt(args):
+    target = validate_repo_url(args.url)
+    if not target:
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         f"github_project_url inválido: {redact_url(args.url)}")
+    owner, repo = target
+    path = state_file_for(owner, repo)
+    execution_id = (args.execution_id or "").strip()
+    if not execution_id:
+        raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                         "--execution-id es obligatorio (está en el título del Issue)")
+    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')
+    status, data, _ = github.api(
+        "GET", "/search/issues?" + urllib.parse.urlencode({"q": query, "per_page": 30}),
+        token)
+    if status != 200:
+        raise SkillError(EXIT_RUNTIME, "SEARCH_FAILED",
+                         f"búsqueda de Issues devolvió {status}: "
+                         f"{data.get('message', '')}")
+    matches = [issue for issue in (data.get("items") or [])
+               if github.canonical_title_match(issue, execution_id)]
+    if not matches:
+        raise SkillError(EXIT_NOT_FOUND, "ISSUE_NOT_FOUND",
+                         f"no se encontró un Issue con título canónico para "
+                         f"Execution ID {execution_id} en {owner}/{repo}")
+    if len(matches) > 1:
+        raise SkillError(EXIT_NOT_FOUND, "ISSUE_AMBIGUOUS",
+                         "múltiples Issues con el mismo Execution ID; revisa "
+                         "manualmente cuál adoptar",
+                         {"issues": [issue.get("html_url") for issue in matches]})
+    issue = matches[0]
+
+    lock = StateLock(path)
+    with lock:
+        existing = load_state(path)
+        if is_unfinished(existing) and not args.force:
+            raise SkillError(EXIT_RESUME_REQUIRED, "ADOPT_CONFLICT",
+                             f"ya hay un proceso activo (Issue "
+                             f"#{existing['active_process_id']}); usa --force "
+                             "para reemplazarlo (se conservan token e historial)",
+                             {"active_issue": existing["active_process_id"],
+                              "next": ["resume", "adopt --force"]})
+        number = issue["number"]
+        comments = github.fetch_all_comments(owner, repo, number, token)
+        events = events_from_comments(comments)
+        plan = parse_plan_from_body(issue.get("body") or "")
+        verdict = plan_resume(events, plan, issue.get("state", "open"))
+        action = verdict["action"]
+        if issue.get("state") == "open":
+            active = number
+            process_state = ("ERROR" if events and events[-1]["status"] == STATUS_ERROR
+                             else "RUNNING")
+        elif action == "NONE":
+            active = None
+            process_state = ("CANCELADO" if verdict.get("outcome") == "CANCELADO"
+                             else "FINALIZED")
+        else:
+            active, process_state = None, "ABORTED"
+
+        state = {
+            "schema_version": SCHEMA_VERSION,
+            "github_project_url": f"https://github.com/{owner}/{repo}",
+            "owner": owner, "repo": repo,
+            "active_process_id": active,
+            "execution_id": execution_id,
+            "issue_url": issue.get("html_url"),
+            "process_state": process_state,
+            "current_step": verdict.get("resume_from_step"),
+            "completed_steps": verdict.get("completed_steps", []),
+            "plan": plan,
+            "github_token": (existing or {}).get("github_token"),
+            "history": (existing or {}).get("history", []),
+            "created_at": now_iso(), "adopted": True,
+        }
+        if process_state == "ABORTED":
+            state["aborted"] = {"issue_number": number,
+                                "issue_url": issue.get("html_url"),
+                                "at": now_iso()}
+        lock.ensure_owner()
+        save_state(path, state)
+        emit({
+            "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),
+        })
+    return EXIT_OK
+
+
+def cmd_clear(args):
+    url = getattr(args, "url", None)
+    if url:
+        target = validate_repo_url(url)
+        if not target:
+            raise SkillError(EXIT_VALIDATION, "VALIDATION_ERROR",
+                             f"github_project_url inválido: {redact_url(url)}")
+        path = state_file_for(*target)
+    else:
+        path = select_state_path(allow_recent=False)
+
+    lock = StateLock(path)
+    with lock:
+        state = load_state(path)
+        if state is None:
+            emit({"ok": True, "action": "CLEAR", "cleared": False,
+                  "detail": f"no hay estado local en {path}"})
+            return EXIT_OK
+        was_unfinished = is_unfinished(state)
+        number = state.get("active_process_id")
+        lock.ensure_owner()
+        if args.hard:
+            try:
+                path.unlink()
+            except OSError as error:
+                raise SkillError(EXIT_RUNTIME, "STATE_UNREADABLE",
+                                 f"no se pudo eliminar {path}: {error}")
+            action = "CLEAR_HARD"
+        else:
+            state.update({"active_process_id": None,
+                          "process_state": "CLEARED", "current_step": None,
+                          "cleared_at": now_iso()})
+            save_state(path, state)
+            action = "CLEAR_SOFT"
+        output = {"ok": True, "action": action, "state_file": str(path)}
+        if was_unfinished and number:
+            output["warning"] = (f"se descartó un proceso INCONCLUSO (Issue #{number}); "
+                                 "el Issue permanece abierto en GitHub (usa 'adopt' "
+                                 "para recuperarlo si fue un error)")
+        emit(output)
+    return EXIT_OK
+
+
+def cmd_doctor(args):
+    checks = []
+
+    def add(name, ok, detail, required=True):
+        checks.append({"check": name, "ok": bool(ok),
+                       "detail": str(detail), "required": bool(required)})
+
+    add("python", sys.version_info >= (3, 8), sys.version.split()[0])
+    directory = state_dir()
+    try:
+        directory.mkdir(parents=True, exist_ok=True)
+        probe = directory / ".write-probe"
+        probe.write_text("ok", encoding="utf-8")
+        probe.unlink()
+        add("state-dir-writable", True,
+            f"{directory} (crea el directorio y un archivo de prueba: efecto de "
+            "escritura intencional)")
+    except OSError as error:
+        add("state-dir-writable", False, f"{directory}: {error}")
+
+    state_for_token = None
+    url = getattr(args, "url", None)
+    if url:
+        target = validate_repo_url(url)
+        if not target:
+            add("repo-url", False, f"inválida: {redact_url(url)}")
+        else:
+            path = state_file_for(*target)
+            state_for_token = load_state(path) if path.exists() else None
+    try:
+        token, source = github.resolve_token(getattr(args, "token", None),
+                                             state_for_token)
+    except Exception as error:
+        token, source = None, f"error: {error}"
+    add("token", bool(token),
+        f"source={source}" if token else
+        "sin token (usa --token, GITHUB_TOKEN/GH_TOKEN, --store-token o "
+        "'gh auth login')")
+
+    if token:
+        try:
+            status, data, _ = github.api("GET", "/rate_limit", token)
+            add("github-api", status == 200, f"HTTP {status}")
+            if status == 200:
+                core = (data.get("resources") or {}).get("core") or {}
+                add("rate-limit", True,
+                    f"remaining={core.get('remaining')}/{core.get('limit')}",
+                    required=False)
+        except SkillError as error:
+            add("github-api", False, error.message)
+    add("gh-cli", github.shutil.which("gh") is not None,
+        "presente (fuente opcional de token)" if github.shutil.which("gh")
+        else "ausente (opcional: solo fuente alternativa de token)",
+        required=False)
+    add("state-files", True,
+        ", ".join(path.name for path in list_state_files()) or "ninguno",
+        required=False)
+
+    if url:
+        target = validate_repo_url(url)
+        if target:
+            add("repo-url", True, f"https://github.com/{target[0]}/{target[1]}")
+            if token:
+                ok, code, detail = github.check_issues_write(target[0], target[1], token)
+                add("issues-write", ok, f"{code}: {detail}")
+
+    emit({"ok": all(check["ok"] for check in checks if check["required"]),
+          "doctor": checks})
+    return EXIT_OK