Skip to main content
← Back to list
01Issue
FeatureOpenSwamp CLIPublic
AssigneesNone

Relationships

#1797 software-factory: rename gates[].pass to gates[].satisfied - collides with a transition named 'pass'

Opened by brucejo75 · 8/23/2026

Summary

@swamp/software-factory reports each gate's evaluation result in a boolean field named pass. That name collides with the most natural name for a transition in any review-shaped lifecycle — pass / fail out of a verification stage. The result is that the single word "pass" means two unrelated things in the same status payload, at exactly the point a human is being asked to make a decision.

Suggested rename: gates[].satisfied, which also matches the field the engine already uses one level up, transitions[].satisfied.

Why it matters

There are three genuinely distinct states in a run, and today two of them are spelled with the same word:

  1. Gate passed — one condition evaluated true (gates[].pass).
  2. Transition satisfied — all of that transition's gates pass (transitions[].satisfied). Satisfied means armed, not moved.
  3. Transition taken — advance actually ran and the stage changed.

In our meris-sdlc definition the verification stage's outgoing transitions are named pass and fail. So status can simultaneously report a gate whose pass is true on a transition named pass that is not satisfied — and a human reading "pass" cannot tell whether a gate went green, whether the run moved, or whether they owe an approval. We hit this for real: the operator asked "I assume we are pass at this point?" while the run was sitting in verification with the pass transition satisfied but not advanced.

We have worked around it with a house style rule (never say "we passed"; always name which of gate-passed / transition-satisfied / transition-taken changed), and we are renaming our own transitions to verified / regressed. Both are workarounds for a field name, and the second one is only available because the transition names happen to be ours. The field name is not.

Why not just rename our transitions and move on

We are doing that too, but it does not fix the general case:

  • pass / fail is the obvious naming for a review or verification stage, so every consumer authoring a QA-shaped lifecycle walks into this independently.
  • The alternative for a consumer who wants the field renamed is maintaining a fork of the engine to change one JSON field name, which is wildly disproportionate.

Suggested fix

Rename gates[].pass to gates[].satisfied in the status payload, matching transitions[].satisfied. If backwards compatibility matters, emit both for a release and document pass as deprecated.

Arguments against, for the record

  • It is a breaking change to a payload consumers may already parse. Emitting both fields for one release cycle mitigates this.
  • satisfied at two nesting levels with different scopes (one gate vs. all gates on a transition) could itself be read as ambiguous. We think it is not — the nesting disambiguates it, and consistency beats two words for one concept.

Environment

  • @swamp/software-factory 2026.06.24.1
  • swamp CLI 20260818.201833.0-sha.70d2f529

Upstream repository: https://github.com/swamp-club/swamp-extensions

Environment

  • Extension: @swamp/software-factory@2026.06.24.1
  • swamp: 20260818.201833.0-sha.70d2f529
  • OS: linux (x86_64)
  • Deno: 2.8.3
  • Shell: /bin/bash
02Bog Flow
◉OPEN○TRIAGED○IN PROGRESS○SHIPPED

Open

8/23/2026, 4:13:44 AM

No activity in this phase yet.

03Sludge Pulse

Sign in to post a ripple.