@probelabs/visor 0.1.124 → 0.1.126

package/dist/docs/lifecycle-hooks.md

@@ -1,6 +1,13 @@
 # Lifecycle Hooks
 
-Lifecycle hooks allow you to execute preprocessing or setup tasks automatically before a step runs. This is particularly useful for enriching context, fetching external data, or preparing the environment.
+Visor provides four lifecycle hooks that allow you to control step execution at different phases:
+
+| Hook | When it Runs | Use Case |
+|------|--------------|----------|
+| `on_init` | **Before** step execution | Preprocessing, data fetching, context enrichment |
+| `on_success` | **After** step succeeds | Post-processing, notifications, routing to next step |
+| `on_fail` | **After** step fails | Error handling, retries, remediation |
+| `on_finish` | **After all** forEach iterations complete | Aggregation, validation across all items |
 
 ## `on_init` Hook
 
@@ -245,9 +252,322 @@ See the `examples/` directory for comprehensive examples:
 4. **Use `run_js` for conditionals**: Avoid fetching unnecessary data
 5. **Handle failures gracefully**: Consider what happens if preprocessing fails
 
-### See Also
+---
+
+## `on_success` Hook
+
+The `on_success` hook runs **after** a step completes successfully. It allows you to:
+- Run post-processing steps
+- Trigger notifications or downstream actions
+- Jump back to a previous step for re-evaluation (routing)
+
+### Basic Usage
+
+```yaml
+steps:
+  build:
+    type: command
+    exec: npm run build
+    on_success:
+      run: [notify, deploy]
+```
+
+### Configuration Options
+
+```yaml
+on_success:
+  # Run additional steps after success
+  run: [step1, step2]
+
+  # Optional: jump back to an ancestor step
+  goto: previous-step
+
+  # Optional: simulate a different event during goto
+  goto_event: pr_updated
+
+  # Dynamic step selection (JS expression returning string[])
+  run_js: |
+    return outputs['build'].hasWarnings ? ['review-warnings'] : [];
+
+  # Dynamic routing (JS expression returning step id or null)
+  goto_js: |
+    // Re-run once using history length as attempt counter
+    return outputs.history['build'].length === 1 ? 'setup' : null;
+
+  # Declarative transitions (evaluated in order, first match wins)
+  transitions:
+    - when: "outputs['build'].score >= 90"
+      to: publish
+    - when: "outputs['build'].score >= 70"
+      to: review
+    - when: "true"
+      to: null  # No routing
+```
+
+### Example: Conditional Post-Processing
+
+```yaml
+steps:
+  analyze:
+    type: ai
+    prompt: Analyze code quality
+    on_success:
+      run_js: |
+        const result = outputs['analyze'];
+        if (result.issues?.length > 0) {
+          return ['create-report', 'notify-team'];
+        }
+        return ['mark-approved'];
+
+  create-report:
+    type: command
+    exec: generate-report.sh
+    on: []
+
+  notify-team:
+    type: http
+    url: https://slack.webhook.url
+    on: []
+
+  mark-approved:
+    type: command
+    exec: gh pr review --approve
+    on: []
+```
+
+---
+
+## `on_fail` Hook
+
+The `on_fail` hook runs **after** a step fails. It provides mechanisms for:
+- Automatic retries with backoff
+- Running remediation steps before retry
+- Jumping back to an ancestor step for re-execution
+
+### Basic Usage
+
+```yaml
+steps:
+  deploy:
+    type: command
+    exec: ./deploy.sh
+    on_fail:
+      retry:
+        max: 3
+        backoff:
+          mode: exponential
+          delay_ms: 1000
+```
+
+### Configuration Options
+
+```yaml
+on_fail:
+  # Retry configuration
+  retry:
+    max: 3                           # Maximum retry attempts
+    backoff:
+      mode: fixed | exponential      # Backoff strategy
+      delay_ms: 1000                 # Initial delay
+
+  # Run remediation steps before retry
+  run: [cleanup, reset-state]
+
+  # Jump back to ancestor step
+  goto: setup
+
+  # Simulate different event during goto
+  goto_event: pr_updated
+
+  # Dynamic remediation (JS returning string[])
+  run_js: |
+    if (output.error?.includes('lock')) {
+      return ['clear-locks'];
+    }
+    return [];
+
+  # Dynamic routing (JS returning step id or null)
+  goto_js: |
+    return attempt < 2 ? 'install-deps' : null;
+
+  # Declarative transitions
+  transitions:
+    - when: "output.error?.includes('timeout')"
+      to: null  # Don't route, just retry
+    - when: "output.error?.includes('auth')"
+      to: refresh-auth
+```
+
+### Example: Remediation with Retry
+
+```yaml
+steps:
+  install:
+    type: command
+    exec: npm ci
+
+  test:
+    type: command
+    depends_on: [install]
+    exec: npm test
+    on_fail:
+      run: [clean-cache]
+      retry:
+        max: 2
+        backoff:
+          mode: fixed
+          delay_ms: 500
+
+  clean-cache:
+    type: command
+    exec: rm -rf node_modules/.cache
+    on: []  # Helper step only
+```
+
+---
+
+## `on_finish` Hook
+
+The `on_finish` hook runs **once** after a `forEach` step completes **all** iterations and all dependent checks. This is ideal for:
+- Aggregating results from all forEach iterations
+- Making routing decisions based on collective outcomes
+- Validation across all processed items
+
+**Note:** `on_finish` only applies to steps with `forEach: true`.
+
+### When It Triggers
+
+1. The forEach step produces an array of items
+2. All dependent steps execute for each item
+3. After ALL iterations complete, `on_finish` triggers once
+
+### Basic Usage
+
+```yaml
+steps:
+  process-files:
+    type: command
+    exec: "echo '[\"/a.ts\", \"/b.ts\", \"/c.ts\"]'"
+    forEach: true
+    on_finish:
+      run: [summarize-results]
+      goto_js: |
+        const results = outputs.history['validate-file'];
+        const allValid = results.every(r => r.valid);
+        return allValid ? null : 'process-files';  # Retry if any failed
+
+  validate-file:
+    type: ai
+    depends_on: [process-files]
+    prompt: Validate {{ outputs['process-files'] }}
+
+  summarize-results:
+    type: script
+    content: |
+      const results = outputs.history['validate-file'];
+      return {
+        total: results.length,
+        passed: results.filter(r => r.valid).length
+      };
+    on: []
+```
+
+### Available Context
+
+The `on_finish` context is richer than other hooks:
+
+```javascript
+{
+  step: { id: 'process-files', tags: [...] },
+  attempt: 1,              // Current attempt number
+  loop: 0,                 // Current loop in routing
+  outputs: {
+    'process-files': [...],  // Array of forEach items
+    'validate-file': [...],  // ALL dependent results
+    history: { ... }         // Alias for outputs_history
+  },
+  outputs_history: {
+    'process-files': [[...], ...],
+    'validate-file': [[...], ...],
+  },
+  outputs_raw: {
+    'process-files': [...],  // Aggregate/parent values
+  },
+  forEach: {
+    items: 3,              // Number of items
+    last_wave_size: 3,
+    last_items: [...],
+    is_parent: true
+  },
+  memory: { get, set, has, getAll, increment, clear },
+  pr: { number, title, author, branch, base },
+  files: [...],
+  env: { ... },
+  event: { name: '...' }
+}
+```
+
+### Example: Validation with Retry
+
+```yaml
+steps:
+  extract-facts:
+    type: ai
+    forEach: true
+    transform_js: JSON.parse(output).facts
+    on_finish:
+      run: [aggregate-validations]
+      goto_js: |
+        const allValid = memory.get('all_valid', 'validation');
+        const attempt = memory.get('attempt', 'validation') || 0;
+
+        if (allValid || attempt >= 2) {
+          return null;  // Success or max attempts
+        }
+
+        memory.increment('attempt', 1, 'validation');
+        return 'generate-response';  # Retry from ancestor
+
+  validate-fact:
+    type: ai
+    depends_on: [extract-facts]
+    prompt: Validate this fact...
+
+  aggregate-validations:
+    type: script
+    content: |
+      const results = outputs.history['validate-fact'];
+      const allValid = results.every(r => r.is_valid);
+      memory.set('all_valid', allValid, 'validation');
+      return { total: results.length, valid: results.filter(r => r.is_valid).length };
+    on: []
+```
+
+---
+
+## Loop Protection & Safety
+
+All routing hooks (`on_success`, `on_fail`, `on_finish`) are subject to loop protection:
+
+```yaml
+routing:
+  max_loops: 10  # Per-scope cap on routing transitions
+```
+
+- **Retry counters**: Each step tracks attempt count independently
+- **Loop budget**: Total routing transitions (goto + run) are capped per scope
+- **forEach isolation**: Each item has its own loop/attempt counters
+
+For hard caps on step executions, see [Execution Limits](./limits.md).
+
+---
+
+## See Also
 
+- [Failure Routing](./failure-routing.md) - Complete guide to on_success, on_fail, on_finish
 - [Custom Tools](./custom-tools.md) - Define reusable MCP tools
 - [Workflows](./workflows.md) - Create reusable workflows
 - [Liquid Templates](./liquid-templates.md) - Template syntax for dynamic values
+- [Output History](./output-history.md) - Accessing historical outputs in routing
+- [Execution Limits](./limits.md) - Configuring execution caps
 - [RFC: on_init Hook](./rfc/on_init-hook.md) - Design proposal and rationale

package/dist/docs/limits.md

@@ -9,13 +9,14 @@ This feature protects workflows from accidental infinite loops by capping how ma
 
 ### Configuration
 
-Global (default is 50 if omitted):
+Global limits (defaults shown):
 
 ```yaml
 version: "1.0"
 
 limits:
-  max_runs_per_check: 50  # Applies to every step unless overridden
+  max_runs_per_check: 50   # Applies to every step unless overridden
+  max_workflow_depth: 3    # Maximum nesting depth for nested workflows
 ```
 
 Per-step override:
@@ -47,9 +48,23 @@ steps:
 
 ### How this differs from `routing.max_loops`
 
-- `routing.max_loops` caps routing transitions (e.g., goto/retry waves) per scope.
-- `limits.max_runs_per_check` caps actual step executions per step (also per scope for `forEach`).
-- Both guard rails can be used together: set a modest routing budget (e.g., 5–10) and leave the execution cap at the default (50) or tailor per step.
+- `routing.max_loops` caps routing transitions (e.g., goto/retry waves) per scope. Default: 10.
+- `limits.max_runs_per_check` caps actual step executions per step (also per scope for `forEach`). Default: 50.
+- `limits.max_workflow_depth` caps nested workflow invocations. Default: 3.
+- Both execution and routing guard rails can be used together: set a modest routing budget (e.g., 5-10) and leave the execution cap at the default (50) or tailor per step.
+
+### Workflow Depth Limit
+
+The `max_workflow_depth` setting prevents infinite recursion when workflows call other workflows:
+
+```yaml
+limits:
+  max_workflow_depth: 3  # Maximum nesting depth (default: 3)
+```
+
+When the depth limit is exceeded, the workflow provider throws an error. This protects against:
+- Accidentally creating recursive workflow chains
+- Runaway nested workflow invocations
 
 ### Recommendations
 

package/dist/docs/liquid-templates.md

@@ -103,6 +103,20 @@ The `json` filter serializes objects to JSON strings, useful for debugging or pa
 # Debug output object
 {{ outputs | json }}
 
+# Debug specific check output
+{{ outputs.security | json }}
+
+# Pass to command safely
+echo '{{ pr | json }}' | jq .
+
+# Create JSON payload
+{
+  "title": {{ pr.title | json }},
+  "files": {{ files | json }},
+  "outputs": {{ outputs | json }}
+}
+```
+
 ### Author Permission Filters
 
 > **📖 For complete documentation, see [Author Permissions Guide](./author-permissions.md)**
@@ -165,20 +179,6 @@ Ticket key: {{ outputs['fetch-tickets'].tickets[0].key }}
 
 If the underlying value is plain text, it behaves as a normal string.
 
-# Debug specific check output
-{{ outputs.security | json }}
-
-# Pass to command safely
-echo '{{ pr | json }}' | jq .
-
-# Create JSON payload
-{
-  "title": {{ pr.title | json }},
-  "files": {{ files | json }},
-  "outputs": {{ outputs | json }}
-}
-```
-
 ### String Filters
 
 ```liquid
@@ -198,6 +198,78 @@ echo '{{ pr | json }}' | jq .
 {{ files | map: "filename" }}   # Array of filenames
 ```
 
+### Encoding Filters
+
+```liquid
+# Base64 encoding/decoding
+{{ "user:password" | base64 }}           # Encode to base64
+{{ encoded_value | base64_decode }}       # Decode from base64
+
+# JSON escaping (for use inside JSON string values)
+"jql": "{{ myValue | json_escape }}"
+```
+
+### Shell Escaping Filters
+
+For safely passing values to shell commands:
+
+```liquid
+# Single-quote escaping (recommended, POSIX-compliant)
+{{ value | shell_escape }}         # "hello'world" becomes "'hello'\''world'"
+{{ value | escape_shell }}         # Alias for shell_escape
+
+# Double-quote escaping (less safe, use when needed)
+{{ value | shell_escape_double }}  # Escapes $, `, \, ", and !
+```
+
+### Utility Filters
+
+```liquid
+# Safe nested access using dot-path
+{{ obj | get: 'a.b.c' }}           # Access nested property safely
+
+# Check if value is non-empty
+{% if items | not_empty %}         # True for non-empty arrays/strings/objects
+  Has items
+{% endif %}
+
+# Pick first non-empty value
+{{ a | coalesce: b, c }}           # Returns first non-empty value
+
+# Expression-based array filtering (Shopify-style)
+{{ items | where_exp: 'i', 'i.is_valid == true' }}
+
+# String manipulation
+{{ value | unescape_newlines }}    # Convert "\n" to actual newlines
+```
+
+### Label Sanitization Filters
+
+For safely formatting labels (only allows `[A-Za-z0-9:/\- ]`):
+
+```liquid
+{{ label | safe_label }}           # Sanitize a single label
+{{ labels | safe_label_list }}     # Sanitize an array of labels
+```
+
+### Memory Store Filters
+
+Access the persistent memory store from templates:
+
+```liquid
+# Get a value from memory
+{{ "my-key" | memory_get }}
+{{ "my-key" | memory_get: "namespace" }}
+
+# Check if a key exists
+{% if "my-key" | memory_has %}
+  Key exists in memory
+{% endif %}
+
+# List all keys in a namespace
+{{ "namespace" | memory_list }}
+```
+
 ### Chat History Helper
 
 The `chat_history` filter turns one or more check histories into a linear, timestamp‑sorted chat transcript. This is especially useful for human‑input + AI chat flows (Slack, CLI, etc.).

package/dist/docs/loop-routing-refactor.md

@@ -25,14 +25,16 @@ The previous behavior de‑duplicated a step when re‑routed in the same event,
 - Skip static `on_success.goto` chains when the target produced fatal issues (including `fail_if`).
 - For `origin='on_fail'`, schedule only direct dependents of the failed target; skip dependents when any direct dep has fatal issues.
 
-4) One‑shot opt‑in
-- `tags: [one_shot]` prevents a terminal step (e.g., `finish`) from running more than once per grouped run.
+4) One‑shot opt‑in (NOT YET IMPLEMENTED)
+- `tags: [one_shot]` would prevent a terminal step (e.g., `finish`) from running more than once per grouped run.
+- Status: Planned but not yet implemented in codebase.
 
 5) Test‑visible history
 - `executeChecks` now attaches `reviewSummary.history` with a safe snapshot of per‑step outputs history for deterministic testing (no I/O).
 
 6) Task‑refinement agent (manual‑only)
 - `defaults/task-refinement.yaml` uses `ask` → `refine` loop with `fail_if` and `on_fail/on_success` only; no `repeatable`, no `goto_js`, no `schedule`.
+- The `finish` step uses an `if` guard to prevent re-execution (workaround for unimplemented `one_shot` tag).
 - Embedded tests: one‑pass and multi‑turn pass locally.
 
 ## Removed