Handoff SCA de contexto para agentes (local-first)¶

Esta guía define cómo transferir contexto de atlantyqa-universe entre sesiones y entre agentes (Codex, Claude o agente local soberano) sin perder semántica ni gobernanza.

1) Qué significa SCA aquí¶

En esta operativa, SCA se aplica como:

Source inventory: fuentes versionadas y trazables.
Context compaction: resumen compacto por capas semánticas.
Action contract: reglas de ejecución y validación local-first.

2) Mindmap de capas SCA¶

mindmap
  root((SCA Handoff ATLANTYQA))
    Source inventory
      "README + docs clave"
      "Workflows + PR template"
      "Datasets de gobernanza"
      "Schemas soberanos"
    Context compaction
      "Headings"
      "Compact points"
      "Hash por archivo"
      "Interacciones opcionales"
    Action contract
      "HILT obligatorio"
      "Validación local-first"
      "Commits taxosemánticos"
      "PR con evidencia"

3) Artefactos materializados¶

Schema de handoff: schemas/agent-context-handoff-sca-v1.0.yaml
Schema de transferencia raw literal: schemas/agent-context-raw-transfer-v1.0.yaml
Builder de context pack: scripts/build-agent-context-pack.py
Builder de transferencia raw literal: scripts/build-agent-context-raw-archive.py
Acción ejecutable en apertura/actualización de PR: scripts/agent_pr_context_sync.py
Bootstrap/update local de contexto por agente: scripts/agent_context_bootstrap_local.py
Validador de coherencia del context-pack: scripts/validate_agent_context_pack.py
Triage de errores de workflows: scripts/workflow_errorlog_assistant.py
Ledger incremental de interacción: knowledge/datasets/agent-context-transfer-log.jsonl

4) Generar context pack en local¶

4.1 Para Codex¶

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

4.2 Para Claude¶

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

4.3 Para agente local propio¶

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

Outputs:

outputs/agent-context/context-pack-<timestamp>.json
outputs/agent-context/context-pack-<timestamp>.md
outputs/agent-context/context-pack-latest.json
outputs/agent-context/context-pack-latest.md

4.4 Transferencia literal 100% raw (sin resumir)¶

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"

Outputs:

outputs/agent-context/raw/agent-context-raw-<timestamp>.tar.gz
outputs/agent-context/raw/agent-context-raw-<timestamp>.manifest.json
outputs/agent-context/raw/agent-context-raw-<timestamp>.index.md
aliases agent-context-raw-latest.tar.gz, agent-context-raw-manifest-latest.json, agent-context-raw-index-latest.md

5) Incluir histórico de interacción (opcional)¶

Si guardas exportes de conversaciones/propuestas en archivos:

python3 scripts/build-agent-context-pack.py \
  --profile local-agent \
  --interaction-file inputs/deep-research-report.md \
  --interaction-file docs/internal/release-rc-mvp-synthesis.md

5.1) Registrar resumen compacto al cerrar sesión (recomendado)¶

Esto deja rastro incremental para nuevos colaboradores/agentes:

python3 scripts/build-agent-context-pack.py \
  --profile codex \
  --interaction-actor Kabehz \
  --interaction-agent codex \
  --interaction-scope "pr-42-workflow-triage" \
  --interaction-summary "Resumen breve de cambios, decisiones y próximos pasos" \
  --interaction-ref "https://github.com/atlantyqa-labs/atlantyqa-universe/pull/42"

El comando:

añade entrada al ledger knowledge/datasets/agent-context-transfer-log.jsonl,
regenera context-pack,
actualiza alias context-pack-latest.*.

6) Flujo recomendado por PR¶

Actualiza cambios del scope.
Ejecuta acción de sync de contexto para PR:

python3 scripts/agent_pr_context_sync.py \
  --summary "Scope y decisiones del incremento" \
  --scope "pr-open-context-sync" \
  --agent-id codex \
  --actor-login Kabehz \
  --comment-pr \
  --commit-ledger

Si falla un workflow, ejecuta workflow_errorlog_assistant.py.
Publica en PR:
causa raíz,
evidencia ERRORLOG,
acciones aplicadas por actor.

7) Triage de workflow con acciones 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>"

Outputs:

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

El reporte incluye:

candidatos de causa raíz,
bloques ERRORLOG,
acciones por actor (PR Author, Reviewer, Ops/Governance),
plantilla de comentario lista para pegar en PR.

8) Bootstrap/update local para situar al agente en el punto exacto¶

8.1 Bootstrap inicial (por agente)¶

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

Este modo deja en un solo paso:

context-pack + bootstrap prompt/brief,
instalación de unit/timer systemd --user por actor tech,
timer activo para no perder contexto entre sesiones.

8.2 Update incremental (cuando ya existe contexto local)¶

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"

Artefactos generados para onboarding operativo:

outputs/agent-context/bootstrap/codex-bootstrap-prompt.txt
outputs/agent-context/bootstrap/codex-bootstrap-brief.md

9) Quality gate del context-pack antes de subir¶

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

Si exiges evidencia de transferencia raw literal en el mismo pack compacto:

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

Criterios de paso (método ATLANTYQA):

head_commit_short del pack alineado con git rev-parse --short HEAD.
Anchors críticos presentes (README, PR template, Project v2, workflows, schemas).
startup_checklist y agent_bootstrap.prompt no vacíos.
Continuidad de ledger (interaction_ledger_recent coherente con última entrada).

10) Reglas no negociables del handoff¶

No desactivar gates HILT para pasar CI.
No mezclar cambios funcionales y autogenerados sin trazabilidad.
Mantener scopes pequeños por commit/PR.
Validar local-first antes de pedir review.

11) ¿Daemon local? criterio óptimo para no perder contexto¶

Recomendación ATLANTYQA:

usar timer + one-shot (systemd user) como modo por defecto,
evitar proceso monolítico 24/7 salvo necesidad explícita.

Motivo técnico:

minimiza riesgo de memory leak acumulativo,
mantiene trazabilidad descentralizada por colaborador,
evita solapamientos con lock exclusivo y timeouts por ciclo.

Comando manual equivalente (one-shot):

python3 scripts/agent_context_steward.py \
  --mode once \
  --profile codex \
  --with-raw-transfer \
  --raw-file docs/internal/release-rc-mvp-synthesis.md \
  --raw-file inputs/deep-research-report.md \
  --raw-file "inputs/Equipo Mínimo Viable para Cumplimiento Normativo Integral en una SL (España_EU).docx" \
  --raw-file knowledge/datasets/agent-context-transfer-log.jsonl \
  --require-raw-transfer \
  --include-ledger-limit 50

Plantillas systemd --user:

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

Onboarding guiado para perfiles tech:

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