@exaudeus/workrail 3.27.0 → 3.29.0

package/workflows/workflow-for-workflows.v2.json

@@ -32,7 +32,7 @@
     "BASELINE DISCIPLINE: choose both an authoring baseline and an outcome baseline whenever possible. Copy structural patterns, not domain language.",
     "VALIDATION GATE: validate with real validators, not regex approximations. When validator output and authoring assumptions conflict, runtime wins.",
     "DEEP REVIEW: authoring integrity and outcome effectiveness are separate concerns. A workflow is not ready unless both pass.",
-    "THOROUGH MODE: for complex or high-trust workflow work, prefer the deepest review path: state economy audit, execution simulation, adversarial review, and redesign if hard gates fail.",
+    "RIGOR: always run the deepest review path -- state economy audit, execution simulation, adversarial review, and redesign if hard gates fail. There is no reduced-rigor mode.",
     "ARTIFACT STRATEGY: the workflow JSON file is the primary output. Intermediate notes go in output.notesMarkdown. Do not create extra planning artifacts unless the workflow is genuinely complex.",
     "V2 DURABILITY: use output.notesMarkdown as the primary durable record. Do not mirror execution state into CONTEXT.md or markdown checkpoint files.",
     "ANTI-PATTERNS TO AVOID IN AUTHORED WORKFLOWS: no pseudo-function metaGuidance, no learning-path branching, no satisfaction-score loops, no heavy clarification batteries, no regex-as-primary-validation, no celebration phases.",
@@ -70,7 +70,7 @@
       "id": "authoring-guide-v2",
       "title": "Workflow Authoring Guide (v2)",
       "source": "docs/authoring-v2.md",
-      "resolveFrom": "workspace",
+      "resolveFrom": "package",
       "purpose": "Current v2 authoring principles, references guidance, and durable execution patterns.",
       "authoritative": true
     },
@@ -78,7 +78,7 @@
       "id": "workflow-authoring-reference",
       "title": "Workflow Authoring Reference",
       "source": "docs/design/workflow-authoring-v2.md",
-      "resolveFrom": "workspace",
+      "resolveFrom": "package",
       "purpose": "Detailed v2 workflow authoring patterns for loops, conditions, references, and workflow structure.",
       "authoritative": true
     },
@@ -86,7 +86,7 @@
       "id": "routines-guide",
       "title": "Routines Guide",
       "source": "docs/design/routines-guide.md",
-      "resolveFrom": "workspace",
+      "resolveFrom": "package",
       "purpose": "Current guide for deciding when to use delegation, direct execution, or template injection in authored workflows.",
       "authoritative": false
     },
@@ -141,23 +141,38 @@
         ],
         "procedure": [
           "Read the schema, authoring spec, v2 authoring guides, and the strongest relevant example workflows.",
-          "Decide `authoringMode`: `create` or `modernize_existing`.",
           "Classify the target workflow archetype: `review_audit`, `coding_execution`, `diagnostic_investigation`, `planning_design`, `linear_operational`, or `content_analysis`.",
-          "Classify `workflowComplexity`: Simple, Medium, or Complex. Classify `rigorMode`: QUICK, STANDARD, or THOROUGH.",
-          "Choose an `authoringBaseline` for engine-native authoring quality and an `outcomeBaseline` for the kind of job the authored workflow should perform. If no good baseline exists for one of them, set it to `none` and explain why.",
-          "If `authoringMode = modernize_existing`, build a value inventory BEFORE forming opinions about what to change. Read the original and classify each meaningful mechanism: (1) enforcement mechanisms (forcing functions, hard gates, required outputs), (2) domain knowledge (problem-specific principles the agent would not otherwise know), (3) behavioral rules (persistent constraints on how the agent works). This inventory is the preservation checklist.",
-          "If `authoringMode = modernize_existing`, identify what must stay the same about purpose, what feels stale, and what modernization constraints apply."
+          "Classify `workflowComplexity`: Simple, Medium, or Complex.",
+          "Choose an `authoringBaseline` for engine-native authoring quality and an `outcomeBaseline` for the kind of job the authored workflow should perform. If no good baseline exists for one of them, set it to `none` and explain why."
         ],
         "outputRequired": {
           "notesMarkdown": "Task understanding, baseline choices, patterns to borrow or avoid, and any real open questions.",
-          "context": "Capture authoringMode, workflowArchetype, workflowComplexity, rigorMode, taskDescription, intendedAudience, successCriteria, domainConstraints, targetWorkflowPath, modernizationGoals, authoringBaseline, outcomeBaseline, baselineDecisionRationale, authoringPatternsToBorrow, outcomePatternsToBorrow, patternsToAvoid, openQuestions, and valueInventory (modernize_existing only)."
+          "context": "Capture authoringMode, workflowArchetype, workflowComplexity, taskDescription, intendedAudience, successCriteria, domainConstraints, targetWorkflowPath, modernizationGoals, authoringBaseline, outcomeBaseline, baselineDecisionRationale, authoringPatternsToBorrow, outcomePatternsToBorrow, patternsToAvoid, openQuestions, and valueInventory (modernize_existing only)."
         },
         "verify": [
           "The task is understood well enough to design the workflow without guessing blindly.",
           "Both authoring and outcome baselines are explicit, or their absence is justified."
         ]
       },
-      "requireConfirmation": true
+      "requireConfirmation": true,
+      "promptFragments": [
+        {
+          "id": "phase-0-modernize-inventory",
+          "when": {
+            "var": "authoringMode",
+            "equals": "modernize_existing"
+          },
+          "text": "Decide `authoringMode`: `create` or `modernize_existing`."
+        },
+        {
+          "id": "phase-0-modernize-scope",
+          "when": {
+            "var": "authoringMode",
+            "equals": "modernize_existing"
+          },
+          "text": "If `authoringMode = modernize_existing`, build a value inventory BEFORE forming opinions about what to change. Read the original and classify each meaningful mechanism: (1) enforcement mechanisms (forcing functions, hard gates, required outputs), (2) domain knowledge (problem-specific principles the agent would not otherwise know), (3) behavioral rules (persistent constraints on how the agent works). This inventory is the preservation checklist."
+        }
+      ]
     },
     {
       "id": "phase-1-define-effectiveness-target",
@@ -187,10 +202,6 @@
     {
       "id": "phase-2-design-workflow-architecture",
       "title": "Phase 2: Design the Workflow Architecture",
-      "runCondition": {
-        "var": "workflowComplexity",
-        "not_equals": "Simple"
-      },
       "promptBlocks": {
         "goal": "Decide the workflow architecture before you write JSON.",
         "constraints": [
@@ -200,8 +211,7 @@
         "procedure": [
           "Decide the phase list, one-line goal for each phase, and overall ordering.",
           "Design loops with explicit exit rules, bounded maxIterations, and real reasons for another pass.",
-          "Decide confirmation gates, delegation vs template injection vs direct execution, promptFragments, references, artifacts, and metaGuidance.",
-          "If `authoringMode = modernize_existing`, decide preserve-in-place, restructure, or rewrite. For each item in valueInventory, record: `preserved` (structurally present with equivalent enforcement), `replaced` (new mechanism prevents same failure mode  -- justify equivalence), or `dropped` (intentionally removed  -- justify the loss). Phase-level mapping alone is insufficient; track what was inside each restructured or removed phase."
+          "Decide confirmation gates, delegation vs template injection vs direct execution, promptFragments, references, artifacts, and metaGuidance."
         ],
         "outputRequired": {
           "notesMarkdown": "Structured workflow outline, loop design, confirmation design, delegation design, artifact plan, and modernization mapping.",
@@ -212,6 +222,14 @@
         ]
       },
       "promptFragments": [
+        {
+          "id": "phase-2-simple-scope",
+          "when": {
+            "var": "workflowComplexity",
+            "equals": "Simple"
+          },
+          "text": "This is a Simple workflow. Keep the architecture lightweight: a flat phase list, no loops required, minimal confirmations, no delegation. The goal is clarity and direct execution, not structural sophistication."
+        },
         {
           "id": "phase-2-simple-direct",
           "when": {
@@ -219,19 +237,19 @@
             "equals": "Simple"
           },
           "text": "For Simple workflows, keep the architecture linear and compact. Do not invent loops or ceremony unless the task truly needs them."
+        },
+        {
+          "id": "phase-2-modernize-mapping",
+          "when": {
+            "var": "authoringMode",
+            "equals": "modernize_existing"
+          },
+          "text": "If `authoringMode = modernize_existing`, decide preserve-in-place, restructure, or rewrite. For each item in valueInventory, record: `preserved` (structurally present with equivalent enforcement), `replaced` (new mechanism prevents same failure mode  -- justify equivalence), or `dropped` (intentionally removed  -- justify the loss). Phase-level mapping alone is insufficient; track what was inside each restructured or removed phase."
         }
       ],
       "requireConfirmation": {
-        "or": [
-          {
-            "var": "workflowComplexity",
-            "not_equals": "Simple"
-          },
-          {
-            "var": "rigorMode",
-            "not_equals": "QUICK"
-          }
-        ]
+        "var": "workflowComplexity",
+        "not_equals": "Simple"
       }
     },
     {
@@ -257,18 +275,16 @@
           "The authored workflow has an explicit plan for false-confidence resistance and quality review."
         ]
       },
-      "requireConfirmation": {
-        "or": [
-          {
-            "var": "rigorMode",
-            "equals": "THOROUGH"
-          },
-          {
+      "promptFragments": [
+        {
+          "id": "phase-3-simple-scope",
+          "when": {
             "var": "workflowComplexity",
-            "equals": "Complex"
-          }
-        ]
-      }
+            "equals": "Simple"
+          },
+          "text": "This is a Simple workflow. Quality architecture should be proportional: identify one primary false-confidence mode and one key hard gate. Skip full reviewer family design -- a single self-executed review pass is sufficient."
+        }
+      ]
     },
     {
       "id": "phase-4-draft-or-revise",
@@ -344,10 +360,6 @@
           "promptFragments": [
             {
               "id": "phase-5a-thorough",
-              "when": {
-                "var": "rigorMode",
-                "equals": "THOROUGH"
-              },
               "text": "After structural validation passes, also check the workflow manually against required-level authoring-spec rules and fix any failures before moving on."
             }
           ],
@@ -388,13 +400,13 @@
         "equals": false
       },
       "promptBlocks": {
-        "goal": "Do not silently continue with a structurally broken workflow.",
+        "goal": "Stop execution. A structurally broken workflow must not proceed to the quality gate loop. Surface the errors and require user intervention.",
         "constraints": [
           "Present the situation honestly."
         ],
         "procedure": [
           "List the remaining validation errors and assess their severity.",
-          "Present the options: proceed with known issues documented, or stop so the user can intervene manually."
+          "Stop and require user intervention. Do not proceed into the quality gate loop with a structurally broken workflow. The user must explicitly decide how to resolve each remaining error before this workflow can continue."
         ]
       },
       "requireConfirmation": true
@@ -410,7 +422,7 @@
           "contractRef": "wr.contracts.loop_control",
           "loopId": "quality_gate_loop"
         },
-        "maxIterations": 2
+        "maxIterations": 3
       },
       "body": [
         {
@@ -435,7 +447,21 @@
               "Weak or unused fields are either wired meaningfully or removed."
             ]
           },
-          "requireConfirmation": false
+          "requireConfirmation": false,
+          "assessmentRefs": [
+            "state-economy-gate"
+          ],
+          "assessmentConsequences": [
+            {
+              "when": {
+                "anyEqualsLevel": "low"
+              },
+              "effect": {
+                "kind": "require_followup",
+                "guidance": "state_economy low -- one or more context fields are unused, weakly consumed, or carry no decision weight. Remove or wire them before proceeding: trace a concrete downstream use for each field, or delete it from the workflow."
+              }
+            }
+          ]
         },
         {
           "id": "phase-6b-execution-simulation",
@@ -463,14 +489,6 @@
             ]
           },
           "promptFragments": [
-            {
-              "id": "phase-6b-quick",
-              "when": {
-                "var": "rigorMode",
-                "equals": "QUICK"
-              },
-              "text": "For QUICK rigor, keep the simulation compact but still answer where the workflow would likely disappoint the user if it disappointed them at all."
-            },
             {
               "id": "phase-6b-modernize-check",
               "when": {
@@ -480,7 +498,21 @@
               "text": "For modernize_existing: after tracing the workflow forward, check each item in valueInventory. For each enforcement mechanism and domain knowledge item: would the modernized workflow produce the same behavior? Any item where the answer is no or weaker is a loss  -- fix it directly or record the accepted tradeoff with justification."
             }
           ],
-          "requireConfirmation": false
+          "requireConfirmation": false,
+          "assessmentRefs": [
+            "simulation-outcome-gate"
+          ],
+          "assessmentConsequences": [
+            {
+              "when": {
+                "anyEqualsLevel": "low"
+              },
+              "effect": {
+                "kind": "require_followup",
+                "guidance": "simulation_outcome low -- the simulation found likely unsatisfying or false-confidence outputs that were not fixed inline. Address the identified weak steps or degraded-path failures before the adversarial review."
+              }
+            }
+          ]
         },
         {
           "id": "phase-6c-adversarial-quality-review",
@@ -492,11 +524,11 @@
               "Reviewer-family or validator output is evidence, not authority."
             ],
             "procedure": [
-              "Score these dimensions 0-2 with one sentence of evidence each: `voiceClarity`, `ceremonyLevel`, `loopSoundness`, `delegationBoundedness`, `artifactClarity`, `taskEffectiveness`, `falseConfidenceResistance`, `stateMinimality`, `coverageSharpness`, `domainFit`, `handoffUtility`, `rigorAdaptability` (0 = adapts to complexity/rigor levels, 2 = single-weight), `enforcementStrength` (0 = behavioral rules have structural teeth; 2 = important rules are prose-only with no enforcement mechanism), and `modernizationDiscipline` (0 = every valueInventory item preserved, equivalently replaced with justification, or dropped with justification; 2 = items missing or replaced with weaker versions without justification  -- score 0 for create mode).",
-              "If delegation is available and rigor is THOROUGH, run an adversarial review bundle with these lenses: `engine_native_reviewer`, `task_effectiveness_reviewer`, `state_economy_reviewer`, `false_confidence_reviewer`, `domain_fit_reviewer`, and `maintainer_reviewer`.",
+              "Score these dimensions 0-2 with one sentence of evidence each: `voiceClarity`, `ceremonyLevel`, `loopSoundness`, `delegationBoundedness`, `artifactClarity`, `taskEffectiveness`, `falseConfidenceResistance`, `stateMinimality`, `coverageSharpness`, `domainFit`, `handoffUtility`, and `complexityScaling` (0 = has appropriate fast paths or scope-sensitive branching for simpler inputs; 2 = single-weight, over-engineers simple cases)2 = single-weight), `enforcementStrength` (0 = behavioral rules have structural teeth; 2 = important rules are prose-only with no enforcement mechanism), and `modernizationDiscipline` (0 = every valueInventory item preserved, equivalently replaced with justification, or dropped with justification; 2 = items missing or replaced with weaker versions without justification  -- score 0 for create mode).",
+              "Run an adversarial review bundle with these lenses: `engine_native_reviewer`, `task_effectiveness_reviewer`, `state_economy_reviewer`, `false_confidence_reviewer`, `domain_fit_reviewer`, and `maintainer_reviewer`.",
               "Synthesize what the review confirmed, what it challenged, and what changed your mind.",
               "When scoring `falseConfidenceResistance`, explicitly check: do the workflow's quality gates protect edge cases and degraded paths, or only the happy path? A workflow that passes its own checks on ideal input but fails silently on minimal or unexpected input scores 2.",
-              "Set hard-gate failures whenever any of these are materially weak: `taskEffectiveness`, `falseConfidenceResistance`, `stateMinimality`, `coverageSharpness`, `domainFit`, or `handoffUtility`.",
+              "Set hard-gate failures whenever any of these are materially weak: `taskEffectiveness`, `falseConfidenceResistance`, `stateMinimality`, `coverageSharpness`, `domainFit`, or `handoffUtility`, and `complexityScaling` (0 = has appropriate fast paths or scope-sensitive branching for simpler inputs; 2 = single-weight, over-engineers simple cases).",
               "Set `authoringIntegrityPassed = true` only if structural and authoring-quality dimensions are all acceptable. Set `outcomeEffectivenessPassed = true` only if the workflow is likely to achieve satisfying results for the user."
             ],
             "outputRequired": {
@@ -509,20 +541,8 @@
           },
           "promptFragments": [
             {
-              "id": "phase-6c-standard",
-              "when": {
-                "var": "rigorMode",
-                "equals": "STANDARD"
-              },
-              "text": "For STANDARD rigor, you may keep the review self-executed unless uncertainty remains material. If you do delegate, prefer a small adversarial bundle."
-            },
-            {
-              "id": "phase-6c-thorough",
-              "when": {
-                "var": "rigorMode",
-                "equals": "THOROUGH"
-              },
-              "text": "For THOROUGH rigor, assume the first review is not enough. Use adversarial reviewer lanes unless a hard limitation makes them impossible."
+              "id": "phase-6c-rigor",
+              "text": "Always use adversarial reviewer lanes. Assume the first review is not enough -- use the full adversarial bundle unless a hard limitation makes it impossible."
             },
             {
               "id": "phase-6c-heritage-review",
@@ -533,7 +553,29 @@
               "text": "For modernize_existing: add a heritage_reviewer to the adversarial bundle. Its job is to check each valueInventory item and find what was lost or weakened  -- it ignores format improvements. It must answer: which enforcement mechanisms are now prose-only? Which domain knowledge items are absent? Which behavioral rules were removed without equivalent replacement? Heritage_reviewer findings drive enforcementStrength and modernizationDiscipline scores."
             }
           ],
-          "requireConfirmation": false
+          "requireConfirmation": false,
+          "validationCriteria": [
+            {
+              "type": "contains",
+              "value": "complexityScaling",
+              "message": "Review must score complexityScaling"
+            }
+          ],
+          "assessmentRefs": [
+            "authoring-integrity-gate",
+            "outcome-effectiveness-gate"
+          ],
+          "assessmentConsequences": [
+            {
+              "when": {
+                "anyEqualsLevel": "low"
+              },
+              "effect": {
+                "kind": "require_followup",
+                "guidance": "authoring_integrity low -- structural or quality dimensions are unacceptable; fix voice, ceremony, loop, delegation, or state problems before this workflow can be trusted. outcome_effectiveness low -- task effectiveness, false-confidence resistance, coverage sharpness, or domain fit are materially weak; redesign, do not patch."
+              }
+            }
+          ]
         },
         {
           "id": "phase-6d-redesign-and-revalidate",
@@ -545,7 +587,6 @@
               "If structure changes, re-run real validators before leaving this step."
             ],
             "procedure": [
-              "If `authoringIntegrityPassed` and `outcomeEffectivenessPassed` are both true and `hardGateFailures` is empty, say that no redesign is needed.",
               "Otherwise classify the needed redesign severity as `minor`, `architectural`, or `unsafe_to_ship` and apply the necessary fixes directly to the workflow file.",
               "If the redesign changed structure, run the real validators again and update the validation state before leaving this step."
             ],
@@ -557,7 +598,19 @@
               "Structural redesign problems are handled as redesign problems, not cosmetic ones."
             ]
           },
-          "requireConfirmation": false
+          "requireConfirmation": false,
+          "runCondition": {
+            "or": [
+              {
+                "var": "authoringIntegrityPassed",
+                "equals": false
+              },
+              {
+                "var": "outcomeEffectivenessPassed",
+                "equals": false
+              }
+            ]
+          }
         },
         {
           "id": "phase-6e-quality-loop-decision",
@@ -597,7 +650,7 @@
         "procedure": [
           "Read spec/workflow-tags.json to see the available tags and their 'when' phrases.",
           "Based on the workflow's purpose and description, select 1-3 tags from the closed set (coding, review_audit, investigation, design, documentation, tickets, learning, routines, authoring).",
-          "Add the workflow ID as a new entry under 'workflows' in spec/workflow-tags.json: { \"tags\": [\"<tag1>\"] }.",
+          "Check whether the workflow ID already exists in the `workflows` section. If it does, update the existing entry tags rather than adding a duplicate. If it does not exist, add a new entry under 'workflows' in spec/workflow-tags.json: { \"tags\": [\"<tag1>\"] }.",
           "If the workflow is a test fixture or internal utility not meant for end-user discovery, add 'hidden': true.",
           "Save the tags file. Do not modify any other field.",
           "Write the 'about' field into the workflow JSON: a markdown string (100-400 words) written for a human deciding whether to use this workflow. Cover what it does, when to use it, what it produces, and how to get good results. This is a user-facing surface -- not agent instructions (use metaGuidance for that).",
@@ -645,5 +698,63 @@
       "requireConfirmation": false
     }
   ],
-  "validatedAgainstSpecVersion": 3
+  "validatedAgainstSpecVersion": 3,
+  "assessments": [
+    {
+      "id": "state-economy-gate",
+      "purpose": "Every context field in the authored workflow earns its keep: it is set, consumed, and influences a concrete decision or output.",
+      "dimensions": [
+        {
+          "id": "state_economy",
+          "purpose": "All context fields have a traceable downstream use. No field is captured speculatively or carried without purpose.",
+          "levels": [
+            "low",
+            "high"
+          ]
+        }
+      ]
+    },
+    {
+      "id": "simulation-outcome-gate",
+      "purpose": "A concrete execution simulation has been completed and identified weak steps, likely unsatisfying outputs, and false-confidence modes -- and any found were fixed inline.",
+      "dimensions": [
+        {
+          "id": "simulation_outcome",
+          "purpose": "Simulation completed over at least one happy path and one degraded/edge-case path. Issues found were fixed or explicitly accepted.",
+          "levels": [
+            "low",
+            "high"
+          ]
+        }
+      ]
+    },
+    {
+      "id": "authoring-integrity-gate",
+      "purpose": "The authored workflow is structurally sound and meets authoring quality standards: voice, ceremony, loops, delegation, and state are all acceptable.",
+      "dimensions": [
+        {
+          "id": "authoring_integrity",
+          "purpose": "Structural and authoring-quality dimensions passed the adversarial review. No hard gate failure on voice, ceremony, loopSoundness, delegationBoundedness, or stateMinimality.",
+          "levels": [
+            "low",
+            "high"
+          ]
+        }
+      ]
+    },
+    {
+      "id": "outcome-effectiveness-gate",
+      "purpose": "The authored workflow is likely to produce genuinely satisfying results: task effectiveness, false-confidence resistance, coverage sharpness, domain fit, and handoff utility are all acceptable.",
+      "dimensions": [
+        {
+          "id": "outcome_effectiveness",
+          "purpose": "The workflow passes adversarial review on task effectiveness, falseConfidenceResistance, coverageSharpness, domainFit, and handoffUtility. No hard gate failure on any outcome dimension.",
+          "levels": [
+            "low",
+            "high"
+          ]
+        }
+      ]
+    }
+  ]
 }