@exaudeus/workrail 3.66.0 → 3.68.0

package/workflows/ui-ux-design-workflow.json

@@ -1,5 +1,5 @@
 {
-  "id": "ui-ux-design-workflow",
+  "id": "wr.ui-ux-design",
   "name": "UI/UX Design Workflow",
   "version": "0.1.0",
   "metricsProfile": "design",
@@ -25,7 +25,7 @@
   ],
   "metaGuidance": [
     "PROCESS IS THE VALUE: the biggest failure mode in AI-assisted design is skipping to solutions before understanding the problem. This workflow makes that structurally impossible. Do not shortcut Phase 0.",
-    "EVIDENCE OVER PLATITUDES: every finding must cite a specific element from the context packet. 'Consider reducing cognitive load' is not a finding. 'The settings panel has 14 options, violating Miller’s Law (7±2)' is a finding.",
+    "EVIDENCE OVER PLATITUDES: every finding must cite a specific element from the context packet. 'Consider reducing cognitive load' is not a finding. 'The settings panel has 14 options, violating Miller\u2019s Law (7\u00b12)' is a finding.",
     "SIMPLE CRITERIA: designComplexity=Simple is only valid for a single existing component with a minor change, no new user flows, no information architecture changes, and no new interaction patterns. If uncertain, classify upward.",
     "HONEST LIMITS: this workflow produces a text-based design spec. It cannot produce visual mockups, conduct usability testing, or verify visual quality. Say so explicitly in the handoff and flag what still needs human visual review.",
     "CONTEXT BLINDNESS: if the user has not provided design system, existing component patterns, or platform conventions, surface this gap in Phase 0 and ask. Do not silently design without this context.",
@@ -75,14 +75,14 @@
       "promptBlocks": {
         "goal": "Generate 2-3 genuinely different design directions before committing to any one of them.",
         "constraints": [
-          "Directions must be genuinely different — not variations of the same pattern with different labels.",
+          "Directions must be genuinely different \u2014 not variations of the same pattern with different labels.",
           "Each direction needs an information architecture sketch: how is content organized, what is the primary navigation path, what is the visual hierarchy?",
           "Do not select a direction in this phase. Exploration comes before convergence."
         ],
         "procedure": [
           "Generate Direction A: the most conventional approach that follows existing platform patterns and design system. Low risk, familiar to users.",
-          "Generate Direction B: an approach that prioritizes the primary user goal differently — different IA, different entry point, or different interaction model.",
-          "Generate Direction C (if designComplexity=Complex): a third direction that challenges the assumptions in A and B — a more radical rethinking of the problem.",
+          "Generate Direction B: an approach that prioritizes the primary user goal differently \u2014 different IA, different entry point, or different interaction model.",
+          "Generate Direction C (if designComplexity=Complex): a third direction that challenges the assumptions in A and B \u2014 a more radical rethinking of the problem.",
           "For each direction, describe: (1) the primary IA sketch (main sections, navigation path, content hierarchy), (2) the core interaction model (how does the user accomplish their goal?), (3) the key tradeoffs relative to user goals and constraints.",
           "After describing all directions, restate which user goals each direction serves well and where each direction is weakest."
         ],
@@ -108,8 +108,8 @@
       "promptBlocks": {
         "goal": "Assemble a neutral context packet that all reviewer families will use as shared truth, then declare which reviewers are needed.",
         "constraints": [
-          "The context packet is neutral — it presents the design problem and directions without advocating for any one.",
-          "Select the direction to develop further before running reviewers — reviewers evaluate a specific direction, not an abstract problem.",
+          "The context packet is neutral \u2014 it presents the design problem and directions without advocating for any one.",
+          "Select the direction to develop further before running reviewers \u2014 reviewers evaluate a specific direction, not an abstract problem.",
           "All 5 reviewer families are active for Complex designs; IA and UX laws reviewers are always included for Standard."
         ],
         "procedure": [
@@ -152,7 +152,7 @@
         "procedure": [
           "Before delegating, restate the selected direction and the user goal it serves best.",
           "Spawn one WorkRail Executor per selected reviewer family simultaneously. Each executor receives: the designContextPacket, their specific reviewer mission, and the finding format requirement.",
-          "Reviewer family missions: (1) IA reviewer — evaluate content hierarchy, navigation paths, grouping logic, and information scent against user goals; cite specific IA decisions; (2) UX laws reviewer — check each relevant law: Hick's Law (decision count), Miller's Law (working memory), Jakob's Law (familiar patterns), Fitts's Law (target size and distance), Peak-End Rule (emotional journey), Tesler's Law (irreducible complexity), Von Restorff Effect (visual differentiation of important elements); cite specific violations or confirmations; (3) accessibility reviewer — check WCAG requirements: color contrast ratios (4.5:1 normal, 3:1 large text), keyboard navigation path, touch target sizes (44x44px minimum), screen reader labels, focus indicators, animation controls; produce specific requirements not 'follow WCAG'; (4) edge cases reviewer — for each interactive element, explicitly address: empty state (no data), error state (failed action), loading state, first-use/onboarding, offline or degraded state, destructive actions; flag any state not addressed in the current design; (5) content reviewer — evaluate every label, button copy, placeholder, error message, and helper text against clarity, user language vs. technical jargon, and actionability of error messages.",
+          "Reviewer family missions: (1) IA reviewer \u2014 evaluate content hierarchy, navigation paths, grouping logic, and information scent against user goals; cite specific IA decisions; (2) UX laws reviewer \u2014 check each relevant law: Hick's Law (decision count), Miller's Law (working memory), Jakob's Law (familiar patterns), Fitts's Law (target size and distance), Peak-End Rule (emotional journey), Tesler's Law (irreducible complexity), Von Restorff Effect (visual differentiation of important elements); cite specific violations or confirmations; (3) accessibility reviewer \u2014 check WCAG requirements: color contrast ratios (4.5:1 normal, 3:1 large text), keyboard navigation path, touch target sizes (44x44px minimum), screen reader labels, focus indicators, animation controls; produce specific requirements not 'follow WCAG'; (4) edge cases reviewer \u2014 for each interactive element, explicitly address: empty state (no data), error state (failed action), loading state, first-use/onboarding, offline or degraded state, destructive actions; flag any state not addressed in the current design; (5) content reviewer \u2014 evaluate every label, button copy, placeholder, error message, and helper text against clarity, user language vs. technical jargon, and actionability of error messages.",
           "After receiving all executor outputs, synthesize explicitly: what was confirmed, what was new, what looks weak or generic, and what has citations vs. what is speculation.",
           "Set evidenceWeakCount to the number of findings without specific citations."
         ],
@@ -250,13 +250,13 @@
       "promptBlocks": {
         "goal": "Verify all quality gates pass before writing the design spec.",
         "constraints": [
-          "If any gate fails, fix the underlying issue before advancing — do not write the spec over known gaps."
+          "If any gate fails, fix the underlying issue before advancing \u2014 do not write the spec over known gaps."
         ],
         "procedure": [
-          "Gate 1 — Evidence citations: confirm every finding in reviewerFindings cites a specific design element from the context packet. Flag any finding that is generic advice without a specific reference and either improve it or mark it advisory-only.",
-          "Gate 2 — Reviewer coverage: confirm every declared reviewer family has at least one substantive finding. If a family has no findings, state explicitly why (e.g., 'IA reviewer found no issues — the single-screen design has no navigation structure to evaluate').",
-          "Gate 3 — Edge case coverage: confirm empty state, error state, loading state, and first-use are addressed for each interactive element in the selected design direction. List any that are not yet addressed.",
-          "Gate 4 — Accessibility specificity: confirm accessibility requirements are listed as specific constraints (color contrast ratios, touch target sizes, keyboard tab order), not as a generic 'follow WCAG' instruction."
+          "Gate 1 \u2014 Evidence citations: confirm every finding in reviewerFindings cites a specific design element from the context packet. Flag any finding that is generic advice without a specific reference and either improve it or mark it advisory-only.",
+          "Gate 2 \u2014 Reviewer coverage: confirm every declared reviewer family has at least one substantive finding. If a family has no findings, state explicitly why (e.g., 'IA reviewer found no issues \u2014 the single-screen design has no navigation structure to evaluate').",
+          "Gate 3 \u2014 Edge case coverage: confirm empty state, error state, loading state, and first-use are addressed for each interactive element in the selected design direction. List any that are not yet addressed.",
+          "Gate 4 \u2014 Accessibility specificity: confirm accessibility requirements are listed as specific constraints (color contrast ratios, touch target sizes, keyboard tab order), not as a generic 'follow WCAG' instruction."
         ],
         "outputRequired": {
           "notesMarkdown": "Gate check results: which passed, which failed, what was fixed.",
@@ -281,7 +281,7 @@
           "Do not drift into implementation planning (specific component libraries, code) unless explicitly asked."
         ],
         "procedure": [
-          "Write the design spec covering: (1) Design Decision — which direction was chosen and the specific reason it was chosen over the others; (2) Information Architecture — content hierarchy, navigation structure, primary user path; (3) Interaction Design — how each interactive element works, what triggers what, what feedback the user gets; (4) States — for each element: default, hover/focus, loading, error, empty, first-use, disabled; (5) Accessibility Requirements — specific requirements (color contrast ratios, keyboard tab order, touch target sizes, screen reader labels); (6) Content — all copy, labels, error messages, placeholders, and onboarding text; (7) Reviewer Findings — per-dimension findings with citations that the design should address or has already addressed; (8) Open Questions — what still needs human input (visual design, usability testing, design system component availability).",
+          "Write the design spec covering: (1) Design Decision \u2014 which direction was chosen and the specific reason it was chosen over the others; (2) Information Architecture \u2014 content hierarchy, navigation structure, primary user path; (3) Interaction Design \u2014 how each interactive element works, what triggers what, what feedback the user gets; (4) States \u2014 for each element: default, hover/focus, loading, error, empty, first-use, disabled; (5) Accessibility Requirements \u2014 specific requirements (color contrast ratios, keyboard tab order, touch target sizes, screen reader labels); (6) Content \u2014 all copy, labels, error messages, placeholders, and onboarding text; (7) Reviewer Findings \u2014 per-dimension findings with citations that the design should address or has already addressed; (8) Open Questions \u2014 what still needs human input (visual design, usability testing, design system component availability).",
           "Close the spec by naming: what visual review a human designer should perform, and what this workflow cannot verify (visual quality, usability, emotional feel)."
         ],
         "outputRequired": {

package/workflows/workflow-diagnose-environment.json

@@ -1,5 +1,5 @@
 {
-  "id": "workflow-diagnose-environment",
+  "id": "wr.diagnose-environment",
   "name": "Diagnostic: Environment & Subagents",
   "version": "1.0.0",
   "metricsProfile": "none",

package/workflows/workflow-for-workflows.json

@@ -1,7 +1,7 @@
 {
-  "id": "workflow-for-workflows",
+  "id": "wr.workflow-for-workflows",
   "name": "Workflow Authoring Workflow",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "metricsProfile": "design",
   "description": "Use this to author or modernize a WorkRail workflow. Guides through understanding the task, defining effectiveness targets, designing architecture and quality gates, drafting, validating, assigning tags, and handing off.",
   "about": "## Workflow Authoring Workflow\n\nThis is the standard WorkRail workflow for creating a new workflow from scratch or modernizing an existing one. It is the trust gate for all other workflows: a workflow is not considered production-ready until it has passed through here.\n\n**What it does:**\nThe workflow walks through the full authoring lifecycle: understanding the task, choosing the right baseline and archetype, designing the phase and quality-gate architecture, drafting the workflow JSON, running structural validators, auditing state fields for bloat, simulating execution against real scenarios, running an adversarial quality review, and producing a final trust handoff. For modernization tasks it builds a value inventory first to ensure enforcement mechanisms, domain knowledge, and behavioral rules are preserved or equivalently replaced.\n\n**When to use it:**\n- You want to author a new WorkRail workflow for a recurring task or problem\n- You have an existing workflow that is outdated, uses legacy patterns (pseudo-DSL, regex validation, satisfaction-score loops), or produces shallow results\n- You want a workflow that will pass the WorkRail quality bar and be trusted to run in production\n\n**What it produces:**\nA validated, tagged workflow JSON file with a `validatedAgainstSpecVersion` stamp. A final trust handoff with readiness verdict, known failure modes, residual weaknesses, and testing guidance.\n\n**How to get good results:**\nDescribe the recurring task the workflow should solve, who will run it, and what a satisfying result looks like. For modernization, point to the existing workflow file. The workflow reads the schema and authoring spec itself  -- you do not need to know the JSON format in advance.",
@@ -211,10 +211,8 @@
         ],
         "procedure": [
           "Decide the phase list, one-line goal for each phase, and overall ordering.",
-          "Identify meaningful input classifications that require different workflow paths. For each variant dimension, decide the branching mechanism: `runCondition` on separate steps (diverging paths), `promptFragments` (additive behavior on a shared base), or a separate workflow entirely. For each captured variable that drives branching, define its closed set of valid values — unexpected values are a common source of silent misbehavior.",
           "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 the authored workflow encodes domain knowledge tied to a specific version of an external system or codebase, decide how to handle staleness: prefer reading the codebase at runtime over hardcoding patterns, or explicitly document versioned assumptions so they surface as maintenance debt."
+          "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.",
@@ -267,7 +265,7 @@
         "procedure": [
           "Decide whether the authored workflow needs a hypothesis step, neutral fact packet, reviewer or validator families, contradiction loop, final validation bundle, or explicit blind-spot handling.",
           "Design the confidence model, blind-spot model, and state economy plan.",
-          "Decide the hard-gate dimensions that would make the authored workflow unsafe or unsatisfying if they fail. Choose the right enforcement mechanism for each gate: `assessments` + `assessmentRefs` + `assessmentConsequences` for bounded confidence judgments (each dimension captures a distinct orthogonal failure mode — see `mr-review-workflow.agentic.v2.json` and `bug-investigation.agentic.v2.json`); `validationCriteria` with context-aware conditions for completion-gating on structured checklists or required output content (the engine enforces that required content appears in the response before the step can complete, without a loop — conditions on individual rules can match the workflow's branching context); a re-verification loop for fix-and-verify cycles where the agent must act then prove the action worked. Do not default to a loop when `validationCriteria` is the right tool, or to `requireConfirmation` when a hard gate is needed.",
+          "Decide the hard-gate dimensions that would make the authored workflow unsafe or unsatisfying if they fail. If hard gates exist, implement them using the native `assessments` + `assessmentRefs` + `assessmentConsequences` schema fields rather than informal notes or `requireConfirmation` alone. Each dimension should capture a distinct orthogonal failure mode -- not restate the workflow's existing confidence band. See `mr-review-workflow.agentic.v2.json` and `bug-investigation.agentic.v2.json` as exemplars.",
           "Write the redesign triggers that should force architectural revision rather than cosmetic refinement."
         ],
         "outputRequired": {
@@ -556,84 +554,14 @@
               "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."
             }
           ],
-          "hasValidation": true,
+          "requireConfirmation": false,
           "validationCriteria": [
-            {
-              "type": "contains",
-              "value": "voiceClarity",
-              "message": "Review must score voiceClarity"
-            },
-            {
-              "type": "contains",
-              "value": "ceremonyLevel",
-              "message": "Review must score ceremonyLevel"
-            },
-            {
-              "type": "contains",
-              "value": "loopSoundness",
-              "message": "Review must score loopSoundness"
-            },
-            {
-              "type": "contains",
-              "value": "delegationBoundedness",
-              "message": "Review must score delegationBoundedness"
-            },
-            {
-              "type": "contains",
-              "value": "artifactClarity",
-              "message": "Review must score artifactClarity"
-            },
-            {
-              "type": "contains",
-              "value": "taskEffectiveness",
-              "message": "Review must score taskEffectiveness"
-            },
-            {
-              "type": "contains",
-              "value": "falseConfidenceResistance",
-              "message": "Review must score falseConfidenceResistance"
-            },
-            {
-              "type": "contains",
-              "value": "stateMinimality",
-              "message": "Review must score stateMinimality"
-            },
-            {
-              "type": "contains",
-              "value": "coverageSharpness",
-              "message": "Review must score coverageSharpness"
-            },
-            {
-              "type": "contains",
-              "value": "domainFit",
-              "message": "Review must score domainFit"
-            },
-            {
-              "type": "contains",
-              "value": "handoffUtility",
-              "message": "Review must score handoffUtility"
-            },
             {
               "type": "contains",
               "value": "complexityScaling",
               "message": "Review must score complexityScaling"
-            },
-            {
-              "type": "contains",
-              "value": "enforcementStrength",
-              "message": "Review must score enforcementStrength"
-            },
-            {
-              "type": "contains",
-              "value": "modernizationDiscipline",
-              "condition": {
-                "var": "authoringMode",
-                "equals": "modernize_existing"
-              },
-              "message": "Modernization reviews must score modernizationDiscipline"
             }
           ],
-          "requireConfirmation": false,
           "assessmentRefs": [
             "authoring-integrity-gate",
             "outcome-effectiveness-gate"
@@ -743,6 +671,33 @@
       },
       "requireConfirmation": false
     },
+    {
+      "id": "phase-7b-declare-metrics-profile",
+      "title": "Phase 7b: Declare metricsProfile",
+      "promptBlocks": {
+        "goal": "Declare the metricsProfile field in the authored workflow JSON, or explicitly justify omitting it. The metricsProfile field enables engine-injected metrics instrumentation footers in step prompts. When set, the engine injects context key accumulation reminders into every step prompt -- guiding compliant agents to report outcome, commit SHAs, PR numbers, and diff stats at session completion. Without this field, captureConfidence is always 'none' and no session metrics are collected.",
+        "procedure": [
+          "Choose the correct profile based on what the workflow produces:",
+          "  - 'coding': produces code commits. Use for implementation, refactoring, bug-fix, migration, and documentation-writing workflows.",
+          "  - 'review': produces a review decision on a PR or MR. Use for code review, audit, and change validation workflows.",
+          "  - 'research': produces a finding or recommendation but no commits. Use for investigation, diagnosis, and analysis workflows.",
+          "  - 'design': produces a design artifact (pitch, spec, ADR, architecture doc) but no commits.",
+          "  - 'ticket': creates or updates work items in an external system (Jira, GitHub Issues, Linear).",
+          "  - 'none': meta-workflow, authoring tool, utility routine, or no measurable outcome. Set explicitly and document the reason.",
+          "Add `\"metricsProfile\": \"<profile>\"` as a top-level field in the workflow JSON, after `recommendedPreferences` if that field exists.",
+          "If choosing 'none', record the justification in your notes so the decision is auditable."
+        ],
+        "constraints": [
+          "Do not invent a new profile value. The closed set is: 'coding', 'review', 'research', 'design', 'ticket', 'none'.",
+          "The engine does NOT derive the profile from tags automatically. You must set it explicitly.",
+          "workflow-for-workflows itself produces a workflow JSON artifact (a design output) -- use 'design'. It does not commit code."
+        ],
+        "outputRequired": {
+          "notesMarkdown": "State the chosen metricsProfile and a one-line justification. If omitting, explain why."
+        }
+      },
+      "requireConfirmation": false
+    },
     {
       "id": "phase-7-final-trust-handoff",
       "title": "Phase 7: Final Trust Handoff",