name the until/fail-when dialect (JMESPath Community Edition) on consumer surfaces #145

New issue

Closed

opened 2026-06-16 00:45:11 +00:00 by coilysiren · 0 comments

coilysiren commented

2026-06-16 00:45:11 +00:00

Owner

Problem

The until / fail-when expressions in specverb complex actions are JMESPath, evaluated through the jmespath-community/go-jmespath interpreter (http/respfmt/eval.go). No consumer-facing surface names the language:

the generated guardfile reference doc (renderProse in http/specverb/describe.go) prints the raw expressions with no label, and
a $name reference (a bound input or as capture, supplied through the Community Edition's variable scope) has no syntax in baseline JMESPath.

So the conditions were never portable to an original-spec evaluator (jmespath.org), yet nothing flagged it. A reader meeting length(workflow_runs[?run_number==$run ...]) cold has no way to know what language it is, or that it is the Community Edition superset rather than baseline.

Decision

Document the dialect as JMESPath Community Edition (the stance picked: embrace it, name it, do not constrain to a baseline allowlist).

Done in this change

renderProse now closes the action stanzas with a "Condition language" note naming JMESPath Community Edition (jmespath.site), contrasting it with baseline (jmespath.org), and explaining the $name scope. Pinned by a Contains assertion in the action markdown test.

Follow-up (separate, downstream)

The ward repo's committed ward-kdl.forgejo.guardfile.md regenerates only against a released cli-guard (its Makefile pins REF). Once this lands and cli-guard releases, ward bumps the ref and regenerates the doc so the note reaches ward's committed copy. Tracked separately in the ward repo.

## Problem The `until` / `fail-when` expressions in specverb complex actions are JMESPath, evaluated through the `jmespath-community/go-jmespath` interpreter (`http/respfmt/eval.go`). No consumer-facing surface names the language: - the generated guardfile reference doc (`renderProse` in `http/specverb/describe.go`) prints the raw expressions with no label, and - a `$name` reference (a bound input or `as` capture, supplied through the Community Edition's variable scope) has **no syntax in baseline JMESPath**. So the conditions were never portable to an original-spec evaluator (jmespath.org), yet nothing flagged it. A reader meeting `length(workflow_runs[?run_number==$run ...])` cold has no way to know what language it is, or that it is the Community Edition superset rather than baseline. ## Decision Document the dialect as JMESPath Community Edition (the stance picked: embrace it, name it, do not constrain to a baseline allowlist). ## Done in this change `renderProse` now closes the action stanzas with a "Condition language" note naming JMESPath Community Edition (jmespath.site), contrasting it with baseline (jmespath.org), and explaining the `$name` scope. Pinned by a `Contains` assertion in the action markdown test. ## Follow-up (separate, downstream) The ward repo's committed `ward-kdl.forgejo.guardfile.md` regenerates only against a **released** cli-guard (its Makefile pins `REF`). Once this lands and cli-guard releases, ward bumps the ref and regenerates the doc so the note reaches ward's committed copy. Tracked separately in the ward repo.

coilysiren referenced this issue from a commit

2026-06-16 00:45:58 +00:00

docs(specverb): name the until/fail-when dialect in generated action docs

coilysiren closed this issue

2026-06-16 00:45:58 +00:00