@probelabs/visor 0.1.124 → 0.1.126

package/dist/docs/fail-if.md

@@ -24,25 +24,109 @@ fail_if: outputs["fetch-tickets"].error
 
 Inside the expression you can use:
 
+### Primary context variables
+
 - `output`: the current check's structured output.
   - Includes `issues` and any other fields produced by the provider.
-  - For custom schemas, all top‑level JSON fields are preserved and exposed here.
+  - For custom schemas, all top-level JSON fields are preserved and exposed here.
   - For command output that is JSON, fields are available directly; for plain text, treat `output` as a string.
 - `outputs`: a map of dependency outputs keyed by check name. Each value is that check's `output` if present; otherwise the whole check result.
 
-**Helper functions:**
-- String: `contains(haystack, needle)`, `startsWith(s,prefix)`, `endsWith(s,suffix)`, `length(x)`
-- Control: `always()`, `success()`, `failure()`
-- Author permissions: `hasMinPermission(level)`, `isOwner()`, `isMember()`, `isCollaborator()`, `isContributor()`, `isFirstTimer()` - See [Author Permissions](./author-permissions.md)
-- Issue/file matching helpers (see source FailureConditionEvaluator for the full list)
+### Additional context variables
+
+- `memory`: accessor for the memory store (see [Memory](./memory.md))
+  - `memory.get(key, namespace?)` - Get a value
+  - `memory.has(key, namespace?)` - Check if key exists
+  - `memory.list(namespace?)` - List keys
+  - `memory.getAll(namespace?)` - Get all key-value pairs
+- `inputs`: workflow inputs (for workflows)
+- `env`: environment variables
+- `debug`: debug information (if available)
+  - `debug.errors` - Array of error messages
+  - `debug.processingTime` - Processing time in milliseconds
+  - `debug.provider` - AI provider used
+  - `debug.model` - AI model used
+
+### Context for `if` conditions
+
+When used in `if` conditions (not `fail_if`), additional context is available:
+
+- `branch`: current branch name
+- `baseBranch`: target branch (default: `main`)
+- `filesChanged`: array of changed file paths
+- `filesCount`: number of changed files
+- `event`: GitHub event context with `event_name`, `action`, `repository`, etc.
+- `checkName`, `schema`, `group`: check metadata
+
+### Legacy context (backward compatibility)
+
+- `issues`: shorthand for `output.issues`
+- `criticalIssues`, `errorIssues`, `warningIssues`, `infoIssues`, `totalIssues`: count of issues by severity
+- `metadata`: object containing `checkName`, `schema`, `group`, issue counts, `hasChanges`, `branch`, `event`
+
+## Helper functions
+
+### String helpers
+- `contains(haystack, needle)` - Case-insensitive substring check
+- `startsWith(s, prefix)` - Case-insensitive prefix check
+- `endsWith(s, suffix)` - Case-insensitive suffix check
+- `length(x)` - Length of string, array, or object keys
+
+### Control helpers
+- `always()` - Always returns `true`
+- `success()` - Returns `true`
+- `failure()` - Returns `false`
+
+### Debugging
+- `log(...args)` - Print debug output prefixed with emoji. See [Debugging Guide](./debugging.md)
+
+### Issue/file matching helpers
+- `hasIssue(issues, field, value)` - Check if any issue has a field matching value
+- `countIssues(issues, field, value)` - Count issues matching field/value
+- `hasFileMatching(issues, pattern)` - Check if any issue affects a file matching pattern
+- `hasIssueWith(issues, field, value)` - Alias for `hasIssue`
+- `hasFileWith(issues, pattern)` - Alias for `hasFileMatching`
+
+### Author permission helpers
+- `hasMinPermission(level)` - Check if author has at least the specified permission level
+- `isOwner()` - Check if author is repository owner
+- `isMember()` - Check if author is organization member
+- `isCollaborator()` - Check if author is collaborator
+- `isContributor()` - Check if author has contributed before
+- `isFirstTimer()` - Check if author is a first-time contributor
+
+See [Author Permissions](./author-permissions.md) for detailed usage.
 
-Truthiness rules follow JavaScript: non‑empty strings are truthy, `""` and `null`/`undefined` are falsy, `0` is falsy.
+## Truthiness
+
+Truthiness rules follow JavaScript: non-empty strings are truthy, `""` and `null`/`undefined` are falsy, `0` is falsy.
+
+## Complex failure conditions
+
+For more control, use the complex form with additional options:
+
+```yaml
+failure_conditions:
+  no_critical_issues:
+    condition: "criticalIssues > 0"
+    message: "Critical security issues found"
+    severity: error      # error, warning, or info
+    halt_execution: true # Stop all execution immediately
+```
+
+Options:
+- `condition`: The expression to evaluate (required)
+- `message`: Human-readable message when condition triggers (optional)
+- `severity`: Issue severity level - `error`, `warning`, or `info` (default: `error`)
+- `halt_execution`: If `true`, stops all workflow execution immediately (default: `false`)
 
 ## What happens when a condition is met
 
-- The engine adds an error‑severity issue to the check with ruleId `<checkName>_fail_if` (or `global_fail_if` for the global rule).
+- The engine adds an issue to the check with ruleId `<checkName>_fail_if` (or `global_fail_if` for the global rule).
+- Issue severity is `error` by default (configurable with complex form).
 - Direct dependents of that check are skipped with reason `dependency_failed`.
-- Skipped checks do not execute their providers; they appear as ⏭ in the details table.
+- Skipped checks do not execute their providers; they appear as skipped in the details table.
+- If `halt_execution: true`, the entire workflow stops immediately.
 
 Only direct dependencies gate execution. Transitive checks are gated through the chain (i.e., if A fails B, and C depends on B, C will also be skipped once B is skipped).
 
@@ -88,8 +172,29 @@ fail_if: output.some(x => x.status === 'fail')
 
 Per‑item fail logic is not evaluated via `fail_if`; use `if:` to skip item work or emit issues inside the per‑item action.
 
+## Multi-line expressions
+
+You can write multi-line expressions with debug statements:
+
+```yaml
+fail_if: |
+  log("Checking output:", output);
+  log("Issue count:", output.issues?.length);
+  output.issues?.some(i => i.severity === 'critical')
+```
+
+The last expression determines the boolean result. Lines are joined using the comma operator.
+
 ## Notes
 
-- Fail conditions are evaluated during dependency‑aware execution as part of the engine (not only in providers), ensuring dependents are reliably skipped even if a provider path didn’t attach issues.
-- Issue ruleIds are consistent: `<checkName>_fail_if` for per‑check and `global_fail_if` for global.
+- Fail conditions are evaluated during dependency-aware execution as part of the engine (not only in providers), ensuring dependents are reliably skipped even if a provider path didn't attach issues.
+- Issue ruleIds are consistent: `<checkName>_fail_if` for per-check and `global_fail_if` for global.
+- Expressions support optional chaining (`?.`) and nullish coalescing (`??`) for safe property access.
+- If expression evaluation fails, the condition is treated as `false` (fail-safe behavior).
+
+## Related documentation
 
+- [Author Permissions](./author-permissions.md) - Permission helper functions
+- [Debugging Guide](./debugging.md) - Using `log()` and other debugging techniques
+- [Memory](./memory.md) - Memory store access in expressions
+- [Configuration](./configuration.md) - Full configuration reference

package/dist/docs/failure-conditions-implementation.md

@@ -1,5 +1,17 @@
 # Enhanced Failure Condition System for Visor
 
+> **Status: Partially Outdated**
+>
+> This document was written during initial implementation and some details are now outdated.
+> For current usage, see:
+> - [fail-if.md](./fail-if.md) - Primary documentation for failure conditions (recommended)
+> - [failure-conditions-schema.md](./failure-conditions-schema.md) - Configuration schema reference
+>
+> Key differences from current implementation:
+> - Integration is now via `StateMachineExecutionEngine` (not `CheckExecutionEngine`)
+> - The simpler `fail_if` syntax is now the recommended approach
+> - Additional helper functions exist (see fail-if.md for complete list)
+
 This document provides a complete overview of the enhanced failure condition configuration system implemented for the Visor code review tool.
 
 ## Overview
@@ -18,9 +30,9 @@ The enhanced failure condition system allows users to define flexible, powerful
    - TypeScript interfaces for failure conditions
    - Context object definition for expression evaluation
 
-3. **CheckExecutionEngine Integration** (`src/check-execution-engine.ts`)
-   - Integration with existing check execution pipeline
-   - Automated evaluation after check completion
+3. **StateMachineExecutionEngine Integration** (`src/state-machine-execution-engine.ts`)
+   - Integration with the state machine execution pipeline
+   - Automated evaluation after check completion via `evaluateFailureConditions()` method
 
 ## Configuration Schema
 
@@ -85,11 +97,20 @@ The context object available to all JavaScript expressions (evaluated in a secur
 
 ## Available Helper Functions
 
+> **Note**: This list is incomplete. See [fail-if.md](./fail-if.md#helper-functions) for the complete and current list of helper functions.
+
 ### Issue Analysis
 - `hasIssueWith(issues, field, value)` - Check if any issue has field matching value
 - `countIssues(issues, field, value)` - Count issues with field matching value
 - `hasFileWith(issues, text)` - Check if any issue file path contains text
 
+### Additional helpers (not listed here)
+- String helpers: `contains()`, `startsWith()`, `endsWith()`, `length()`
+- Control helpers: `always()`, `success()`, `failure()`
+- Debug helper: `log()` for debugging expressions
+- Permission helpers: `hasMinPermission()`, `isOwner()`, `isMember()`, etc.
+- Memory accessor: `memory.get()`, `memory.has()`, `memory.list()`, `memory.getAll()`
+
 ## Example Use Cases
 
 ### Basic Quality Gates
@@ -157,13 +178,15 @@ failure_conditions:
 
 ## Integration Points
 
-### CheckExecutionEngine
+### StateMachineExecutionEngine
 ```typescript
 // Evaluate conditions after check completion
 const results = await engine.evaluateFailureConditions(
   checkName,
   reviewSummary,
-  config
+  config,
+  previousOutputs,
+  authorAssociation
 );
 
 // Check if execution should halt
@@ -172,6 +195,8 @@ if (FailureConditionEvaluator.shouldHaltExecution(results)) {
 }
 ```
 
+> **Note**: The integration was originally in `CheckExecutionEngine` but has been migrated to `StateMachineExecutionEngine` as part of the engine refactor.
+
 ### GitHub Action Integration
 Failure conditions can be used to:
 - Set action exit codes
@@ -268,4 +293,13 @@ steps:
 
 The enhanced failure condition system provides a flexible, powerful foundation for implementing custom quality gates and policies in Visor. By leveraging JavaScript expressions (evaluated in a secure sandbox) with comprehensive context access, teams can create sophisticated review workflows that adapt to their specific needs and standards.
 
-The system maintains full backward compatibility while opening new possibilities for automated code quality enforcement and intelligent review assistance.
+The system maintains full backward compatibility while opening new possibilities for automated code quality enforcement and intelligent review assistance.
+
+## Related Documentation
+
+- [fail-if.md](./fail-if.md) - **Primary documentation** for failure conditions (recommended starting point)
+- [failure-conditions-schema.md](./failure-conditions-schema.md) - Configuration schema reference
+- [author-permissions.md](./author-permissions.md) - Permission helper functions
+- [debugging.md](./debugging.md) - Using `log()` and debugging techniques
+- [memory.md](./memory.md) - Memory store access in expressions
+- [configuration.md](./configuration.md) - Full configuration reference

package/dist/docs/failure-conditions-schema.md

@@ -1,42 +1,63 @@
-# Enhanced Failure Condition Configuration Schema
+# Failure Condition Configuration Schema
 
-This document describes the enhanced failure condition configuration system for Visor that supports JavaScript expressions (evaluated in a secure sandbox) for flexible and powerful failure evaluation.
+This document describes the failure condition configuration system for Visor that supports JavaScript expressions (evaluated in a secure sandbox) for flexible and powerful failure evaluation.
 
-## YAML Configuration Schema
+> **Note:** The simple `fail_if` syntax is now preferred over the legacy `failure_conditions` object syntax. See [Fail If](./fail-if.md) for the recommended approach.
 
-### Global Failure Conditions
+## Quick Start: Using `fail_if` (Recommended)
+
+The simplest way to define failure conditions:
 
 ```yaml
 version: "1.0"
 
-# Global failure conditions apply to all checks
-failure_conditions:
-  # Simple JavaScript expression for basic failure conditions
-  critical_threshold: "metadata.criticalIssues > 0"
+# Global fail_if applies to all steps unless overridden
+fail_if: "output.error || criticalIssues > 0"
 
-  # Complex conditions with multiple criteria
-  security_gate: "metadata.checkName == 'security' && metadata.criticalIssues > 0"
+steps:
+  security:
+    type: ai
+    prompt: "Analyze for security vulnerabilities..."
+    schema: code-review
+    on:
+      - pr_opened
+      - pr_updated
+    # Step-specific fail_if overrides global
+    fail_if: "criticalIssues > 0 || errorIssues >= 3"
 
-  # Schema-based conditions
-  code_review_quality: "metadata.schema == 'code-review' && metadata.totalIssues > 10"
+  performance:
+    type: ai
+    prompt: "Analyze performance implications..."
+    schema: code-review
+    on:
+      - pr_opened
+      - pr_updated
+    # Complex condition with helper functions
+    fail_if: "hasIssue(issues, 'category', 'performance') && errorIssues > 1"
+```
+
+## Legacy: Complex Failure Conditions
 
-  # Combined conditions with logical operators
-  deployment_blocker: "metadata.criticalIssues > 0 || (metadata.errorIssues > 5 && metadata.checkName == 'security')"
+For more control, use the complex `failure_conditions` object syntax (deprecated but still supported):
 
-# Alternative object syntax for more complex conditions
+```yaml
+version: "1.0"
+
+# Object syntax for complex conditions with additional options
 failure_conditions:
   critical_security_issues:
-    condition: "metadata.criticalIssues > 0 && metadata.checkName == 'security'"
+    condition: "criticalIssues > 0"
     message: "Critical security issues detected - deployment blocked"
     severity: "error"
+    halt_execution: true  # Stop all execution immediately
 
   performance_degradation:
-    condition: "metadata.checkName == 'performance' && metadata.errorIssues >= 3"
+    condition: "hasIssue(issues, 'category', 'performance') && errorIssues >= 3"
     message: "Performance issues detected that may impact production"
     severity: "warning"
 
   insufficient_coverage:
-    condition: "metadata.schema == 'code-review' && metadata.totalIssues > 15"
+    condition: "totalIssues > 15"
     message: "Too many code quality issues - consider additional review"
     severity: "info"
 
@@ -49,69 +70,160 @@ steps:
     on:
       - pr_opened
       - pr_updated
-
-    # Check-specific failure conditions override global ones
-    failure_conditions:
-      block_on_any_critical: "metadata.criticalIssues > 0"
-      warn_on_multiple_errors: "metadata.errorIssues >= 2"
-
-  performance:
-    type: ai
-    prompt: "Analyze performance implications..."
-    group: review
-    schema: code-review
-    on:
-      - pr_opened
-      - pr_updated
-
-    # Inherits global failure conditions unless overridden
+    # Step-specific failure conditions override global ones with same name
     failure_conditions:
-      performance_regression: "metadata.errorIssues > 1 && issues.some(i => i.category == 'performance')"
+      block_on_any_critical: "criticalIssues > 0"
+      warn_on_multiple_errors: "errorIssues >= 2"
 ```
 
 ### Advanced JavaScript Expression Examples
 
 ```yaml
-failure_conditions:
-  # Issue analysis with helper functions
-  sql_injection_check: "hasFileWith(issues, 'sql') && hasIssueWith(issues, 'severity', 'critical')"
+steps:
+  security-check:
+    type: ai
+    prompt: "Analyze for security issues..."
+    # Issue analysis with helper functions
+    fail_if: "hasFileWith(issues, 'sql') && hasIssue(issues, 'severity', 'critical')"
 
-  # Multiple file types analysis
-  critical_files_affected: "hasFileWith(issues, '.ts') || hasFileWith(issues, '.js') && hasIssueWith(issues, 'severity', 'critical')"
+  critical-files:
+    type: ai
+    prompt: "Review critical files..."
+    # Multiple file types analysis
+    fail_if: "(hasFileWith(issues, '.ts') || hasFileWith(issues, '.js')) && hasIssue(issues, 'severity', 'critical')"
 
-  # Complex metadata-based conditions
-  large_change_with_issues: "metadata.totalIssues > 5 && debug && debug.processingTime > 30000"
+  performance-check:
+    type: ai
+    prompt: "Analyze performance..."
+    # Time-based conditions (if debug info is available)
+    fail_if: "debug && debug.processingTime > 60000 && errorIssues > 0"
 
-  # Schema and group combinations
-  review_blocking_issues: "metadata.schema == 'code-review' && metadata.group == 'review' && metadata.criticalIssues > 0"
+  auth-check:
+    type: ai
+    prompt: "Check authentication code..."
+    # File-specific security checks with counting
+    fail_if: "hasFileWith(issues, 'auth') && countIssues(issues, 'severity', 'critical') > 0"
 
-  # Time-based conditions (if debug info is available)
-  slow_analysis_with_errors: "debug && debug.processingTime > 60000 && metadata.errorIssues > 0"
+  security-count:
+    type: ai
+    prompt: "Security analysis..."
+    # Count-based conditions
+    fail_if: "countIssues(issues, 'category', 'security') >= 3"
+```
 
-  # File-specific security checks
-  sensitive_file_changes: "hasFileWith(issues, 'auth') || hasFileWith(issues, 'password') || hasFileWith(issues, 'secret')"
+## Available Context Variables
+
+### Primary Context
+
+| Variable | Description |
+|----------|-------------|
+| `output` | Current step's structured output (includes `issues` and provider-specific fields) |
+| `outputs` | Map of dependency outputs keyed by step name |
+| `memory` | Memory store accessor (see [Memory](./memory.md)) |
+| `inputs` | Workflow inputs (for workflows) |
+| `env` | Environment variables |
+| `debug` | Debug information (`errors`, `processingTime`, `provider`, `model`) |
+
+### Legacy Context (Backward Compatibility)
+
+| Variable | Description |
+|----------|-------------|
+| `issues` | Shorthand for `output.issues` |
+| `criticalIssues` | Count of critical severity issues |
+| `errorIssues` | Count of error severity issues |
+| `warningIssues` | Count of warning severity issues |
+| `infoIssues` | Count of info severity issues |
+| `totalIssues` | Total issue count |
+| `metadata` | Object with `checkName`, `schema`, `group`, issue counts, etc. |
+
+### Additional Context for `if` Conditions
+
+| Variable | Description |
+|----------|-------------|
+| `branch` | Current branch name |
+| `baseBranch` | Target branch (default: `main`) |
+| `filesChanged` | Array of changed file paths |
+| `filesCount` | Number of changed files |
+| `event` | GitHub event context (`event_name`, `action`, `repository`, etc.) |
+| `checkName` | Current check name |
+| `schema` | Check schema |
+| `group` | Check group |
+
+## Available Helper Functions
+
+### String Helpers
+
+| Function | Description |
+|----------|-------------|
+| `contains(haystack, needle)` | Case-insensitive substring check |
+| `startsWith(s, prefix)` | Case-insensitive prefix check |
+| `endsWith(s, suffix)` | Case-insensitive suffix check |
+| `length(x)` | Length of string, array, or object keys |
+
+### Control Helpers
+
+| Function | Description |
+|----------|-------------|
+| `always()` | Always returns `true` |
+| `success()` | Returns `true` |
+| `failure()` | Returns `false` |
+
+### Issue/File Matching Helpers
+
+| Function | Description |
+|----------|-------------|
+| `hasIssue(issues, field, value)` | Check if any issue has a field matching value |
+| `countIssues(issues, field, value)` | Count issues matching field/value |
+| `hasFileMatching(issues, pattern)` | Check if any issue affects a file matching pattern |
+| `hasIssueWith(issues, field, value)` | Alias for `hasIssue` |
+| `hasFileWith(issues, pattern)` | Alias for `hasFileMatching` |
+
+### Permission Helpers
+
+| Function | Description |
+|----------|-------------|
+| `hasMinPermission(level)` | Check if author has at least the specified permission level |
+| `isOwner()` | Check if author is repository owner |
+| `isMember()` | Check if author is organization member |
+| `isCollaborator()` | Check if author is collaborator |
+| `isContributor()` | Check if author has contributed before |
+| `isFirstTimer()` | Check if author is a first-time contributor |
+
+### Debugging
+
+| Function | Description |
+|----------|-------------|
+| `log(...args)` | Print debug output prefixed with emoji (see [Debugging Guide](./debugging.md)) |
 
-  # Count-based conditions
-  multiple_security_issues: "countIssues(issues, 'category', 'security') >= 3"
+## Configuration Priority and Inheritance
 
-  # Combined conditions
-  critical_auth_issues: "hasFileWith(issues, 'auth') && countIssues(issues, 'severity', 'critical') > 0"
-```
+1. **Step-specific conditions** override global conditions with the same name
+2. **Global conditions** apply to all steps unless specifically overridden
+3. **Multiple conditions** are evaluated independently - any true condition triggers a failure
 
-## Configuration Priority and Inheritance
+## Interaction with Criticality
+
+Failure conditions (`fail_if`) and design-by-contract (`assume`, `guarantee`) work together with criticality:
+
+- **Critical steps** (external/control-plane/policy):
+  - Require meaningful `assume` and `guarantee`.
+  - `continue_on_failure: false` by default; dependents skip when this step fails.
+  - Retries only for transient provider faults; no auto-retry for logical failures (`fail_if`/`guarantee`).
+- **Non-critical steps**:
+  - Contracts recommended; may allow `continue_on_failure: true`.
+  - Same retry bounds; tolerant gating.
 
-1. **Check-specific conditions** override global conditions with the same name
-2. **Global conditions** apply to all checks unless specifically overridden
-3. **Built-in conditions** (if any) have the lowest priority
-4. **Multiple conditions** are evaluated independently - any true condition triggers a failure
+See [Fault Management and Contracts](./guides/fault-management-and-contracts.md) for the full policy checklist and examples.
 
 ## Backward Compatibility
 
-The enhanced system maintains full backward compatibility:
+The system maintains full backward compatibility with both `fail_if` and `failure_conditions`:
 
 ```yaml
-# Legacy format (still supported)
+# Simple fail_if (recommended)
 version: "1.0"
+fail_if: "criticalIssues > 0"
+
 steps:
   security:
     type: ai
@@ -119,11 +231,15 @@ steps:
     on:
       - pr_opened
       - pr_updated
+    fail_if: "errorIssues >= 1"
 
-# Enhanced format with failure conditions
+# Legacy failure_conditions (still supported)
 version: "1.0"
 failure_conditions:
-  default_critical: "metadata.criticalIssues > 0"
+  default_critical:
+    condition: "criticalIssues > 0"
+    message: "Critical issues found"
+    severity: error
 
 steps:
   security:
@@ -132,42 +248,82 @@ steps:
     on:
       - pr_opened
       - pr_updated
+    failure_conditions:
+      security_specific: "errorIssues >= 1"
+```
 
-## Interaction with Criticality
+## Migration Guide
 
-Failure conditions (`fail_if`) and design‑by‑contract (`assume`, `guarantee`) work together with criticality:
+### Migrating from `failure_conditions` to `fail_if`
 
-- Critical steps (external/control‑plane/policy):
-  - Require meaningful `assume` and `guarantee`.
-  - `continue_on_failure: false` by default; dependents skip when this step fails.
-  - Retries only for transient provider faults; no auto‑retry for logical failures (`fail_if`/`guarantee`).
-- Non‑critical steps:
-  - Contracts recommended; may allow `continue_on_failure: true`.
-  - Same retry bounds; tolerant gating.
+If you have existing `failure_conditions` configurations, migrate them to `fail_if`:
 
-See docs/guides/fault-management-and-contracts.md for the full policy checklist and examples.
-    failure_conditions:
-      security_specific: "metadata.errorIssues >= 1"
+**Before (legacy):**
+```yaml
+failure_conditions:
+  critical_blocker:
+    condition: "metadata.criticalIssues > 0"
+    message: "Critical issues found"
+    severity: error
+  quality_gate:
+    condition: "metadata.totalIssues > 10"
+    severity: warning
 ```
 
-## Migration Guide
+**After (recommended):**
+```yaml
+# Simple condition - just use fail_if
+fail_if: "criticalIssues > 0 || totalIssues > 10"
+```
 
-### Step 1: Add Global Conditions
+If you need the `halt_execution` feature, keep using the complex form:
 ```yaml
-# Add to existing configuration
 failure_conditions:
-  critical_blocker: "metadata.criticalIssues > 0"
-  quality_gate: "metadata.totalIssues > 10"
+  critical_blocker:
+    condition: "criticalIssues > 0"
+    message: "Critical issues found"
+    severity: error
+    halt_execution: true
+```
+
+### Step-by-Step Migration
+
+1. Replace `metadata.criticalIssues` with `criticalIssues` (legacy variables still work)
+2. Replace `hasIssueWith` with `hasIssue` (both work, but `hasIssue` is clearer)
+3. Use `fail_if` string instead of `failure_conditions` object when possible
+4. Test with `--debug` flag to verify expressions evaluate correctly
+
+### Testing Your Conditions
+
+Use debug mode to test conditions and refine expressions:
+
+```bash
+visor --config your-config.yaml --debug
 ```
 
-### Step 2: Add Check-Specific Conditions
+You can also use the `log()` helper in expressions:
 ```yaml
-steps:
-  security:
-    # existing configuration...
-    failure_conditions:
-      security_gate: "metadata.errorIssues >= 1"
+fail_if: |
+  log("Issues:", issues);
+  log("Critical count:", criticalIssues);
+  criticalIssues > 0
 ```
 
-### Step 3: Test and Refine
-Use debug mode to test conditions and refine expressions based on actual results.
+## Complex Failure Condition Options
+
+When using the object syntax, these options are available:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `condition` | string | required | JavaScript expression to evaluate |
+| `message` | string | - | Human-readable message when condition triggers |
+| `severity` | string | `"error"` | Severity level: `error`, `warning`, or `info` |
+| `halt_execution` | boolean | `false` | If `true`, stops all workflow execution immediately |
+
+## Related Documentation
+
+- [Fail If](./fail-if.md) - Recommended simple syntax for failure conditions
+- [Author Permissions](./author-permissions.md) - Permission helper functions
+- [Debugging Guide](./debugging.md) - Using `log()` and debugging techniques
+- [Memory](./memory.md) - Memory store access in expressions
+- [Fault Management and Contracts](./guides/fault-management-and-contracts.md) - Criticality and contracts