@probelabs/visor 0.1.124 → 0.1.126

package/dist/docs/recipes.md

@@ -179,16 +179,15 @@ Quick reference:
 - `role_map: 'step=role,other=role'` as a compact override
 
 See also:
-- `docs/human-input-provider.md`
-- `docs/liquid-templates.md` (Chat History Helper)
-- `docs/output-history.md`
-- `examples/slack-simple-chat.yaml`
+- [human-input-provider.md](./human-input-provider.md)
+- [liquid-templates.md](./liquid-templates.md) (Chat History Helper)
+- [output-history.md](./output-history.md)
+- [examples/slack-simple-chat.yaml](../examples/slack-simple-chat.yaml)
 
 ### Advanced routing & contracts (general patterns)
 
 #### Inner loops vs. closing the loop
 
-- **Close the loop**: Leaf steps use `on_success: goto: <entry-step>` to end the workflow and return to a single top-level `human-input`. Each new event (Slack message, webhook, CLI run) starts a fresh execution.
 - **Close the loop**: Leaf steps use `on_success: goto: <entry-step>` to end the workflow and return to a single top-level `human-input`. Each new event (Slack message, webhook, CLI run) starts a fresh execution.
 - **Inner loop**: Add a local `human-input` and route inside a sub‑flow:
   - Example shape: `router → section-confirm → section-answer → section-confirm`.
@@ -208,7 +207,7 @@ See also:
         to: project-intent
   ```
 - Reserve `goto_js` / `run_js` for legacy or very dynamic use cases.
-- More details: `docs/guides/fault-management-and-contracts.md`, `docs/loop-routing-refactor.md`.
+- More details: [fault-management-and-contracts.md](./guides/fault-management-and-contracts.md), [loop-routing-refactor.md](./loop-routing-refactor.md).
 
 - Pattern A — central router + transitions (explicit routing):
   - Use a single “router” step that sets control fields (e.g. `output.intent`, `output.kind`).
@@ -281,7 +280,7 @@ See also:
 - Use `assume` for preconditions about upstream state (memory, env, `outputs[...]`).
 - Use `guarantee` for postconditions about this step’s own output (shape, control flags, size caps).
 - For `info` steps, contracts are recommended but optional; keep `assume` + `guarantee` adjacent when present.
-- More details: `docs/guides/criticality-modes.md`, `docs/guides/fault-management-and-contracts.md`.
+- More details: [criticality-modes.md](./guides/criticality-modes.md), [fault-management-and-contracts.md](./guides/fault-management-and-contracts.md).
 
 #### JSON Schemas instead of `schema: plain`
 
@@ -469,6 +468,6 @@ The real error messages and responses help identify whether the issue is with yo
 
 ### More examples
 
-- `docs/NPM_USAGE.md` – CLI usage and flags
-- `GITHUB_CHECKS.md` – Checks, outputs, and workflow integration
+- [docs/NPM_USAGE.md](./NPM_USAGE.md) – CLI usage and flags
+- [docs/GITHUB_CHECKS.md](./GITHUB_CHECKS.md) – Checks, outputs, and workflow integration
 - `examples/` – MCP, Jira, and advanced configs

package/dist/docs/rfc/git-checkout-step.md

@@ -1,7 +1,9 @@
 # RFC: Git Checkout Step Provider
 
 ## Status
-**Accepted** - Implementation in progress
+**Implemented** - Feature is complete and available for use
+
+See [Git Checkout Provider Documentation](/docs/providers/git-checkout.md) for usage instructions.
 
 ### Decision Record
 - **Date**: 2025-11-21

package/dist/docs/rfc/on_init-hook.md

@@ -1,9 +1,20 @@
 # RFC: `on_init` Lifecycle Hook for Context Preprocessing
 
-**Status:** Proposal
+**Status:** Implemented
 **Author:** Visor Team
 **Created:** 2024-01-XX
-**Updated:** 2024-01-XX
+**Updated:** 2025-01-28
+
+---
+
+## Implementation Notes
+
+This RFC has been implemented. Key implementation files:
+- Type definitions: `src/types/config.ts` (OnInitConfig, OnInitToolInvocation, etc.)
+- Handler implementation: `src/state-machine/dispatch/on-init-handlers.ts`
+- Integration with execution: `src/state-machine/dispatch/execution-invoker.ts`
+- Tests: `tests/integration/on-init-flow.test.ts`
+- Example: `examples/on-init-import-demo.yaml`
 
 ---
 
@@ -1204,11 +1215,13 @@ on_init:
 
 ## 13. References
 
-- [Existing `on_success` implementation](src/state-machine/states/routing.ts#599)
-- [Existing `on_fail` implementation](src/state-machine/states/routing.ts#816)
-- [Existing `on_finish` implementation](src/state-machine/states/routing.ts#231)
+- [Existing `on_success` implementation](src/state-machine/states/routing.ts) (search for `Process on_success routing`)
+- [Existing `on_fail` implementation](src/state-machine/states/routing.ts) (search for `Process on_fail routing`)
+- [Existing `on_finish` implementation](src/state-machine/states/routing.ts) (search for `Process on_finish routing`)
 - [Workflow provider](src/providers/workflow-check-provider.ts)
 - [Custom tool executor](src/providers/custom-tool-executor.ts)
+- [on_init handler implementation](src/state-machine/dispatch/on-init-handlers.ts)
+- [on_init type definitions](src/types/config.ts) (search for `OnInitConfig`)
 
 ---
 

package/dist/docs/rfc/workspace-isolation.md

@@ -1,5 +1,21 @@
 # Isolated Workspace with Full Run Separation
 
+## Status
+**Implemented** - Feature is complete and available for use
+
+### Decision Record
+- **Date**: 2025 (exact date not recorded)
+- **Decision**: Implement isolated workspaces using git worktrees in `/tmp`
+- **Rationale**: Provides full isolation between parallel visor runs, avoids git-in-git issues, and enables human-readable project paths within the workspace
+
+### Implementation Files
+- `src/utils/workspace-manager.ts` - Core WorkspaceManager class
+- `src/state-machine/context/build-engine-context.ts` - Workspace initialization via `initializeWorkspace()`
+- `src/providers/git-checkout-provider.ts` - Integration to add projects to workspace
+- `src/types/engine.ts` - Added `workspace` and `originalWorkingDirectory` to EngineContext
+- `src/types/git-checkout.ts` - Added `workspace_path` to GitCheckoutOutput
+- `tests/unit/workspace-manager.test.ts` - Unit tests
+
 ## Goal
 
 Provide **full isolation between parallel visor runs** with human-readable project names. Each run gets its own workspace in `/tmp` containing worktrees for all projects, ensuring no interference between concurrent executions.

package/dist/docs/roadmap/criticality-implementation-tasks.md

@@ -1,33 +1,33 @@
 # Criticality & Contracts — Implementation Tasks (Do‑It‑Right)
 
-This file lists the remaining engineering tasks to fully implement the criticality model, contracts, and transitions as documented. Items are grouped and check‑listable. “(optional)” items can be phased in later.
+This file lists the remaining engineering tasks to fully implement the criticality model, contracts, and transitions as documented. Items are grouped and check‑listable. "(optional)" items can be phased in later.
 
 ## 1) Schema & Types
-- [ ] Add `criticality` field to `CheckConfig` (`external | internal | policy | info`).
+- [x] Add `criticality` field to `CheckConfig` (`external | internal | policy | info`).
 - [ ] (optional) Add `assume_mode: 'skip' | 'fail'` to control unmet preconditions handling.
 - [ ] (optional) Add `retry_on: ['transient'] | ['transient','logical']` to narrow retry classes.
-- [ ] Update JSON schema generator and `src/generated/config-schema.ts`.
-- [ ] Update TypeScript types (`src/types/config.ts`, SDK exports).
+- [x] Update JSON schema generator and `src/generated/config-schema.ts`.
+- [x] Update TypeScript types (`src/types/config.ts`, SDK exports).
 
 ## 2) Config Validation & Linting
-- [ ] Validator: warn when `criticality` omitted on mutating providers (external inference) or forEach parents (control‑plane inference).
-- [ ] Validator: warn when critical steps lack `assume`/`guarantee`.
-- [ ] Validator: warn when `assume` references this step’s own `output`.
+- [x] Validator: warn when `criticality` omitted on mutating providers (external inference) or forEach parents (control‑plane inference).
+- [x] Validator: warn when critical steps lack `assume`/`guarantee`.
+- [ ] Validator: warn when `assume` references this step's own `output`.
 - [ ] Validator: warn when `guarantee` contains policy thresholds better modeled as `fail_if`.
 - [ ] Validator: ensure `transitions[].to` targets exist (or null) and expressions compile.
 
 ## 3) Engine Policy Mapping
-- [ ] Derive defaults from `criticality` at load time (but allow per‑check overrides):
+- [x] Derive defaults from `criticality` at load time (but allow per‑check overrides):
       - external/control‑plane/policy: `continue_on_failure=false`, retries transient‑only (max 2–3), loop budgets tighter (e.g., 8), contracts required.
       - non‑critical: contracts optional, `continue_on_failure` may be true, default loop budget 10, retries standard.
-- [ ] Enforce “no auto‑retry for logical failures” in critical modes (fail_if/guarantee violations).
+- [x] Enforce "no auto‑retry for logical failures" in critical modes (fail_if/guarantee violations).
 - [ ] (optional) Per‑criticality loop budget override (e.g., control‑plane default 8).
 
 ## 4) Runtime Semantics (clarity & safety)
-- [ ] Ensure `assume` is evaluated pre‑exec (no access to this step’s `output`), with clear error messaging.
-- [ ] Ensure `guarantee` is evaluated post‑exec, with issues emitted as `contract/guarantee_failed`.
-- [ ] Keep expressions sandboxed, pure, and short‑timed; log evaluation errors as fail‑secure decisions.
-- [ ] Transitions precedence over `goto_js` when both present; loop budget enforcement per scope.
+- [x] Ensure `assume` is evaluated pre‑exec (no access to this step's `output`), with clear error messaging.
+- [x] Ensure `guarantee` is evaluated post‑exec, with issues emitted as `contract/guarantee_failed`.
+- [x] Keep expressions sandboxed, pure, and short‑timed; log evaluation errors as fail‑secure decisions.
+- [x] Transitions precedence over `goto_js` when both present; loop budget enforcement per scope.
 - [ ] (optional) forEach per‑item concurrency with default 1; cap via config.
 
 ## 5) Side‑Effect Classification
@@ -45,33 +45,33 @@ This file lists the remaining engineering tasks to fully implement the criticali
 - [ ] Journal: ensure all contract/transition decisions and expressions are captured with scope/timestamps.
 
 ## 8) Persistence
-- [ ] Keep JSON snapshot export (done) and add (optional) debug‑resume path gated by a debug flag.
+- [x] Keep JSON snapshot export (done) and add (optional) debug‑resume path gated by a debug flag.
 
 ## 9) Defaults & Examples
-- [ ] Update `defaults/visor.yaml` (and any bundled defaults) to declare `criticality` for relevant checks and prefer `transitions` over `goto_js` where applicable.
-- [ ] Update `defaults/task-refinement.yaml` and `defaults/agent-builder.yaml` to use `criticality` and transitions where appropriate; ensure no `assume` refers to own output.
+- [x] Update `defaults/visor.yaml` (and any bundled defaults) to declare `criticality` for relevant checks and prefer `transitions` over `goto_js` where applicable.
+- [x] Update `defaults/task-refinement.yaml` and `defaults/workflow-builder.yaml` to use `criticality` and transitions where appropriate; ensure no `assume` refers to own output.
 - [ ] Convert inline YAML arrays in defaults to block‑style lists for consistency.
 - [ ] Add an annotated example block with all primitives (if, assume, guarantee, fail_if, transitions) and modes (reference the guides) in the defaults or examples folder.
 - [ ] Verify defaults run green via dist CLI:
       - `npm run build:cli`
       - `node dist/index.js test defaults/visor.tests.yaml --progress compact`
-      - Any other default suites (`task-refinement`, `agent-builder`) if present.
+      - Any other default suites (`task-refinement`, `workflow-builder`) if present.
 
 ## 10) Tests
-- [ ] Unit (engine/native):
+- [x] Unit (engine/native):
       - `assume` skip vs guard‑step hard‑fail (no provider call on skip).
       - `guarantee` violation adds `contract/guarantee_failed` and does not double‑execute provider.
       - Transitions precedence over `goto_js`; undefined transition falls back to `goto`.
       - Loop budget enforcement per scope (error surfaced; routing halts in that scope).
       - Criticality policy mapping (external/control‑plane/policy/non‑critical) sets defaults (gating, retries, budgets).
-- [ ] Integration:
+- [x] Integration:
       - Critical external step blocks downstream mutating side‑effects on contract/fail_if failure (dependents gated).
       - Control‑plane forEach parent respects tighter loop budget; no oscillation beyond cap.
       - Retry classifier: transient provider errors retried; logical (fail_if/guarantee) not auto‑retried in critical modes.
       - Non‑critical step with `continue_on_failure: true` does not block pipeline.
 - [ ] YAML e2e / Defaults:
       - `defaults/visor.yaml` flow passes using transitions.
-      - `defaults/task-refinement.yaml` and `defaults/agent-builder.yaml` pass with `criticality` declared.
+      - `defaults/task-refinement.yaml` and `defaults/workflow-builder.yaml` pass with `criticality` declared.
       - Add a strict safety profile scenario (e.g., `safety: strict`) and ensure it passes.
 - [ ] CI Gates:
       - Add a job to build CLI and run default YAML suites with `--progress compact`.
@@ -79,14 +79,14 @@ This file lists the remaining engineering tasks to fully implement the criticali
 
 ## 11) Docs (remaining polish)
 - [ ] README or landing page: link to Criticality Modes and Fault Management guides.
-- [ ] Ensure quick‑starts show `criticality` in at least one example (SDK & CLI done).
+- [x] Ensure quick‑starts show `criticality` in at least one example (SDK & CLI done).
 - [ ] Sweep older docs for inline arrays (`[a, b]`) and convert to block lists.
-- [ ] Add “assume vs guarantee — do’s and don’ts” callout in any doc that introduces contracts (done for two guides).
+- [x] Add "assume vs guarantee — do's and don'ts" callout in any doc that introduces contracts (done for two guides).
 
 ## Acceptance Criteria
-- [ ] All tests pass (unit/integration/YAML) with representative critical/non‑critical mixes.
-- [ ] Config validator warns on unsafe/missing contracts and mis‑declared criticality.
-- [ ] Engine enforces defaults per `criticality` while allowing explicit overrides.
-- [ ] Logs have timestamps; debug gated; decisions visible in journal and metrics.
+- [x] All tests pass (unit/integration/YAML) with representative critical/non‑critical mixes.
+- [x] Config validator warns on unsafe/missing contracts and mis‑declared criticality.
+- [x] Engine enforces defaults per `criticality` while allowing explicit overrides.
+- [x] Logs have timestamps; debug gated; decisions visible in journal and metrics.
 - [ ] No dist/ artifacts in commits.
-- [ ] Updated defaults (`defaults/visor.yaml`, `defaults/task-refinement.yaml`, `defaults/agent-builder.yaml`) run green via dist CLI in CI.
+- [ ] Updated defaults (`defaults/visor.yaml`, `defaults/task-refinement.yaml`, `defaults/workflow-builder.yaml`) run green via dist CLI in CI.

package/dist/docs/router-patterns.md

@@ -71,19 +71,25 @@ Here, the router (`route-intent`) is connected to the branch (`capabilities-answ
 - as a data dependency: `capabilities-answer.depends_on: [route-intent]`
 - as a control‑flow source: `route-intent.on_success.transitions → capabilities-answer`
 
-### Why this is a problem
+### Why this can be a problem
 
 When `route-intent` finishes, `transitions` fire and emit a `ForwardRunRequested(target='capabilities-answer')`.
 
 WavePlanning then:
 
 1. Builds the forward‑run subset starting from the target.
-2. Adds **all transitive dependencies** of that target via `depends_on`.
+2. Adds transitive dependencies of that target via `depends_on`.
    - `capabilities-answer.depends_on: [route-intent]`
    - `route-intent.depends_on: [ask]`
-3. Schedules a wave that re‑runs `route-intent` (and `ask`), then `capabilities-answer`.
+3. **However**, the engine now skips re‑running dependencies that have already succeeded in the current run.
 
-Each time `route-intent` re‑runs, its `transitions` fire again, enqueueing another forward‑run to `capabilities-answer`, which again pulls `route-intent` in as a dependency. This repeats until `routing.max_loops` is hit.
+**Note**: The engine's forward‑run planner was updated to deduplicate successful runs. Dependencies that have `successfulRuns > 0` are not re‑scheduled. This means the "double‑edge" pattern no longer causes runaway loops in most cases.
+
+**When it still matters**:
+
+- **Explicit loops via `goto`**: When a leaf step uses `goto: ask`, that *is* an intentional re‑run. The router will execute again on each loop iteration, which is expected behavior controlled by `routing.max_loops`.
+- **Failed dependencies**: If a dependency failed (not succeeded), it will be re‑run. This can cause unexpected behavior if the failure was intentional.
+- **Clarity**: Even though the engine handles deduplication, having both `depends_on` and `transitions` edges to the same step creates conceptual ambiguity about intent.
 
 **Symptoms:**
 
@@ -101,9 +107,9 @@ This is exactly the pattern we saw in the Slack org‑assistant flow when:
 
 ---
 
-## Recommended pattern: router as pure control‑plane
+## Recommended patterns
 
-### Core idea
+### Pattern A: Router as pure control‑plane (no branch dependencies)
 
 Treat router checks as **control‑plane only**:
 
@@ -112,9 +118,29 @@ Treat router checks as **control‑plane only**:
   - Uses `on_success.transitions` to select branches.
 - Branches:
   - **Do not** `depends_on` the router.
-  - Instead, they **read** the router’s output from `outputs['router']` and gate with `if` / `assume`.
+  - Instead, they **read** the router's output from `outputs['router']` and gate with `if` / `assume`.
+
+This pattern avoids any ambiguity about the relationship between router and branches.
+
+### Pattern B: Router with branch dependencies (common pattern)
+
+In practice, many workflows use `depends_on` on branches to ensure ordering and data access:
+
+- Router:
+  - `depends_on` its true *inputs* (e.g. `ask`, context fetch steps).
+  - Uses `on_success.transitions` to select branches.
+- Branches:
+  - **Do** `depends_on: [router]` for explicit ordering.
+  - Also use `if` guards to skip when not selected.
 
-This gives a clean, acyclic structure:
+This pattern is safe because the engine's forward‑run planner skips re‑running dependencies that already succeeded. See `examples/slack-simple-chat.yaml` for a working implementation.
+
+### Choosing between patterns
+
+- **Pattern A** is cleaner when branches don't actually need router output (pure control‑flow).
+- **Pattern B** is more explicit and is the common pattern in real workflows where branches need access to router fields like `output.intent` or `output.project`.
+
+#### Example: Pattern A (no branch dependencies)
 
 ```yaml
 ask:
@@ -125,9 +151,6 @@ route-intent:
   type: ai
   group: chat
   depends_on: [ask]
-  ai:
-    disableTools: true
-    allowedTools: []
   schema:
     type: object
     properties:
@@ -147,9 +170,6 @@ capabilities-answer:
   group: chat
   # no depends_on: [route-intent]
   if: "outputs['route-intent']?.intent === 'capabilities'"
-  ai:
-    disableTools: true
-    allowedTools: []
   prompt: |
     Explain briefly what you can help with.
   on_success:
@@ -167,19 +187,67 @@ chat-answer:
     goto: ask
 ```
 
-**Engine behavior:**
+#### Example: Pattern B (with branch dependencies)
+
+This is the pattern used in `examples/slack-simple-chat.yaml`:
+
+```yaml
+ask:
+  type: human-input
+  group: chat
+
+route-intent:
+  type: ai
+  group: chat
+  depends_on: [ask]
+  schema:
+    type: object
+    properties:
+      intent:
+        type: string
+        enum: [chat, capabilities]
+    required: [intent]
+  on_success:
+    transitions:
+      - when: "output.intent === 'capabilities'"
+        to: capabilities-answer
+      - when: "output.intent === 'chat'"
+        to: chat-answer
+
+capabilities-answer:
+  type: ai
+  group: chat
+  depends_on: [route-intent]  # explicit dependency
+  if: "outputs['route-intent']?.intent === 'capabilities'"
+  prompt: |
+    Explain briefly what you can help with.
+  on_success:
+    goto: ask
+
+chat-answer:
+  type: ai
+  group: chat
+  depends_on: [route-intent]  # explicit dependency
+  if: "outputs['route-intent']?.intent === 'chat'"
+  prompt: |
+    You are a concise, friendly assistant.
+    Latest user message: {{ outputs['ask'].text }}
+  on_success:
+    goto: ask
+```
+
+**Engine behavior (both patterns):**
 
 - Initial wave:
   - DAG: `ask` → `route-intent`
   - Router runs once, then emits transitions.
 - Forward‑run for `capabilities-answer`:
-  - Only includes the branch and any *real* dependencies the branch declares (e.g. context fetch, project status).
-  - Does **not** pull `route-intent` back in, because the branch no longer `depends_on` it.
+  - In Pattern A: Only the branch runs (no dependencies to pull in).
+  - In Pattern B: The branch depends on `route-intent`, but since it already succeeded, it is **not** re‑run.
 - Loops:
   - `capabilities-answer` closing to `ask` via `goto: ask` is explicit and controlled.
-  - Router still runs once per loop cycle (when `ask` completes), but is not re‑run just because the branch was targeted by a transition.
-
-This pattern avoids the “router as both dependency and transition source” cycle that caused loops in Slack.
+  - Router runs once per loop cycle (when `ask` completes and flows to `route-intent`).
+  - Loop count is controlled by `routing.max_loops`.
 
 ---
 
@@ -207,7 +275,9 @@ project-status-answer:
 
 ### Use `transitions` / `goto` for control‑flow
 
-Examples:
+There are three routing hooks: `on_success`, `on_fail`, and `on_finish`.
+
+**`on_success`** — Fires when the check completes without fatal issues:
 
 ```yaml
 route-intent:
@@ -229,8 +299,33 @@ project-deploy-answer:
         to: project-deploy-confirm
 ```
 
-- Router edges are expressed only via `transitions`.
-- Inner “deployment helper” loop is controlled by transitions on `done`.
+**`on_fail`** — Fires when the check fails (fatal issues or `fail_if` triggered):
+
+```yaml
+validate-input:
+  type: ai
+  fail_if: "output.valid === false"
+  on_fail:
+    goto: ask  # Loop back for retry
+    # or use transitions:
+    # transitions:
+    #   - when: "output.error === 'auth'"
+    #     to: auth-handler
+```
+
+**`on_finish`** — Fires regardless of success/failure:
+
+```yaml
+cleanup-step:
+  type: command
+  on_finish:
+    run: log-completion  # Always run logging
+```
+
+**`goto` vs `run`**:
+
+- `goto`: Preempts remaining work and jumps to the target. Used for loops and error recovery.
+- `run`: Schedules the target after current wave completes. Used for side-effects like logging.
 
 ### Use `if` and `assume` for semantics, not wiring
 
@@ -255,42 +350,44 @@ Guidelines:
 
 ---
 
-## Migration: from router‑as‑dependency to router‑as‑control‑plane
+## Migration and testing best practices
 
-If you have existing workflows where:
+### When to migrate
 
-- router checks use `on_success.transitions`, and
-- branches also `depends_on` the router, and
-- leaf steps loop back via `goto: <entry-step>`,
+If you have existing workflows with unexpected loop counts or router re‑runs, consider these options:
 
-then you’re in the “double‑edge” pattern and may hit the same kind of loops we saw in Slack.
+1. **Keep Pattern B** (branches depend on router) — This is safe with the current engine. Just ensure you have:
+   - `if` guards on branches
+   - `routing.max_loops` set appropriately
+   - Test assertions for expected call counts
 
-### Migration steps
+2. **Migrate to Pattern A** (branches don't depend on router) — This is cleaner if branches don't actually need router output.
 
-1. **Identify router checks**  
+### Migration steps (if needed)
+
+1. **Identify router checks**
    - Look for AI/script steps that:
      - read from a single human‑input or transport context, and
      - fan‑out into multiple branches via `transitions`.
 
-2. **Remove router from branch `depends_on`**  
+2. **Remove router from branch `depends_on`** (optional)
    - For each branch:
-     - Remove `depends_on: [router]`.
+     - Remove `depends_on: [router]` if you don't need explicit ordering.
      - Keep other dependencies (e.g. context fetch, sub‑routers).
 
-3. **Add `if` / `assume` guards on branches**
-   - Replace router‑dependency semantics with guards:
+3. **Ensure `if` guards on branches**
+   - All branches should have guards regardless of pattern:
 
    ```yaml
    chat-answer:
-     # was: depends_on: [route-intent]
      if: "outputs['route-intent']?.intent === 'chat'"
    ```
 
 4. **Keep explicit loops**
    - Leave `goto: ask` and inner loops (`project-deploy-confirm` ↔ `project-deploy-answer`) as they are.
-   - The loop behavior remains explicit and is no longer entangled with router dependencies.
+   - The loop behavior is explicit and controlled by `routing.max_loops`.
 
-5. **Increase `routing.max_loops` and add strict call expectations**
+5. **Add strict call expectations in tests**
    - In YAML tests, set a reasonable `routing.max_loops` (e.g. 5–10).
    - Assert `exactly` call counts for:
      - router(s),
@@ -328,12 +425,27 @@ Once most configs follow this pattern, engine‑level improvements (e.g. smarter
   - Use routers (`route-intent`, `project-intent`, …) as control‑plane steps:
     - `depends_on` only real inputs,
     - route with `transitions`.
-  - Keep branches free of router `depends_on`; gate them with `if` / `assume`.
-  - Use `depends_on` only for real data dependencies.
+  - Use `if` guards on branches to skip when not selected by the router.
+  - Use `depends_on` for real data dependencies (including router → branch when you need the router's output).
   - Use `goto`/`transitions` for loops and control‑flow.
+  - Set `routing.max_loops` and add strict call count expectations in tests.
+
+- **Acceptable**:
+  - Having `depends_on: [router]` on branches when you need explicit ordering or access to router output — the engine deduplicates successful runs.
 
 - **Avoid**:
-  - Wiring the same edge both via `depends_on` and `transitions`.
-  - Using `assume` as a routing mechanism.
+  - Relying on implicit re‑runs of routers (use explicit `goto` for loops).
+  - Using `assume` as a routing mechanism (use `if` or `transitions` instead).
+
+Following these patterns produces clearer configs, leverages the engine's forward‑run deduplication, and makes loop behavior explicit and testable.
+
+---
+
+## Related documentation
 
-Following this pattern produces clearer configs, avoids accidental router loops, and matches how the state‑machine’s forward‑run planner is intended to be used.***
+- [Recipes](./recipes.md) — General routing patterns and chat examples
+- [Fault Management and Contracts](./guides/fault-management-and-contracts.md) — `assume`, `guarantee`, and criticality
+- [Criticality Modes](./guides/criticality-modes.md) — When to use `internal`, `external`, `policy`, `info`
+- [Loop Routing Refactor](./loop-routing-refactor.md) — Technical details on forward-run deduplication
+- [Human Input Provider](./human-input-provider.md) — Chat loops and `human-input` type
+- [Debugging Guide](./debugging.md) — Tracing routing decisions with OpenTelemetry

package/dist/docs/schema-templates.md

@@ -1,6 +1,6 @@
-## 📋 Schema-Template System
+## Schema-Template System
 
-Visor pairs JSON Schemas (data shape) with Liquid templates (rendering) so outputs are predictable, auditable, and GitHub‑native.
+Visor pairs JSON Schemas (data shape) with Liquid templates (rendering) so outputs are predictable, auditable, and GitHub-native.
 
 ### Overview
 - Schema validates check output at runtime (via AJV)
@@ -20,16 +20,23 @@ steps:
   overview:
     type: ai
     group: summary
-    schema: text
+    schema: overview
     prompt: "Summarize PR in markdown"
 ```
 
 ### Built-in Schemas
-- code-review: structured findings with severity, file, line → native annotations
-- text: free‑form markdown content (no annotations)
+
+| Schema | Description | Output Structure |
+|--------|-------------|------------------|
+| `code-review` | Structured findings with severity, file, line | `{ issues: [...] }` with GitHub annotations |
+| `plain` | Free-form markdown/text content | `{ content: "..." }` |
+| `overview` | PR summary with optional metadata tags | `{ text: "...", tags: {...} }` |
+| `issue-assistant` | Issue triage with intent classification | `{ text: "...", intent: "...", labels: [...] }` |
 
 ### Grouping
 
+Checks with the same `group` value are consolidated into a single GitHub comment:
+
 ```yaml
 steps:
   security:   { group: code-review }
@@ -38,31 +45,60 @@ steps:
   assistant:  { group: dynamic } # always creates a new comment
 ```
 
+The special `dynamic` group creates a unique comment for each execution.
+
 ### Custom Schemas
 
-```yaml
-schemas:
-  custom-metrics:
-    file: ./schemas/metrics.json
+You can use custom schemas in three ways:
 
+**1. File path reference:**
+```yaml
 steps:
   metrics:
-    schema: custom-metrics
+    schema: ./schemas/metrics.json
     group: metrics
 ```
 
+**2. Inline JSON Schema object:**
+```yaml
+steps:
+  custom-check:
+    schema:
+      type: object
+      required: [result]
+      properties:
+        result:
+          type: string
+```
+
+**3. With custom template:**
+```yaml
+steps:
+  metrics:
+    schema: ./schemas/metrics.json
+    template:
+      file: ./templates/metrics.liquid
+    # Or inline template content:
+    # template:
+    #   content: "{{ output.result }}"
+```
+
 ### GitHub Checks API Compatibility
 
 For status checks and annotations, use structured output with `issues[]` having:
-- severity: critical | error | warning | info
-- file, line, message
+- `severity`: `warning` | `error` | `critical`
+- `file`: path relative to repository root
+- `line`: line number (required)
+- `message`: description of the issue
+
+Optional fields: `endLine`, `ruleId`, `category`, `suggestion`, `replacement`.
 
-Unstructured (none/plain) → posted as-is, no status checks.
+Unstructured schemas (`plain`) are posted as-is without status check annotations.
 
 ### Enhanced Prompts
-- Smart auto‑detection, Liquid templating, file‑based prompts
+- Smart auto-detection, Liquid templating, file-based prompts
 - Template context: `pr`, `files`, `event`, `outputs`, `utils`
 - See [Liquid Templates Guide](./liquid-templates.md) for available variables and filters
 
-See full examples in `defaults/.visor.yaml`.
+See full examples in `defaults/visor.yaml`.