@exaudeus/workrail 3.14.0 → 3.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "3.14.0",
+  "version": "3.16.0",
   "description": "Step-by-step workflow enforcement for AI agents via MCP",
   "license": "MIT",
   "repository": {
@@ -39,7 +39,7 @@
     "dev": "npm run build && node dist/mcp-server.js",
     "watch": "tsc --watch",
     "validate:workflows": "bash scripts/validate-workflows.sh",
-    "validate:registry": "node scripts/validate-workflows-registry.ts",
+    "validate:registry": "node --experimental-strip-types scripts/validate-workflows-registry.ts",
     "stamp-workflow": "node scripts/stamp-workflow.ts",
     "validate:authoring-spec": "node scripts/validate-authoring-spec.js",
     "validate:authoring-docs": "node scripts/generate-authoring-docs.js --check",
@@ -77,7 +77,8 @@
     "codemod:v2-contexts": "npx ts-node scripts/codemods/run.ts --mod v2-contexts --tsconfig tsconfig.test.json --write",
     "codemod:v2-prune": "npx ts-node scripts/codemods/run.ts --mod v2-prune --tsconfig tsconfig.test.json --write",
     "codemod:guard": "npx ts-node scripts/codemods/run.ts --mod guard --tsconfig tsconfig.test.json",
-    "codemod:test-platform-guard": "npx ts-node scripts/codemods/run.ts --mod test-platform-guard --tsconfig tsconfig.test.json"
+    "codemod:test-platform-guard": "npx ts-node scripts/codemods/run.ts --mod test-platform-guard --tsconfig tsconfig.test.json",
+    "prepare": "bash scripts/setup-hooks.sh"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.24.0",
@@ -89,7 +90,7 @@
     "dotenv": "^17.2.0",
     "express": "^5.1.0",
     "neverthrow": "^8.2.0",
-    "open": "^10.2.0",
+    "open": "^11.0.0",
     "reflect-metadata": "^0.2.0",
     "semver": "^7.7.2",
     "tsconfig-paths": "^4.2.0",
@@ -121,8 +122,8 @@
     "happy-dom": "^20.0.11",
     "jsdom": "^27.0.0",
     "lit": "^3.3.1",
-    "node-fetch": "^2.7.0",
-    "semantic-release": "^24.2.0",
+    "node-fetch": "^3.3.2",
+    "semantic-release": "^25.0.3",
     "ts-morph": "^27.0.2",
     "typescript": "^5.9.3",
     "vite": "^7.1.9",

package/spec/authoring-spec.json

@@ -3,7 +3,7 @@
   "version": 3,
   "title": "WorkRail Authoring Rules",
   "purpose": "Canonical current rules for authoring good WorkRail workflows. workflow.schema.json remains the source of truth for legal structure.",
-  "lastReviewed": "2026-03-21",
+  "lastReviewed": "2026-04-04",
   "principles": [
     "Schema defines what is valid. These rules define what is good.",
     "Prefer current authoring rules over design rationale or historical notes.",
@@ -931,6 +931,87 @@
         }
       ]
     },
+    {
+      "id": "assessment-gates",
+      "title": "Assessment gates",
+      "rules": [
+        {
+          "id": "assessment-use-for-bounded-judgment",
+          "status": "active",
+          "level": "recommended",
+          "scope": [
+            "workflow.assessments",
+            "step.assessmentRefs",
+            "step.assessmentConsequences"
+          ],
+          "rule": "Use assessment gates when a step needs the agent to submit a bounded, durable judgment before the workflow can safely advance -- not for generic scoring or ceremony.",
+          "why": "Assessment gates force explicit structured reasoning at a decision point and durably record the result. Generic scoring that never affects routing adds noise without value.",
+          "enforcement": ["advisory"],
+          "sourceRefs": [
+            {
+              "kind": "example",
+              "path": "workflows/mr-review-workflow.agentic.v2.json",
+              "note": "Uses a three-dimension readiness gate on the final validation step."
+            },
+            {
+              "kind": "example",
+              "path": "workflows/bug-investigation.agentic.v2.json",
+              "note": "Uses a single-dimension diagnosis readiness gate before handoff."
+            }
+          ],
+          "checks": [
+            "The assessment is at a step where a wrong answer would produce a bad handoff.",
+            "At least one dimension has a consequence that keeps the step pending and requires follow-up.",
+            "The assessment result is durably recorded and useful to a future resume agent."
+          ],
+          "antiPatterns": [
+            "Using assessments as a generic five-level scoring rubric with no routing consequence",
+            "Declaring an assessment but never referencing it from any step"
+          ]
+        },
+        {
+          "id": "assessment-dimension-orthogonality",
+          "status": "active",
+          "level": "required",
+          "scope": [
+            "workflow.assessments"
+          ],
+          "rule": "Each dimension in an assessment must capture a distinct failure mode that the other dimensions cannot catch. A dimension that restates existing workflow state (such as a generic 'confidence' dimension that mirrors the workflow's confidence band) adds ceremony without structure.",
+          "why": "The value of multiple dimensions is that each one independently blocks advancement for a different reason. Correlated or vague dimensions collapse to a single gate with extra steps.",
+          "enforcement": ["advisory"],
+          "checks": [
+            "Each dimension is independently checkable without needing to know the result of the others.",
+            "No dimension restates a context variable the workflow already computes (e.g. recommendationConfidenceBand).",
+            "A 'low' rating on any one dimension alone justifies a follow-up, regardless of the others."
+          ],
+          "antiPatterns": [
+            "A single 'confidence' dimension that mirrors the workflow's existing confidence band",
+            "Multiple dimensions that all reduce to 'did I do a good job overall'",
+            "Dimensions so correlated that one being low always means the others are low too"
+          ]
+        },
+        {
+          "id": "assessment-v1-constraints",
+          "status": "active",
+          "level": "required",
+          "scope": [
+            "step.assessmentRefs",
+            "step.assessmentConsequences"
+          ],
+          "rule": "V1 supports exactly one assessmentRef per step and at most one assessmentConsequences entry per step. Use anyEqualsLevel as the trigger -- the engine checks all submitted dimensions and fires if any equals that level.",
+          "why": "anyEqualsLevel is the only trigger form. It works for both single-dimension and multi-dimension assessments without requiring the author to choose between two forms.",
+          "enforcement": ["schema"],
+          "checks": [
+            "No more than one assessmentRefs entry per step.",
+            "No more than one assessmentConsequences entry per step.",
+            "The consequence uses anyEqualsLevel to declare which level blocks -- not a named dimension."
+          ],
+          "antiPatterns": [
+            "Trying to encode multiple consequences via workarounds"
+          ]
+        }
+      ]
+    },
     {
       "id": "delegation",
       "title": "Delegation and subagents",

package/spec/workflow-tags.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "./workflow-tags.schema.json",
+  "version": 1,
+  "tags": [
+    {
+      "id": "coding",
+      "displayName": "Coding & Development",
+      "when": [
+        "implementing a feature or task",
+        "refactoring or improving existing code",
+        "converting code between platforms or languages"
+      ],
+      "examples": ["coding-task-workflow-agentic", "cross-platform-code-conversion"]
+    },
+    {
+      "id": "review_audit",
+      "displayName": "Review & Audit",
+      "when": [
+        "reviewing a merge request before merging",
+        "auditing a service for production readiness",
+        "checking architecture for scalability issues"
+      ],
+      "examples": ["mr-review-workflow-agentic", "production-readiness-audit"]
+    },
+    {
+      "id": "investigation",
+      "displayName": "Investigation & Debugging",
+      "when": [
+        "diagnosing a bug or unexpected behavior in code",
+        "diagnosing tool, environment, or MCP server issues"
+      ],
+      "examples": ["bug-investigation-agentic", "workflow-diagnose-environment"]
+    },
+    {
+      "id": "design",
+      "displayName": "Design & Discovery",
+      "when": [
+        "designing a UI or UX feature from scratch",
+        "exploring and thinking through a problem or decision",
+        "generating and comparing design candidates"
+      ],
+      "examples": ["ui-ux-design-workflow", "wr.discovery"]
+    },
+    {
+      "id": "documentation",
+      "displayName": "Documentation",
+      "when": [
+        "creating new documentation for a project, feature, or API",
+        "updating or maintaining existing documentation",
+        "writing documentation for a single bounded component or concept"
+      ],
+      "examples": ["document-creation-workflow", "documentation-update-workflow"]
+    },
+    {
+      "id": "tickets",
+      "displayName": "Tickets & Planning",
+      "when": [
+        "creating Jira tickets for a feature or epic",
+        "grooming and refining a backlog",
+        "generating test cases from ticket requirements"
+      ],
+      "examples": ["adaptive-ticket-creation", "ticket-grooming"]
+    },
+    {
+      "id": "learning",
+      "displayName": "Learning & Personal",
+      "when": [
+        "creating learning materials or a course",
+        "designing a presentation",
+        "making a major personal decision like where to relocate"
+      ],
+      "examples": ["personal-learning-materials-creation-branched", "presentation-creation"]
+    },
+    {
+      "id": "routines",
+      "displayName": "Routines",
+      "when": [
+        "gathering context about a codebase",
+        "generating design candidates",
+        "running a hypothesis challenge or adversarial review",
+        "running a final verification pass"
+      ],
+      "examples": ["routine-context-gathering", "routine-hypothesis-challenge"]
+    },
+    {
+      "id": "authoring",
+      "displayName": "Workflow Authoring",
+      "when": [
+        "creating a new WorkRail workflow from scratch",
+        "modernizing or updating an existing workflow"
+      ],
+      "examples": ["workflow-for-workflows"]
+    }
+  ],
+  "workflows": {
+    "adaptive-ticket-creation": { "tags": ["tickets"] },
+    "architecture-scalability-audit": { "tags": ["review_audit"] },
+    "bug-investigation-agentic": { "tags": ["investigation"] },
+    "coding-task-workflow-agentic": { "tags": ["coding"] },
+    "cross-platform-code-conversion": { "tags": ["coding"] },
+    "document-creation-workflow": { "tags": ["documentation"] },
+    "documentation-update-workflow": { "tags": ["documentation"] },
+    "intelligent-test-case-generation": { "tags": ["tickets", "coding"] },
+    "mr-review-workflow-agentic": { "tags": ["review_audit"] },
+    "personal-learning-course-design": { "tags": ["learning"] },
+    "personal-learning-materials-creation-branched": { "tags": ["learning"] },
+    "presentation-creation": { "tags": ["learning"] },
+    "production-readiness-audit": { "tags": ["review_audit"] },
+    "relocation-workflow-us": { "tags": ["learning"] },
+    "routine-context-gathering": { "tags": ["routines"] },
+    "routine-design-review": { "tags": ["routines"] },
+    "routine-execution-simulation": { "tags": ["routines"] },
+    "routine-feature-implementation": { "tags": ["routines", "coding"] },
+    "routine-final-verification": { "tags": ["routines"] },
+    "routine-hypothesis-challenge": { "tags": ["routines"] },
+    "routine-ideation": { "tags": ["routines"] },
+    "routine-parallel-work-partitioning": { "tags": ["routines"] },
+    "routine-philosophy-alignment": { "tags": ["routines"] },
+    "routine-plan-analysis": { "tags": ["routines"] },
+    "routine-plan-generation": { "tags": ["routines"] },
+    "routine-tension-driven-design": { "tags": ["routines"] },
+    "scoped-documentation-workflow": { "tags": ["documentation"] },
+    "ticket-grooming": { "tags": ["tickets"] },
+    "ui-ux-design-workflow": { "tags": ["design"] },
+    "workflow-diagnose-environment": { "tags": ["investigation"] },
+    "workflow-for-workflows": { "tags": ["authoring"] },
+    "wr.discovery": { "tags": ["design", "investigation"] },
+    "test-artifact-loop-control": { "tags": ["coding"], "hidden": true },
+    "test-session-persistence": { "tags": ["coding"], "hidden": true },
+    "test-missing-context": { "tags": ["coding"], "hidden": true }
+  }
+}

package/spec/workflow.schema.json

@@ -182,6 +182,24 @@
       "type": "integer",
       "minimum": 1,
       "description": "The authoring spec version this workflow was last validated against."
+    },
+    "about": {
+      "type": "string",
+      "description": "Human-readable overview for display in the console and other UIs. Markdown is supported. Write for a user deciding whether to use this workflow: what it does, when to use it, what it produces, and how to get good results. User-facing surface -- not an agent instruction (use metaGuidance for that).",
+      "minLength": 1,
+      "maxLength": 4096
+    },
+    "examples": {
+      "type": "array",
+      "description": "Short illustrative goal strings showing what this workflow is used for. Write for humans browsing the catalog and for agents selecting the right workflow. Each item should be concrete and specific enough to be informative.",
+      "items": {
+        "type": "string",
+        "minLength": 10,
+        "maxLength": 120
+      },
+      "minItems": 1,
+      "maxItems": 6,
+      "uniqueItems": true
     }
   },
   "required": [
@@ -1064,23 +1082,15 @@
     },
     "assessmentConsequenceTrigger": {
       "type": "object",
-      "description": "Exact-match trigger on one declared assessment dimension and one declared canonical level.",
+      "description": "Fires when ANY dimension in the submitted assessment equals the given level. The consequence blocks advancement until the agent addresses all dimensions that scored at that level.",
       "properties": {
-        "dimensionId": {
-          "type": "string",
-          "minLength": 1,
-          "maxLength": 64
-        },
-        "equalsLevel": {
+        "anyEqualsLevel": {
           "type": "string",
           "minLength": 1,
           "maxLength": 64
         }
       },
-      "required": [
-        "dimensionId",
-        "equalsLevel"
-      ],
+      "required": ["anyEqualsLevel"],
       "additionalProperties": false
     },
     "assessmentConsequenceEffect": {

package/workflows/adaptive-ticket-creation.json

@@ -2,7 +2,14 @@
   "id": "adaptive-ticket-creation",
   "name": "Adaptive Ticket Creation Workflow",
   "version": "1.0.0",
-  "description": "Create high-quality Jira tickets by automatically selecting the right complexity path (Simple, Standard, or Epic) based on request analysis. One polished ticket for simple requests; structured decomposition with estimates for epics.",
+  "description": "Use this to create high-quality Jira tickets for features, tasks, or epics. Automatically selects the right complexity path (Simple, Standard, or Epic) and generates properly structured tickets with acceptance criteria and estimates.",
+  "about": "## Adaptive Ticket Creation Workflow\n\nUse this to create well-structured Jira tickets for features, tasks, or epics. The workflow automatically selects the right complexity path (Simple, Standard, or Epic) based on the request, so you don't have to decide upfront how much process you need.\n\n### What it produces\n\n- **Simple path**: one complete, developer-ready Jira ticket with a context-rich description, checkbox-style acceptance criteria, and an effort estimate.\n- **Standard path**: a high-level plan plus a batch of related tickets covering all deliverables.\n- **Epic path**: everything in Standard, plus full epic decomposition, per-story estimates with risk ratings, dependency mapping, and a reusable team rules file at `.workflow_rules/ticket_creation.md` that future runs load automatically.\n\n### When to use it\n\n- You need to create one or more Jira tickets and want them to be genuinely developer-ready.\n- You have a feature request, bug, task, or epic that needs to be broken down and estimated.\n- Your team has specific ticket conventions (naming, sizing, labels) -- the workflow learns and stores these on the Epic path.\n\n### How to get good results\n\n- Provide as much context as you have: PRD links, design files, existing related tickets, and any known constraints.\n- If your team has a `.workflow_rules/ticket_creation.md` file, the workflow loads it automatically and applies your conventions.\n- On the Epic path, the workflow asks you to approve the high-level plan and the decomposition before generating tickets. Use these checkpoints to catch scope issues early.\n- Acceptance criteria are written as checkbox-style observable conditions, not restatements of requirements. If your team has a specific AC format, describe it in the rules file.",
+  "examples": [
+    "Create a Jira ticket for adding biometric authentication to the mobile login screen",
+    "Break down the new real-time notifications feature into an epic with stories and estimates",
+    "Write tickets for all backend work needed to support the v2 search API",
+    "Create a single bug ticket for the checkout crash when applying a promo code on iOS 17"
+  ],
   "preconditions": [
     "User has provided a description of the feature, task, or work to be ticketed.",
     "Agent has file system access for loading team preferences and persisting rules."
@@ -81,8 +88,14 @@
       "title": "Path C, Phase 1: Gather Context and Surface Gaps",
       "runCondition": {
         "or": [
-          { "var": "pathComplexity", "equals": "Standard" },
-          { "var": "pathComplexity", "equals": "Epic" }
+          {
+            "var": "pathComplexity",
+            "equals": "Standard"
+          },
+          {
+            "var": "pathComplexity",
+            "equals": "Epic"
+          }
         ]
       },
       "promptBlocks": {
@@ -116,8 +129,14 @@
       "title": "Path C, Phase 2: Create High-Level Plan",
       "runCondition": {
         "or": [
-          { "var": "pathComplexity", "equals": "Standard" },
-          { "var": "pathComplexity", "equals": "Epic" }
+          {
+            "var": "pathComplexity",
+            "equals": "Standard"
+          },
+          {
+            "var": "pathComplexity",
+            "equals": "Epic"
+          }
         ]
       },
       "promptBlocks": {
@@ -218,8 +237,14 @@
       "title": "Path C/E, Phase 5: Batch Ticket Generation",
       "runCondition": {
         "or": [
-          { "var": "pathComplexity", "equals": "Standard" },
-          { "var": "pathComplexity", "equals": "Epic" }
+          {
+            "var": "pathComplexity",
+            "equals": "Standard"
+          },
+          {
+            "var": "pathComplexity",
+            "equals": "Epic"
+          }
         ]
       },
       "promptBlocks": {
@@ -282,4 +307,4 @@
       "requireConfirmation": false
     }
   ]
-}
+}

package/workflows/architecture-scalability-audit.json

@@ -2,7 +2,14 @@
   "id": "architecture-scalability-audit",
   "name": "Architecture Scalability Audit (v1 • Evidence-Driven • Dimension-Scoped • rigorMode-Adaptive)",
   "version": "0.1.0",
-  "description": "Audit a bounded codebase scope for architecture scalability. The user declares which scalability dimensions matter (load, data volume, team/org, feature extensibility, operational); the workflow audits only those dimensions and produces per-dimension verdicts grounded in actual code, not generic advice.",
+  "description": "Use this to audit a bounded codebase scope for architecture scalability. Declare which scalability dimensions matter (load, data volume, team size, feature extensibility, operational); the workflow investigates each and produces evidence-grounded findings.",
+  "about": "## Architecture Scalability Audit\n\nThis workflow audits a bounded codebase scope for scalability across the dimensions you care about. It does not produce generic \"won't scale\" warnings -- every finding must cite a specific file, class, method, or pattern, and every concern must name a concrete growth scenario (e.g. 10x traffic, 100x records, 3x team size).\n\n**What it does:**\nYou declare the scope boundary and the scalability dimensions that matter for your context. The workflow reads the codebase to understand the architecture, assigns one dedicated reviewer family per dimension, runs them in parallel from a shared fact packet, reconciles contradictions and blind spots through a synthesis loop, and delivers a per-dimension verdict (will_break / risk / fine) with an overall scalability readiness verdict.\n\n**The five scalability dimensions you can select:**\n- **load** -- handles more requests, users, or throughput\n- **data_volume** -- handles more records, storage, or query size\n- **team_org** -- more teams or developers working on this scope without friction\n- **feature_extensibility** -- more features added without rearchitecting\n- **operational** -- more deployments, environments, or operational complexity\n\n**When to use it:**\n- Before investing significantly in a component you expect to grow\n- When planning capacity for a new traffic tier or data volume increase\n- When evaluating a codebase acquired through a merger, partnership, or open-source adoption\n- When a team is growing and you want to know if the architecture will hold under parallel development\n\n**What it produces:**\nAn overall scalability verdict, per-dimension findings with specific code references and growth scenarios, cross-cutting concerns that span multiple dimensions, a prioritized concern list, and explicit callouts of what is already well-designed for scale.\n\n**How to get good results:**\nBe specific about the scope boundary -- name the service, module, or feature explicitly and say what is out of scope. Choose the dimensions relevant to your actual growth pressures; the workflow will not add dimensions you did not select. If you know a specific growth target (e.g. \"we expect 50x user growth in 18 months\"), mention it.",
+  "examples": [
+    "Audit the search service for load and data_volume scalability before the Black Friday traffic ramp",
+    "Check the analytics pipeline for data_volume and operational scalability -- we are moving from 1M to 100M events/day",
+    "Scalability audit of the user management module for team_org and feature_extensibility as we split into three squads",
+    "Audit the cart and checkout services for load scalability -- scope is /cart and /checkout only"
+  ],
   "recommendedPreferences": {
     "recommendedAutonomy": "guided",
     "recommendedRiskPolicy": "conservative"
@@ -33,7 +40,12 @@
       "promptBlocks": {
         "goal": "Establish a precise bounded scope and confirm which scalability dimensions this audit will cover.",
         "constraints": [
-          [{ "kind": "ref", "refId": "wr.refs.notes_first_durability" }],
+          [
+            {
+              "kind": "ref",
+              "refId": "wr.refs.notes_first_durability"
+            }
+          ],
           "Scope must be bounded before investigation begins. Unbounded scope produces generic findings.",
           "Dimension selection is the user's decision. Explore the codebase to inform the conversation, but the user declares which dimensions matter."
         ],
@@ -87,7 +99,12 @@
       "promptBlocks": {
         "goal": "Freeze a neutral scalability fact packet and assign one reviewer family per declared dimension.",
         "constraints": [
-          [{ "kind": "ref", "refId": "wr.refs.notes_first_durability" }],
+          [
+            {
+              "kind": "ref",
+              "refId": "wr.refs.notes_first_durability"
+            }
+          ],
           "The fact packet is the primary truth for all dimension reviewer families.",
           "Keep the scalability hypothesis as a reference to challenge, not a frame to defend.",
           "One reviewer family per declared dimension only. Do not add families for undeclared dimensions."
@@ -110,7 +127,10 @@
       "promptFragments": [
         {
           "id": "phase-2-quick",
-          "when": { "var": "auditComplexity", "equals": "Simple" },
+          "when": {
+            "var": "auditComplexity",
+            "equals": "Simple"
+          },
           "text": "For a Simple audit, keep the fact packet compact — scope summary, key patterns, and declared dimensions only. Skip exhaustive realism signal enumeration."
         }
       ],
@@ -122,8 +142,18 @@
       "promptBlocks": {
         "goal": "Run one reviewer family per declared dimension in parallel, then synthesize their findings as evidence rather than verdicts.",
         "constraints": [
-          [{ "kind": "ref", "refId": "wr.refs.notes_first_durability" }],
-          [{ "kind": "ref", "refId": "wr.refs.synthesis_under_disagreement" }],
+          [
+            {
+              "kind": "ref",
+              "refId": "wr.refs.notes_first_durability"
+            }
+          ],
+          [
+            {
+              "kind": "ref",
+              "refId": "wr.refs.synthesis_under_disagreement"
+            }
+          ],
           "Each reviewer family uses scalabilityFactPacket as primary truth.",
           "Reviewer-family outputs are raw evidence. The main agent owns synthesis and verdict assignment.",
           "Each reviewer family audits only its declared dimension — no cross-dimension scope creep."
@@ -148,12 +178,18 @@
       "promptFragments": [
         {
           "id": "phase-3-quick",
-          "when": { "var": "auditComplexity", "equals": "Simple" },
+          "when": {
+            "var": "auditComplexity",
+            "equals": "Simple"
+          },
           "text": "For a Simple audit, self-execute each dimension investigation directly without spawning WorkRail Executors. One dimension at a time, using tools to inspect the codebase. This keeps the audit proportionate to the scope."
         },
         {
           "id": "phase-3-thorough",
-          "when": { "var": "auditComplexity", "equals": "Complex" },
+          "when": {
+            "var": "auditComplexity",
+            "equals": "Complex"
+          },
           "text": "For a Complex audit, spawn all dimension executors simultaneously, then after synthesis run routine-hypothesis-challenge against any will_break finding before closing this phase. This adds an adversarial check on the most serious findings."
         }
       ],
@@ -179,7 +215,12 @@
           "promptBlocks": {
             "goal": "Resolve contradictions between dimension findings and sharpen cross-cutting concerns.",
             "constraints": [
-              [{ "kind": "ref", "refId": "wr.refs.parallelize_cognition_serialize_synthesis" }],
+              [
+                {
+                  "kind": "ref",
+                  "refId": "wr.refs.parallelize_cognition_serialize_synthesis"
+                }
+              ],
               "Contradiction resolution is main-agent work. Do not delegate synthesis.",
               "A cross-cutting concern that spans multiple dimensions is its own finding."
             ],

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

@@ -1,8 +1,15 @@
 {
   "id": "bug-investigation-agentic",
-  "name": "Bug Investigation (v2 • Notes-First • WorkRail Executor)",
+  "name": "Bug Investigation (v2 \u2022 Notes-First \u2022 WorkRail Executor)",
   "version": "2.0.0",
-  "description": "A v2-first bug investigation workflow focused on moving from theory to proof with notes-first durability, explicit trigger fields, de-anchored fresh-eye review, and investigation-only handoff boundaries.",
+  "description": "Use this to diagnose a bug or unexpected behavior in code. Builds a hypothesis, gathers evidence, and proves or disproves the root cause before concluding.",
+  "about": "## Bug Investigation Workflow\n\nThis workflow guides an AI agent through a rigorous, evidence-driven investigation of a bug or unexpected behavior. It is designed to prevent the most common failure mode in AI debugging: jumping to a plausible-sounding conclusion without sufficient proof.\n\n**What it does:**\nThe workflow moves through triage, context gathering, hypothesis generation, evidence planning, iterative evidence collection, diagnosis validation, and a final handoff. It explicitly distinguishes between theories (formed by reading code) and proof (confirmed by running tests or reproducing the failure). The final output is a diagnosis with a confidence rating, the strongest alternative explanations that were ruled out, and a high-level fix direction  -- not a patch.\n\n**When to use it:**\n- You have a specific bug report, failing test, or production incident to investigate\n- The root cause is not immediately obvious and multiple explanations are plausible\n- You want a trustworthy diagnosis before spending time writing a fix\n- The bug carries enough risk that you need to be confident before changing code\n\n**What it produces:**\nA structured investigation handoff covering: root cause type (single cause, multi-factor, working as designed, etc.), proof summary, ruled-out alternatives, residual uncertainty, likely files involved, and verification steps for whoever implements the fix.\n\n**How to get good results:**\nProvide repro steps, observed symptoms, and expected behavior upfront. Include any relevant logs, failing test commands, or environment details you already have. The more concrete the repro, the faster the workflow can gather real evidence rather than theorizing. If the bug is intermittent, say so  -- the workflow adapts its rigor based on reproducibility confidence.",
+  "examples": [
+    "Investigate why the payments API returns 500 after deploying the rate limiter",
+    "Debug why the mobile app crashes on logout when a background sync is in progress",
+    "Find out why search results are missing items added in the last 10 minutes",
+    "Diagnose why CI passes locally but the integration test fails on the build server"
+  ],
   "recommendedPreferences": {
     "recommendedAutonomy": "guided",
     "recommendedRiskPolicy": "conservative"
@@ -39,7 +46,10 @@
         {
           "id": "confidence",
           "purpose": "How confident the agent is that the diagnosis is ready for final handoff.",
-          "levels": ["low", "high"]
+          "levels": [
+            "low",
+            "high"
+          ]
         }
       ]
     }
@@ -47,7 +57,7 @@
   "steps": [
     {
       "id": "phase-0-triage-and-intake",
-      "title": "Phase 0: Triage (Bug Intake • Risk • Mode)",
+      "title": "Phase 0: Triage (Bug Intake \u2022 Risk \u2022 Mode)",
       "prompt": "Understand the bug report and choose the right rigor.\n\nCapture:\n- `bugSummary`: concise statement of the issue\n- `reproSummary`: repro steps, symptoms, expected behavior, environment notes\n- `investigationComplexity`: Small / Medium / Large\n- `riskLevel`: Low / Medium / High\n- `rigorMode`: QUICK / STANDARD / THOROUGH\n- `automationLevel`: High / Medium / Low\n- `maxParallelism`: 0 / 2 / 3\n\nDecision guidance:\n- QUICK: clear repro, narrow surface area, low ambiguity\n- STANDARD: moderate ambiguity, moderate system breadth, or meaningful risk\n- THOROUGH: high ambiguity, high-risk production impact, broad surface area, or multiple plausible causes\n\nSet context variables:\n- `bugSummary`\n- `reproSummary`\n- `investigationComplexity`\n- `riskLevel`\n- `rigorMode`\n- `automationLevel`\n- `maxParallelism`\n- `reproducibilityConfidence` (High / Medium / Low)\n\nAsk for confirmation only if the chosen rigor materially affects expectations or if critical repro details are still missing.",
       "requireConfirmation": true
     },
@@ -57,8 +67,14 @@
       "prompt": "If critical inputs are missing, ask only for the minimum needed to investigate.\n\nPossible asks:\n- missing repro steps or failing test command\n- missing expected behavior\n- missing environment constraints or permissions\n- missing logs or stack traces when the codebase alone cannot answer the gap\n\nDo NOT ask for information you can discover with tools.",
       "requireConfirmation": {
         "or": [
-          { "var": "automationLevel", "equals": "Low" },
-          { "var": "automationLevel", "equals": "Medium" }
+          {
+            "var": "automationLevel",
+            "equals": "Low"
+          },
+          {
+            "var": "automationLevel",
+            "equals": "Medium"
+          }
         ]
       }
     },
@@ -78,8 +94,14 @@
       "prompt": "Reassess investigation scope after real context is known.\n\nReview:\n- `contextUnknownCount`\n- `executionPathCount`\n- `suspiciousPointCount`\n- actual systems/components involved\n- whether risk or ambiguity is larger than originally assessed\n\nDo:\n- confirm or adjust `investigationComplexity`\n- confirm or adjust `riskLevel`\n- confirm or adjust `rigorMode`\n- confirm or adjust `maxParallelism`\n\nSet context variables:\n- `investigationComplexity`\n- `riskLevel`\n- `rigorMode`\n- `maxParallelism`\n- `retriageChanged`\n\nRule:\n- upgrade rigor when the real investigation surface is broader or riskier than expected",
       "requireConfirmation": {
         "or": [
-          { "var": "retriageChanged", "equals": true },
-          { "var": "automationLevel", "equals": "Low" }
+          {
+            "var": "retriageChanged",
+            "equals": true
+          },
+          {
+            "var": "automationLevel",
+            "equals": "Low"
+          }
         ]
       }
     },
@@ -118,7 +140,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    \"decision\": \"continue\"\n  }]\n}\n```",
+          "prompt": "Decide whether the evidence loop should continue.\n\nDecision rules:\n- if `contradictionCount > 0` \u2192 continue\n- else if `unresolvedEvidenceGapCount > 0` \u2192 continue\n- else if `hasStrongAlternative = true` and the alternative is not meaningfully weaker \u2192 continue\n- else if `diagnosisType = inconclusive_but_narrowed` and further evidence is not realistically available \u2192 stop with bounded uncertainty\n- else \u2192 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"
@@ -130,12 +152,13 @@
       "id": "phase-5-diagnosis-validation",
       "title": "Phase 5: Diagnosis Validation Bundle",
       "prompt": "Stress-test the current diagnosis before handoff.\n\nSet `diagnosisConfidenceBand` using these rules:\n- High = all symptoms explained, no material contradictions, no unresolved evidence gaps\n- Medium = likely diagnosis, but one bounded uncertainty remains\n- Low = multiple viable explanations remain or contradictions are unresolved\n\nMode-adaptive validation:\n- QUICK: self-challenge; if `diagnosisConfidenceBand != High` or contradictions remain, optionally spawn ONE WorkRail Executor running `routine-hypothesis-challenge`\n- STANDARD: if delegation is available, spawn TWO WorkRail Executors SIMULTANEOUSLY running `routine-hypothesis-challenge` and `routine-execution-simulation`\n- THOROUGH: if delegation is available, spawn THREE WorkRail Executors SIMULTANEOUSLY running `routine-hypothesis-challenge`, `routine-execution-simulation`, and an additional `routine-hypothesis-challenge` pass focused on breaking the current diagnosis from a different angle\n\nParallel-output synthesis rules:\n- if 2+ validators raise serious concerns, reopen evidence or shortlist work\n- if exactly one validator raises a concern, investigate it before escalating\n- if no validator can materially break the diagnosis and `contradictionCount = 0`, proceed to handoff\n\nAfter synthesizing the validation result, assess whether the diagnosis is ready for final handoff.\n\nSet context variables:\n- `diagnosisConfidenceBand`\n- `validationFindingsCountBySeverity`\n- `validationSummary`\n\nBoundary rule:\n- allowed: high-level fix direction, likely files involved, verification recommendations\n- not allowed: implementation plan, patch sequencing, PR plan, or code-writing momentum",
-      "assessmentRefs": ["diagnosis_readiness_gate"],
+      "assessmentRefs": [
+        "diagnosis_readiness_gate"
+      ],
       "assessmentConsequences": [
         {
           "when": {
-            "dimensionId": "confidence",
-            "equalsLevel": "low"
+            "anyEqualsLevel": "low"
           },
           "effect": {
             "kind": "require_followup",
@@ -145,8 +168,14 @@
       ],
       "requireConfirmation": {
         "or": [
-          { "var": "diagnosisConfidenceBand", "equals": "Low" },
-          { "var": "contradictionCount", "not_equals": 0 }
+          {
+            "var": "diagnosisConfidenceBand",
+            "equals": "Low"
+          },
+          {
+            "var": "contradictionCount",
+            "not_equals": 0
+          }
         ]
       }
     },