@exaudeus/workrail 1.0.0 → 1.2.0

package/dist/v2/durable-core/schemas/session/validation-event.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationPerformedDataV1Schema = exports.ValidationPerformedResultV1Schema = void 0;
+const zod_1 = require("zod");
+const constants_js_1 = require("../../constants.js");
+const utf8_bounded_string_js_1 = require("../lib/utf8-bounded-string.js");
+function utf8ByteLength(s) {
+    return new TextEncoder().encode(s).length;
+}
+const ValidationIssueV1Schema = (0, utf8_bounded_string_js_1.utf8BoundedString)({
+    label: 'validation issue',
+    minLength: 1,
+    maxBytes: 512,
+});
+const ValidationSuggestionV1Schema = (0, utf8_bounded_string_js_1.utf8BoundedString)({
+    label: 'validation suggestion',
+    minLength: 1,
+    maxBytes: 1024,
+});
+exports.ValidationPerformedResultV1Schema = zod_1.z
+    .object({
+    valid: zod_1.z.boolean(),
+    issues: zod_1.z.array(ValidationIssueV1Schema).readonly(),
+    suggestions: zod_1.z.array(ValidationSuggestionV1Schema).readonly(),
+})
+    .strict()
+    .superRefine((v, ctx) => {
+    const issuesBytes = v.issues.reduce((sum, s) => sum + utf8ByteLength(s), 0);
+    if (issuesBytes > constants_js_1.MAX_VALIDATION_ISSUES_BYTES) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: `validation issues exceed ${constants_js_1.MAX_VALIDATION_ISSUES_BYTES} bytes (UTF-8)`,
+            path: ['issues'],
+        });
+    }
+    const suggestionsBytes = v.suggestions.reduce((sum, s) => sum + utf8ByteLength(s), 0);
+    if (suggestionsBytes > constants_js_1.MAX_VALIDATION_SUGGESTIONS_BYTES) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: `validation suggestions exceed ${constants_js_1.MAX_VALIDATION_SUGGESTIONS_BYTES} bytes (UTF-8)`,
+            path: ['suggestions'],
+        });
+    }
+});
+exports.ValidationPerformedDataV1Schema = zod_1.z
+    .object({
+    validationId: zod_1.z.string().min(1),
+    attemptId: zod_1.z.string().min(1),
+    contractRef: zod_1.z.string().min(1),
+    result: exports.ValidationPerformedResultV1Schema,
+})
+    .strict();

package/dist/v2/durable-core/tokens/payloads.d.ts

@@ -55,22 +55,22 @@ export declare const AckTokenPayloadV1Schema: z.ZodObject<{
     sessionId: string & {
         readonly __brand: "v2.SessionId";
     };
+    attemptId: string & {
+        readonly __brand: "v2.AttemptId";
+    };
     runId: string & {
         readonly __brand: "v2.RunId";
     };
     nodeId: string & {
         readonly __brand: "v2.NodeId";
     };
-    attemptId: string & {
-        readonly __brand: "v2.AttemptId";
-    };
     tokenVersion: 1;
     tokenKind: "ack";
 }, {
     sessionId: string;
+    attemptId: string;
     runId: string;
     nodeId: string;
-    attemptId: string;
     tokenVersion: 1;
     tokenKind: "ack";
 }>;
@@ -93,22 +93,22 @@ export declare const CheckpointTokenPayloadV1Schema: z.ZodObject<{
     sessionId: string & {
         readonly __brand: "v2.SessionId";
     };
+    attemptId: string & {
+        readonly __brand: "v2.AttemptId";
+    };
     runId: string & {
         readonly __brand: "v2.RunId";
     };
     nodeId: string & {
         readonly __brand: "v2.NodeId";
     };
-    attemptId: string & {
-        readonly __brand: "v2.AttemptId";
-    };
     tokenVersion: 1;
     tokenKind: "checkpoint";
 }, {
     sessionId: string;
+    attemptId: string;
     runId: string;
     nodeId: string;
-    attemptId: string;
     tokenVersion: 1;
     tokenKind: "checkpoint";
 }>;
@@ -160,22 +160,22 @@ export declare const TokenPayloadV1Schema: z.ZodDiscriminatedUnion<"tokenKind",
     sessionId: string & {
         readonly __brand: "v2.SessionId";
     };
+    attemptId: string & {
+        readonly __brand: "v2.AttemptId";
+    };
     runId: string & {
         readonly __brand: "v2.RunId";
     };
     nodeId: string & {
         readonly __brand: "v2.NodeId";
     };
-    attemptId: string & {
-        readonly __brand: "v2.AttemptId";
-    };
     tokenVersion: 1;
     tokenKind: "ack";
 }, {
     sessionId: string;
+    attemptId: string;
     runId: string;
     nodeId: string;
-    attemptId: string;
     tokenVersion: 1;
     tokenKind: "ack";
 }>, z.ZodObject<{
@@ -189,22 +189,22 @@ export declare const TokenPayloadV1Schema: z.ZodDiscriminatedUnion<"tokenKind",
     sessionId: string & {
         readonly __brand: "v2.SessionId";
     };
+    attemptId: string & {
+        readonly __brand: "v2.AttemptId";
+    };
     runId: string & {
         readonly __brand: "v2.RunId";
     };
     nodeId: string & {
         readonly __brand: "v2.NodeId";
     };
-    attemptId: string & {
-        readonly __brand: "v2.AttemptId";
-    };
     tokenVersion: 1;
     tokenKind: "checkpoint";
 }, {
     sessionId: string;
+    attemptId: string;
     runId: string;
     nodeId: string;
-    attemptId: string;
     tokenVersion: 1;
     tokenKind: "checkpoint";
 }>]>;

package/dist/v2/infra/local/workspace-anchor/index.d.ts

@@ -0,0 +1,9 @@
+import { ResultAsync as RA } from 'neverthrow';
+import type { WorkspaceAnchorPortV2, WorkspaceAnchor, WorkspaceAnchorError } from '../../../ports/workspace-anchor.port.js';
+export declare class LocalWorkspaceAnchorV2 implements WorkspaceAnchorPortV2 {
+    private readonly cwd;
+    constructor(cwd: string);
+    resolveAnchors(): RA<readonly WorkspaceAnchor[], WorkspaceAnchorError>;
+    private resolve;
+    private gitCommand;
+}

package/dist/v2/infra/local/workspace-anchor/index.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalWorkspaceAnchorV2 = void 0;
+const neverthrow_1 = require("neverthrow");
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const execAsync = (0, util_1.promisify)(child_process_1.exec);
+class LocalWorkspaceAnchorV2 {
+    constructor(cwd) {
+        this.cwd = cwd;
+    }
+    resolveAnchors() {
+        return neverthrow_1.ResultAsync.fromPromise(this.resolve(), (cause) => ({
+            code: 'ANCHOR_RESOLVE_FAILED',
+            message: `Failed to resolve workspace anchors: ${String(cause)}`,
+        }));
+    }
+    async resolve() {
+        const anchors = [];
+        const branch = await this.gitCommand('git rev-parse --abbrev-ref HEAD');
+        if (branch && branch !== 'HEAD') {
+            anchors.push({ key: 'git_branch', value: branch });
+        }
+        const sha = await this.gitCommand('git rev-parse HEAD');
+        if (sha && /^[0-9a-f]{40}$/.test(sha)) {
+            anchors.push({ key: 'git_head_sha', value: sha });
+        }
+        return anchors;
+    }
+    async gitCommand(cmd) {
+        try {
+            const { stdout } = await execAsync(cmd, {
+                cwd: this.cwd,
+                timeout: 5000,
+                encoding: 'utf8',
+            });
+            return stdout.trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.LocalWorkspaceAnchorV2 = LocalWorkspaceAnchorV2;

package/dist/v2/ports/workspace-anchor.port.d.ts

@@ -0,0 +1,18 @@
+import type { ResultAsync } from 'neverthrow';
+export type WorkspaceAnchor = {
+    readonly key: 'git_branch';
+    readonly value: string;
+} | {
+    readonly key: 'git_head_sha';
+    readonly value: string;
+} | {
+    readonly key: 'repo_root_hash';
+    readonly value: string;
+};
+export type WorkspaceAnchorError = {
+    readonly code: 'ANCHOR_RESOLVE_FAILED';
+    readonly message: string;
+};
+export interface WorkspaceAnchorPortV2 {
+    resolveAnchors(): ResultAsync<readonly WorkspaceAnchor[], WorkspaceAnchorError>;
+}

package/dist/v2/ports/workspace-anchor.port.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/v2/projections/artifacts.d.ts

@@ -0,0 +1,22 @@
+import type { Result } from 'neverthrow';
+import type { DomainEventV1 } from '../durable-core/schemas/session/index.js';
+export type ArtifactProjectionError = {
+    readonly code: 'PROJECTION_INVARIANT_VIOLATION';
+    readonly message: string;
+};
+export interface ProjectedArtifactV2 {
+    readonly content: unknown;
+    readonly outputId: string;
+    readonly sha256: string;
+    readonly contentType: string;
+    readonly byteLength: number;
+    readonly createdAtEventIndex: number;
+}
+export interface NodeArtifactsViewV2 {
+    readonly artifacts: readonly ProjectedArtifactV2[];
+}
+export interface ArtifactsProjectionV2 {
+    readonly byNodeId: Readonly<Record<string, NodeArtifactsViewV2>>;
+}
+export declare function projectArtifactsV2(events: readonly DomainEventV1[]): Result<ArtifactsProjectionV2, ArtifactProjectionError>;
+export declare function getArtifactContentsForNode(projection: ArtifactsProjectionV2, nodeId: string): readonly unknown[];

package/dist/v2/projections/artifacts.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectArtifactsV2 = projectArtifactsV2;
+exports.getArtifactContentsForNode = getArtifactContentsForNode;
+const neverthrow_1 = require("neverthrow");
+function projectArtifactsV2(events) {
+    const byNodeId = {};
+    for (let i = 1; i < events.length; i++) {
+        if (events[i].eventIndex < events[i - 1].eventIndex) {
+            return (0, neverthrow_1.err)({
+                code: 'PROJECTION_INVARIANT_VIOLATION',
+                message: 'Events must be sorted by eventIndex ascending',
+            });
+        }
+    }
+    for (const e of events) {
+        if (e.kind !== 'node_output_appended')
+            continue;
+        if (e.data.outputChannel !== 'artifact')
+            continue;
+        const payload = e.data.payload;
+        if (payload.payloadKind !== 'artifact_ref')
+            continue;
+        const contentPayload = payload;
+        if (contentPayload.content === undefined)
+            continue;
+        const nodeId = e.scope?.nodeId;
+        if (!nodeId)
+            continue;
+        if (!byNodeId[nodeId]) {
+            byNodeId[nodeId] = { artifacts: [] };
+        }
+        byNodeId[nodeId].artifacts.push({
+            content: contentPayload.content,
+            outputId: e.data.outputId,
+            sha256: payload.sha256,
+            contentType: payload.contentType,
+            byteLength: payload.byteLength,
+            createdAtEventIndex: e.eventIndex,
+        });
+    }
+    const result = {};
+    for (const [nodeId, view] of Object.entries(byNodeId)) {
+        result[nodeId] = { artifacts: view.artifacts };
+    }
+    return (0, neverthrow_1.ok)({ byNodeId: result });
+}
+function getArtifactContentsForNode(projection, nodeId) {
+    const view = projection.byNodeId[nodeId];
+    if (!view)
+        return [];
+    return view.artifacts.map(a => a.content);
+}

package/dist/v2/projections/projection-timing.d.ts

@@ -0,0 +1,13 @@
+import type { Result } from 'neverthrow';
+export interface ProjectionTimingV2 {
+    readonly projectionName: string;
+    readonly eventCount: number;
+    readonly durationMs: number;
+}
+export type ProjectionTimingSink = (timing: ProjectionTimingV2) => void;
+export declare const noopTimingSink: ProjectionTimingSink;
+export declare function withProjectionTiming<E, T>(projectionName: string, fn: (events: readonly {
+    readonly eventIndex: number;
+}[]) => Result<T, E>, sink?: ProjectionTimingSink): (events: readonly {
+    readonly eventIndex: number;
+}[]) => Result<T, E>;

package/dist/v2/projections/projection-timing.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noopTimingSink = void 0;
+exports.withProjectionTiming = withProjectionTiming;
+const noopTimingSink = () => { };
+exports.noopTimingSink = noopTimingSink;
+function withProjectionTiming(projectionName, fn, sink = exports.noopTimingSink) {
+    return (events) => {
+        const start = performance.now();
+        const result = fn(events);
+        const durationMs = performance.now() - start;
+        try {
+            sink({
+                projectionName,
+                eventCount: events.length,
+                durationMs: Math.round(durationMs * 100) / 100,
+            });
+        }
+        catch {
+        }
+        return result;
+    };
+}

package/dist/v2/projections/run-context.d.ts

@@ -0,0 +1,22 @@
+import type { Result } from 'neverthrow';
+import type { DomainEventV1 } from '../durable-core/schemas/session/index.js';
+import type { JsonObject } from '../durable-core/canonical/json-types.js';
+import type { RunId } from '../durable-core/ids/index.js';
+export type ProjectionError = {
+    readonly code: 'PROJECTION_INVARIANT_VIOLATION';
+    readonly message: string;
+} | {
+    readonly code: 'PROJECTION_CORRUPTION_DETECTED';
+    readonly message: string;
+};
+export interface RunContextV2 {
+    readonly runId: RunId;
+    readonly context: JsonObject;
+    readonly contextId: string;
+    readonly source: 'initial' | 'agent_delta';
+    readonly setAtEventIndex: number;
+}
+export interface RunContextProjectionV2 {
+    readonly byRunId: Readonly<Record<string, RunContextV2>>;
+}
+export declare function projectRunContextV2(events: readonly DomainEventV1[]): Result<RunContextProjectionV2, ProjectionError>;

package/dist/v2/projections/run-context.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectRunContextV2 = projectRunContextV2;
+const neverthrow_1 = require("neverthrow");
+const index_js_1 = require("../durable-core/ids/index.js");
+function projectRunContextV2(events) {
+    for (let i = 1; i < events.length; i++) {
+        if (events[i].eventIndex < events[i - 1].eventIndex) {
+            return (0, neverthrow_1.err)({ code: 'PROJECTION_INVARIANT_VIOLATION', message: 'Events must be sorted by eventIndex ascending' });
+        }
+    }
+    const byRunId = {};
+    for (const e of events) {
+        if (e.kind !== 'context_set')
+            continue;
+        const runId = e.scope.runId;
+        const context = e.data.context;
+        if (!context || typeof context !== 'object' || Array.isArray(context)) {
+            return (0, neverthrow_1.err)({
+                code: 'PROJECTION_CORRUPTION_DETECTED',
+                message: `context_set event has invalid context type (runId=${runId}, eventId=${e.eventId})`,
+            });
+        }
+        byRunId[runId] = {
+            runId: (0, index_js_1.asRunId)(runId),
+            context: context,
+            contextId: e.data.contextId,
+            source: e.data.source,
+            setAtEventIndex: e.eventIndex,
+        };
+    }
+    return (0, neverthrow_1.ok)({ byRunId });
+}

package/dist/v2/projections/run-dag.d.ts

@@ -1,6 +1,6 @@
 import type { Result } from 'neverthrow';
 import type { DomainEventV1 } from '../durable-core/schemas/session/index.js';
-export type NodeKindV2 = 'step' | 'checkpoint';
+export type NodeKindV2 = 'step' | 'checkpoint' | 'blocked_attempt';
 export type EdgeKindV2 = 'acked_step' | 'checkpoint';
 export type ProjectionError = {
     readonly code: 'PROJECTION_INVARIANT_VIOLATION';

package/dist/v2/projections/run-status-signals.js

@@ -4,7 +4,6 @@ exports.projectRunStatusSignalsV2 = projectRunStatusSignalsV2;
 const neverthrow_1 = require("neverthrow");
 const run_dag_js_1 = require("./run-dag.js");
 const gaps_js_1 = require("./gaps.js");
-const advance_outcomes_js_1 = require("./advance-outcomes.js");
 function projectRunStatusSignalsV2(events) {
     const dagRes = (0, run_dag_js_1.projectRunDagV2)(events);
     if (dagRes.isErr())
@@ -14,10 +13,6 @@ function projectRunStatusSignalsV2(events) {
     if (gapsRes.isErr())
         return (0, neverthrow_1.err)(gapsRes.error);
     const gaps = gapsRes.value;
-    const advanceRes = (0, advance_outcomes_js_1.projectAdvanceOutcomesV2)(events);
-    if (advanceRes.isErr())
-        return (0, neverthrow_1.err)(advanceRes.error);
-    const advances = advanceRes.value;
     const prefsByNodeId = {};
     for (const e of events) {
         if (e.kind !== 'preferences_changed')
@@ -34,9 +29,9 @@ function projectRunStatusSignalsV2(events) {
         const hasBlockingCategoryGap = (gaps.unresolvedCriticalByRunId[runId] ?? []).some((g) => g.reason.category === 'user_only_dependency' ||
             g.reason.category === 'contract_violation' ||
             g.reason.category === 'capability_missing');
-        const latestAdvance = tip ? advances.byNodeId[tip] : undefined;
-        const blockedByAdvance = latestAdvance?.outcome.kind === 'blocked';
-        const isBlocked = prefs.autonomy !== 'full_auto_never_stop' && (blockedByAdvance || hasBlockingCategoryGap);
+        const tipNodeKind = tip ? run.nodesById[tip]?.nodeKind : undefined;
+        const blockedByTopology = tipNodeKind === 'blocked_attempt';
+        const isBlocked = prefs.autonomy !== 'full_auto_never_stop' && (blockedByTopology || hasBlockingCategoryGap);
         byRunId[runId] = {
             runId,
             preferredTipNodeId: tip,

package/package.json

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

package/spec/workflow.schema.json

@@ -107,6 +107,23 @@
         "additionalProperties": false
       },
       "uniqueItems": true
+    },
+    "recommendedPreferences": {
+      "type": "object",
+      "description": "Workflow-level preference recommendations. When effective preferences exceed these, structured warnings are emitted. Never hard-blocks user choice.",
+      "properties": {
+        "recommendedAutonomy": {
+          "type": "string",
+          "enum": ["guided", "full_auto_stop_on_user_deps", "full_auto_never_stop"],
+          "description": "Recommended autonomy level for this workflow"
+        },
+        "recommendedRiskPolicy": {
+          "type": "string",
+          "enum": ["conservative", "balanced", "aggressive"],
+          "description": "Recommended risk policy for this workflow"
+        }
+      },
+      "additionalProperties": false
     }
   },
   "required": [
@@ -169,6 +186,7 @@
         "requireConfirmation": { "$ref": "#/$defs/confirmationRule" },
         "runCondition": { "$ref": "#/$defs/condition" },
         "validationCriteria": { "oneOf": [ { "type": "array", "items": { "$ref": "#/$defs/validationRule" } }, { "$ref": "#/$defs/validationComposition" } ] },
+        "outputContract": { "$ref": "#/$defs/outputContract" },
         "functionDefinitions": { "type": "array", "items": { "$ref": "#/$defs/functionDefinition" } },
         "functionCalls": { "type": "array", "items": { "$ref": "#/$defs/functionCall" } },
         "functionReferences": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*\\(\\)$" } }
@@ -286,6 +304,30 @@
           "type": "string",
           "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
           "description": "Custom variable name for current index (forEach loops)"
+        },
+        "conditionSource": {
+          "description": "Explicit condition source for while/until loops. Auto-derived by compiler when absent.",
+          "oneOf": [
+            {
+              "type": "object",
+              "properties": {
+                "kind": { "const": "artifact_contract" },
+                "contractRef": { "type": "string", "minLength": 1 },
+                "loopId": { "type": "string", "minLength": 1 }
+              },
+              "required": ["kind", "contractRef", "loopId"],
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "kind": { "const": "context_variable" },
+                "condition": { "$ref": "#/$defs/condition" }
+              },
+              "required": ["kind", "condition"],
+              "additionalProperties": false
+            }
+          ]
         }
       },
       "required": ["type", "maxIterations"],
@@ -516,6 +558,24 @@
         }
       ]
     },
+    "outputContract": {
+      "type": "object",
+      "description": "Typed output contract declaring required artifact schema",
+      "properties": {
+        "contractRef": {
+          "type": "string",
+          "description": "Artifact contract reference (e.g. wr.contracts.loop_control)",
+          "minLength": 1
+        },
+        "required": {
+          "type": "boolean",
+          "description": "Whether the artifact is required (default true)",
+          "default": true
+        }
+      },
+      "required": ["contractRef"],
+      "additionalProperties": false
+    },
     "functionCall": {
       "type": "object",
       "properties": {

package/spec/workflow.schema.v0.0.1.json

@@ -223,6 +223,9 @@
                 "$ref": "#/$defs/validationComposition"
               }
             ]
+          },
+          "outputContract": {
+            "$ref": "#/$defs/outputContract"
           }
         },
         "required": [
@@ -243,6 +246,23 @@
         "maxLength": 256
       },
       "uniqueItems": true
+    },
+    "recommendedPreferences": {
+      "type": "object",
+      "description": "Workflow-level preference recommendations. When effective preferences exceed these, structured warnings are emitted. Never hard-blocks user choice.",
+      "properties": {
+        "recommendedAutonomy": {
+          "type": "string",
+          "enum": ["guided", "full_auto_stop_on_user_deps", "full_auto_never_stop"],
+          "description": "Recommended autonomy level for this workflow"
+        },
+        "recommendedRiskPolicy": {
+          "type": "string",
+          "enum": ["conservative", "balanced", "aggressive"],
+          "description": "Recommended risk policy for this workflow"
+        }
+      },
+      "additionalProperties": false
     }
   },
   "required": [
@@ -388,6 +408,24 @@
           "$ref": "#/$defs/validationComposition"
         }
       ]
+    },
+    "outputContract": {
+      "type": "object",
+      "description": "Typed output contract declaring required artifact schema",
+      "properties": {
+        "contractRef": {
+          "type": "string",
+          "description": "Artifact contract reference (e.g. wr.contracts.loop_control)",
+          "minLength": 1
+        },
+        "required": {
+          "type": "boolean",
+          "description": "Whether the artifact is required (default true)",
+          "default": true
+        }
+      },
+      "required": ["contractRef"],
+      "additionalProperties": false
     }
   }
 }

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

@@ -1,8 +1,12 @@
 {
   "id": "coding-task-workflow-agentic",
   "name": "Agentic Task Dev Workflow (Invariants • Architecture • Vertical Slices • PR Sizing • Audits • Resumable)",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Coding workflow that explores multiple approaches before committing—avoids anchoring on the first idea. Flow: constraints → approaches → compare → decide → slices → verify. Use when getting it right matters.",
+  "recommendedPreferences": {
+    "recommendedAutonomy": "guided",
+    "recommendedRiskPolicy": "conservative"
+  },
   "preconditions": [
     "User provides a task description (ticket text or equivalent) and success criteria (even if partial).",
     "Agent has read access to the codebase and can use tools (search/read/edit/terminal).",
@@ -283,17 +287,8 @@
         "var": "taskComplexity",
         "not_equals": "Small"
       },
-      "prompt": "Initialize a bounded plan-iteration loop.\n\n**Set (required):** `continuePlanning = true`.\n\nRule: max 5 iterations. Continue while issues are found; stop when a pass is clean (no findings).",
-      "requireConfirmation": false,
-      "validationCriteria": {
-        "and": [
-          {
-            "type": "contains",
-            "value": "continuePlanning = true",
-            "message": "Must explicitly set: continuePlanning = true (otherwise the planning loop may not run)"
-          }
-        ]
-      }
+      "prompt": "Initialize a bounded plan-iteration loop.\n\nRule: max 5 iterations. Continue while issues are found; stop when a pass is clean (no findings).\n\nThe loop will enter automatically. The exit decision step inside the loop will use a typed artifact to control continuation.",
+      "requireConfirmation": false
     },
     {
       "id": "phase-5-plan-iterations",
@@ -344,15 +339,13 @@
         {
           "id": "phase-5d-loop-exit-decision",
           "title": "Loop Exit Decision (Fail-Safe)",
-          "prompt": "**Non-optional:** prevent forgotten `continuePlanning` updates.\n\n**Output (exact format):**\n- `continuePlanning`: true|false\n- `reason`: one sentence\n- `whatChangedSinceLastIteration`: 1–3 bullets\n\n**Loop continuation logic (continue while issues found):**\n\n- If `planFindings` is **NON-EMPTY** (issues found this pass):\n  → Set `continuePlanning = true`\n  → Rationale: Amendments need verification; may have introduced new issues\n\n- If `planFindings` is **EMPTY** (clean pass):\n  → Set `continuePlanning = false`\n  → Rationale: Plan is stable, no more issues to find\n\n**Max iterations (5) still applies** — if you've hit 5 iterations and still finding issues, exit anyway and note remaining concerns.\n\n**Override to exit early:**\n- User explicitly requests to proceed\n- All findings are Minor AND `planConfidence >= 8`\n\nIf continuing, name what was found + what changes next iteration.\n\n**CONTEXT LOGGING:** Update CONTEXT.md Decision Log (follow format from metaGuidance) and update Machine State Checkpoint (keep last 3).\n\n**Set:** `continuePlanning`",
+          "prompt": "**Non-optional:** Provide a loop control decision artifact.\n\n**Output (exact format):**\n- Loop control artifact with decision: continue or stop\n- `reason`: one sentence\n- `whatChangedSinceLastIteration`: 1–3 bullets\n\n**Loop continuation logic (continue while issues found):**\n\n- If `planFindings` is **NON-EMPTY** (issues found this pass):\n  → decision: continue\n  → Rationale: Amendments need verification; may have introduced new issues\n\n- If `planFindings` is **EMPTY** (clean pass):\n  → decision: stop\n  → Rationale: Plan is stable, no more issues to find\n\n**Max iterations (5) still applies** — if you've hit 5 iterations and still finding issues, exit anyway and note remaining concerns.\n\n**Override to exit early:**\n- User explicitly requests to proceed\n- All findings are Minor AND `planConfidence >= 8`\n\nIf continuing, name what was found + what changes next iteration.\n\n**CONTEXT LOGGING:** Update CONTEXT.md Decision Log (follow format from metaGuidance) and update Machine State Checkpoint (keep last 3).",
           "requireConfirmation": true,
+          "outputContract": {
+            "contractRef": "wr.contracts.loop_control"
+          },
           "validationCriteria": {
             "and": [
-              {
-                "type": "contains",
-                "value": "continuePlanning",
-                "message": "Must explicitly set: continuePlanning = true or false"
-              },
               {
                 "type": "contains",
                 "value": "reason:",