@exaudeus/workrail 3.27.0 → 3.29.0

package/docs/plans/workflow-v2-roadmap.md

@@ -0,0 +1,74 @@
+# Workflow v2 Roadmap
+
+This is the **canonical planning/status doc** for WorkRail v2.
+
+Use it for:
+
+- the v2 mission and invariants
+- what is already shipped
+- what remains partial or open
+- realistic next work
+
+Do **not** use this doc for long-form design history or chat-resumption guidance. Those belong in the companion design doc and the code.
+
+## Mission
+
+Make WorkRail workflows **resumable, rewind-safe, deterministic, and durable** without depending on chat transcript state.
+
+## Core invariants
+
+### 1. Execution happens through opaque workflow tokens
+
+Agents should round-trip tokens, not construct engine internals.
+
+### 2. Durable truth is append-only
+
+Sessions and runs should be projections over append-only execution truth, not mutable JSON truth stores.
+
+### 3. Runs are pinned to compiled workflow content
+
+Execution should stay tied to a deterministic workflow snapshot rather than drift with later edits.
+
+### 4. Rewinds must stay safe
+
+If a user or client rewinds chat state, WorkRail should preserve execution integrity through branching/recovery rather than silent corruption.
+
+## Shipped or largely shipped
+
+- v2 MCP tool surface (`list_workflows`, `inspect_workflow`, `start_workflow`, `continue_workflow`, `checkpoint_workflow`, `resume_session`)
+- append-only execution substrate and projections
+- token-based execution boundary
+- checkpointing and session resumption
+- typed output validation and blocked retry UX
+- substantial hardening/modularization work
+
+## Still partial
+
+- lifecycle validation coverage breadth (see `docs/plans/workflow-validation-roadmap.md`)
+
+## Still open
+
+- progress notifications
+- stronger verification/evidence contract model
+- parallel `forEach` execution
+- subagent composition chains
+
+See `docs/plans/v2-followup-enhancements.md` for the detailed open follow-up initiative list.
+
+## Recommended next work
+
+### Near-term
+
+1. **Progress notifications**
+2. **Verification/evidence contract improvements**
+
+### After that
+
+1. **Parallel loop execution and richer delegated composition**
+
+## Canonical companions
+
+- `docs/plans/workflow-v2-design.md`
+- `docs/plans/v2-followup-enhancements.md`
+- `docs/roadmap/open-work-inventory.md`
+- `docs/tickets/next-up.md`

package/docs/plans/workflow-validation-design.md

@@ -0,0 +1,98 @@
+# Workflow Validation Design
+
+This is the **canonical durable design doc** for the workflow validation initiative.
+
+Use it for:
+
+- architectural rules that should remain true over time
+- the validation model and shared boundaries
+- important design constraints that explain *why* the system is shaped this way
+
+Do **not** use this doc as a code-shadow full of exact signatures or large copy-paste implementation recipes. Those drift too easily.
+
+## Core design rule
+
+Validation must track what runtime actually does, not a simplified approximation of it.
+
+If validation and runtime diverge, the validator becomes a false assurance layer.
+
+## Architectural principles
+
+### Shared resolution, not duplicate resolution
+
+Validation and runtime should rely on the same source/variant resolution logic rather than maintaining parallel implementations.
+
+This includes:
+
+- workflow discovery
+- candidate resolution
+- first-step/start construction
+- feature-flag-sensitive variant choice
+
+### One validation pipeline, many consumers
+
+CLI, MCP tools, registry validation, and any future runtime assertions should all rely on the same validation pipeline rather than each adding their own interpretation of “valid.”
+
+### Fail loudly instead of hiding invalid workflows
+
+If invalid workflows are filtered out or silently degraded, the system cannot make trustworthy claims about validity.
+
+### Validate the lifecycle, not just the file
+
+Static validation is necessary but insufficient. A stronger validation story includes execution-oriented checks and lifecycle coverage for important bundled workflows.
+
+## Validation tiers
+
+### Tier 1: File validation
+
+Purpose:
+
+- schema conformance
+- structural correctness
+
+This is the cheapest and most local layer, but it is not enough on its own.
+
+### Tier 2: Registry validation
+
+Purpose:
+
+- validate discoverable workflows as runtime resolves them
+- catch duplicate IDs, source conflicts, and variant-resolution mismatches
+
+This is the tier that closes the gap between individual file validity and actual runtime selection behavior.
+
+### Tier 3: Execution validation
+
+Purpose:
+
+- verify lifecycle integrity
+- catch failures that only appear when stepping through execution paths
+
+This tier is what turns validation from “static confidence” into stronger runtime equivalence.
+
+## Important design consequences
+
+### Validation is partly a runtime-design problem
+
+Some validation gaps cannot be solved only by adding new checks. They require runtime behavior to stop hiding invalid states or silently degrading.
+
+### Tests are part of the contract
+
+Lifecycle harnesses and regression coverage are not optional polish. They are part of the proof that the validation story matches execution reality.
+
+### Code is the implementation truth
+
+This doc should explain the durable model, but exact signatures, file counts, and phased code recipes belong in code/tests or short-lived implementation work, not in the permanent design doc.
+
+## Current design priorities
+
+1. preserve runtime/validation parity
+2. make failures visible rather than hidden
+3. expand lifecycle confidence pragmatically
+4. avoid sprawling operator/process docs that duplicate the plan
+
+## Companion docs
+
+- `docs/plans/workflow-validation-roadmap.md`
+- `docs/roadmap/open-work-inventory.md`
+- `docs/tickets/next-up.md`

package/docs/plans/workflow-validation-roadmap.md

@@ -0,0 +1,108 @@
+# Workflow Validation Roadmap
+
+This is the **canonical planning/status doc** for the workflow validation initiative.
+
+Use it for:
+
+- mission and invariants
+- what is shipped
+- what is still open
+- realistic next work
+
+Do **not** use this doc for line-by-line implementation scaffolding. That belongs either in the code, tests, or the companion design doc.
+
+## Mission
+
+Make workflow validation the authoritative, runtime-equivalent gate for all workflows.
+
+In practice, that means:
+
+- invalid workflows should be caught before user-visible execution
+- invalid workflows should not be silently hidden
+- validation and runtime should agree on what workflow is actually being executed
+
+## Durable invariants
+
+### 1. Runtime workflow-definition failures are validator failures
+
+If a workflow passes validation and later fails during execution because the workflow definition itself is invalid, the validator is incomplete.
+
+### 2. Validation and runtime must speak the same error language
+
+If runtime can discover workflow-definition errors that validation cannot represent, the validation model is incomplete.
+
+### 3. Validation and runtime must resolve the same workflow
+
+Registry validation and runtime must use the same resolution path for sources, variants, and start construction.
+
+### 4. There is one authoritative validation pipeline
+
+No consumer should decide “is this workflow valid?” by reimplementing validation outside the shared pipeline.
+
+## Validation model
+
+### Tier 1: File validation
+
+Checks whether an individual workflow file is structurally valid.
+
+### Tier 2: Registry validation
+
+Checks workflows as runtime actually discovers and resolves them across sources and variants.
+
+### Tier 3: Execution validation
+
+Checks that workflows can actually run through lifecycle paths without workflow-definition failures.
+
+## Current status
+
+### Shipped or largely shipped
+
+- unified validation pipeline groundwork
+- registry-centric validation groundwork
+- validation/runtime resolution-parity direction
+- fail-louder runtime direction for some previously hidden errors
+
+### Still partial
+
+- lifecycle-harness breadth and real coverage targets
+- normalization of stale validation status/operator docs
+- fully explicit closure on remaining runtime-vs-validation gaps
+
+### Still open
+
+- broader lifecycle coverage for bundled workflows
+- final cleanup of stale operator-oriented validation docs
+- any remaining closure work needed for a trustworthy “done” claim
+
+## Remaining work
+
+### Near-term
+
+1. **Expand lifecycle validation coverage**
+   - define a realistic target
+   - cover more bundled workflows
+   - stop implying closure that the current test surface does not support
+
+2. **Finish validation status cleanup**
+   - reduce stale operator docs and duplicated entrypoints
+   - make this roadmap the clear planning source of truth
+
+3. **Confirm remaining gaps explicitly**
+   - document whether any runtime-definition failure classes remain outside the validator
+
+### Later, if needed
+
+1. tighten any remaining runtime/validator parity gaps
+2. revisit whether additional execution-integrity tooling is needed
+
+## What success looks like
+
+- validation is the trusted gate for bundled workflows
+- the remaining open work is small, explicit, and measurable
+- the planning/docs surface is simple enough that contributors know where truth lives
+
+## Live companions
+
+- `docs/plans/workflow-validation-design.md`
+- `docs/roadmap/open-work-inventory.md`
+- `docs/tickets/next-up.md`

package/docs/plans/workrail-platform-vision.md

@@ -0,0 +1,420 @@
+# WorkRail Platform Vision: From Engine to Ecosystem
+
+## Problem statement
+
+WorkRail is a powerful workflow execution engine. But getting workflows into users' hands -- discovering, installing, sharing, configuring -- is harder than it should be. The engine works well once running; everything around it creates friction.
+
+This matters because WorkRail's value scales with adoption. A workflow that only runs on the author's machine is a personal tool. A workflow that any agent on any team can discover and run is infrastructure. The gap between those two is the problem this document addresses.
+
+## Personas
+
+### Solo developer
+
+Works alone or on a small project. Wants structured agent execution for recurring tasks (code review, feature implementation, bug triage). Doesn't want to learn a new system -- just wants the agent to be better.
+
+- **Entry point**: installs workrail, uses bundled workflows
+- **Progression**: tweaks a workflow prompt, eventually authors their own
+- **Pain today**: setup is manual, no guidance, has to understand the internals
+
+### Team member
+
+Part of a team sharing a repo. The team has conventions and patterns they want agents to follow consistently. Wants to use team workflows without thinking about it.
+
+- **Entry point**: clones a repo, team workflows should just be there
+- **Progression**: contributes improvements to team workflows
+- **Pain today**: has to manually install workflows, references break across machines, no project-level discovery
+
+### Platform/infrastructure team
+
+Maintains shared patterns that other teams should follow (contribution models, API design, deployment). Wants to distribute workflows that encode "how to do X correctly" so that consuming teams get it right without tribal knowledge.
+
+- **Entry point**: authors workflows with embedded references (schemas, guides, patterns)
+- **Progression**: maintains and versions workflows that other teams consume
+- **Pain today**: workspace references break outside the source repo, no distribution mechanism, no way to update consumers
+
+### Open source author
+
+Ships a library or framework. Wants to include a workflow that helps users integrate it correctly. The workflow should work for anyone who installs the package, regardless of their setup.
+
+- **Entry point**: includes a workflow in their package
+- **Progression**: maintains the workflow alongside the code
+- **Pain today**: no portable packaging, no reference portability, no install mechanism
+
+### Non-developer
+
+Works in content, ops, data, product. Heard that agents can follow structured workflows. Wants to encode a process (incident response, content review, data pipeline check) without writing JSON.
+
+- **Entry point**: describes what they want, agent creates the workflow
+- **Progression**: tweaks the workflow through conversation, not code
+- **Pain today**: would bounce immediately. JSON authoring is a hard wall.
+
+## Progressive complexity model
+
+Users should be able to use WorkRail at any level without understanding the levels above.
+
+### Level 0: Use bundled workflows
+
+- Install workrail. Bundled workflows are available immediately.
+- Pick one, run it. No authoring, no configuration.
+- **Requirement**: zero-config start. Works out of the box.
+
+### Level 1: Install a shared workflow
+
+- Someone gives you a workflow (file, URL, package name).
+- One action to install. Setup prompt handles it.
+- **Requirement**: single-step install. Agent-assisted. No manual file management.
+
+### Level 2: Customize an existing workflow
+
+- Fork a workflow and modify it for your needs.
+- Edit prompts, add steps, change confirmation gates.
+- Could be JSON editing, markdown editing, or conversational ("make Phase 3 more thorough").
+- **Requirement**: multiple authoring surfaces. JSON is not the only option.
+
+### Level 3: Author a new workflow
+
+- Create a workflow from scratch for a recurring task.
+- Full access to all features (loops, fragments, references, delegation).
+- Use the workflow-for-workflows or author manually.
+- **Requirement**: strong authoring spec, good examples, validation tooling.
+
+### Level 4: Distribute workflows
+
+- Package a workflow with its references and companion files.
+- Share within a team (repo-local), across teams (multi-repo), or publicly (published package).
+- **Requirement**: portable reference resolution, directory-based packaging, optional registry.
+
+## Discovery architecture
+
+Workflow discovery must be layered, automatic, and work without per-project configuration.
+
+### Discovery layers (in resolution order)
+
+| Layer | Source | When it applies | Setup required |
+|-------|--------|----------------|----------------|
+| Bundled | Shipped with the workrail package | Always | None |
+| User-installed | `~/.workrail/workflows/` | Always | Place files or use setup prompt |
+| Project-local | `.workrail/workflows/` in any ancestor directory of configured roots | When roots are configured | One-time: add root to config |
+| Module-local | `.workrail/workflows/` in subdirectories of configured roots | When roots are configured | None (auto-discovered within roots) |
+
+### Multi-root configuration
+
+A single MCP server instance serves workflows from multiple workspace roots. Roots are configured in `~/.workrail/config.json`:
+
+```json
+{
+  "workspaceRoots": [
+    "~/git/work/monorepo",
+    "~/git/personal/workrail",
+    "~/git/oss/my-library"
+  ]
+}
+```
+
+The server scans all roots at startup. Within each root, it recursively discovers `.workrail/workflows/` directories at any depth.
+
+Adding a root is a one-time operation, handled by the setup prompt. Removing a root removes its workflows from discovery.
+
+### Grouped listing
+
+`list_workflows` returns workflows grouped by source, not as a flat list:
+
+```
+Available Workflows:
+
+## WorkRail Built-in
+- coding-task-agentic: Lean Coding Task
+- workflow-for-workflows: Workflow Authoring
+
+## monorepo (repo-level)
+- ci-release: CI Release Flow
+
+## Payments (monorepo/features/payments)
+- payment-integration: Payment Integration
+- payment-api-review: Payment API Review
+
+## Platform (monorepo/platform)
+- platform-contribution: Platform Contribution Guide
+```
+
+Groups are named from a `.workrail/config.json` in the module directory if present, falling back to the directory name.
+
+### ID disambiguation
+
+If two workflows share the same ID across groups, `start_workflow` accepts either:
+- The bare ID (if unique across all groups)
+- A qualified ID: `group/workflow-id` (if ambiguous)
+
+The agent handles disambiguation conversationally when needed.
+
+## Sharing model
+
+### Same repo (team sharing)
+
+Convention-based. Place workflows in `.workrail/workflows/` in the repo or module. Teammates clone the repo, add the root to their config (once), and all workflows are discovered.
+
+```
+my-repo/
+  .workrail/
+    workflows/
+      team-code-review.json
+      team-feature-impl.json
+```
+
+No install step. No sync. Git handles versioning, review, and distribution.
+
+### Cross-repo (org sharing)
+
+Multi-root config. Each repo is a root. Workflows from all repos are available in a single `list_workflows` call.
+
+For workflows that reference files (schemas, guides), use `resolveFrom: workflow` so references resolve relative to the workflow file's location. The workflow and its references are a self-contained directory.
+
+```
+shared-workflows-repo/
+  contribution/
+    .workrail/
+      workflows/
+        platform-contribution.json
+      refs/
+        contribution-schema.json
+        patterns-guide.md
+```
+
+Clone the repo, add it as a root, done.
+
+### Public sharing
+
+A workflow directory is the unit of distribution:
+
+```
+my-workflow/
+  workflow.json
+  refs/
+    schema.json
+    guide.md
+  README.md
+```
+
+Distribution mechanisms (any of these work):
+- Git repository (clone or submodule)
+- npm package
+- Tarball / zip
+- Direct file sharing (for single-file workflows with no references)
+
+The setup prompt handles installation: "Install this workflow from [URL/path]" -- the agent downloads, places it in `~/.workrail/workflows/`, and verifies references resolve.
+
+## Reference evolution
+
+### Current state
+
+References are pointers to files. The engine resolves paths and tells the agent where to look. The agent reads the files with its own tools. Two resolution bases: `workspace` (user's project) and `package` (workrail's own files).
+
+### Problems
+
+1. `workspace` references break outside the source repo (not portable)
+2. `package` references use brittle path arithmetic (`__dirname` + `../../../`)
+3. No way to deliver reference content at the right time (all-at-once on start)
+4. No way to co-locate references with a workflow for sharing
+
+### Evolution
+
+#### Add `resolveFrom: "workflow"`
+
+Resolves paths relative to the workflow file's location on disk. This is the portability primitive: a workflow directory with co-located references works anywhere.
+
+```json
+{
+  "id": "api-schema",
+  "source": "refs/api-schema.json",
+  "resolveFrom": "workflow"
+}
+```
+
+As long as the `refs/` directory travels with the workflow file, the reference resolves.
+
+#### Add step-level attachments
+
+A step declares which references it needs. The engine reads the file and includes the content in the tool response. The agent doesn't make a separate `read_file` call.
+
+```json
+{
+  "id": "implement-api",
+  "title": "Implement the API endpoint",
+  "attachments": ["api-schema"],
+  "prompt": "Implement the endpoint according to the attached schema."
+}
+```
+
+Content is delivered just-in-time. Phase 0 gets the overview doc. Phase 3 gets the schema. Context is fresh at the point of use.
+
+#### Safety limits
+
+- Size cap per attachment (default 32KB, configurable per reference)
+- Total attachment budget per step (default 64KB)
+- Oversized references fall back to pointer-only with a note: "Reference 'X' is too large to attach. Read it with your file tools at: [path]"
+
+#### MCP resources for bundled content
+
+Package-bundled references (schema, authoring spec, setup guide) are also exposed as MCP resources. Agents and clients that support resources can discover and read them without a workflow context.
+
+## Authoring surface evolution
+
+### Now: JSON + agent-assisted
+
+JSON remains the engine format. The workflow-for-workflows helps authors create workflows through structured agent guidance. The authoring spec and schema define correctness.
+
+### Next: Markdown authoring
+
+A simpler format for Level 2 users who want to tweak workflows without deep JSON knowledge:
+
+```markdown
+# Code Review Workflow
+
+## Step 1: Understand the changes
+Read the PR description and the changed files. Summarize what was changed and why.
+
+## Step 2: Review for correctness
+Check each file for bugs, edge cases, and missing error handling.
+
+> [!confirm]
+> Confirm findings with the user before proceeding.
+
+## Step 3: Write review comments
+Post your findings as PR review comments.
+```
+
+A compiler converts this to JSON. The markdown format supports a subset of features (steps, prompts, confirmation gates). Advanced features (loops, fragments, conditions) require JSON.
+
+### Later: Visual editing
+
+A web UI for workflow authoring. Drag-and-drop steps, visual loop configuration, prompt editing with preview. Outputs JSON. This is the Level 2 experience for non-developers.
+
+The console surface (`console/`) is the natural home for this.
+
+## MCP primitive usage
+
+WorkRail currently uses only MCP tools. The full MCP spec offers three primitives, each suited to different interactions.
+
+### Tools (agent-controlled actions)
+
+Keep for execution:
+- `start_workflow` -- create session, begin execution
+- `continue_workflow` -- advance or rehydrate
+- `checkpoint_workflow` -- record progress
+
+Keep for queries that benefit from agent timing:
+- `list_workflows` -- discovery (also useful as a resource, see below)
+- `inspect_workflow` -- detailed workflow view
+
+### Resources (discoverable content)
+
+Add for content that should be discoverable without a tool call:
+- `workrail://spec/workflow-schema` -- JSON schema
+- `workrail://spec/authoring-spec` -- authoring guidance
+- `workrail://docs/setup-guide` -- setup and configuration guide
+- `workrail://workflows/{id}` -- workflow metadata (mirrors inspect_workflow)
+
+Resources complement tools. Clients that support resources get richer discoverability. Clients that only support tools use the existing tool surface. No degradation.
+
+### Prompts (user-triggered interactions)
+
+Add for user-initiated actions that don't need full workflow execution:
+- `/setup-workrail` -- first-time setup, add repos, configure preferences
+- `/start {workflow}` -- user-friendly workflow start (wraps start_workflow)
+- `/help-authoring` -- guidance for writing workflows
+
+Prompts surface in client UIs as slash commands or menu items. They lower the barrier for users who don't know the tool names.
+
+### Backward compatibility
+
+All three primitives are additive. The existing tool surface continues to work unchanged. Resources and prompts are available to clients that support them and invisible to clients that don't.
+
+## Agent-driven setup
+
+Setup and configuration are handled by an MCP prompt backed by a setup guide resource.
+
+### The setup guide
+
+A concise reference document (`docs/setup-guide.md`) shipped with the package and exposed as an MCP resource. Covers:
+
+- WorkRail directory structure and conventions
+- How to add a workspace root
+- How to install a shared workflow
+- How to configure preferences
+- How to verify the setup
+- Troubleshooting common issues
+
+### The setup prompt
+
+```
+/setup-workrail
+```
+
+When triggered:
+1. Server returns the setup guide content as context
+2. Agent reads the user's intent conversationally
+3. Agent performs the setup (file operations, config updates, validation)
+4. Agent verifies with `list_workflows` and reports what's available
+
+Handles all setup scenarios:
+- "Set up workrail for my monorepo"
+- "I got this workflow from a teammate" (pastes JSON)
+- "Add my other repo to workrail"
+- "Change my default preferences"
+- "Show me what's available"
+
+### Why not a workflow for setup?
+
+A workflow adds session overhead (tokens, checkpoints, event log) for a task that takes 2 minutes. The setup interaction is stateless and conversational. An MCP prompt with a reference doc is the right weight.
+
+## Phased delivery
+
+### Now (no engine changes)
+
+1. **Write the setup guide** (`docs/setup-guide.md`)
+2. **Add multi-root config** support to `~/.workrail/config.json`
+3. **Recursive module discovery** within configured roots
+4. **Grouped `list_workflows` output** with source tagging
+
+### Next (small engine changes)
+
+5. **`resolveFrom: workflow`** for portable co-located references
+6. **MCP resources** for bundled docs (schema, authoring spec, setup guide)
+7. **MCP prompt** for `/setup-workrail`
+8. **Module-level `.workrail/config.json`** for group naming
+
+### Later (medium engine changes)
+
+9. **Step-level attachments** for timed content delivery
+10. **Markdown authoring format** with compiler to JSON
+11. **MCP prompt** for `/start {workflow}`
+12. **`workrail install` CLI** for one-command workflow installation
+
+### Future (larger scope)
+
+13. **Workflow overlay/extension** system (customize without forking)
+14. **Visual authoring** in the console UI
+15. **Published workflow packages** (npm or dedicated registry)
+16. **Content pinning** at compile time for fully self-contained workflows
+
+## Design constraints
+
+- **Backward compatible**: every change is additive. Existing workflows, tools, and configs continue to work.
+- **Client-agnostic**: works with any MCP client. Features that depend on resources/prompts degrade gracefully to tools-only.
+- **Convention over configuration**: sensible defaults, auto-discovery, minimal required config.
+- **Agent-first setup**: the agent handles infrastructure work. The user makes decisions, not file operations.
+- **Progressive disclosure**: Level 0 users never see Level 4 complexity. Each level is self-contained.
+
+## Open questions
+
+1. **Workflow ID namespacing**: should IDs be globally unique, or scoped to their group? Global uniqueness is simpler but constraining. Group-scoped requires qualified IDs for disambiguation.
+
+2. **Config file location**: `~/.workrail/config.json` is user-global. Should there also be a project-level config (`.workrail/config.json` at repo root) for team-shared settings like group names?
+
+3. **Markdown authoring scope**: how much of the JSON feature set should markdown support? Enough for Level 2 (steps, prompts, confirmations) or more (loops, conditions, fragments)?
+
+4. **Reference content delivery format**: when step-level attachments deliver content, how should it be framed? Inline in the prompt? Separate content section? Depends on content type (markdown vs JSON vs code)?
+
+5. **Overlay/extension design**: what's the minimum safe override surface for derived workflows? References only? References + metaGuidance? Step-level patches?
+
+6. **Update semantics**: when a shared workflow is updated upstream, how does the consumer know? Pull-based (check on start)? Notification? Manual?