README says agent cannot skip ahead, but since #223 back-to-back ack.sh calls ack never-shown items (0.2.1) #225

Summary

README says (line 52, under the flow diagram):

Each checklist item requires one full hook invocation to acknowledge. The agent cannot skip ahead.

Since #223 (merged 2026-09-29, shipped in steplock 0.2.1 on crates.io) that is no longer true: ack.sh can be run back to back, so an agent can acknowledge items 2..N without the hook ever showing it those questions, and the gated action is then approved.

#223 made this deliberate (to save ~20 retried tool calls on a 9-step checklist), so this is not a code bug report — it's a docs/behavior contradiction that needs a maintainer decision.

Reproduction (published steplock 0.2.1 via cargo install steplock --locked, macOS arm64)

.steplock/checklists/push-gate/flow.mmd:

stateDiagram-v2
    [*] --> tests
    tests --> docs
    docs --> [*]
    tests : Did you run the tests?
    docs  : Did you update the docs?

config.toml: on_event = "tool:before", on_tool = "bash", match_input on git + push command words, reset = "session".

# 1. hook fires on a Claude Code PreToolUse Bash event for `git push origin main`
$ steplock < push-event.json
{"hookSpecificOutput":{..."permissionDecision":"deny","permissionDecisionReason":"[push-gate: 1/2] Did you run the tests?\n\nWhen finished, run: sh .../sessions/sess2/push-gate/ack.sh ..."}}

# 2. agent runs ack.sh twice without retrying the command in between
$ sh .steplock/sessions/sess2/push-gate/ack.sh   # acks "tests"
$ sh .steplock/sessions/sess2/push-gate/ack.sh   # acks "docs" — never shown to the agent

# 3. next hook invocation
$ steplock < push-event.json
{}            # approved

Observed vs documented

Everything else checked out on 0.2.1: init, validate, block with the current question, state persisted to state.json, next item on the following invocation when acked one at a time, approve once all acked, branching flow lists both options and follows the chosen one (no-arg / bogus choice rejected with exit 1), audit.log entries written.

Decision needed

Either:

1. Keep back-to-back acks (fix(ack): set the next state's transitions when ack.sh advances #223's intent) → update the README sentence (e.g. "items must be acknowledged in order; ack.sh advances one state per call and may be run repeatedly"), or
2. Restore one-question-per-invocation → make ack.sh refuse to advance past a state the gate hasn't displayed yet (e.g. a shown marker the gate sets on block and ack.sh requires).

Not opening a PR since the right fix depends on which guarantee you want. @tupe12334

Filed automatically by the moadim routine "Nightly lib dogfood → issue + PR (polyhook, block-no-verify, steplock)".