ADR-017 — GitHub Flow — Session Ship

ADR-017: GitHub Flow — Session Ship

Estado

Accepted

Fecha

2026-07-17

Aceptación

Gate humano 2026-07-17 — change OpenSpec github-flow-session-ship.

Amendment aceptado 2026-09-13 por petición explícita: cierre rápido y tests solo manuales; seguimiento en scanner-regression-coverage.

Contexto

La semilla trabaja con ramas feature/* y Pull Requests, pero no tenía una metodología Git explícita. /sd-pr evitaba merge; scripts/sd-ship.sh era stub; /cierre-session no garantizaba dejar master actualizado. El humano definió que el cierre de sesión debe terminar con merge del PR a master y working tree en master al día.

Referencia operativa: IVPrior scripts/fh-ship.sh (PR → merge → sync), adaptada a seed sin CI obligatoria aún.

Decisión

1. GitHub Flow

2. Cierre de sesión = ship completo

Tras aprobación humana, /cierre-session MUST:

1. Conservar la evidencia disponible y las validaciones pendientes; no ejecutar checks automáticamente.
2. Invocar make ship / scripts/sd-ship.sh (o equivalente documentado).
3. Merge del PR de la sesión a master (default).
4. git checkout master && git pull --ff-only origin master.
5. Working tree limpio en master.

Escape: humano pide solo PR → --no-merge o /sd-pr.

3. Roles de comandos

4. Tests manuales (amendment 2026-09-13)

El PC del usuario no tiene capacidad para ejecutar suites extensas durante el trabajo o el cierre. Por decisión explícita, .github/workflows/manual-tests.yml se activa únicamente con workflow_dispatch. No hay triggers de push/PR, cron ni workflow automático, ni build, lint o typecheck en ese workflow.

• suite=all: tests monorepo (incluye HTTP API), Python, sincronización de agentes y regresión Playwright schedules/Today.
• suite=unit: monorepo/HTTP, Python y agentes.
• suite=browser: Playwright schedules/Today con PostgreSQL/Redis efímeros y API/Web en modo desarrollo; sin build de producción ni scans de mercado reales.
• Tests opcionales y separados del merge: ship no los lanza, espera ni exige aprobados. Los resultados pendientes se documentan.
• Hooks locales: pre-commit informativo; pre-push únicamente impide push directo a master/main. Ninguno ejecuta tests, lint, typecheck ni build.
• El cierre recuerda el workflow y propone gh workflow run manual-tests.yml --ref master -f suite=all, sin ejecutarlo. Requiere que el archivo ya esté integrado en la rama por defecto.

5. Ship script

scripts/sd-ship.sh implementa push → PR create/reuse → merge → sync base. scripts/iv-ship.sh delega a esa implementación. --skip-check y --no-wait son compatibles sin efecto; --wait avisa que los tests se lanzan aparte. --no-merge conserva el PR abierto. No usa --no-verify, --admin ni force push; respeta las restricciones existentes de GitHub.

Alternativas consideradas

GitFlow (develop + release)

Rechazado — overhead para seed y agentes; contradice cierre rápido a master.

Solo PR sin merge en cierre

Rechazado por el humano — deja master desactualizado y PRs abiertos al cerrar sesión.

Trunk sin PR (commit directo a master)

Rechazado — pierde trazabilidad Spec Kit/OpenSpec y review.

Consecuencias

Positivas

• Ciclo de sesión completo y predecible para agentes.
• Alineación con GitHub Flow y con IVPrior ship.
• /sd-pr queda como herramienta explícita “sin merge”.

Negativas

• Un merge puede integrar código sin tests ejecutados; es el compromiso aceptado para evitar demoras de cierre. Los tests siguen disponibles bajo petición manual.
• Repos sin gh auth no pueden shippear (prerrequisito documentado).

Referencias

• OpenSpec: openspec/changes/github-flow-session-ship/
• ADR-016 (Makefile / make ship)
• IVPrior: scripts/fh-ship.sh
• Skills: cierre-session, sd-branch, sd-pr