@exaudeus/workrail 3.73.2 → 3.74.0

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-04-22",
+  "lastReviewed": "2026-04-28",
   "principles": [
     "Schema defines what is valid. These rules define what is good.",
     "Prefer current authoring rules over design rationale or historical notes.",
@@ -189,6 +189,10 @@
       "id": "artifact.verification",
       "description": "Verification or handoff artifacts"
     },
+    {
+      "id": "artifact.coordinator-result",
+      "description": "wr.coordinator_result artifact emitted by coordinator-phase workflows to signal phase completion to the coordinator"
+    },
     {
       "id": "delegation.context-packet",
       "description": "Structured context passed to subagents"
@@ -1429,6 +1433,37 @@
       "id": "artifacts",
       "title": "Artifacts and planning surfaces",
       "rules": [
+        {
+          "id": "coordinator-result-artifact-schema",
+          "status": "active",
+          "level": "required",
+          "scope": [
+            "artifact.coordinator-result"
+          ],
+          "rule": "When a workflow step signals coordinator phase completion, emit a `wr.coordinator_result` artifact with exactly 4 fields: `outcome` (enum: success|failed|timed_out|await_degraded), `summary` (string), `sessionId` (string), `error` (string|null). No additional fields allowed.",
+          "why": "Coordinators read this artifact to determine whether to proceed, retry, or escalate. Extra fields pollute the schema boundary and break forward compatibility. The 4-field constraint is a hard limit, not a guideline.",
+          "enforcement": [
+            "advisory"
+          ],
+          "checks": [
+            "Exactly 4 fields present: outcome, summary, sessionId, error.",
+            "outcome is one of: success, failed, timed_out, await_degraded.",
+            "error is string|null -- null when outcome is success, non-null string when outcome is failed.",
+            "No workflow-specific fields (prUrl, branchName, commitSha, etc.) in wr.coordinator_result. Those belong in workflow-specific artifacts."
+          ],
+          "antiPatterns": [
+            "Adding prUrl, branchName, or commitSha to wr.coordinator_result",
+            "Using a free-form notes string instead of the typed outcome enum",
+            "Omitting sessionId (required for coordinator tracing and console parent-child display)"
+          ],
+          "sourceRefs": [
+            {
+              "kind": "runtime",
+              "path": "src/coordinators/types.ts",
+              "note": "ChildSessionResult discriminated union -- the runtime type that wr.coordinator_result maps to."
+            }
+          ]
+        },
         {
           "id": "artifact-canonicality",
           "status": "active",