feat: bind gate verdict to workflow input via verdict_input

[markuswondrak]

Summary

Adds an optional verdict_input field to gate steps, letting an external system supply a verdict through a declared workflow input instead of requiring an interactive TTY prompt. This enables non-interactive approval flows (web UIs, Slack, APIs) without a gate-specific CLI flag or a parallel switch workaround.

Closes / implements the approach proposed in discussion #3717.

What changed

GateStep (steps/gate/__init__.py)

• New optional field verdict_input: names a declared workflow input that may carry the gate's verdict.
• Resolution order: if the named input holds a non-empty string matching an options entry (case-insensitive), the gate auto-decides and records the canonical spelling in output.choice. A present-but-non-matching value fails immediately with a clear error. An absent/empty value falls back to today's TTY-prompt-or-pause behaviour unchanged.
• on_reject: retry interaction: a bound reject verdict is consumed (the stored input is reset to "") before the gate pauses, so the next resume prompts or pauses again unless another verdict is supplied.
• Validation (GateStep.validate()) rejects a non-string or empty verdict_input value.

Engine (engine.py)

• validate_workflow now threads the set of declared input names through _validate_steps and reports an error when a gate's verdict_input references an undeclared input (mirrors the existing wait_for id cross-check).
• WorkflowEngine persists result.error in each step's state record so failed-step error messages survive across runs.

CLI (_commands.py)

• workflow run and workflow resume surface the first persisted step error after a failed or aborted run via a new _failed_step_error helper.

Docs (docs/reference/workflows.md)

• New Gate Verdict Inputs section documents the field, input-value semantics table, YAML example, resume invocation, and on_reject: retry reset behaviour.

Usage

inputs:
  spec_verdict:
    type: string
    default: ""
steps:
  - id: review-spec
    type: gate
    message: "Approve the specification?"
    options: [approve, reject]
    on_reject: retry
    verdict_input: spec_verdict

# Resume with an external verdict
specify workflow resume <run_id> --input spec_verdict=approve

Manual test results

Agent: GitHub Copilot CLI (claude-sonnet-4.6) | OS/Shell: Linux/bash

Command tested	Notes
specify workflow run	Verified gate pauses without verdict input, auto-decides with matching input, fails with non-matching input
specify workflow resume	Verified verdict supplied via --input is consumed and gate applies on_reject semantics
specify workflow validate	Verified undeclared verdict_input reference is reported as a validation error

AI disclosure

This PR was written by GitHub Copilot CLI (model: claude-sonnet-4.6) and human-reviewed.

[Copilot]

Pull request overview

Adds workflow-input-driven gate verdicts for non-interactive approval flows.

Changes:

• Resolves gate verdicts from declared workflow inputs.
• Validates bindings, persists step errors, and surfaces errors in human CLI output.
• Adds documentation and comprehensive tests.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/specify_cli/workflows/steps/gate/__init__.py	Implements verdict input resolution and retry consumption.
src/specify_cli/workflows/engine.py	Validates bindings and persists step errors.
src/specify_cli/workflows/_commands.py	Displays persisted errors in human output.
docs/reference/workflows.md	Documents gate verdict inputs.
tests/test_workflows.py	Covers resolution, validation, persistence, retry, and CLI behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mnriem]

Please address Copilot feedback

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

src/specify_cli/workflows/_commands.py:907

• The --json branches return _workflow_run_payload(state) before this helper is called, so the external systems this feature targets receive only status: "failed" for an invalid verdict and lose the promised explanatory error. Include _failed_step_error(state) in the shared run/resume payload (and cover both JSON commands) so machine-readable runs surface the persisted error too.

            return str(sd["error"])

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.