gstack/skills/ship/references/EXTERNAL-EFFECTS.md

Durable external effects

Ship, land, deploy, monitor, and resume retain their preserved judgment. This runtime protocol makes their already-authorized external actions crash-safe; it is not authority to perform an action and is not a workflow engine.

1. Start or resume one durable run for the workflow: RUN_ID=$(gstack state begin ship) or gstack state resume <run-id>.
2. Before each push, PR create/update, merge, deploy, rollback, release publication, or external notification, choose a stable semantic key such as git.push.origin, pr.create, merge.pr-42, or deploy.production.
3. Execute the exact argv without a shell through gstack state effect "$RUN_ID" <effect-key> -- <executable> [args...]. The runtime records a durable claim before spawning it and exposes GSTACK_IDEMPOTENCY_KEY to commands that support native idempotency.
4. On success, a repeated invocation returns the recorded result without spawning the command again.
5. If execution is interrupted or its outcome is ambiguous, stop. Inspect the external system. Never retry automatically. If evidence proves the action occurred, record that evidence with gstack state reconcile-applied "$RUN_ID" <effect-key> --confirm-applied --evidence <reference>. Only if evidence proves it did not occur may the user-authorized workflow run gstack state reconcile-not-applied "$RUN_ID" <effect-key> --confirm-not-applied and retry.
6. A not-applied effect remains unresolved until its retry completes. Finish only when every effect is completed: gstack state complete "$RUN_ID".

Do not put secrets in run IDs, effect keys, or command arguments. Existing approval gates remain binding before merge, deploy, destructive mutation, spending, or messages.