[Feature]: Document a test harness for scripting gate verdicts non-interactively

[doquanghuy]

Problem Statement

Spec Kit's gate step prompts operators interactively for a
verdict. There's no documented way to script those verdicts in a
test runner, so:

• Spec Kit's own CI cannot exercise gate behaviour end-to-end —
  changes to gate prompt format, output channel, or switch routing
  on verdict can regress without coverage.
• Workflows authored on Spec Kit that depend on gate semantics
  cannot be CI-tested without hand-rolling a pexpect driver
  against an undocumented prompt format.

Proposed Solution

A documented way to script gate verdicts during
specify workflow run. Two possible shapes:

A. --gate-script flag

specify workflow run my-pipeline --gate-script verdicts.yaml

schema: speckit.gate-script/v1
verdicts:
  - {gate_id: "review-overview", iteration: 0, verdict: "improve"}
  - {gate_id: "review-overview", iteration: 1, verdict: "approve"}

B. Document the canonical gate-prompt regex (e.g. anchored
markers like SPECKIT_GATE_PROMPT_BEGIN: <id> …
SPECKIT_GATE_PROMPT_END) so contributors can write pexpect
drivers against a stable contract.

A is more CI-friendly; B is more flexible for advanced cases.

Component

Specify CLI (initialization, commands)

AI Agent (if applicable)

All agents

Acceptance Criteria

• Documented contract for scripting gate verdicts (A or B).
• At least one example test in Spec Kit's suite exercising an
  improve → approve cycle.
• Default behaviour preserved: gates still prompt
  interactively when no script is provided.

Additional Context

If gate behaviour is intentionally manual-only, please say so and
I'll close.

AI disclosure: drafted with Claude Opus, human-reviewed.

[doquanghuy]

@mnriem please take a look at this, thank you!

[mnriem]

Thanks for filing this — the desire to run workflows unattended in CI is valid.

However, the workflow engine already supports this pattern today using the existing if step type and workflow inputs:

inputs:
  ci_mode:
    type: boolean
    default: false

steps:
  - id: maybe-review-spec
    type: if
    condition: "{{ not inputs.ci_mode }}"
    then:
      - id: review-spec
        type: gate
        message: "Review the generated spec."
        options: [approve, reject]
        on_reject: abort
    else: []

CI invocation:

specify workflow run my-pipeline --input ci_mode=true

This skips the gate entirely in CI while preserving interactive behavior by default. Workflow authors can wrap any gate in an if step and control it via inputs — no changes to the engine or CLI required.

Would this approach work for your use case? If there's a scenario the if-step pattern doesn't cover, let us know and we can revisit.

[doquanghuy]

Thanks @mnriem — that pattern works for the use case. Wrapping each gate in type: if with a ci_mode boolean input cleanly handles CI/non-interactive runs without any new CLI surface or schema. Closing this and the corresponding PR (#2667) in favour of the existing-primitives approach.

For reference, the canonical CI invocation per your example:

```bash
specify workflow run my-pipeline --input ci_mode=true
```

Appreciate the quick steer.

AI disclosure: drafted with Claude Opus, human-reviewed.