@probelabs/visor 0.1.124 → 0.1.126

package/dist/docs/dev-playbook.md

@@ -1,9 +1,85 @@
-## 🧭 Developer Experience Playbook
-
-- Start with defaults: copy `defaults/.visor.yaml` or an example; run `npx -y @probelabs/visor@latest --check all --debug`.
-- Treat config as code: review `.visor.yaml` and templates; pin providers/models for reproducibility.
-- Roll out gradually: gate heavier checks with tags (`local`, `fast`, `critical`).
-- Secure credentials: prefer GitHub App in production; scope/rotate API keys.
-- Make feedback actionable: group related checks; use `/review --check ...` triggers; enable `reuse_ai_session` for follow-ups.
-- Keep suppressions intentional: annotate context; audit `visor-disable-file` periodically.
-- Validate locally: `npx -y @probelabs/visor@latest --check security --output markdown`; run tests; `--fail-fast` for fast lanes.
+## Developer Experience Playbook
+
+This guide covers both contributing to Visor and using it effectively.
+
+### Quick Start for Contributors
+
+```bash
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run tests
+npm test
+
+# Run the CLI locally
+./dist/index.js --help
+```
+
+### Development Commands
+
+#### Build
+| Command | Description |
+|---------|-------------|
+| `npm run build` | Build CLI and SDK |
+| `npm run build:cli` | Build CLI only |
+| `npm run build:sdk` | Build SDK only |
+| `npm run clean` | Clean dist directory |
+
+#### Testing
+| Command | Description |
+|---------|-------------|
+| `npm test` | Run all tests (Jest + YAML tests) |
+| `npm run test:watch` | Run tests in watch mode |
+| `npm run test:coverage` | Generate coverage report |
+| `npm run test:yaml` | Run YAML-based tests only |
+| `npm run test:yaml:parallel` | Run YAML tests with parallelism |
+
+#### Code Quality
+| Command | Description |
+|---------|-------------|
+| `npm run lint` | Lint TypeScript files |
+| `npm run lint:fix` | Auto-fix linting issues |
+| `npm run format` | Format code with Prettier |
+| `npm run format:check` | Check code formatting |
+
+#### Release
+| Command | Description |
+|---------|-------------|
+| `npm run release` | Interactive release |
+| `npm run release:patch` | Release patch version |
+| `npm run release:minor` | Release minor version |
+| `npm run release:major` | Release major version |
+
+#### Deployment
+| Command | Description |
+|---------|-------------|
+| `npm run deploy` | Deploy site and worker |
+| `npm run deploy:site` | Deploy site to Cloudflare Pages |
+| `npm run deploy:worker` | Deploy worker to Cloudflare |
+
+#### Simulation & Debugging
+| Command | Description |
+|---------|-------------|
+| `npm run simulate:issue` | Simulate GitHub issue event |
+| `npm run simulate:comment` | Simulate GitHub comment event |
+
+### Using Visor Effectively
+
+- **Start with defaults**: Copy `defaults/visor.yaml` or an example from `examples/`; run `npx -y @probelabs/visor@latest --check all --debug`.
+- **Treat config as code**: Review `.visor.yaml` and templates; pin providers/models for reproducibility.
+- **Roll out gradually**: Gate heavier checks with tags (`local`, `fast`, `critical`). See [Tag Filtering](tag-filtering.md).
+- **Secure credentials**: Prefer GitHub App in production; scope/rotate API keys. See [Security](security.md).
+- **Make feedback actionable**: Group related checks; use `/review --check ...` triggers; enable `reuse_ai_session` for follow-ups.
+- **Keep suppressions intentional**: Annotate context; audit `visor-disable-file` periodically. See [Suppressions](suppressions.md).
+- **Validate locally**: `npx -y @probelabs/visor@latest --check security --output markdown`; run tests; `--fail-fast` for fast lanes.
+
+### Related Documentation
+
+- [Configuration](configuration.md) - Full configuration reference
+- [Debugging](debugging.md) - Debugging techniques and troubleshooting
+- [Troubleshooting](troubleshooting.md) - Common issues and solutions
+- [CI/CLI Mode](ci-cli-mode.md) - Running Visor in CI environments
+- [Output Formats](output-formats.md) - Available output formats

package/dist/docs/engine-pause-resume-rfc.md

@@ -1,10 +1,10 @@
 # RFC: Proper Pause/Resume for State-Machine Engine (Event‑Bus + Snapshots)
 
-Status: draft
+Status: implemented
 
 Owner: visor engine
 
-Last updated: 2025-11-20
+Last updated: 2026-01-28
 
 ## Summary
 
@@ -165,19 +165,19 @@ We will add first‑class pause/resume to the state‑machine engine so long‑r
 ## Work Items
 
 - Runner
-  - [ ] Add `deserializeRunState()`
-  - [ ] Add `runner.setState()`
+  - [x] Add `runner.setState()` - Implemented in `src/state-machine/runner.ts`
+  - [~] Add `deserializeRunState()` - Not needed; resume uses fresh run with journal hydration
 - Engine
-  - [ ] Add `resumeFromSnapshot()`
-  - [ ] On HumanInputRequested → `saveSnapshotToFile()` (path via threadKey+checkId)
+  - [x] Add `resumeFromSnapshot()` - Implemented in `src/state-machine-execution-engine.ts`
+  - [x] On HumanInputRequested → `saveSnapshotToFile()` (path via threadKey+checkId)
 - Slack
-  - [ ] PromptState stores `snapshotPath` alongside prompt metadata
-  - [ ] Socket runner loads snapshot and calls `resumeFromSnapshot()` on reply
+  - [x] PromptState stores `snapshotPath` alongside prompt metadata - Implemented in `src/slack/prompt-state.ts`
+  - [x] Socket runner loads snapshot and calls `resumeFromSnapshot()` on reply - Implemented in `src/slack/socket-runner.ts`
 - Tests
-  - [ ] Unit: serialize/deserialize round‑trip
-  - [ ] Integration: pause/resume end‑to‑end (Slack fixture), snapshot deletion
+  - [x] Unit: workspace initialization test in `tests/unit/resume-from-snapshot-workspace.test.ts`
+  - [x] Integration: pause/resume tests in `tests/integration/slack-pause-resume-e2e.test.ts` and `tests/integration/slack-resume-from-snapshot.test.ts`
 - Docs
-  - [ ] Update Slack integration docs and human‑input provider docs
+  - [x] Human-input provider docs mention workflow pausing in `docs/human-input-provider.md`
 
 ## Alternatives Considered
 

package/dist/docs/engine-state-machine-plan.md

@@ -1,5 +1,11 @@
 # Engine State Machine (v2) Research
 
+> **Status: COMPLETED**
+>
+> This planning document describes the state machine engine implementation. All milestones (M0-M4) have been completed. The state machine is now the default engine, and `CheckExecutionEngine` in `src/check-execution-engine.ts` is a compatibility wrapper that re-exports `StateMachineExecutionEngine`.
+>
+> **Note:** Line references in section 1 ("Current Engine Map") are historical and refer to the legacy implementation that has since been refactored into `src/state-machine/`. See `src/state-machine/runner.ts` and `src/state-machine/states/` for the current implementation.
+
 This note captures the current execution flow of the Visor engine, the surfaces where a feature flag can live, and an initial proposal for a bespoke state-machine-based Runner v2. The user-provided research artifact referenced in the request is not available inside this workspace yet, so there are a few open questions that we should fill in once we can read it.
 
 > Safety Model & Criticality (Summary)
@@ -296,12 +302,13 @@ Execution steps:
 3. Emit telemetry (`engine.contract.assume_failed`, `engine.contract.guarantee_failed`) so CI and runtime monitoring can flag contract regressions.
 
 By lifting control flow into `transitions` and correctness rules into `assume`/`guarantee`, we make configurations statically analyzable, reduce reliance on imperative `goto_js`, and move closer to NASA-inspired static validation goals while still honoring legacy constructs for advanced scenarios.
-## 5. Routing and Loops (spec to impl status)
+
+## 6. Routing and Loops (spec to impl status)
 
 - on_success/on_fail evaluate `run`, `run_js`, and `goto` (with optional `goto_event`).
 - on_finish for forEach parents is processed after children complete; loop budget enforced.
 
-### 5.1 Declarative transitions (implemented)
+### 6.1 Declarative transitions (implemented)
 
 In addition to `goto`/`goto_js`, checks can use declarative transitions on `on_success`, `on_fail`, and `on_finish`:
 
@@ -318,7 +325,7 @@ on_finish:
 - Backward compatible: if `transitions` is omitted or none match, the engine falls back to `goto_js/goto`.
 - Helpers available: `outputs`, `outputs_history`, `output`, `event`, `memory`, plus `any/all/none/count`.
 
-### 5.2 Assume/Guarantee contracts (implemented)
+### 6.2 Assume/Guarantee contracts (implemented)
 
 Per-check contracts:
 

package/dist/docs/event-driven-github-integration-rfc.md

@@ -1,7 +1,8 @@
 # RFC: Event-Driven Integrations via Frontends (GitHub, Slack, …)
 
-**Status**: Proposed
+**Status**: Implemented (Phases 1-2 Complete)
 **Created**: 2025-11-19
+**Updated**: 2026-01-28
 **Author**: Architecture Planning
 
 ## Abstract
@@ -710,24 +711,32 @@ Kept intentionally small after adopting defaults above:
 ## Implementation Checklist
 
 ### Phase 1: Foundation
-- [ ] Implement `EventBus` class with subscription management
-- [ ] Add `eventBus` optional parameter to `StateMachineRunner`
-- [ ] Modify `emitEvent()` to publish to event bus
+- [x] Implement `EventBus` class with subscription management (`src/event-bus/event-bus.ts`)
+- [x] Implement `EventEnvelope` and `IntegrationEvent` types (`src/event-bus/types.ts`)
+- [x] Add `eventBus` optional parameter to `StateMachineRunner` (via `EngineContext`)
+- [x] Implement `FrontendsHost` with `Frontend` API (`src/frontends/host.ts`)
+- [x] Implement `NdjsonSink` frontend (`src/frontends/ndjson-sink.ts`)
 - [ ] Add unit tests for `EventBus`
 
-### Phase 2: GitHub Adapter
-- [ ] Implement `GitHubEventAdapter` with request handlers
-- [ ] Add feature flag `experimental.eventDrivenGitHub`
-- [ ] Wire up adapter in `state-machine-execution-engine.ts`
+### Phase 2: GitHub Frontend
+- [x] Implement `GitHubFrontend` with request handlers (`src/frontends/github-frontend.ts`)
+- [x] Wire up adapter in `state-machine-execution-engine.ts`
+- [x] Implement comment grouping with section markers
+- [x] Implement debounce/coalescing for comment updates
+- [x] Implement mutex-based serialization for updates
+- [ ] Add feature flag `experimental.eventDrivenGitHub` (skipped - frontends are enabled by default)
 - [ ] Add integration tests for dual-mode operation
 
-### Phase 3: Multi-Platform Examples
-- [ ] Implement `SlackEventAdapter` (example)
+### Phase 3: Multi-Platform Frontends
+- [x] Implement `SlackFrontend` with direct replies (`src/frontends/slack-frontend.ts`)
+- [x] Slack reaction management (acknowledgement and completion)
+- [x] Mermaid diagram rendering and upload
+- [x] Human input prompt handling via prompt-state
 - [ ] Implement `MetricsEventAdapter` (example)
 - [ ] Document adapter API and patterns
 
 ### Phase 4: Migration (Breaking Change)
-- [ ] Remove `gitHubChecks` from `EngineContext`
+- [ ] Remove `gitHubChecks` from `EngineContext` (legacy DI still present for backward compatibility)
 - [ ] Make `eventBus` required parameter
 - [ ] Update all state handlers to emit events
 - [ ] Update all tests to new pattern

package/dist/docs/event-triggers.md

@@ -22,10 +22,11 @@ Visor can be triggered in two main modes:
 When running as a GitHub Action, Visor responds to these events:
 
 ### Pull Request Events (`pull_request`)
-- **Actions**: `opened`, `synchronize`, `edited`
+- **Actions**: `opened`, `synchronize`, `edited`, `closed`
 - **Trigger mapping**:
   - `opened` → `pr_opened`
   - `synchronize` / `edited` → `pr_updated`
+  - `closed` → `pr_closed`
 - **Log format**:
   ```
   🤖 Mode: GitHub Action
@@ -35,6 +36,18 @@ When running as a GitHub Action, Visor responds to these events:
   🔀 Context: Pull Request #123
   ```
 
+### Pull Request Review Events (`pull_request_review`)
+- **Actions**: `submitted`, `edited`, `dismissed`
+- **Trigger mapping**: `pr_updated`
+- **Log format**:
+  ```
+  🤖 Mode: GitHub Action
+  📂 Repository: owner/repo
+  📋 Event: pull_request_review (action: submitted)
+  🎯 Trigger: pr_updated
+  🔀 Context: Pull Request #123
+  ```
+
 ### Issue Events (`issues`)
 - **Actions**: `opened`, `edited`, etc.
 - **Trigger mapping**: `issue_opened`
@@ -51,6 +64,7 @@ When running as a GitHub Action, Visor responds to these events:
 - **Actions**: `created`, `edited`
 - **Trigger mapping**: `issue_comment`
 - **Context**: Can be on either a Pull Request or an Issue
+- **Note**: The EventMapper class may treat PR comments as `pr_updated` for advanced routing, but the GitHub Action entry point maps all issue comments to `issue_comment`.
 - **Log format** (on PR):
   ```
   🤖 Mode: GitHub Action
@@ -68,6 +82,28 @@ When running as a GitHub Action, Visor responds to these events:
   💬 Context: Comment on Issue #456
   ```
 
+### Schedule Events (`schedule`)
+- **Trigger mapping**: `schedule`
+- **Use case**: Cron-triggered workflows
+- **Log format**:
+  ```
+  🤖 Mode: GitHub Action
+  📂 Repository: owner/repo
+  📋 Event: schedule
+  🎯 Trigger: schedule
+  ```
+
+### Workflow Dispatch Events (`workflow_dispatch`)
+- **Trigger mapping**: `schedule` (treated as scheduled execution)
+- **Use case**: Manual workflow triggers
+- **Log format**:
+  ```
+  🤖 Mode: GitHub Action
+  📂 Repository: owner/repo
+  📋 Event: workflow_dispatch
+  🎯 Trigger: schedule
+  ```
+
 ## Example Logs
 
 ### Before (old logging):
@@ -135,9 +171,24 @@ This is **normal and correct** - it means:
    ✓ Skipping bot's own comment to prevent recursion. Author: probelabs[bot], Type: Bot, Has markers: true
    ```
 
+## Available Event Triggers
+
+The complete list of event triggers that can be used in the `on` field:
+
+| Trigger | Description |
+|---------|-------------|
+| `pr_opened` | Pull request was opened |
+| `pr_updated` | Pull request was updated (synchronize, edited, or review submitted) |
+| `pr_closed` | Pull request was closed (merged or dismissed) |
+| `issue_opened` | Issue was opened |
+| `issue_comment` | Comment on an issue (not a PR) |
+| `manual` | Manual CLI invocation |
+| `schedule` | Scheduled execution (cron or workflow_dispatch) |
+| `webhook_received` | HTTP webhook was received (via http_input provider) |
+
 ## Configuration
 
-Checks are configured to run on specific triggers using the `on` field:
+Steps are configured to run on specific triggers using the `on` field:
 
 ```yaml
 steps:
@@ -150,13 +201,24 @@ steps:
     on: [issue_comment, issue_opened]  # Runs on issue events
     type: ai
     # ... rest of config
+
+  scheduled-report:
+    on: [schedule]  # Only runs on scheduled triggers
+    type: ai
+    schedule: "0 9 * * 1"  # Every Monday at 9am
+    # ... rest of config
+
+  webhook-handler:
+    on: [webhook_received]  # Only runs when webhook is received
+    type: http_input
+    # ... rest of config
 ```
 
-If `on` is not specified, the check can run on any event type.
+If `on` is not specified, the check can run on any event type (except `manual`-only checks when using `--event all`).
 
 ### Using goto_event to simulate a different trigger for a jump
 
-Sometimes you want to “re-run” an ancestor step as if a different event happened (e.g., from an `issue_comment` flow you want to re-execute a PR step under `pr_updated`). Use `goto_event` together with `goto`:
+Sometimes you want to "re-run" an ancestor step as if a different event happened (e.g., from an `issue_comment` flow you want to re-execute a PR step under `pr_updated`). Use `goto_event` together with `goto` in `on_success` or `on_fail` blocks:
 
 ```yaml
 steps:
@@ -173,7 +235,14 @@ steps:
       goto_event: pr_updated  # simulate PR update for the inline jump
 ```
 
-During that inline execution, event filtering and `if:` expressions see the simulated event. The current step is then re-run once. For a full PR re-run from an issue comment, synthesize a PR event and re-invoke the action entrypoint (see failure-routing docs for details).
+During that inline execution, event filtering and `if:` expressions see the simulated event. The current step is then re-run once.
+
+The `goto_event` field accepts any valid `EventTrigger` value:
+- `pr_opened`, `pr_updated`, `pr_closed`
+- `issue_opened`, `issue_comment`
+- `manual`, `schedule`, `webhook_received`
+
+For complete documentation on failure routing, retry policies, and loop control, see [Failure Routing](./failure-routing.md).
 
 ## CLI Event Simulation
 
@@ -188,12 +257,21 @@ visor --event pr_updated
 # Simulate a PR opened event
 visor --event pr_opened
 
+# Simulate a PR closed event
+visor --event pr_closed
+
 # Simulate an issue comment event
 visor --event issue_comment
 
 # Simulate an issue opened event
 visor --event issue_opened
 
+# Simulate a manual trigger (runs checks with on: [manual])
+visor --event manual
+
+# Simulate a scheduled trigger
+visor --event schedule
+
 # Run all checks regardless of event filters (default)
 visor --event all
 ```
@@ -215,10 +293,13 @@ visor --check security --event pr_updated
 
 | Flag | Behavior | Use Case |
 |------|----------|----------|
-| `--event pr_updated` | Only runs checks with `on: [pr_updated]` | Test PR update scenario locally |
 | `--event pr_opened` | Only runs checks with `on: [pr_opened]` | Test PR opened scenario |
+| `--event pr_updated` | Only runs checks with `on: [pr_updated]` | Test PR update scenario locally |
+| `--event pr_closed` | Only runs checks with `on: [pr_closed]` | Test PR close/merge scenario |
+| `--event issue_opened` | Only runs checks with `on: [issue_opened]` | Test issue opened scenario |
 | `--event issue_comment` | Only runs checks with `on: [issue_comment]` | Test comment assistant |
 | `--event manual` | Only runs checks with `on: [manual]` | Test manual-triggered checks |
+| `--event schedule` | Only runs checks with `on: [schedule]` | Test scheduled/cron checks |
 | `--event all` | Runs all checks (except manual-only) | Default behavior, ignores `on:` filters |
 | (no flag) | Auto-detects based on schema | Smart default |
 
@@ -290,3 +371,11 @@ visor --event issue_comment
 ```bash
 visor --event all  # or just: visor
 ```
+
+## Related Documentation
+
+- [Configuration](./configuration.md) - Full configuration reference including check types
+- [CI/CLI Mode](./ci-cli-mode.md) - Running Visor in CI environments
+- [Failure Routing](./failure-routing.md) - Auto-fix loops and `goto_event` usage
+- [Commands](./commands.md) - CLI commands and PR comment commands
+- [Tag Filtering](./tag-filtering.md) - Selective check execution with tags

package/dist/docs/execution-statistics-rfc.md

@@ -1,9 +1,22 @@
 # RFC: Enhanced Execution Logging & Statistics
 
-**Status:** Implemented
+**Status:** Implemented (with architectural changes)
 **Date:** 2025-10-04
 **Version:** 1.0
 
+> **Note (January 2026):** This RFC has been implemented, but the underlying architecture
+> has evolved significantly since the original design. The `CheckExecutionEngine` class
+> described below has been replaced by `StateMachineExecutionEngine` (see
+> `src/state-machine-execution-engine.ts`). Statistics tracking is now handled via:
+> - `src/types/execution.ts` - Type definitions for `CheckExecutionStats` and `ExecutionStatistics`
+> - `src/state-machine/dispatch/stats-manager.ts` - Runtime statistics collection
+> - `src/state-machine/execution/summary.ts` - Result aggregation
+>
+> The data structures remain largely compatible with the RFC specification, with some
+> additions like `skippedRuns`, `providerDurationMs`, and additional skip reasons
+> (`forEach_empty`, `assume`). The formatting methods (`formatStatusColumn`,
+> `formatDetailsColumn`) remain in the engine class for test compatibility.
+
 ## Summary
 
 This RFC describes the implementation of comprehensive execution statistics tracking and enhanced logging for Visor checks, providing users with clear visibility into forEach iterations, skip reasons, and overall execution metrics.
@@ -285,6 +298,5 @@ Potential future improvements:
 
 ## References
 
-- Implementation PR: [Link to PR]
-- Related Issues: Enhanced logging visibility (#XX)
-- Documentation: Updated in CLAUDE.md and README.md
+- Implementation: See `src/state-machine-execution-engine.ts`, `src/types/execution.ts`, and `src/state-machine/dispatch/stats-manager.ts`
+- Tests: `tests/unit/execution-statistics.test.ts`, `tests/unit/execution-statistics-formatting.test.ts`, `tests/integration/execution-statistics-integration.test.ts`

package/dist/docs/fact-validator-gap-analysis.md

@@ -1,7 +1,18 @@
 # on_finish Hook - Implementation Status
 
+> **Note (2026-01-28)**: This is a **historical planning document** from October 2025.
+> The `on_finish` feature has been implemented but the codebase has since been refactored.
+> Some file paths and line numbers in this document are outdated.
+>
+> **Current implementation locations:**
+> - Core logic: `src/engine/on-finish/orchestrator.ts`, `src/engine/on-finish/utils.ts`
+> - State machine integration: `src/state-machine/states/level-dispatch.ts`, `src/state-machine/dispatch/foreach-processor.ts`
+> - Tests: `tests/engine/foreach-on-finish.engine.test.ts`, `tests/e2e/on-finish-*.test.ts`
+>
+> For current usage documentation, see `docs/failure-routing.md` and `docs/foreach-dependency-propagation.md`.
+
 **Last Updated:** 2025-10-16
-**Status:** ✅ FEATURE COMPLETE (Infrastructure Ready)
+**Status:** ✅ FEATURE COMPLETE (Infrastructure Ready) - See note above for current locations
 
 ## What Was Built
 

package/dist/docs/fact-validator-implementation-plan.md

@@ -1,23 +1,31 @@
 # Fact Validator Implementation Plan
 
-## 🎯 CURRENT STATUS: 50% COMPLETE
+> **Note (2026-01-28)**: This is a historical planning document. The core `on_finish` hook
+> infrastructure has been implemented and refactored since this plan was written.
+> Implementation has moved from `src/check-execution-engine.ts` to a dedicated module at
+> `src/engine/on-finish/orchestrator.ts` and `src/engine/on-finish/utils.ts`. Method names
+> like `executeCheckInline()` and `handleOnFinishHooks()` mentioned below no longer exist.
+> The test file references may also be outdated. See the actual source files for current
+> implementation details.
 
-**Last Updated:** 2025-10-16
+## 🎯 CURRENT STATUS: 50% COMPLETE (Phases 1-4 done, Phases 5-6 pending)
+
+**Last Updated:** 2025-10-16 (see note above for 2026 status)
 
 ### Implementation Status
 
 | Component | Status | Files |
 |-----------|--------|-------|
-| **Phase 1: Infrastructure** | ✅ COMPLETE | `src/types/config.ts`, `src/config.ts`, `src/check-execution-engine.ts` |
-| **Phase 2: Execution** | ✅ COMPLETE | `src/check-execution-engine.ts` (lines 283-748) |
+| **Phase 1: Infrastructure** | ✅ COMPLETE | `src/types/config.ts`, `src/config.ts` |
+| **Phase 2: Execution** | ✅ COMPLETE | `src/engine/on-finish/orchestrator.ts`, `src/engine/on-finish/utils.ts` |
 | **Phase 3: Configuration** | ✅ COMPLETE | `examples/fact-validator.yaml` |
-| **Phase 4: Documentation** | ⏳ PENDING | - |
-| **Phase 5: Testing** | ⏳ PENDING | - |
+| **Phase 4: Documentation** | ✅ COMPLETE | `docs/failure-routing.md`, `docs/dependencies.md`, `docs/foreach-dependency-propagation.md` |
+| **Phase 5: Testing** | 🚧 PARTIAL | `tests/engine/foreach-on-finish.engine.test.ts`, `tests/unit/on-finish-validation.test.ts` |
 | **Phase 6: Deployment** | ⏳ PENDING | - |
 
 ### Test Results
 
-✅ **1438 tests passing, 0 failures**
+✅ **16 on_finish-specific tests passing** (as of 2026-01-28)
 
 ### What's Working
 
@@ -613,10 +621,10 @@ if (check.on_finish && !check.forEach) {
 
 ### Documentation Updates
 
-1. **`docs/failure-routing.md`**: Add `on_finish` section
-2. **`docs/dependencies.md`**: Explain `on_finish` with forEach
-3. **`examples/foreach-on-finish.yaml`**: Complete working example
-4. **`docs/foreach-dependency-propagation.md`**: Update with `on_finish`
+1. **`docs/failure-routing.md`**: Add `on_finish` section ✅
+2. **`docs/dependencies.md`**: Explain `on_finish` with forEach ✅
+3. **`examples/fact-validator.yaml`**: Complete working example ✅
+4. **`docs/foreach-dependency-propagation.md`**: Update with `on_finish` ✅
 
 ## Testing Strategy