Manual práctico GitHub.com + GitHub App para actores¶

Este manual explica la operativa real de colaboración en atlantyqa-universe para:

colaboradores técnicos
reviewers/aprobadores
lead de gobernanza
operaciones/infra/compliance

Base técnica usada por este manual:

PR template: .github/pull_request_template.md
labels: .github/labels.yml
Project v2: .github/project_v2/README.md
workflows de labels/campos: .github/workflows/auto-label-by-paths.yml, .github/workflows/project-fields-from-labels.yml, .github/workflows/add_to_project.yml
gate HDP: .github/workflows/human-decision-protocol-gate.yml

1) Overview (mindmap)¶

mindmap
  root((Colaboración GitHub ATLANTYQA))
    Captura
      "Issue desde template"
      "Labels iniciales"
      "Project v2"
    Ejecución
      "Rama desde main"
      "Cambios pequeños"
      "Validación local"
    Integración
      "PR con evidencia"
      "Root cause + rollback"
      "HDP checkbox o HDP-*"
    Decisión
      "Review CODEOWNERS"
      "Aprobadores requeridos"
      "Gates CI/HDP"
    Cierre
      "Merge a main"
      "Estado Done"
      "Release RC rolling"

2) Capas operativas (mindmap)¶

mindmap
  root((Capas de operación))
    Actores
      "Colaborador"
      "Reviewer"
      "Lead/HILT"
      "Infra/Ops"
    Canales
      "GitHub Web"
      "GitHub App móvil"
      "Terminal local + git/gh"
    Artefactos
      "Issue"
      "Branch"
      "PR"
      "Project v2 item"
      "Workflow runs"
    Gobierno
      "Labels"
      "PR body"
      "HDP gate"
      "CODEOWNERS"
    Evidencia
      "logs"
      "run IDs"
      "referencia issue/PR"
      "riesgo residual + next action"

3) Flujo canónico Issue -> PR -> Merge¶

crear/seleccionar issue (template correcto).
etiquetar o dejar que auto-label-by-paths clasifique la PR.
mover item en Project v2 (Backlog -> In Progress).
crear rama desde main (feat/<issue>-<scope> o fix/<issue>-<scope>).
aplicar cambio mínimo verificable y capturar evidencia.
abrir PR con cuerpo completo (template).
completar decisión humana (HDP):
modo A: checkboxes
modo B (móvil): bloque HDP-*
solicitar revisión/aprobación.
pasar gates y mergear.

4) Operativa por actor¶

Actor	Acción mínima diaria	Resultado esperado
Colaborador	abrir/actualizar issue + PR con evidencia	cambio trazable, sin decisiones asumidas
Reviewer	validar causa raíz, evidencia, rollback, riesgo	dictamen técnico consistente
Lead/HILT	resolver decisión humana final	PR desbloqueada o cambios requeridos
Infra/Ops	validar impacto operativo y seguridad	continuidad operativa y compliance

5) Uso de labels (rápido y útil)¶

5.1 Etiquetas estructurales¶

dominio: domain-docs, domain-ui, domain-core, domain-gitops, domain-ops
skill: skill-python, skill-frontend, skill-devsecops, skill-docker, skill-docs, skill-data-ai
cómputo: compute-low, compute-medium, compute-heavy
nivel: level-beta, level-stable, level-critical
rol: role-gitops-engineer, role-ai-ops, role-docs-engineer, role-ux-local

5.2 Estado Project v2 por label (override)¶

status-backlog
status-in-progress
status-in-review
status-done
status-blocked

Sin override, la política actual es:

PR: In Progress por defecto
Issue nueva: Backlog

5.3 Reglas prácticas¶

no mezclar labels contradictorias (ej. compute-low y compute-heavy).
usa labels de override de estado solo cuando quieras forzar transición.
mantén 1-2 labels por eje (dominio/skill/compute) para no generar ruido.

6) Cuerpo de PR: qué debe llevar siempre¶

Sigue .github/pull_request_template.md.

Bloques obligatorios en la práctica:

contexto + issue relacionado
root cause real
cambio aplicado y trade-offs
validación técnica ejecutada
plan de rollback
cumplimiento y seguridad
protocolo de decisión humana (HDP)

Ejemplo mínimo de directivas móviles HDP:

HDP-TYPE: operativa-diaria
HDP-APPROVER: loky
HDP-DECISION: aprobado
HDP-TRACE: #123
HDP-EVIDENCE: https://github.com/atlantyqa-labs/atlantyqa-universe/actions/runs/123456
HDP-RISK: bajo
HDP-NEXT: merge-a-main

Si es proceso-regulado, añade:

HDP-COMPLIANCE: yes

7) GitHub App móvil: rutina recomendada¶

abrir notificación de PR/Issue.
revisar Checks y Files changed.
validar si falta evidencia o HDP.
comentar en bloque único (evitar comentarios dispersos).
aplicar decisión:
Approve
Request changes
Comment
si procede, aplicar labels de estado (status-*).

8) Checklist operativo por PR¶

[ ] issue enlazado (#123 o URL).
[ ] labels coherentes con el cambio.
[ ] evidencia reproducible (comandos/runs/logs).
[ ] riesgo residual y siguiente acción.
[ ] HDP completo (checkbox o HDP-*).
[ ] reviewer/aprobador solicitado.

9) Errores frecuentes y solución rápida¶

Error: gate HDP falla¶

causa típica: falta sección ## Protocolo de decisión humana o faltan campos HDP-*.
solución: completar template o pegar bloque móvil válido.

Error: estado vuelve a `Backlog`¶

revisar si hay label status-backlog.
confirmar que el workflow nuevo de status ya está en main.
revisar logs de project-fields-from-labels.

Error: actor de automatización aparece como humano¶

ocurre cuando se usa PROJECT_TOKEN PAT personal.
solución: configurar GITHUB_APP_ID + GITHUB_APP_PRIVATE_KEY para trazabilidad bot.

10) Anti-patrones a evitar¶

PR grande con cambios no relacionados.
pedir aprobación sin evidencias.
asumir decisiones humanas sin HDP.
editar estado/labels sin contexto en comentarios.
cerrar issue sin validar impacto post-merge.

11) Lectura rápida de errores de workflows (ERRORLOG + acciones por actor)¶

Cuando un workflow falle, usa el asistente local para obtener causa raíz probable y plan de acción por actor:

python3 scripts/workflow_errorlog_assistant.py \
  --run-url "https://github.com/atlantyqa-labs/atlantyqa-universe/actions/runs/<run_id>/job/<job_id>?pr=<pr>" \
  --actor-login "<github_login>"

Salida generada:

outputs/workflow-triage/workflow-triage-<timestamp>.md
outputs/workflow-triage/workflow-triage-<timestamp>.json

Qué aporta:

bloques ERRORLOG de alta señal.
candidatos de causa raíz.
acciones concretas por actor:
PR Author
Reviewer
Ops/Governance
plantilla de comentario para pegar en la PR.

12) Handoff de contexto para nuevos agentes/sesiones¶

Para transferir contexto compacto del repo entre sesiones (Codex/Claude/agente local), usa:

python3 scripts/build-agent-context-pack.py --profile codex

Guía completa:

docs/portal/agent-context-handoff-sca.md

13) Acción ejecutable al abrir PR desde agente¶

Para actualizar contexto automáticamente al abrir/actualizar PR:

python3 scripts/agent_pr_context_sync.py \
  --summary "Resumen del cambio en esta actualización de PR" \
  --scope "pr-open-context-sync" \
  --agent-id codex \
  --actor-login Kabehz \
  --comment-pr \
  --commit-ledger

Qué hace:

añade entrada compacta al ledger de contexto,
regenera context-pack,
publica comentario divulgativo en PR (si hay PR detectada),
deja commit segregado del ledger (si --commit-ledger).

14) Bootstrap/update local + validación del context-pack (recomendado)¶

Sitúa al agente en el contexto exacto del repositorio antes de codificar:

Bootstrap inicial + timer por actor tech en un solo paso:

python3 scripts/agent_context_bootstrap_local.py \
  --profile codex \
  --mode bootstrap \
  --actor-login Kabehz \
  --bootstrap-systemd-steward \
  --steward-only-tech-people \
  --steward-enable-now

Update incremental (cuando el bootstrap ya existe):

python3 scripts/agent_context_bootstrap_local.py \
  --profile codex \
  --mode update \
  --agent-id codex \
  --actor-login Kabehz \
  --interaction-scope "pr-open-context-sync" \
  --interaction-summary "Resumen compacto del incremento"

Valida coherencia antes de subir cambios:

python3 scripts/validate_agent_context_pack.py \
  --pack outputs/agent-context/context-pack-latest.json \
  --ledger knowledge/datasets/agent-context-transfer-log.jsonl \
  --report outputs/agent-context/context-pack-validation-latest.md

El reporte context-pack-validation-latest.md debe quedar en PASS.

15) Transferencia completa literal (100% raw) para colaboradores¶

Si necesitas traspasar el histórico íntegro (sin resumir), genera archivo raw + manifiesto:

python3 scripts/build-agent-context-raw-archive.py \
  --raw-file docs/internal/release-rc-mvp-synthesis.md \
  --raw-file inputs/deep-research-report.md \
  --raw-dir inputs \
  --glob "*.docx"

Después enlaza ese manifiesto dentro del pack compacto:

python3 scripts/build-agent-context-pack.py \
  --profile codex \
  --raw-transfer-manifest outputs/agent-context/raw/agent-context-raw-manifest-latest.json

Y valida que el pack exige presencia real del raw:

python3 scripts/validate_agent_context_pack.py \
  --pack outputs/agent-context/context-pack-latest.json \
  --ledger knowledge/datasets/agent-context-transfer-log.jsonl \
  --require-raw-transfer \
  --report outputs/agent-context/context-pack-validation-latest.md

16) Steward local descentralizado (sin perder histórico, sin memory leak)¶

Para equipos con múltiples dispositivos/clones, usa el steward local:

python3 scripts/agent_context_steward.py --mode once --profile codex --with-raw-transfer --require-raw-transfer

Beneficio:

conserva histórico literal + pack compacto en cada entorno local,
aplica retención segura (prune) sin romper trazabilidad,
evita fugas por proceso largo: ejecutar por timer systemd --user.

Plantillas listas:

ops/systemd/user/atq-context-steward.service
ops/systemd/user/atq-context-steward.timer
ops/systemd/user/README.md

Guía ultra-rápida por perfil tech:

docs/portal/tech-people-context-steward-quickstart.md

Norma ATQ-CST-001:

no usar atq-context-steward.timer/service genéricos,
usar siempre unidades por actor (atq-context-steward-<persona>.*) con scripts/install_context_steward_for_actor.py --migrate-legacy-generic.