human-gated-ship

1# SPDX-License-Identifier: Apache-2.02# yaml-language-server: $schema=https://nika.sh/spec/v1/workflow.schema.json3#4# TEMPLATE · human-gated-ship · gates in parallel → a human signs → ship · evidence always lands.5#6#   [check_a]─┐                             ┌──▶[act]──▶[record]7#   [check_b]─┴─▶[gates]──▶[human ⏸]──yes──┘    exec     nika:notify (always)8#   exec ×2       assert     nika:prompt9#10# Anything you cannot take back — a deploy, a send, a publish. The machine11# proves the preconditions in parallel, an assert refuses to even ASK when a12# gate is red, the human decides once with the full picture, and the evidence13# lands whether the answer was yes, no, or the ship blew up.14#15# Demonstrates ·16#   - `nika:assert` before the question · never ask a human to rubber-stamp a17#     red board18#   - `after: <task>: success` · a STATE edge (ordering, no data) vs `with:` (a19#     value edge) — two different kinds of arrow20#   - `after: <task>: terminal` · the always-runs pattern · evidence on success,21#     failure OR refusal22#   - fail-closed defaults · unattended, the answer is NO23#24# Needs · nothing to rehearse. To ship FOR REAL: TEAM_WEBHOOK_URL in the25#   environment, real commands in the three `exec:` slots — then delete the26#   `on_error:` on `record` so a lost audit trail is loud.27#28# Run · nika run <file>                    # unattended · gates run, the answer defaults to NO29#       Headless, `default: false` answers for you — delete that line and the30#       run PAUSES instead (exit 4 · durable, not a failure) and prints its31#       own resume line ·32#       nika run <file> --resume <trace> --answer human=true · or false33nika: v134workflow:35  id: human-gated-ship-template  # SLOT: kebab-case workflow id36  # SLOT: one honest sentence — `nika new` matches intents against these words37  description: "verify in parallel · human GO · act · record"38​39⛨permits:                            # SLOT: the blast radius · default-deny once present40  ⛨exec: ["echo"]                    # SLOT: ONLY the programs the gates + act run (argv form)41  ⛨tools: ["nika:assert", "nika:prompt", "nika:notify"]42  # `host_from_self` below sanctions the FLOW (the secret may BE the URL) — it43  # does not grant the capability to reach anyone. The host stays unknown at44  # check, so it is judged at RUN against this list: name the webhook host here45  # or the record is refused mid-run, after the ship already happened.46  ⛨net: { http: ["hooks.slack.com"] }   # SLOT: the webhook host · nothing else may leave47​48⛨secrets:49  ⛨webhook:50    ⛨source: env51    ⛨key: TEAM_WEBHOOK_URL           # SLOT: where the record lands52    ⛨egress:53      - ⛨to: "nika:notify"54        ⛨host_from_self: true        # the secret value IS the destination URL55policy:                              # NEP-0014 · the gate runs under a NAMED endorsement mode56  endorsement: solo57​58tasks:59  # ── the verification wave · all checks run in parallel ──60  check_a:61    ▷exec:62      command: ["echo", "ok"]        # SLOT: gate 1 (argv form · injection-safe)63      capture: structured64​65  check_b:66    ▷exec:67      command: ["echo", "ok"]        # SLOT: gate 268      capture: structured69​70  gates:71    with:72      all_green: ${{ tasks.check_a.output.exit_code == 0 && tasks.check_b.output.exit_code == 0 }}   # two value edges · one boundary expression73    ◆invoke:74      tool: "nika:assert"75      args:76        condition: "${{ with.all_green }}"77        message: "A gate is RED: refusing to proceed"   # SLOT78​79  human:80    after:81      gates: success              # state, no data · no question until the board is green82    ◆invoke:83      # On a terminal this ASKS. Headless, it answers with `default:` below —84      # the run completes, it does not pause (measured · act settles skipped).85      # The durable pause belongs to a prompt with NO default: headless it86      # PAUSES (exit 4 · not a failure) and prints its own resume line:87      #   nika run <file> --resume <trace> --answer human=true · or false88      tool: "nika:prompt"89      args:90        message: "All gates GREEN. Proceed?"   # SLOT: the decision, fully informed91        # Fail CLOSED. The unattended answer to "should I do the irreversible92        # thing" is no — `default: true` would hand CI a rubber stamp.93        default: false94​95  act:96    with:97      go: ${{ tasks.human.output }}   # the answer crosses as a value edge98    when: ${{ with.go == true }}99    ▷exec:100      command: ["echo", "shipped"]   # SLOT: the irreversible action (argv · program must be in permits.exec)101      # default capture · a failing ship fails LOUDLY (NIKA-EXEC-001):102      # never `capture: structured` on the irreversible step (exit codes103      # would become data and a red ship would read as success)104​105  record:106    after:107      act: terminal                 # the always-pattern · runs on success, failure, OR refusal108    with:109      acted: ${{ tasks.act.status }}   # observe the outcome · same pass-set as the after edge110    ◆invoke:111      tool: "nika:notify"112      args:113        channel: webhook114        target: "${{ secrets.webhook }}"115        message: "Run finished · act=${{ with.acted }}"   # SLOT · success | failure | skipped116        severity: info117    on_error:118      # Rehearsal only. With TEAM_WEBHOOK_URL unset the reference cannot resolve119      # and this task fails NIKA-VAR-001 (measured) — which would make the120      # skeleton red on a machine that has no webhook. Recovering keeps the121      # scaffold runnable; DELETE this block for real use, because a ship whose122      # audit trail silently vanished is exactly what this task exists to prevent.123      recover: "REHEARSAL · no webhook configured · nothing was sent"124​125outputs:126  acted: ${{ tasks.act.status }}127​