feat(spec): add support for negate condition (#1451)

* **New Features**
* Added an optional "negate" flag for preconditions at both DAG and step
levels to invert condition evaluation.
  * API and schema updated to include the new negate field.

* **Tests**
* Expanded test coverage for negated preconditions across DAGs, steps,
commands, environment variables, and error scenarios.

Author: yohamta0

api/v2/api.gen.go

@@ -2572,6 +2572,9 @@ components:
         expected:
           type: string
           description: "Expected result of the condition evaluation"
+        negate:
+          type: boolean
+          description: "If true, inverts the condition result (run when condition does NOT match)"
         error:
           type: string
           description: "Error message if the condition is not met"

api/v2/api.yaml

@@ -15,6 +15,7 @@ type Condition struct {
 
 	Condition    string // Condition to evaluate
 	Expected     string // Expected value
+	Negate       bool   // Negate the condition result (run when condition does NOT match)
 	errorMessage string // Error message if the condition is not met
 }
 
@@ -24,10 +25,12 @@ func (c *Condition) MarshalJSON() ([]byte, error) {
 	return json.Marshal(struct {
 		Condition    string `json:"condition,omitempty"`
 		Expected     string `json:"expected,omitempty"`
+		Negate       bool   `json:"negate,omitempty"`
 		ErrorMessage string `json:"error,omitempty"`
 	}{
 		Condition:    c.Condition,
 		Expected:     c.Expected,
+		Negate:       c.Negate,
 		ErrorMessage: c.errorMessage,
 	})
 }
@@ -38,13 +41,15 @@ func (c *Condition) UnmarshalJSON(data []byte) error {
 	var tmp struct {
 		Condition    string `json:"condition,omitempty"`
 		Expected     string `json:"expected,omitempty"`
+		Negate       bool   `json:"negate,omitempty"`
 		ErrorMessage string `json:"error,omitempty"`
 	}
 	if err := json.Unmarshal(data, &tmp); err != nil {
 		return err
 	}
 	c.Condition = tmp.Condition
 	c.Expected = tmp.Expected
+	c.Negate = tmp.Negate
 	c.errorMessage = tmp.ErrorMessage
 	return nil
 }

internal/core/condition.go

@@ -808,6 +808,13 @@ func parsePrecondition(ctx BuildContext, precondition any) ([]*core.Condition, e
 				}
 				ret.Condition = val
 
+			case "negate":
+				val, ok := vv.(bool)
+				if !ok {
+					return nil, core.NewValidationError("preconditions", vv, ErrPreconditionNegateMustBeBool)
+				}
+				ret.Negate = val
+
 			default:
 				return nil, core.NewValidationError("preconditions", key, fmt.Errorf("%w: %s", ErrPreconditionHasInvalidKey, key))
 

internal/core/spec/builder.go

@@ -813,6 +813,19 @@ preconditions:
 		assert.Len(t, th.Preconditions, 1)
 		assert.Equal(t, &core.Condition{Condition: "test -f file.txt", Expected: "true"}, th.Preconditions[0])
 	})
+	t.Run("PreconditionsWithNegate", func(t *testing.T) {
+		data := []byte(`
+preconditions:
+  - condition: "${STATUS}"
+    expected: "success"
+    negate: true
+`)
+		dag, err := spec.LoadYAML(context.Background(), data)
+		require.NoError(t, err)
+		th := DAG{t: t, DAG: dag}
+		assert.Len(t, th.Preconditions, 1)
+		assert.Equal(t, &core.Condition{Condition: "${STATUS}", Expected: "success", Negate: true}, th.Preconditions[0])
+	})
 	t.Run("MaxActiveRuns", func(t *testing.T) {
 		data := []byte(`
 maxActiveRuns: 5
@@ -1611,6 +1624,25 @@ steps:
 		assert.Len(t, th.Steps[0].Preconditions, 1)
 		assert.Equal(t, &core.Condition{Condition: "test -f file.txt", Expected: "true"}, th.Steps[0].Preconditions[0])
 	})
+	t.Run("StepPreconditionsWithNegate", func(t *testing.T) {
+		t.Parallel()
+
+		data := []byte(`
+steps:
+  - name: "step_with_negate"
+    command: "echo hello"
+    preconditions:
+      - condition: "${STATUS}"
+        expected: "success"
+        negate: true
+`)
+		dag, err := spec.LoadYAML(context.Background(), data)
+		require.NoError(t, err)
+		th := DAG{t: t, DAG: dag}
+		assert.Len(t, th.Steps, 1)
+		assert.Len(t, th.Steps[0].Preconditions, 1)
+		assert.Equal(t, &core.Condition{Condition: "${STATUS}", Expected: "success", Negate: true}, th.Steps[0].Preconditions[0])
+	})
 	t.Run("RepeatPolicyExitCode", func(t *testing.T) {
 		t.Parallel()
 

internal/core/spec/builder_test.go

@@ -8,6 +8,7 @@ var (
 	ErrInvalidScheduleType                 = errors.New("invalid schedule type")
 	ErrDotEnvMustBeStringOrArray           = errors.New("dotenv must be a string or an array of strings")
 	ErrPreconditionValueMustBeString       = errors.New("precondition value must be a string")
+	ErrPreconditionNegateMustBeBool        = errors.New("precondition negate must be a boolean")
 	ErrPreconditionHasInvalidKey           = errors.New("precondition has invalid key")
 	ErrPreconditionMustBeArrayOrString     = errors.New("precondition must be a string or an array of strings")
 	ErrInvalidStepData                     = errors.New("invalid step data")

internal/core/spec/errors.go

@@ -756,3 +756,102 @@ steps:
 		"STEP_DIR": stepWorkDir,
 	})
 }
+
+// TestPreconditionNegate verifies that preconditions with negate:true work correctly.
+// When negate is true, the step runs when the condition does NOT match.
+func TestPreconditionNegate(t *testing.T) {
+	t.Parallel()
+
+	th := test.Setup(t)
+
+	t.Run("NegateSkipsWhenConditionMatches", func(t *testing.T) {
+		t.Parallel()
+
+		// When negate:true and condition matches expected, step should be skipped
+		dag := th.DAG(t, `type: graph
+env:
+  - STATUS: success
+steps:
+  - command: echo "always runs"
+    output: OUT1
+  - command: echo "should skip"
+    output: OUT2
+    preconditions:
+      - condition: "${STATUS}"
+        expected: "success"
+        negate: true
+`)
+		agent := dag.Agent()
+		agent.RunSuccess(t)
+		dag.AssertOutputs(t, map[string]any{
+			"OUT1": "always runs",
+			"OUT2": "", // Should be empty because step was skipped
+		})
+	})
+
+	t.Run("NegateRunsWhenConditionDoesNotMatch", func(t *testing.T) {
+		t.Parallel()
+
+		// When negate:true and condition does NOT match expected, step should run
+		dag := th.DAG(t, `type: graph
+env:
+  - STATUS: failure
+steps:
+  - command: echo "always runs"
+    output: OUT1
+  - command: echo "should run"
+    output: OUT2
+    preconditions:
+      - condition: "${STATUS}"
+        expected: "success"
+        negate: true
+`)
+		agent := dag.Agent()
+		agent.RunSuccess(t)
+		dag.AssertOutputs(t, map[string]any{
+			"OUT1": "always runs",
+			"OUT2": "should run",
+		})
+	})
+
+	t.Run("NegateWithCommandExitCode", func(t *testing.T) {
+		t.Parallel()
+
+		// When negate:true with a command, step runs when command fails (non-zero exit)
+		dag := th.DAG(t, `type: graph
+steps:
+  - command: echo "should run"
+    output: OUT1
+    preconditions:
+      - condition: "false"
+        negate: true
+`)
+		agent := dag.Agent()
+		agent.RunSuccess(t)
+		dag.AssertOutputs(t, map[string]any{
+			"OUT1": "should run",
+		})
+	})
+
+	t.Run("DAGLevelNegate", func(t *testing.T) {
+		t.Parallel()
+
+		// DAG-level precondition with negate - should run when condition doesn't match
+		dag := th.DAG(t, `
+env:
+  - ENV_TYPE: development
+preconditions:
+  - condition: "${ENV_TYPE}"
+    expected: "production"
+    negate: true
+steps:
+  - command: echo "dag ran"
+    output: OUT1
+`)
+		agent := dag.Agent()
+		agent.RunSuccess(t)
+		dag.AssertOutputs(t, map[string]any{
+			"OUT1": "dag ran",
+		})
+	})
+}

internal/integration/config_test.go

@@ -2,6 +2,7 @@ package runtime
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"os/exec"
 
@@ -45,14 +46,32 @@ func EvalConditions(ctx context.Context, shell []string, cond []*core.Condition)
 
 // EvalCondition evaluates the condition and returns the actual value.
 // It returns an error if the evaluation failed or the condition is invalid.
+// If c.Negate is true, the result is inverted: the condition passes when it
+// would normally fail, and vice versa.
 func EvalCondition(ctx context.Context, shell []string, c *core.Condition) error {
+	var err error
 	switch {
 	case c.Condition != "" && c.Expected != "":
-		return matchCondition(ctx, c)
+		err = matchCondition(ctx, c)
 
 	default:
-		return evalCommand(ctx, shell, c)
+		err = evalCommand(ctx, shell, c)
 	}
+
+	// Apply negation if needed
+	if c.Negate {
+		if err == nil {
+			return fmt.Errorf("%w: condition matched but negate is true", ErrConditionNotMet)
+		}
+		// Only invert logical "not met" failures; keep evaluation/runtime errors.
+		if errors.Is(err, ErrConditionNotMet) {
+			return nil
+		}
+		// Evaluation or runtime error - don't swallow it
+		return err
+	}
+
+	return err
 }
 
 // matchCondition evaluates the condition and checks if it matches the expected value.