@exaudeus/workrail 1.17.0 → 2.0.0

package/README.md

@@ -31,8 +31,8 @@ to conclusions.
 WorkRail replaces the human effort of guiding an agent step-by-step.
 
 Instead of one system prompt that fades over time, WorkRail drip-feeds instructions through
-the [Model Context Protocol](https://modelcontextprotocol.org). The agent calls `workflow_next`,
-gets ONE step, completes it, calls again. Future steps stay hidden until previous ones are done.
+the [Model Context Protocol](https://modelcontextprotocol.org). The agent calls `start_workflow`,
+gets the first step, completes it, calls `continue_workflow`. Future steps stay hidden until previous ones are done.
 
 **The agent can't skip to implementation because it doesn't know those steps exist yet.**
 
@@ -44,7 +44,7 @@ You                      Agent                     WorkRail
  │  "Fix the auth bug"     │                          │
  │────────────────────────>│                          │
  │                         │                          │
- │                         │  workflow_next()         │
+ │                         │  start_workflow()        │
  │                         │─────────────────────────>│
  │                         │                          │
  │                         │   Step 1: Understand     │
@@ -55,7 +55,7 @@ You                      Agent                     WorkRail
  │    see exactly?"        │                          │
  │<────────────────────────│                          │
  │                         │                          │
- │         ...             │  workflow_next()         │
+ │         ...             │  continue_workflow()     │
  │                         │─────────────────────────>│
  │                         │                          │
  │                         │   Step 2: Plan your      │
@@ -81,21 +81,21 @@ Agent: "I see the issue! In auth.js line 42, there's a null check that
 You:   "There's a bug in the auth flow"
 
 Agent: "I'll use the bug-investigation workflow."
-        → workflow_next()
+        → start_workflow()
        
        Step 1: Investigation Setup
        "Before I investigate, I need to understand the problem.
         What exactly happens when it fails? Can you share the error?"
        
        [Documents bug, reproduction steps, environment]
-        → workflow_next()
+        → continue_workflow()
        
        Step 2: Plan Investigation
        "I'll trace execution from login through the auth middleware.
         Key areas: token validation, session lookup, error handling."
        
        [Creates investigation plan before touching code]
-        → workflow_next()
+        → continue_workflow()
        
        Step 3: Form Hypotheses
        "Based on my analysis, three possible causes:
@@ -164,13 +164,13 @@ The agent will find the workflow, start at step 1, and proceed systematically.
 
 ## Included Workflows
 
-20+ workflows included for development, debugging, review, documentation, and more:
+30+ workflows included for development, debugging, review, documentation, and more:
 
 | Workflow | When to Use |
 |----------|-------------|
-| `coding-task-workflow-with-loops` | Feature development with analysis, planning, and review |
-| `bug-investigation` | Systematic debugging with hypothesis testing |
-| `mr-review-workflow` | Code review with architecture and security checks |
+| `coding-task-workflow-agentic` | Feature development with notes-first durability and audit loops |
+| `bug-investigation-agentic` | Systematic debugging with evidence-based analysis |
+| `mr-review-workflow-agentic` | Code review with parallel reviewer families |
 | `exploration-workflow` | Understanding an unfamiliar codebase |
 | `document-creation-workflow` | Technical documentation with structure |
 

package/dist/application/services/workflow-interpreter.js

@@ -196,7 +196,7 @@ let WorkflowInterpreter = class WorkflowInterpreter {
                         return (0, neverthrow_1.ok)(shouldEnter);
                     }
                     case 'while': {
-                        const res = this.evaluateWhileUntilCondition(loopCompiled, iteration, context, artifacts, frame, false);
+                        const res = this.evaluateWhileUntilCondition(loopCompiled, iteration, context, artifacts, frame, false, trace);
                         if (res.isOk()) {
                             const source = loopCompiled.conditionSource?.kind === 'artifact_contract' ? 'artifact'
                                 : loopCompiled.conditionSource?.kind === 'context_variable' ? 'context'
@@ -208,7 +208,7 @@ let WorkflowInterpreter = class WorkflowInterpreter {
                         return res;
                     }
                     case 'until': {
-                        const res = this.evaluateWhileUntilCondition(loopCompiled, iteration, context, artifacts, frame, true);
+                        const res = this.evaluateWhileUntilCondition(loopCompiled, iteration, context, artifacts, frame, true, trace);
                         if (res.isOk()) {
                             const source = loopCompiled.conditionSource?.kind === 'artifact_contract' ? 'artifact'
                                 : loopCompiled.conditionSource?.kind === 'context_variable' ? 'context'
@@ -303,7 +303,7 @@ let WorkflowInterpreter = class WorkflowInterpreter {
                 return (0, neverthrow_1.err)(error_1.Err.invalidState('Non-exhaustive loop decision'));
         }
     }
-    evaluateWhileUntilCondition(loopCompiled, iteration, context, artifacts, frame, invertForUntil) {
+    evaluateWhileUntilCondition(loopCompiled, iteration, context, artifacts, frame, invertForUntil, traceEntries = []) {
         const source = loopCompiled.conditionSource;
         if (!source) {
             if (!loopCompiled.loop.loop.condition) {
@@ -318,11 +318,19 @@ let WorkflowInterpreter = class WorkflowInterpreter {
         }
         switch (source.kind) {
             case 'artifact_contract': {
-                const result = (0, loop_control_evaluator_1.evaluateLoopControlFromArtifacts)(artifacts, source.loopId);
-                if (result.kind === 'found') {
-                    return (0, neverthrow_1.ok)(result.decision === 'continue');
+                const result = (0, loop_control_evaluator_1.evaluateLoopControlFromArtifacts)(artifacts);
+                traceEntries.push((0, decision_trace_builder_1.traceArtifactMatchResult)(source.loopId, iteration, result));
+                switch (result.kind) {
+                    case 'found':
+                        return (0, neverthrow_1.ok)(result.decision === 'continue');
+                    case 'not_found':
+                    case 'invalid':
+                        return (0, neverthrow_1.ok)(true);
+                    default: {
+                        const _exhaustive = result;
+                        return (0, neverthrow_1.ok)(true);
+                    }
                 }
-                return (0, neverthrow_1.ok)(true);
             }
             case 'context_variable': {
                 const raw = (0, condition_evaluator_1.evaluateCondition)(source.condition, this.projectLoopContextAtIteration(loopCompiled.loop, iteration, context));

package/dist/config/feature-flags.js

@@ -56,10 +56,10 @@ exports.FEATURE_FLAG_DEFINITIONS = [
     {
         key: 'v2Tools',
         envVar: 'WORKRAIL_ENABLE_V2_TOOLS',
-        defaultValue: false,
-        description: 'Enable WorkRail v2 MCP tools and .v2.json workflow overrides behind an explicit opt-in flag',
+        defaultValue: true,
+        description: 'WorkRail v2 MCP tools (list_workflows, start_workflow, continue_workflow, checkpoint_workflow, resume_session) and .v2.json workflow overrides',
         since: '0.9.0',
-        stable: false,
+        stable: true,
     },
 ];
 function parseBoolean(value, defaultValue) {

package/dist/manifest.json

@@ -110,8 +110,8 @@
       "bytes": 1507
     },
     "application/services/workflow-interpreter.js": {
-      "sha256": "e6ea1bc6f3881bc46a901b78720dee584090f86809bfa1979f04efa4c8a35613",
-      "bytes": 21011
+      "sha256": "df7a04c0b2c578cf54e3bc818a08b6e1af18ea75f6ade4901b3e9ceeabf46814",
+      "bytes": 21430
     },
     "application/services/workflow-service.d.ts": {
       "sha256": "b92da17c6d91c90758ec42b4ee3bc448e5d5b1dfe7351f2fe0f5e1d10a715ec6",
@@ -326,8 +326,8 @@
       "bytes": 1512
     },
     "config/feature-flags.js": {
-      "sha256": "c7c5a4db2a0d5f86a9cf91c9a7e2c74f89ce7f1012b93c8237a3d70a783d2b45",
-      "bytes": 6908
+      "sha256": "d8a709e0814b4d9bd9565b795c7b932fbab1d86762b437f7ed64be8e97a99598",
+      "bytes": 6957
     },
     "core/error-handler.d.ts": {
       "sha256": "80451f12ac8e185133ec3dc4c57285491a785f27525ed21e729db1da3f61010d",
@@ -770,12 +770,12 @@
       "bytes": 12661
     },
     "mcp/handlers/v2-execution/start.d.ts": {
-      "sha256": "333f9f36756d2ce55249c6af45198a17b51aa9c6448e063f7621fcd61879f2bf",
-      "bytes": 2684
+      "sha256": "ec0a9cbe95eba29cbf4f66c7fbacd10209b451e9e0a3e15bf92cbc751ef5b0c2",
+      "bytes": 2868
     },
     "mcp/handlers/v2-execution/start.js": {
-      "sha256": "0c6800d22f93a36b45236d17993b445de131e00a72eac8dbd98e2f4d8d9f2b29",
-      "bytes": 15208
+      "sha256": "fa724a733b2f249bcd9300d79f4f5d20fa155f005a2d9837f16f50b44bfd106c",
+      "bytes": 16250
     },
     "mcp/handlers/v2-resume.d.ts": {
       "sha256": "d88f6c35bcaf946666c837b72fda3702a2ebab5e478eb90f7b4b672a0e5fa24f",
@@ -846,8 +846,8 @@
       "bytes": 882
     },
     "mcp/server.js": {
-      "sha256": "5086b482d2eb3c42caac637282a5361b4db6e5d14aaeeb7c5ffdf75d211af0d8",
-      "bytes": 13422
+      "sha256": "c07f8a6e8f89f7620a063673859dcc458212b068237949acff253f15856afd5f",
+      "bytes": 14174
     },
     "mcp/tool-description-provider.d.ts": {
       "sha256": "1d46abc3112e11b68e57197e846f5708293ec9b2281fa71a9124ee2aad71e41b",
@@ -914,8 +914,8 @@
       "bytes": 747
     },
     "mcp/types.d.ts": {
-      "sha256": "2ef7f9c1bffbe365b06469dfad43b45c4ae3b5292dd269b33423bf1c8c9c7c43",
-      "bytes": 4355
+      "sha256": "d61a7d2b9a5f389d9fbf0092f6d38c3e6bb2925f41dce0270ed0c2e54ca856c9",
+      "bytes": 4533
     },
     "mcp/types.js": {
       "sha256": "d10c4070e4c3454d80f0fa9cdc0e978c69c53c13fd09baa8710fcd802fed8926",
@@ -1362,12 +1362,12 @@
       "bytes": 1734
     },
     "v2/durable-core/domain/decision-trace-builder.d.ts": {
-      "sha256": "7caf53d88745ea8f05e3904dee6a03379af5f68cabd9580e99d93e0095992fc9",
-      "bytes": 1520
+      "sha256": "bcc7892a25099be88ca92770d98f2e7e232eef007ff8f48001aefe9c08ee876c",
+      "bytes": 1742
     },
     "v2/durable-core/domain/decision-trace-builder.js": {
-      "sha256": "011f3155612d782c8877238893e53ac3c30962596173202dcbf1a1c4f04932a0",
-      "bytes": 3711
+      "sha256": "411da4951de3603c811afe8f4fa93de724f162834522c84e99a219c28248bf73",
+      "bytes": 4332
     },
     "v2/durable-core/domain/function-definition-expander.d.ts": {
       "sha256": "2720e7c4dfbd9ec0cdf75eb4384fdbea18d4430aeae7f13d9215f0e5e4980468",
@@ -1386,12 +1386,12 @@
       "bytes": 908
     },
     "v2/durable-core/domain/loop-control-evaluator.d.ts": {
-      "sha256": "8fd92ad809a19a00a856374abb5a3e3cc8cbfe7c4a26fa28bc2994294d0bac2e",
-      "bytes": 533
+      "sha256": "fbda4d2cb49d71e066f1b9bc967d5b89f4e2d1c692b865b026cf9e0bad80ad99",
+      "bytes": 517
     },
     "v2/durable-core/domain/loop-control-evaluator.js": {
-      "sha256": "047dcc651b9b25c63e11c8efcff7d27d9d329297db94728a35f52e88399d6e73",
-      "bytes": 810
+      "sha256": "0db4f39141a02c3a60c50955e71e5d925a473cdd01a6d6661b2d6df5d4ca2643",
+      "bytes": 1071
     },
     "v2/durable-core/domain/loop-runtime.d.ts": {
       "sha256": "ee4f8857d72bf0066bccc351a4e8fd8e4800f3d540e9851bb4978179b8ebfc04",
@@ -1430,8 +1430,8 @@
       "bytes": 935
     },
     "v2/durable-core/domain/prompt-renderer.js": {
-      "sha256": "5c360d989c9b8ec6c8319943067b5e5e711d37086de1b8231c7c20c5285ec075",
-      "bytes": 12459
+      "sha256": "5021f3cc9e59db56c5aeddcc8ed6f69df7ea1b1f3011d685695021e039376e49",
+      "bytes": 13910
     },
     "v2/durable-core/domain/reason-model.d.ts": {
       "sha256": "650fcb2d9969a4e6123cccbd4913f4d57aeab21a19bb907aa1e11f95e5a95089",
@@ -1618,12 +1618,12 @@
       "bytes": 1728
     },
     "v2/durable-core/schemas/artifacts/loop-control.d.ts": {
-      "sha256": "f1201fe5ab9680b11959985bf6004adcd8227de74b8151a6b4457553d6394203",
-      "bytes": 2792
+      "sha256": "714e2980400da0aaf814c691d8915653393316e70bc9af9da72130bb07e959be",
+      "bytes": 2768
     },
     "v2/durable-core/schemas/artifacts/loop-control.js": {
-      "sha256": "8f0cb5a113d7700a2a0aca158a7463bd5528b40d2e16dc14d1596e997c5b3b0d",
-      "bytes": 2243
+      "sha256": "c4b2ed38f9fdda3fbe3e4b68b0a228890fd9a7c73117a6d202928acabe6fc0f9",
+      "bytes": 2115
     },
     "v2/durable-core/schemas/compiled-workflow/index.d.ts": {
       "sha256": "d13d2dbbcd0971f7c170788552f533c2605f26e0f352939bf5cd2348437d7519",

package/dist/mcp/handlers/v2-execution/start.d.ts

@@ -6,6 +6,7 @@ import { type SessionId, type RunId, type NodeId, type WorkflowHash } from '../.
 import type { Sha256PortV2 } from '../../../v2/ports/sha256.port.js';
 import type { TokenCodecPorts } from '../../../v2/durable-core/tokens/token-codec-ports.js';
 import { ResultAsync as RA } from 'neverthrow';
+import { type ValidationPipelineDepsPhase1a } from '../../../application/services/workflow-validation-pipeline.js';
 import { type ObservationEventData } from '../../../v2/durable-core/domain/observation-builder.js';
 import { type StartWorkflowError } from '../v2-execution-helpers.js';
 import * as z from 'zod';
@@ -14,6 +15,7 @@ export declare function loadAndPinWorkflow(args: {
     readonly workflowService: import('../../../application/services/workflow-service.js').WorkflowService;
     readonly crypto: Sha256PortV2;
     readonly pinnedStore: import('../../../v2/ports/pinned-workflow-store.port.js').PinnedWorkflowStorePortV2;
+    readonly validationPipelineDeps: ValidationPipelineDepsPhase1a;
 }): RA<{
     readonly workflow: import('../../../types/workflow.js').Workflow;
     readonly workflowHash: WorkflowHash;

package/dist/mcp/handlers/v2-execution/start.js

@@ -10,7 +10,7 @@ const workflow_js_1 = require("../../../types/workflow.js");
 const index_js_1 = require("../../../v2/durable-core/ids/index.js");
 const workflow_hash_ref_js_1 = require("../../../v2/durable-core/ids/workflow-hash-ref.js");
 const neverthrow_1 = require("neverthrow");
-const v1_to_v2_shim_js_1 = require("../../../v2/read-only/v1-to-v2-shim.js");
+const workflow_validation_pipeline_js_1 = require("../../../application/services/workflow-validation-pipeline.js");
 const hashing_js_1 = require("../../../v2/durable-core/canonical/hashing.js");
 const observation_builder_js_1 = require("../../../v2/durable-core/domain/observation-builder.js");
 const workflow_source_js_1 = require("../../../types/workflow-source.js");
@@ -24,7 +24,7 @@ const constants_js_1 = require("../../../v2/durable-core/constants.js");
 const index_js_2 = require("./index.js");
 const start_construction_js_1 = require("../../../v2/durable-core/domain/start-construction.js");
 function loadAndPinWorkflow(args) {
-    const { workflowId, workflowService, crypto, pinnedStore } = args;
+    const { workflowId, workflowService, crypto, pinnedStore, validationPipelineDeps } = args;
     return neverthrow_1.ResultAsync.fromPromise(workflowService.getWorkflowById(workflowId), (e) => ({
         kind: 'precondition_failed',
         message: e instanceof Error ? e.message : String(e),
@@ -39,14 +39,25 @@ function loadAndPinWorkflow(args) {
         return (0, neverthrow_1.okAsync)({ workflow });
     })
         .andThen(({ workflow }) => {
-        const normalizeResult = (0, v1_to_v2_shim_js_1.normalizeV1WorkflowToPinnedSnapshot)(workflow);
-        if (normalizeResult.isErr()) {
+        const pipelineOutcome = (0, workflow_validation_pipeline_js_1.validateWorkflowPhase1a)(workflow, validationPipelineDeps);
+        if (pipelineOutcome.kind !== 'phase1a_valid') {
+            const message = pipelineOutcome.kind === 'schema_failed'
+                ? `Schema validation failed: ${pipelineOutcome.errors.map(e => e.message ?? e.instancePath).join('; ')}`
+                : pipelineOutcome.kind === 'structural_failed'
+                    ? `Structural validation failed: ${pipelineOutcome.issues.join('; ')}`
+                    : pipelineOutcome.kind === 'v1_compilation_failed'
+                        ? `Compilation failed: ${pipelineOutcome.cause.message}`
+                        : pipelineOutcome.kind === 'normalization_failed'
+                            ? `Normalization failed: ${pipelineOutcome.cause.message}`
+                            : pipelineOutcome.kind === 'executable_compilation_failed'
+                                ? `Executable compilation failed: ${pipelineOutcome.cause.message}`
+                                : 'Unknown validation failure';
             return (0, neverthrow_1.errAsync)({
                 kind: 'workflow_compile_failed',
-                message: normalizeResult.error.message,
+                message,
             });
         }
-        const compiled = normalizeResult.value;
+        const compiled = pipelineOutcome.snapshot;
         const workflowHashRes = (0, hashing_js_1.workflowHashForCompiledSnapshot)(compiled, crypto);
         if (workflowHashRes.isErr()) {
             return (0, neverthrow_1.errAsync)({ kind: 'hash_computation_failed', message: workflowHashRes.error.message });
@@ -215,12 +226,13 @@ function mintStartTokens(args) {
     });
 }
 function executeStartWorkflow(input, ctx) {
-    const { gate, sessionStore, snapshotStore, pinnedStore, crypto, tokenCodecPorts, idFactory } = ctx.v2;
+    const { gate, sessionStore, snapshotStore, pinnedStore, crypto, tokenCodecPorts, idFactory, validationPipelineDeps } = ctx.v2;
     return loadAndPinWorkflow({
         workflowId: input.workflowId,
         workflowService: ctx.workflowService,
         crypto,
         pinnedStore,
+        validationPipelineDeps,
     })
         .andThen(({ workflow, firstStep, workflowHash, pinnedWorkflow }) => {
         const anchorsRA = (0, v2_workspace_resolution_js_1.resolveWorkspaceAnchors)(ctx.v2, input.workspacePath)

package/dist/mcp/server.js

@@ -41,6 +41,8 @@ const container_js_1 = require("../di/container.js");
 const tokens_js_1 = require("../di/tokens.js");
 const assert_never_js_1 = require("../runtime/assert-never.js");
 const token_codec_ports_js_1 = require("../v2/durable-core/tokens/token-codec-ports.js");
+const validation_js_1 = require("../application/validation.js");
+const v1_to_v2_shim_js_1 = require("../v2/read-only/v1-to-v2-shim.js");
 const index_js_1 = require("../v2/infra/local/workspace-anchor/index.js");
 const workspace_roots_manager_js_1 = require("./workspace-roots-manager.js");
 const index_js_2 = require("../v2/infra/local/directory-listing/index.js");
@@ -94,6 +96,14 @@ async function createToolContext() {
             const dataDir = container_js_1.container.resolve(tokens_js_1.DI.V2.DataDir);
             const fsPort = container_js_1.container.resolve(tokens_js_1.DI.V2.FileSystem);
             const directoryListing = new index_js_2.LocalDirectoryListingV2(fsPort);
+            const validationEngine = container_js_1.container.resolve(tokens_js_1.DI.Infra.ValidationEngine);
+            const compiler = container_js_1.container.resolve(tokens_js_1.DI.Services.WorkflowCompiler);
+            const validationPipelineDeps = {
+                schemaValidate: validation_js_1.validateWorkflowSchema,
+                structuralValidate: validationEngine.validateWorkflowStructureOnly.bind(validationEngine),
+                compiler,
+                normalizeToExecutable: v1_to_v2_shim_js_1.normalizeV1WorkflowToPinnedSnapshot,
+            };
             v2 = {
                 gate,
                 sessionStore,
@@ -103,6 +113,7 @@ async function createToolContext() {
                 crypto,
                 idFactory,
                 tokenCodecPorts,
+                validationPipelineDeps,
                 resolvedRootUris: [],
                 workspaceResolver: new index_js_1.LocalWorkspaceAnchorV2(process.cwd()),
                 dataDir,

package/dist/mcp/types.d.ts

@@ -16,6 +16,7 @@ import type { WorkspaceContextResolverPortV2 } from '../v2/ports/workspace-ancho
 import type { DataDirPortV2 } from '../v2/ports/data-dir.port.js';
 import type { DirectoryListingPortV2 } from '../v2/ports/directory-listing.port.js';
 import type { SessionSummaryProviderPortV2 } from '../v2/ports/session-summary-provider.port.js';
+import type { ValidationPipelineDepsPhase1a } from '../application/services/workflow-validation-pipeline.js';
 export interface SessionHealthDetails {
     readonly health: SessionHealthV2;
 }
@@ -55,6 +56,7 @@ export interface V2Dependencies {
     readonly crypto: CryptoPortV2;
     readonly idFactory: IdFactoryV2;
     readonly tokenCodecPorts: TokenCodecPorts;
+    readonly validationPipelineDeps: ValidationPipelineDepsPhase1a;
     readonly resolvedRootUris?: readonly string[];
     readonly workspaceResolver?: WorkspaceContextResolverPortV2;
     readonly dataDir?: DataDirPortV2;

package/dist/v2/durable-core/domain/decision-trace-builder.d.ts

@@ -1,4 +1,5 @@
 import type { Result } from 'neverthrow';
+import type { LoopControlEvaluationResult } from './loop-control-evaluator.js';
 export type DecisionTraceEntryKind = 'selected_next_step' | 'evaluated_condition' | 'entered_loop' | 'exited_loop' | 'detected_non_tip_advance';
 export type DecisionTraceRef = {
     readonly kind: 'step_id';
@@ -22,6 +23,7 @@ export declare function traceEnteredLoop(loopId: string, iteration: number): Dec
 export declare function traceEvaluatedCondition(loopId: string, iteration: number, result: boolean, source: 'artifact' | 'context' | 'legacy'): DecisionTraceEntry;
 export declare function traceExitedLoop(loopId: string, reason: string): DecisionTraceEntry;
 export declare function traceSelectedNextStep(stepId: string): DecisionTraceEntry;
+export declare function traceArtifactMatchResult(loopId: string, iteration: number, result: LoopControlEvaluationResult): DecisionTraceEntry;
 export declare function applyTraceBudget(entries: readonly DecisionTraceEntry[]): readonly DecisionTraceEntry[];
 export declare function buildDecisionTraceEventData(traceId: string, entries: readonly DecisionTraceEntry[]): Result<{
     readonly traceId: string;

package/dist/v2/durable-core/domain/decision-trace-builder.js

@@ -4,6 +4,7 @@ exports.traceEnteredLoop = traceEnteredLoop;
 exports.traceEvaluatedCondition = traceEvaluatedCondition;
 exports.traceExitedLoop = traceExitedLoop;
 exports.traceSelectedNextStep = traceSelectedNextStep;
+exports.traceArtifactMatchResult = traceArtifactMatchResult;
 exports.applyTraceBudget = applyTraceBudget;
 exports.buildDecisionTraceEventData = buildDecisionTraceEventData;
 const neverthrow_1 = require("neverthrow");
@@ -38,6 +39,20 @@ function traceSelectedNextStep(stepId) {
         refs: [{ kind: 'step_id', stepId }],
     };
 }
+function traceArtifactMatchResult(loopId, iteration, result) {
+    const detail = (() => {
+        switch (result.kind) {
+            case 'found': return `decision="${result.decision}"`;
+            case 'not_found': return result.reason;
+            case 'invalid': return result.reason;
+        }
+    })();
+    return {
+        kind: 'evaluated_condition',
+        summary: `Loop '${loopId}' iteration ${iteration}: artifact match=${result.kind} — ${detail}`,
+        refs: [{ kind: 'loop_id', loopId }, { kind: 'iteration', value: iteration }],
+    };
+}
 function applyTraceBudget(entries) {
     const capped = entries.slice(0, constants_js_1.MAX_DECISION_TRACE_ENTRIES);
     let totalBytes = 0;

package/dist/v2/durable-core/domain/loop-control-evaluator.d.ts

@@ -10,4 +10,4 @@ export type LoopControlEvaluationResult = {
     readonly kind: 'invalid';
     readonly reason: string;
 };
-export declare function evaluateLoopControlFromArtifacts(artifacts: readonly unknown[], loopId: string): LoopControlEvaluationResult;
+export declare function evaluateLoopControlFromArtifacts(artifacts: readonly unknown[]): LoopControlEvaluationResult;

package/dist/v2/durable-core/domain/loop-control-evaluator.js

@@ -2,23 +2,30 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.evaluateLoopControlFromArtifacts = evaluateLoopControlFromArtifacts;
 const index_js_1 = require("../schemas/artifacts/index.js");
-function evaluateLoopControlFromArtifacts(artifacts, loopId) {
+function evaluateLoopControlFromArtifacts(artifacts) {
     if (artifacts.length === 0) {
         return {
             kind: 'not_found',
-            reason: `No artifacts provided to evaluate loop control for loopId=${loopId}`,
+            reason: 'No artifacts provided for loop control evaluation',
         };
     }
-    const artifact = (0, index_js_1.findLoopControlArtifact)(artifacts, loopId);
-    if (!artifact) {
+    const artifact = (0, index_js_1.findLoopControlArtifact)(artifacts);
+    if (artifact) {
         return {
-            kind: 'not_found',
-            reason: `No loop control artifact found for loopId=${loopId}`,
+            kind: 'found',
+            decision: artifact.decision,
+            artifact,
+        };
+    }
+    const hasKindMatch = artifacts.some(index_js_1.isLoopControlArtifact);
+    if (hasKindMatch) {
+        return {
+            kind: 'invalid',
+            reason: 'Artifact with kind=wr.loop_control found but failed schema validation (bad loopId format, missing decision, or extra fields)',
         };
     }
     return {
-        kind: 'found',
-        decision: artifact.decision,
-        artifact,
+        kind: 'not_found',
+        reason: 'No wr.loop_control artifact found',
     };
 }

package/dist/v2/durable-core/domain/prompt-renderer.js

@@ -114,24 +114,55 @@ function applyPromptBudget(combinedPrompt) {
     const decoder = new TextDecoder('utf-8');
     return decoder.decode(truncatedBytes) + markerText + omissionNote;
 }
+function resolveParentLoopMaxIterations(workflow, stepId) {
+    for (const step of workflow.definition.steps) {
+        if ((0, workflow_js_1.isLoopStepDefinition)(step) && Array.isArray(step.body)) {
+            for (const bodyStep of step.body) {
+                if (bodyStep.id === stepId) {
+                    return step.loop.maxIterations;
+                }
+            }
+        }
+    }
+    return undefined;
+}
+function buildScopeInstruction(iteration, maxIterations) {
+    if (iteration <= 1)
+        return 'Focus on what the first pass missed — do not re-litigate settled findings.';
+    if (maxIterations !== undefined && iteration + 1 >= maxIterations)
+        return 'FINAL PASS — verify prior amendments landed correctly. Only flag regressions or clearly missed issues.';
+    return 'Diminishing returns expected. Focus on gaps and regressions, not fresh territory.';
+}
 function buildLoopContextBanner(args) {
     if (args.loopPath.length === 0 || args.isExitStep)
         return '';
     const current = args.loopPath[args.loopPath.length - 1];
-    const iterationLabel = `Iteration ${current.iteration + 1}`;
-    return [
-        `---`,
-        `**LOOP: ${current.loopId} | ${iterationLabel}** — This step repeats intentionally; the workflow is not stuck or broken.`,
-        ``,
-        `Choose the instruction that matches your current task:`,
-        `- **Drafting / updating**: incorporate amendments discovered in previous iterations before writing.`,
-        `- **Auditing / reviewing**: look for what previous passes *missed*, not what they already caught.`,
-        `- **Applying changes**: follow prior findings precisely; don't re-debate settled decisions.`,
-        ``,
-        `Prior iteration work is visible in the **Ancestry Recap** section below (if present).`,
-        `---`,
-        ``,
-    ].join('\n');
+    const iterationNumber = current.iteration + 1;
+    const maxIter = args.maxIterations;
+    if (current.iteration === 0) {
+        const bound = maxIter !== undefined ? ` (up to ${maxIter} passes)` : '';
+        return [
+            `> This step is part of an iterative loop${bound}. After your work, a decision step determines whether another pass is needed.`,
+            ``,
+        ].join('\n');
+    }
+    const lines = ['---'];
+    if (maxIter !== undefined) {
+        const filled = Math.min(iterationNumber, maxIter);
+        const empty = Math.max(maxIter - filled, 0);
+        const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(empty);
+        lines.push(`**Progress: [${bar}] Pass ${iterationNumber} of ${maxIter}**`);
+    }
+    else {
+        lines.push(`**Pass ${iterationNumber}**`);
+    }
+    lines.push('');
+    lines.push(`**Scope**: ${buildScopeInstruction(current.iteration, maxIter)}`);
+    lines.push('');
+    lines.push('Your previous work is in the **Ancestry Recap** below. Build on it — do not repeat work already done.');
+    lines.push('---');
+    lines.push('');
+    return lines.join('\n');
 }
 function formatOutputContractRequirements(outputContract) {
     const contractRef = outputContract?.contractRef;
@@ -143,7 +174,8 @@ function formatOutputContractRequirements(outputContract) {
                 `Artifact contract: ${index_js_2.LOOP_CONTROL_CONTRACT_REF}`,
                 `Provide an artifact with kind: "wr.loop_control"`,
                 `Required field: decision ("continue" | "stop")`,
-                `Optional field: loopId — omit unless targeting a specific named loop`,
+                `Do NOT include loopId — the engine matches automatically`,
+                `Canonical format:\n\`\`\`json\n{ "artifacts": [{ "kind": "wr.loop_control", "decision": "stop" }] }\n\`\`\``,
             ];
         default:
             return [
@@ -184,7 +216,8 @@ function renderPendingPrompt(args) {
         ? step.outputContract
         : undefined;
     const isExitStep = outputContract?.contractRef === index_js_2.LOOP_CONTROL_CONTRACT_REF;
-    const loopBanner = buildLoopContextBanner({ loopPath: args.loopPath, isExitStep });
+    const maxIterations = resolveParentLoopMaxIterations(args.workflow, args.stepId);
+    const loopBanner = buildLoopContextBanner({ loopPath: args.loopPath, isExitStep, maxIterations });
     const validationCriteria = step.validationCriteria;
     const requirements = (0, validation_requirements_extractor_js_1.extractValidationRequirements)(validationCriteria);
     const requirementsSection = requirements.length > 0

package/dist/v2/durable-core/schemas/artifacts/loop-control.d.ts

@@ -63,4 +63,4 @@ export declare const LoopControlArtifactV1Schema: z.ZodObject<{
 export type LoopControlArtifactV1 = z.infer<typeof LoopControlArtifactV1Schema>;
 export declare function isLoopControlArtifact(artifact: unknown): artifact is LoopControlArtifactV1;
 export declare function parseLoopControlArtifact(artifact: unknown): LoopControlArtifactV1 | null;
-export declare function findLoopControlArtifact(artifacts: readonly unknown[], expectedLoopId: string): LoopControlArtifactV1 | null;
+export declare function findLoopControlArtifact(artifacts: readonly unknown[]): LoopControlArtifactV1 | null;

package/dist/v2/durable-core/schemas/artifacts/loop-control.js

@@ -35,17 +35,14 @@ function parseLoopControlArtifact(artifact) {
     const result = exports.LoopControlArtifactV1Schema.safeParse(artifact);
     return result.success ? result.data : null;
 }
-function findLoopControlArtifact(artifacts, expectedLoopId) {
+function findLoopControlArtifact(artifacts) {
     for (let i = artifacts.length - 1; i >= 0; i--) {
         const artifact = artifacts[i];
         if (!isLoopControlArtifact(artifact))
             continue;
         const parsed = parseLoopControlArtifact(artifact);
-        if (!parsed)
-            continue;
-        if (parsed.loopId === undefined || parsed.loopId === expectedLoopId) {
+        if (parsed)
             return parsed;
-        }
     }
     return null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "1.17.0",
+  "version": "2.0.0",
   "description": "Step-by-step workflow enforcement for AI agents via MCP",
   "license": "MIT",
   "repository": {

package/workflows/bug-investigation.agentic.v2.json

@@ -105,7 +105,7 @@
         {
           "id": "phase-4b-loop-decision",
           "title": "Evidence Loop Decision",
-          "prompt": "Decide whether the evidence loop should continue.\n\nDecision rules:\n- if `contradictionCount > 0` → continue\n- else if `unresolvedEvidenceGapCount > 0` → continue\n- else if `hasStrongAlternative = true` and the alternative is not meaningfully weaker → continue\n- else if `diagnosisType = inconclusive_but_narrowed` and further evidence is not realistically available → stop with bounded uncertainty\n- else → stop\n\nOutput exactly:\n```json\n{\n  \"artifacts\": [{\n    \"kind\": \"wr.loop_control\",\n    \"loopId\": \"bug_evidence_loop\",\n    \"decision\": \"continue\"\n  }]\n}\n```",
+          "prompt": "Decide whether the evidence loop should continue.\n\nDecision rules:\n- if `contradictionCount > 0` → continue\n- else if `unresolvedEvidenceGapCount > 0` → continue\n- else if `hasStrongAlternative = true` and the alternative is not meaningfully weaker → continue\n- else if `diagnosisType = inconclusive_but_narrowed` and further evidence is not realistically available → stop with bounded uncertainty\n- else → stop\n\nOutput exactly:\n```json\n{\n  \"artifacts\": [{\n    \"kind\": \"wr.loop_control\",\n    \"decision\": \"continue\"\n  }]\n}\n```",
           "requireConfirmation": true,
           "outputContract": {
             "contractRef": "wr.contracts.loop_control"

package/workflows/coding-task-workflow-agentic.v2.json

@@ -139,7 +139,7 @@
         {
           "id": "phase-4c-loop-decision",
           "title": "Loop Exit Decision",
-          "prompt": "Provide a loop control artifact.\n\nDecision rules:\n- if `planFindings` is non-empty → continue\n- if `planFindings` is empty → stop, but enumerate what was checked to justify the clean pass\n- if max iterations reached → stop and document remaining concerns\n\nOutput exactly:\n```json\n{\n  \"artifacts\": [{\n    \"kind\": \"wr.loop_control\",\n    \"loopId\": \"plan_audit_loop\",\n    \"decision\": \"continue\"\n  }]\n}\n```",
+          "prompt": "Provide a loop control artifact.\n\nDecision rules:\n- if `planFindings` is non-empty → continue\n- if `planFindings` is empty → stop, but enumerate what was checked to justify the clean pass\n- if max iterations reached → stop and document remaining concerns\n\nOutput exactly:\n```json\n{\n  \"artifacts\": [{\n    \"kind\": \"wr.loop_control\",\n    \"decision\": \"continue\"\n  }]\n}\n```",
           "requireConfirmation": true,
           "outputContract": {
             "contractRef": "wr.contracts.loop_control"

package/workflows/mr-review-workflow.agentic.v2.json

@@ -188,7 +188,7 @@
         {
           "id": "phase-4c-loop-decision",
           "title": "Synthesis Loop Decision",
-          "prompt": "Decide whether the synthesis loop should continue.\n\nDecision rules:\n- if `contradictionCount > 0` → continue\n- else if `coverageUncertainCount > 0` and the uncertainty materially affects the recommendation → continue\n- else if `falsePositiveRiskCount > 0` → continue\n- else if `recommendationDriftDetected = true` → continue\n- else → stop\n\nOutput exactly:\n```json\n{\n  \"artifacts\": [{\n    \"kind\": \"wr.loop_control\",\n    \"loopId\": \"mr_review_synthesis_loop\",\n    \"decision\": \"continue\"\n  }]\n}\n```",
+          "prompt": "Decide whether the synthesis loop should continue.\n\nDecision rules:\n- if `contradictionCount > 0` → continue\n- else if `coverageUncertainCount > 0` and the uncertainty materially affects the recommendation → continue\n- else if `falsePositiveRiskCount > 0` → continue\n- else if `recommendationDriftDetected = true` → continue\n- else → stop\n\nOutput exactly:\n```json\n{\n  \"artifacts\": [{\n    \"kind\": \"wr.loop_control\",\n    \"decision\": \"continue\"\n  }]\n}\n```",
           "requireConfirmation": true,
           "outputContract": {
             "contractRef": "wr.contracts.loop_control"

package/workflows/test-artifact-loop-control.json

@@ -13,7 +13,7 @@
     {
       "id": "init-loop",
       "title": "Initialize Loop",
-      "prompt": "Initialize the bounded iteration loop.\n\n**Provide a loop control artifact:**\n```json\n{\n  \"artifacts\": [{\n    \"kind\": \"wr.loop_control\",\n    \"loopId\": \"test-iteration\",\n    \"decision\": \"continue\",\n    \"metadata\": {\n      \"reason\": \"Starting iteration loop\"\n    }\n  }]\n}\n```\n\nThe artifact must have:\n- kind: 'wr.loop_control'\n- loopId: 'test-iteration' (lowercase with hyphens)\n- decision: 'continue' or 'stop'",
+      "prompt": "Initialize the bounded iteration loop.\n\n**Provide a loop control artifact:**\n```json\n{\n  \"artifacts\": [{\n    \"kind\": \"wr.loop_control\",\n    \"decision\": \"continue\",\n    \"metadata\": {\n      \"reason\": \"Starting iteration loop\"\n    }\n  }]\n}\n```\n\nThe artifact must have:\n- kind: 'wr.loop_control'\n- decision: 'continue' or 'stop'",
       "requireConfirmation": false,
       "outputContract": {
         "contractRef": "wr.contracts.loop_control"
@@ -42,7 +42,7 @@
         {
           "id": "decide-continue",
           "title": "Loop Decision",
-          "prompt": "Decide whether to continue or stop the loop.\n\n**Provide a loop control artifact:**\n```json\n{\n  \"artifacts\": [{\n    \"kind\": \"wr.loop_control\",\n    \"loopId\": \"test-iteration\",\n    \"decision\": \"continue\",\n    \"metadata\": {\n      \"reason\": \"More work needed\",\n      \"iterationIndex\": 1\n    }\n  }]\n}\n```\n\n**Decision logic:**\n- If more work is needed: decision = 'continue'\n- If work is complete: decision = 'stop'\n\nThe artifact must have:\n- kind: 'wr.loop_control'\n- loopId: 'test-iteration'\n- decision: 'continue' or 'stop'",
+          "prompt": "Decide whether to continue or stop the loop.\n\n**Provide a loop control artifact:**\n```json\n{\n  \"artifacts\": [{\n    \"kind\": \"wr.loop_control\",\n    \"decision\": \"continue\",\n    \"metadata\": {\n      \"reason\": \"More work needed\",\n      \"iterationIndex\": 1\n    }\n  }]\n}\n```\n\n**Decision logic:**\n- If more work is needed: decision = 'continue'\n- If work is complete: decision = 'stop'\n\nThe artifact must have:\n- kind: 'wr.loop_control'\n- decision: 'continue' or 'stop'",
           "requireConfirmation": true,
           "outputContract": {
             "contractRef": "wr.contracts.loop_control"

package/workflows/workflow-for-workflows.json

@@ -89,7 +89,7 @@
                 {
                     "id": "discovery-loop-decision",
                     "title": "Discovery Loop Decision",
-                    "prompt": "**Provide a loop control decision artifact.**\n\nBased on the discovery analysis above, decide whether to continue gathering requirements or proceed to synthesis.\n\n**Decision logic:**\n- If critical information is still missing (problem unclear, user needs undefined, success criteria absent): decision = 'continue'\n- If discovery is 80%+ complete (clear problem, user needs, success criteria, basic constraints): decision = 'stop'\n\n**Output (exact format):**\nProvide a loop control artifact:\n```json\n{\n  \"artifacts\": [{\n    \"kind\": \"wr.loop_control\",\n    \"loopId\": \"phase-0-discovery-loop\",\n    \"decision\": \"continue\",\n    \"metadata\": {\n      \"reason\": \"One sentence explaining why continuing or stopping\"\n    }\n  }]\n}\n```",
+                    "prompt": "**Provide a loop control decision artifact.**\n\nBased on the discovery analysis above, decide whether to continue gathering requirements or proceed to synthesis.\n\n**Decision logic:**\n- If critical information is still missing (problem unclear, user needs undefined, success criteria absent): decision = 'continue'\n- If discovery is 80%+ complete (clear problem, user needs, success criteria, basic constraints): decision = 'stop'\n\n**Output (exact format):**\nProvide a loop control artifact:\n```json\n{\n  \"artifacts\": [{\n    \"kind\": \"wr.loop_control\",\n    \"decision\": \"continue\",\n    \"metadata\": {\n      \"reason\": \"One sentence explaining why continuing or stopping\"\n    }\n  }]\n}\n```",
                     "agentRole": "You are a discovery analyst making an explicit go/no-go decision on whether enough requirements have been gathered.",
                     "requireConfirmation": false,
                     "outputContract": {
@@ -418,7 +418,7 @@
         {
             "id": "satisfaction-check",
             "title": "Iteration Satisfaction Check & Loop Decision",
-            "prompt": "Let's assess your satisfaction with the workflow so far.\n\n**Rate your satisfaction (1-10):**\n- 10: Perfect! Ready to deploy\n- 8-9: Very good, minor tweaks only\n- 6-7: Good foundation, needs refinement\n- 4-5: Major improvements needed\n- 1-3: Significant rework required\n\n**Decision logic:**\n- Score 9+: decision = 'stop' (proceed to completion)\n- Score <9: decision = 'continue' (iterate again, up to 3 times total)\n\nAgent: Set context.satisfactionScore and increment context.iterationCount.\n\n**Provide a loop control artifact:**\n```json\n{\n  \"artifacts\": [{\n    \"kind\": \"wr.loop_control\",\n    \"loopId\": \"phase-3-4-refinement-loop\",\n    \"decision\": \"continue\",\n    \"metadata\": {\n      \"reason\": \"Satisfaction score X/10 - [brief reason]\"\n    }\n  }]\n}\n```",
+            "prompt": "Let's assess your satisfaction with the workflow so far.\n\n**Rate your satisfaction (1-10):**\n- 10: Perfect! Ready to deploy\n- 8-9: Very good, minor tweaks only\n- 6-7: Good foundation, needs refinement\n- 4-5: Major improvements needed\n- 1-3: Significant rework required\n\n**Decision logic:**\n- Score 9+: decision = 'stop' (proceed to completion)\n- Score <9: decision = 'continue' (iterate again, up to 3 times total)\n\nAgent: Set context.satisfactionScore and increment context.iterationCount.\n\n**Provide a loop control artifact:**\n```json\n{\n  \"artifacts\": [{\n    \"kind\": \"wr.loop_control\",\n    \"decision\": \"continue\",\n    \"metadata\": {\n      \"reason\": \"Satisfaction score X/10 - [brief reason]\"\n    }\n  }]\n}\n```",
             "agentRole": "You are a quality assessment specialist. Guide the user through evaluating their workflow objectively. Provide a loop control artifact with the decision.",
             "requireConfirmation": false,
             "outputContract": {