Skip to content

SCA context handoff for agents (local-first)

This guide defines how to transfer atlantyqa-universe context across sessions and across agents (Codex, Claude, or a sovereign local agent) without losing semantics or governance.

1) What SCA means here

In this operating model, SCA is:

  1. Source inventory: versioned and traceable sources.
  2. Context compaction: compact summary by semantic layers.
  3. Action contract: execution rules and local-first validation.

2) SCA layer mindmap

mindmap
  root((ATLANTYQA SCA Handoff))
    Source inventory
      "README + key docs"
      "Workflows + PR template"
      "Governance datasets"
      "Sovereign schemas"
    Context compaction
      "Headings"
      "Compact points"
      "File hash"
      "Optional interactions"
    Action contract
      "HILT required"
      "Local-first validation"
      "Taxosemantic commits"
      "PR evidence"

3) Materialized artifacts

  • Handoff schema: schemas/agent-context-handoff-sca-v1.0.yaml
  • Literal raw transfer schema: schemas/agent-context-raw-transfer-v1.0.yaml
  • Context-pack builder: scripts/build-agent-context-pack.py
  • Literal raw transfer builder: scripts/build-agent-context-raw-archive.py
  • Executable PR open/update action: scripts/agent_pr_context_sync.py
  • Local agent bootstrap/update action: scripts/agent_context_bootstrap_local.py
  • Context-pack consistency validator: scripts/validate_agent_context_pack.py
  • Workflow error triage assistant: scripts/workflow_errorlog_assistant.py
  • Incremental interaction ledger: knowledge/datasets/agent-context-transfer-log.jsonl

4) Build local context pack

4.1 For Codex

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

4.2 For Claude

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

4.3 For your own local agent

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 Literal 100% raw transfer (no summarization)

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) Include interaction history (optional)

If you keep exported interactions/proposals in files:

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

This creates incremental traceability for new collaborators/agents:

python3 scripts/build-agent-context-pack.py \
  --profile codex \
  --interaction-actor Kabehz \
  --interaction-agent codex \
  --interaction-scope "pr-42-workflow-triage" \
  --interaction-summary "Short summary of changes, decisions, and next steps" \
  --interaction-ref "https://github.com/atlantyqa-labs/atlantyqa-universe/pull/42"

The command:

  1. appends one entry to knowledge/datasets/agent-context-transfer-log.jsonl,
  2. rebuilds the context-pack,
  3. refreshes context-pack-latest.* aliases.
  1. Update scoped changes.
  2. Run PR context sync action:
python3 scripts/agent_pr_context_sync.py \
  --summary "Scope and decisions for this increment" \
  --scope "pr-open-context-sync" \
  --agent-id codex \
  --actor-login Kabehz \
  --comment-pr \
  --commit-ledger
  1. If workflow fails, run workflow_errorlog_assistant.py.
  2. Post on PR:
  3. root cause,
  4. ERRORLOG evidence,
  5. actions applied by actor.

7) Workflow triage with actor-oriented actions

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

The report includes:

  • root-cause candidates,
  • ERRORLOG snippets,
  • actions by actor (PR Author, Reviewer, Ops/Governance),
  • copy-paste PR comment template.

8) Local bootstrap/update to place agents on exact development point

8.1 Initial bootstrap (per agent)

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

This one-step mode leaves:

  1. context-pack + bootstrap prompt/brief generated,
  2. per-actor systemd --user steward installed for tech profiles,
  3. timer enabled so context is preserved between sessions.

8.2 Incremental update (when local context already exists)

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 "Compact summary of this increment"

Generated onboarding artifacts:

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

9) Context-pack quality gate before upload

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

If you require proof of literal raw transfer inside the compact pack:

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

PASS criteria (ATLANTYQA method):

  1. Pack head_commit_short aligned with local git rev-parse --short HEAD.
  2. Critical anchors present (README, PR template, Project v2, workflows, schemas).
  3. Non-empty startup_checklist and agent_bootstrap.prompt.
  4. Ledger continuity (interaction_ledger_recent matches latest ledger entry).

10) Non-negotiable handoff rules

  1. Do not disable HILT gates to bypass CI.
  2. Do not mix generated and functional changes without traceability.
  3. Keep commit/PR scopes focused.
  4. Validate local-first before requesting review.

11) Local daemon? optimal criterion to avoid context loss

ATLANTYQA recommendation:

  1. use timer + one-shot (systemd user) by default,
  2. avoid 24/7 monolithic daemon unless explicitly needed.

Technical reason:

  • minimizes cumulative memory leak risk,
  • preserves decentralized traceability per collaborator,
  • avoids overlapping runs via exclusive lock + per-cycle timeout.

Equivalent manual one-shot command:

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

systemd --user templates:

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

Guided onboarding for tech profiles:

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