@exaudeus/workrail 3.4.0 → 3.6.0

package/spec/authoring-spec.provenance.json

@@ -0,0 +1,77 @@
+{
+  "version": 1,
+  "title": "WorkRail Authoring Spec Provenance",
+  "purpose": "Maintainer-facing provenance and source hierarchy for authoring-spec.json.",
+  "canonicalSources": [
+    {
+      "path": "spec/workflow.schema.json",
+      "role": "Legal workflow structure"
+    },
+    {
+      "path": "src/application/services/validation-engine.ts",
+      "role": "Structural authoring invariants actually enforced"
+    },
+    {
+      "path": "src/infrastructure/storage/schema-validating-workflow-storage.ts",
+      "role": "Runtime-authoritative schema validation"
+    },
+    {
+      "path": "scripts/validate-workflows-registry.ts",
+      "role": "Registry and discoverability validation"
+    },
+    {
+      "path": "src/v2/durable-core/domain/prompt-renderer.ts",
+      "role": "Runtime prompt rendering and prompt composition behavior"
+    }
+  ],
+  "secondarySources": [
+    {
+      "path": "docs/design/workflow-authoring-v2.md",
+      "role": "Design intent and model rationale"
+    },
+    {
+      "path": "docs/authoring-v2.md",
+      "role": "High-level v2 authoring guidance"
+    },
+    {
+      "path": "docs/authoring.md",
+      "role": "Human-readable guide"
+    },
+    {
+      "path": "docs/workflow-validation.md",
+      "role": "Practical validation workflow"
+    },
+    {
+      "path": "docs/reference/god-tier-workflow-validation.md",
+      "role": "Validation philosophy and correctness bar"
+    },
+    {
+      "path": "workflows/coding-task-workflow-agentic.lean.v2.json",
+      "role": "Current example of modern workflow style"
+    }
+  ],
+  "nonCanonicalSources": [
+    {
+      "path": "docs/plans/**",
+      "role": "Historical or supporting context only"
+    },
+    {
+      "path": "ADRs and transitional notes",
+      "role": "Historical or supporting context only"
+    }
+  ],
+  "derivedArtifacts": [
+    {
+      "path": "docs/authoring.md",
+      "role": "Primary human-readable guide derived from authoring-spec.json"
+    },
+    {
+      "path": "docs/authoring-v2.md",
+      "role": "Candidate for merge or retirement once coverage is preserved"
+    }
+  ],
+  "notes": [
+    "This file exists to keep provenance out of the main authoring rules file.",
+    "authoring-spec.json should stay author-facing and current-rule-focused."
+  ]
+}

package/spec/authoring-spec.schema.json

@@ -0,0 +1,370 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://workrail.dev/schemas/authoring-spec/v1",
+  "title": "WorkRail Authoring Spec Schema",
+  "description": "Schema for spec/authoring-spec.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "title",
+    "purpose",
+    "principles",
+    "consumedBy",
+    "changeProtocol",
+    "ruleModel",
+    "scopeCatalog",
+    "topics"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "purpose": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512
+    },
+    "lastReviewed": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+    },
+    "principles": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 256
+      },
+      "minItems": 1
+    },
+    "consumedBy": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 64
+      },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "changeProtocol": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 256
+      },
+      "minItems": 1
+    },
+    "ruleModel": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "levels",
+        "statuses",
+        "enforcementModes",
+        "scopeStyle"
+      ],
+      "properties": {
+        "levels": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["required", "recommended", "discouraged"]
+          },
+          "uniqueItems": true
+        },
+        "statuses": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["active", "experimental", "planned", "deprecated"]
+          },
+          "uniqueItems": true
+        },
+        "enforcementModes": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["runtime", "validator", "ci", "advisory", "planned"]
+          },
+          "uniqueItems": true
+        },
+        "scopeStyle": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        }
+      }
+    },
+    "scopeCatalog": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/scopeEntry"
+      },
+      "minItems": 1
+    },
+    "topics": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/topic"
+      },
+      "minItems": 1
+    },
+    "plannedTopics": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/topic"
+      }
+    },
+    "plannedRules": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/plannedRule"
+      }
+    }
+  },
+  "$defs": {
+    "ruleLevel": {
+      "type": "string",
+      "enum": ["required", "recommended", "discouraged"]
+    },
+    "ruleStatus": {
+      "type": "string",
+      "enum": ["active", "experimental", "planned", "deprecated"]
+    },
+    "enforcementMode": {
+      "type": "string",
+      "enum": ["runtime", "validator", "ci", "advisory", "planned"]
+    },
+    "scopeToken": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)*$",
+      "minLength": 3,
+      "maxLength": 64
+    },
+    "scopeEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "description"],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/scopeToken"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        }
+      }
+    },
+    "topic": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "rules"],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/scopeToken"
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "rules": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/rule"
+          },
+          "minItems": 1
+        }
+      }
+    },
+    "rule": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "status",
+        "level",
+        "scope",
+        "rule",
+        "why",
+        "enforcement"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/scopeToken"
+        },
+        "status": {
+          "$ref": "#/$defs/ruleStatus"
+        },
+        "level": {
+          "$ref": "#/$defs/ruleLevel"
+        },
+        "scope": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/scopeToken"
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "rule": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512
+        },
+        "why": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "enforcement": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/enforcementMode"
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "checks": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256
+          }
+        },
+        "antiPatterns": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256
+          }
+        },
+        "examples": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256
+          }
+        },
+        "exampleRefs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/exampleRef"
+          }
+        },
+        "sourceRefs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/sourceRef"
+          }
+        }
+      }
+    },
+    "plannedRule": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "status",
+        "scope",
+        "rule",
+        "why",
+        "enforcement"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/scopeToken"
+        },
+        "status": {
+          "$ref": "#/$defs/ruleStatus"
+        },
+        "scope": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/scopeToken"
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "rule": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512
+        },
+        "why": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "enforcement": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/enforcementMode"
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "sourceRefs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/sourceRef"
+          }
+        }
+      }
+    },
+    "exampleRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "note": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        }
+      }
+    },
+    "sourceRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "path"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": ["schema", "runtime", "validator", "documentation", "example"]
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "note": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        }
+      }
+    }
+  }
+}

package/spec/workflow.schema.json

@@ -67,7 +67,7 @@
     },
     "metaGuidance": {
       "type": "array",
-      "description": "Persistent best practices that apply throughout the workflow",
+      "description": "Persistent behavioral rules surfaced on start and resume. Not repeated on every step advance. For external document pointers, use 'references' instead.",
       "items": {
         "type": "string",
         "minLength": 1,
@@ -142,6 +142,14 @@
         "$ref": "#/$defs/extensionPoint"
       },
       "uniqueItems": true
+    },
+    "references": {
+      "type": "array",
+      "description": "Workflow-declared references to external documents. Each reference is a pointer — content is never inlined. Declarations participate in the workflow hash; referenced file content does not.",
+      "items": {
+        "$ref": "#/$defs/workflowReference"
+      },
+      "uniqueItems": true
     }
   },
   "required": [
@@ -189,6 +197,49 @@
       "required": ["slotId", "purpose", "default"],
       "additionalProperties": false
     },
+    "workflowReference": {
+      "type": "object",
+      "description": "A pointer to an external document relevant to the workflow. Content is never inlined — the agent reads the file itself if needed.",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier within the workflow",
+          "pattern": "^[a-z][a-z0-9_-]*$",
+          "minLength": 2,
+          "maxLength": 64
+        },
+        "title": {
+          "type": "string",
+          "description": "Human-readable title for the reference",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "source": {
+          "type": "string",
+          "description": "File path relative to workspace root",
+          "minLength": 1,
+          "maxLength": 512
+        },
+        "purpose": {
+          "type": "string",
+          "description": "Why this reference matters to the workflow",
+          "minLength": 1,
+          "maxLength": 512
+        },
+        "authoritative": {
+          "type": "boolean",
+          "description": "Whether this document is authoritative (agent should follow it strictly)"
+        },
+        "resolveFrom": {
+          "type": "string",
+          "enum": ["workspace", "package"],
+          "description": "Resolution base for source path. 'workspace' (default) resolves against the user's project root. 'package' resolves against the workrail package root (for files shipped with the workflow).",
+          "default": "workspace"
+        }
+      },
+      "required": ["id", "title", "source", "purpose", "authoritative"],
+      "additionalProperties": false
+    },
     "stepId": {
       "type": "string",
       "pattern": "^[a-z0-9-]+$",
@@ -246,7 +297,13 @@
         "functionDefinitions": { "type": "array", "items": { "$ref": "#/$defs/functionDefinition" } },
         "functionCalls": { "type": "array", "items": { "$ref": "#/$defs/functionCall" } },
         "functionReferences": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*\\(\\)$" } },
-        "templateCall": { "$ref": "#/$defs/templateCall" }
+        "templateCall": { "$ref": "#/$defs/templateCall" },
+        "promptFragments": {
+          "type": "array",
+          "description": "Conditional prompt fragments appended to the step's base prompt at render time. Each fragment is appended in declaration order when its 'when' condition matches the session context.",
+          "items": { "$ref": "#/$defs/promptFragment" },
+          "minItems": 1
+        }
       },
       "required": ["id", "title"],
       "additionalProperties": false
@@ -471,8 +528,37 @@
         "not": {
           "$ref": "#/$defs/condition",
           "description": "Logical NOT of a condition"
+        },
+        "in": {
+          "type": "array",
+          "description": "Check if variable value is in this array of allowed values"
+        }
+      },
+      "additionalProperties": false
+    },
+    "promptFragment": {
+      "type": "object",
+      "description": "A conditional prompt fragment appended to a step's base prompt at render time when its condition matches the session context.",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for this fragment within the step",
+          "minLength": 1,
+          "maxLength": 64,
+          "pattern": "^[a-z][a-z0-9_-]*$"
+        },
+        "when": {
+          "$ref": "#/$defs/condition",
+          "description": "Condition evaluated against session context at render time. If absent, fragment is always appended."
+        },
+        "text": {
+          "type": "string",
+          "description": "Prompt text appended when the condition matches. Must not contain {{wr.*}} tokens.",
+          "minLength": 1,
+          "maxLength": 4096
         }
       },
+      "required": ["id", "text"],
       "additionalProperties": false
     },
     "confirmationRule": {