@exaudeus/workrail 1.1.0 → 1.3.0

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:",

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

@@ -0,0 +1,59 @@
+{
+  "id": "test-artifact-loop-control",
+  "name": "Test Artifact Loop Control",
+  "description": "Test workflow demonstrating typed artifact loop control (Phase 3 migration pattern)",
+  "version": "1.0.0",
+  "metaGuidance": [
+    "This workflow demonstrates the new artifact-based loop control pattern.",
+    "Instead of prose validation (checking for 'continuePlanning = true' in text),",
+    "agents provide structured artifacts with typed decisions.",
+    "VARIABLE TYPES: Booleans: loopShouldContinue (derived from artifact, not prose)."
+  ],
+  "steps": [
+    {
+      "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'",
+      "requireConfirmation": false,
+      "outputContract": {
+        "contractRef": "wr.contracts.loop_control"
+      }
+    },
+    {
+      "id": "iteration-loop",
+      "type": "loop",
+      "title": "Iteration Loop",
+      "loop": {
+        "type": "while",
+        "condition": {
+          "var": "loopShouldContinue",
+          "equals": true
+        },
+        "maxIterations": 3
+      },
+      "body": [
+        {
+          "id": "do-work",
+          "title": "Do Iteration Work",
+          "prompt": "Perform work for this iteration.\n\nDescribe what you're doing this iteration.",
+          "requireConfirmation": false
+        },
+        {
+          "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'",
+          "requireConfirmation": true,
+          "outputContract": {
+            "contractRef": "wr.contracts.loop_control"
+          }
+        }
+      ]
+    },
+    {
+      "id": "complete",
+      "title": "Complete",
+      "prompt": "The iteration loop has completed. Summarize what was accomplished.",
+      "requireConfirmation": false
+    }
+  ]
+}