Glosario Operativo ATLANTYQA y CLI Canónica¶

Objetivo¶

Dar una base común del lenguaje que usamos mientras operamos atlantyqa-universe:

palabras frecuentes
significado operativo
propósito real
herramientas CLI más usadas
flags canónicos que repetimos en sesión

No pretende cubrir todo Unix ni toda la semántica del repo. Es la base viva para que la tríada y nuevos colaboradores entiendan rápido qué decimos y por qué lo decimos.

Regla de lectura¶

si una palabra mueve una decisión, debe tener significado claro
si una herramienta puede cambiar estado, debe explicarse su propósito
si un flag aparece de forma recurrente, debe entenderse antes de usarlo

Palabras base del método ATLANTYQA¶

Término	Significado	Propósito
`local-first`	trabajar primero en repo, terminal, `.venv`, `outputs/` y bitácora local	preservar evidencia, autoría, prompts operativos y propiedad intelectual
`source of truth`	lugar canónico donde se decide el estado real	evitar ambigüedad entre idea, cambio aplicado y memoria efímera
`brain`	núcleo operativo compartido del método	sincronizar contexto, contratos y rutas reales antes de actuar
`control-plane`	superficie de coordinación y gobierno	alinear personas, ramas, rutas, decisiones y evidencias
`HILT`	`human-in-the-loop`	asegurar revisión humana en decisiones críticas
`FSM`	máquina de estados finitos	operar por estados claros y no por intuición
`bitácora`	memoria de sesión	dejar handoff y continuidad local reproducible
`agent-context`	síntesis reusable	promover aprendizajes estables entre sesiones
`policies`	norma transversal vigente	fijar reglas que ya obligan a todos
`evidencia`	prueba local o remota verificable	justificar decisiones y evitar merge a ciegas
`bloque`	grupo coherente de trabajo	dividir cambios para revisar, validar y empujar sin mezclar demasiado
`doctor`	diagnóstico mínimo de entorno	saber si un colaborador puede operar o está bloqueado
`reviewer`	nodo o rol de revisión	validar PR, riesgo, UX y evidencia
`full-node`	host preparado para operar el sistema completo	no depender de un nodo parcial o incompleto
`bundle`	paquete local de credenciales/config para un colaborador	permitir sync gobernada sin hardcodear secretos
`needs-small-fix`	estado cercano a merge pero aún no listo	señalar fix acotado sin dramatizar
`mergeable`	listo para ruta a `main` con evidencia y decisión humana	cierre operativo claro

Verbos operativos que usamos mucho¶

Verbo	Qué significa aquí
`sync`	alinear rama, host, entorno o contexto compartido
`plan`	preparar y validar sin ejecutar cambios de alto impacto
`apply`	ejecutar cambios reales
`reconcile`	converger estado real con estado deseado
`bootstrap`	preparar una base mínima utilizable
`prune`	podar refs o artefactos redundantes con seguridad
`archive`	preservar antes de borrar o simplificar
`promover`	subir algo desde bitácora/runtime a contexto o política
`validar`	comprobar contratos, UX, gates o estado de runtime

Herramientas CLI canónicas¶

`bash`¶

Uso	Propósito
`bash scripts/atq ...`	entrar por la fachada humana corta
`bash script.sh`	ejecutar un runbook o wrapper del repo

`git`¶

Comando o patrón	Propósito
`git status`	ver estado real del árbol de trabajo
`git diff`	inspeccionar cambios antes de decidir
`git fetch`	sincronizar referencias remotas
`git rebase`	realinear la rama local sobre la punta remota
`git push origin <rama>`	publicar commits en remoto
`git push origin --delete <rama>`	borrar rama remota solo con evidencia y criterio
`git worktree add`	trabajar sobre una punta limpia sin mezclar cambios locales

`gh`¶

Comando o patrón	Propósito
`gh pr view`	leer una PR con contexto real
`gh pr checks`	ver checks/gates de una PR
`gh pr list`	listar PRs activas/cerradas
`gh issue list`	listar issues y trazabilidad
`gh run view`	leer runs y logs de GitHub Actions

`python3`¶

Comando o patrón	Propósito
`python3 -m venv .venv`	crear entorno Python aislado
`python3 script.py`	ejecutar validadores, generadores o guards
`python3 -m pip install ...`	instalar dependencias del entorno activo

`pytest`¶

Comando o patrón	Propósito
`pytest`	validar tests automatizados
`pytest -q`	salida más compacta para CI y sesiones guiadas

`mkdocs`¶

Comando o patrón	Propósito
`mkdocs build --strict`	validar documentación sin warnings tolerados

`jq`¶

Comando o patrón	Propósito
`jq -r`	extraer texto plano desde JSON de APIs o logs

`rsync`¶

Comando o patrón	Propósito
`rsync -a`	copia incremental preservando estructura básica
`rsync --relative`	conservar rutas relativas en backups o syncs

Fachada `atq`: semántica base¶

bash scripts/atq es la puerta humana corta del repo.

Dominio	Significado
`collab`	colaboración humana y nodos locales
`ops`	operación y reconciliación
`host`	preparación del host
`device`	experiencia por dispositivo
`human`	asistencia orientada a audiencia humana

Flags que usamos de forma recurrente¶

Flags semánticos ATLANTYQA¶

Flag	Significado	Propósito
`--mode plan`	modo de preparación	revisar antes de ejecutar
`--mode apply`	modo de ejecución real	aplicar cambios
`--dry-run`	simulación sin efecto real	bajar riesgo antes de `apply`
`--audience <x>`	audiencia humana	adaptar lenguaje, salida y foco
`--hilt-audience <x>`	audiencia con gate humano	reforzar control humano
`--domain <x>`	dominio funcional	ubicar el tipo de operación
`--use-case <x>`	caso de uso concreto	hacer explícita la intención
`--phase <x>`	fase del runbook	trocear la operación por bloques
`--view <x>`	vista de salida	pedir resumen, tsv, gantt u otra presentación

Flags de colaboración¶

Flag	Significado	Propósito
`--role reviewer`	rol de revisor	preparar nodo de validación
`--role full-node`	nodo completo	preparar host con capacidad plena
`--collaborator-id <id>`	id canónico del colaborador	evitar ambigüedad entre alias y login
`--oauth-bundle-file <ruta>`	bundle local de credenciales	conectar sync gobernada sin exponer secretos
`--source-branch <rama>`	rama fuente acordada	sincronizar trabajo sobre la misma base
`--team <team>`	equipo lógico	contextualizar bootstrap/sync
`--host <host>`	host destino	declarar superficie operativa
`--run-doctor`	ejecutar diagnóstico adicional	salir con evidencia de salud del nodo

Flags comunes de herramientas base¶

Herramienta	Flag	Significado	Propósito
`git fetch`	`--all`	todos los remotos	sync amplia de refs
`git fetch`	`--prune`	podar refs remotas borradas	higiene segura de refs
`git push`	`--delete`	borrar ref remota	limpieza explícita
`git log`	`--oneline`	salida breve	lectura rápida de commits
`git branch`	`-r`	ramas remotas	inspección de refs remotas
`sed`	`-n`	no imprimir todo por defecto	leer solo el rango pedido
`rg`	`-n`	incluir número de línea	localizar texto con contexto
`find`	`-maxdepth`	limitar profundidad	inspección más segura y legible
`tar`	`-czf`	comprimir y escribir archivo	snapshot rápido de backup

Comandos que expresan bien el lenguaje ATLANTYQA¶

bash bash scripts/atq collab doctor --collaborator-id ajcg131281 bash scripts/atq collab brain-sync --mode plan --source-branch feat/cmdb-sovereign-v1-20260307 bash scripts/atq ops reconcile --audience onboarding --dry-run gh pr checks 62 git fetch --all --prune

Criterio práctico¶

Si una palabra o flag aparece mucho y todavía obliga a preguntar “¿qué significa aquí?”, todavía no está suficientemente canonizada y conviene añadirla a este glosario.