@mmerterden/multi-agent-pipeline 13.5.1 → 14.1.0

package/pipeline/schemas/agent-state.schema.json

@@ -42,9 +42,16 @@
       "type": ["object", "null"],
       "additionalProperties": false,
       "properties": {
-        "owner": { "type": "string" },
-        "repo": { "type": "string" },
-        "number": { "type": "integer", "minimum": 1 }
+        "owner": {
+          "type": "string"
+        },
+        "repo": {
+          "type": "string"
+        },
+        "number": {
+          "type": "integer",
+          "minimum": 1
+        }
       },
       "required": ["owner", "repo", "number"],
       "description": "GitHub issue coordinates if the task originated from GitHub, else null."
@@ -61,8 +68,14 @@
       "type": ["string", "null"],
       "description": "Absolute path to the task worktree. Null in --local mode."
     },
-    "branch": { "type": "string", "description": "Working branch for this task." },
-    "baseBranch": { "type": "string", "description": "PR target branch (e.g. develop, main)." },
+    "branch": {
+      "type": "string",
+      "description": "Working branch for this task."
+    },
+    "baseBranch": {
+      "type": "string",
+      "description": "PR target branch (e.g. develop, main)."
+    },
     "remoteType": {
       "type": "string",
       "enum": ["github", "bitbucket"],
@@ -79,8 +92,14 @@
       "enum": ["in_progress", "paused", "complete", "failed"],
       "description": "Overall task status."
     },
-    "startedAt": { "type": "string", "format": "date-time" },
-    "finishedAt": { "type": ["string", "null"], "format": "date-time" },
+    "startedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "finishedAt": {
+      "type": ["string", "null"],
+      "format": "date-time"
+    },
     "haltReason": {
       "type": ["string", "null"],
       "description": "Set when a phase halts on a hard error (validator failed twice, no subagent returned, dispatch error past fallback, lock irrecoverable). Format '<phase>:<cause>'. Surfaced to the user and cleared on successful resume. See operations.md 'Halt visibility'."
@@ -88,7 +107,7 @@
     "telemetry": {
       "type": "object",
       "additionalProperties": true,
-      "description": "Run telemetry. mcpCalls[] is consumed by smoke-no-mcp-in-dev-phases.sh to enforce the 'no MCP outside analysis' contract  -  every mcp__* invocation MUST append an entry tagged with the phase it ran in.",
+      "description": "Run telemetry. mcpCalls[] is consumed by smoke-no-mcp-in-dev-phases.sh to enforce the 'no MCP outside analysis' contract  -  every mcp__* invocation MUST append an entry tagged with the phase it ran in. skillCalls[] is Phase 3's self-report of which skills, plugin skills and guides it consulted; Phase 4 Step 1.78 reads it as CORROBORATING evidence only and never computes coverage from it.",
       "properties": {
         "mcpCalls": {
           "type": "array",
@@ -107,17 +126,60 @@
                 "maximum": 7,
                 "description": "Pipeline phase the call ran in. Only 0 (init) and 1 (analysis) are permitted."
               },
-              "timestamp": { "type": "string", "description": "ISO-8601 time of the call." }
+              "timestamp": {
+                "type": "string",
+                "description": "ISO-8601 time of the call."
+              }
+            }
+          }
+        },
+        "skillCalls": {
+          "type": "array",
+          "description": "One entry per skill / plugin skill / stack guide consulted while writing code. Append at the moment of consultation, not retrospectively. This is a self-report and shares the known weakness of mcpCalls[]: an unrecorded consultation and no consultation are byte-identical here, so Step 1.78 treats the deterministic resolver as primary, defaults ledger.source to 'derived', and flags a declared skill it cannot bind to a changed file. Recording it still earns its keep - it is the only signal that distinguishes 'the dev phase applied X to the wrong files' from 'X was never opened'.",
+          "items": {
+            "type": "object",
+            "required": ["skill", "phase", "targetFiles"],
+            "additionalProperties": true,
+            "properties": {
+              "skill": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Skill name as invoked, e.g. ios-coding-standard, ai-ios-engineering-toolkit:create-component, or a guide path for a stack guide."
+              },
+              "phase": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 7,
+                "description": "Phase the consultation happened in. Normally 3."
+              },
+              "targetFiles": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Files the skill was actually applied to. REQUIRED: without it coverage cannot be attributed, because a skill applied to the wrong files still reads as 'applied'."
+              },
+              "timestamp": {
+                "type": "string",
+                "description": "ISO-8601 time of the consultation."
+              },
+              "routedBy": {
+                "type": "string",
+                "description": "Set when a stack toolkit's own index skill chose this skill, as '<toolkit>:index@<version>'. Recorded so a finding can be traced to the index version that selected it  -  the skill set differs between plugin versions. Phase 4 Step 1.78 surfaces these separately in the manifest ledger; it does NOT grant them extra trust, because the resolver stays primary either way."
+              }
             }
           }
         }
       }
     },
-    "autopilot": { "type": "boolean", "default": false },
+    "autopilot": {
+      "type": "boolean",
+      "default": false
+    },
     "onlyDevelop": {
       "type": "boolean",
       "default": false,
-      "description": "--dev flag  -  phases 1, 2, 4, 5 are skipped."
+      "description": "--dev flag  -  phases 1 and 2 are skipped. Phase 4 Review runs (v14.0.0+); Phase 5 is skipped only in the autopilot/local variants, which drop the interactive test gate."
     },
     "localMode": {
       "type": "boolean",
@@ -133,22 +195,62 @@
       "type": ["string", "null"],
       "description": "Pipeline mode for this run (e.g. 'dev', 'local', 'design-check'). Absent = full pipeline."
     },
+    "figmaAccess": {
+      "type": ["object", "null"],
+      "additionalProperties": true,
+      "description": "Resolved Figma ground-truth tier for this run, established in Phase 0 and read by every phase that consumes or verifies a design reference (see the Figma Access Tier rule in multi-agent-refs/rules.md). Absent when the task references no Figma frame.",
+      "properties": {
+        "tier": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 3,
+          "description": "1 = Figma MCP, 2 = Figma REST with the `figma` PAT, 3 = user-attached screenshot."
+        },
+        "tier1Unavailable": {
+          "type": ["string", "null"],
+          "enum": ["host", "auth", null],
+          "description": "Why Tier 1 was not used, when it was not. 'host' = this CLI does not serve the mcp__claude_ai_Figma__* tools (the normal case on Copilot CLI and Codex CLI, since the installer registers only dev-toolkit) and no re-auth was attempted. 'auth' = the tools were served but authentication failed after one retry. The distinction matters downstream: Tier 2 on Codex is routine, Tier 2 on Claude Code points at a dead figma_mcp token worth surfacing."
+        },
+        "reviewBlocking": {
+          "type": "boolean",
+          "default": false,
+          "description": "Set with tier 3. Phase 4 holds the run at review_blocking until a human signs off on the component choice."
+        }
+      }
+    },
     "designCheck": {
       "type": ["object", "null"],
       "additionalProperties": true,
       "description": "State for a /multi-agent:design-check run. Populated in Phase 0 (mock feasibility, scenario inventory, scope), Phase 2 (Figma variants) and Phase 3 (captures, skips, findings).",
       "properties": {
-        "module": { "type": "string", "description": "Module / submodule path being audited." },
-        "platform": { "type": "string", "enum": ["ios", "android"] },
+        "module": {
+          "type": "string",
+          "description": "Module / submodule path being audited."
+        },
+        "platform": {
+          "type": "string",
+          "enum": ["ios", "android"]
+        },
         "mock": {
           "type": "object",
           "additionalProperties": true,
           "description": "design_mock_detect result.",
           "properties": {
-            "supported": { "description": "true | false | 'debug-only'" },
-            "mechanism": { "type": ["string", "null"] },
-            "activation": { "type": ["object", "null"] },
-            "variantsHint": { "type": "array", "items": { "type": "string" } }
+            "supported": {
+              "description": "true | false | 'debug-only'"
+            },
+            "mechanism": {
+              "type": ["string", "null"]
+            },
+            "activation": {
+              "type": ["object", "null"]
+            },
+            "variantsHint": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
           }
         },
         "inventory": {
@@ -156,18 +258,31 @@
           "additionalProperties": true,
           "description": "design_scenario_inventory result, persisted verbatim. THIS is the audit's target set  -  Phase 3 iterates it and Phase 4 gates on it. Never re-derive it by reading the repo.",
           "properties": {
-            "targetCount": { "type": "integer" },
+            "targetCount": {
+              "type": "integer"
+            },
             "targets": {
               "type": "array",
-              "items": { "type": "object", "additionalProperties": true },
+              "items": {
+                "type": "object",
+                "additionalProperties": true
+              },
               "description": "{ id, kind, label, screen, driver, evidence } per state driver (launch-arg / scenario-case / code-scenario / fixture / deep-link)."
             },
             "groups": {
               "type": "array",
-              "items": { "type": "object", "additionalProperties": true }
+              "items": {
+                "type": "object",
+                "additionalProperties": true
+              }
+            },
+            "byKind": {
+              "type": "object",
+              "additionalProperties": true
             },
-            "byKind": { "type": "object", "additionalProperties": true },
-            "truncated": { "type": "boolean" }
+            "truncated": {
+              "type": "boolean"
+            }
           }
         },
         "scope": {
@@ -179,23 +294,36 @@
               "type": ["string", "null"],
               "description": "Raw $ARGUMENTS as given (empty = whole module, '--resume' = remainder of the last run)."
             },
-            "targetIds": { "type": "array", "items": { "type": "string" } },
+            "targetIds": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
             "resumedFrom": {
               "type": ["string", "null"],
               "description": "Report dir of the run this scope resumes, when --resume was used."
             }
           }
         },
-        "figmaUrl": { "type": ["string", "null"] },
+        "figmaUrl": {
+          "type": ["string", "null"]
+        },
         "variants": {
           "type": "array",
           "description": "Mapped variants with their Figma spec, capture, and findings.",
-          "items": { "type": "object", "additionalProperties": true }
+          "items": {
+            "type": "object",
+            "additionalProperties": true
+          }
         },
         "captured": {
           "type": "array",
           "description": "Every capture taken, appended and persisted as it happens so a dying run is resumable. One entry per screenshot, keyed to the target that produced it ('<targetId>', or '<targetId>#<sub-label>' for tap-reachable sub-states).",
-          "items": { "type": "object", "additionalProperties": true }
+          "items": {
+            "type": "object",
+            "additionalProperties": true
+          }
         },
         "skipped": {
           "type": "array",
@@ -205,9 +333,16 @@
             "additionalProperties": true,
             "required": ["id", "reason"],
             "properties": {
-              "id": { "type": "string" },
-              "group": { "type": ["string", "null"] },
-              "reason": { "type": "string", "minLength": 1 }
+              "id": {
+                "type": "string"
+              },
+              "group": {
+                "type": ["string", "null"]
+              },
+              "reason": {
+                "type": "string",
+                "minLength": 1
+              }
             }
           }
         },
@@ -216,13 +351,31 @@
           "additionalProperties": true,
           "description": "design_report coverage verdict for this run. gate='fail' means the run is INCOMPLETE and must be reported as such, with the unaccounted ids and the --resume command.",
           "properties": {
-            "gate": { "type": "string", "enum": ["pass", "fail"] },
-            "audited": { "type": "integer" },
-            "target": { "type": "integer" },
-            "pct": { "type": "number" },
-            "skippedWithReason": { "type": "integer" },
-            "unaccounted": { "type": "integer" },
-            "unaccountedIds": { "type": "array", "items": { "type": "string" } }
+            "gate": {
+              "type": "string",
+              "enum": ["pass", "fail"]
+            },
+            "audited": {
+              "type": "integer"
+            },
+            "target": {
+              "type": "integer"
+            },
+            "pct": {
+              "type": "number"
+            },
+            "skippedWithReason": {
+              "type": "integer"
+            },
+            "unaccounted": {
+              "type": "integer"
+            },
+            "unaccountedIds": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
           }
         },
         "reportDir": {
@@ -236,8 +389,13 @@
       "additionalProperties": false,
       "required": ["name", "email"],
       "properties": {
-        "name": { "type": "string" },
-        "email": { "type": "string", "format": "email" },
+        "name": {
+          "type": "string"
+        },
+        "email": {
+          "type": "string",
+          "format": "email"
+        },
         "username": {
           "type": "string",
           "description": "SCM username (GitHub/Bitbucket). Used to filter out PR author from reviewer list."
@@ -256,20 +414,36 @@
               "type": "string",
               "enum": ["pending", "in_progress", "done", "skipped", "failed"]
             },
-            "startedAt": { "type": "string", "format": "date-time" },
-            "finishedAt": { "type": "string", "format": "date-time" },
-            "model": { "type": "string" },
+            "startedAt": {
+              "type": "string",
+              "format": "date-time"
+            },
+            "finishedAt": {
+              "type": "string",
+              "format": "date-time"
+            },
+            "model": {
+              "type": "string"
+            },
             "files": {
               "type": "array",
-              "items": { "type": "string" },
+              "items": {
+                "type": "string"
+              },
               "description": "Files produced or modified by this phase. Used for semantic revert."
             },
-            "retryCount": { "type": "integer", "minimum": 0, "maximum": 3 },
+            "retryCount": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 3
+            },
             "subStep": {
               "type": "string",
               "description": "Sub-step checkpoint for long phases (3, 7) so resume re-does only the unfinished tail instead of the whole phase. Short token, e.g. 'red'|'green'|'build'|'pr-opened'|'confluence-synced'. See operations.md 'Sub-step checkpoints'."
             },
-            "notes": { "type": "string" },
+            "notes": {
+              "type": "string"
+            },
             "clarificationRounds": {
               "type": "integer",
               "minimum": 0,
@@ -278,12 +452,16 @@
             },
             "clarificationQuestions": {
               "type": "array",
-              "items": { "type": "string" },
+              "items": {
+                "type": "string"
+              },
               "description": "v5.3.0 Phase 2  -  ordered log of questions the orchestrator asked the user when the issue description was ambiguous (missing acceptance criteria, vague language, missing Figma/endpoint links, unclear scope vs. parent story)."
             },
             "clarificationAnswers": {
               "type": "array",
-              "items": { "type": "string" },
+              "items": {
+                "type": "string"
+              },
               "description": "v5.3.0 Phase 2  -  ordered log of user answers aligned with clarificationQuestions (same length)."
             },
             "planIterations": {
@@ -298,7 +476,9 @@
             },
             "planEditRequests": {
               "type": "array",
-              "items": { "type": "string" },
+              "items": {
+                "type": "string"
+              },
               "description": "v5.3.0 Phase 2  -  free-text edit instructions the user typed between plan renders. Preserved verbatim for audit; the planning model (Fable top tier) parses them conversationally to revise the plan."
             }
           }
@@ -312,14 +492,35 @@
         "description": "Per-iteration review record. It accretes fields across phases - summary counts in Phase 4, plus the merged reviewers[] and triage{} detail and validatorResult that run-metrics.mjs and Phase 7 read - so extra keys are allowed.",
         "additionalProperties": true,
         "properties": {
-          "iteration": { "type": "integer", "minimum": 1 },
-          "blocking": { "type": "integer", "minimum": 0 },
-          "important": { "type": "integer", "minimum": 0 },
-          "suggestion": { "type": "integer", "minimum": 0 },
-          "decision": { "type": "string", "enum": ["fix", "accept", "escalate"] },
-          "reviewers": { "type": "array" },
-          "triage": { "type": "object" },
-          "accepted": { "type": "array" },
+          "iteration": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "blocking": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "important": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "suggestion": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "decision": {
+            "type": "string",
+            "enum": ["fix", "accept", "escalate"]
+          },
+          "reviewers": {
+            "type": "array"
+          },
+          "triage": {
+            "type": "object"
+          },
+          "accepted": {
+            "type": "array"
+          },
           "validatorResult": {}
         }
       }
@@ -336,17 +537,27 @@
       "type": ["object", "null"],
       "additionalProperties": false,
       "properties": {
-        "number": { "type": "integer", "minimum": 1 },
-        "url": { "type": "string", "format": "uri" },
+        "number": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "url": {
+          "type": "string",
+          "format": "uri"
+        },
         "version": {
           "type": "integer",
           "minimum": 0,
           "description": "Bitbucket PR version  -  must increment by 1 per PUT."
         },
-        "draft": { "type": "boolean" },
+        "draft": {
+          "type": "boolean"
+        },
         "reviewers": {
           "type": "array",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         }
       }
     },
@@ -354,8 +565,13 @@
       "type": ["object", "null"],
       "additionalProperties": false,
       "properties": {
-        "sha": { "type": "string", "minLength": 7 },
-        "message": { "type": "string" }
+        "sha": {
+          "type": "string",
+          "minLength": 7
+        },
+        "message": {
+          "type": "string"
+        }
       }
     },
     "projects": {
@@ -368,11 +584,21 @@
         "additionalProperties": false,
         "required": ["project", "projectRoot", "branch", "baseBranch", "identity"],
         "properties": {
-          "project": { "type": "string" },
-          "projectRoot": { "type": "string" },
-          "worktreePath": { "type": ["string", "null"] },
-          "branch": { "type": "string" },
-          "baseBranch": { "type": "string" },
+          "project": {
+            "type": "string"
+          },
+          "projectRoot": {
+            "type": "string"
+          },
+          "worktreePath": {
+            "type": ["string", "null"]
+          },
+          "branch": {
+            "type": "string"
+          },
+          "baseBranch": {
+            "type": "string"
+          },
           "remoteType": {
             "type": "string",
             "enum": ["github", "bitbucket", "gitlab", "generic-git"]
@@ -382,9 +608,16 @@
             "additionalProperties": false,
             "required": ["name", "email"],
             "properties": {
-              "name": { "type": "string" },
-              "email": { "type": "string", "format": "email" },
-              "username": { "type": "string" }
+              "name": {
+                "type": "string"
+              },
+              "email": {
+                "type": "string",
+                "format": "email"
+              },
+              "username": {
+                "type": "string"
+              }
             }
           },
           "platform": {
@@ -396,17 +629,30 @@
             "type": ["object", "null"],
             "additionalProperties": false,
             "properties": {
-              "sha": { "type": "string", "minLength": 7 },
-              "message": { "type": "string" }
+              "sha": {
+                "type": "string",
+                "minLength": 7
+              },
+              "message": {
+                "type": "string"
+              }
             }
           },
           "pr": {
             "type": ["object", "null"],
             "additionalProperties": false,
             "properties": {
-              "number": { "type": "integer", "minimum": 1 },
-              "url": { "type": "string", "format": "uri" },
-              "draft": { "type": "boolean" }
+              "number": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "url": {
+                "type": "string",
+                "format": "uri"
+              },
+              "draft": {
+                "type": "boolean"
+              }
             }
           },
           "pushAttempts": {
@@ -417,20 +663,41 @@
           "buildStatus": {
             "description": "Latest Phase 3 build outcome for this repo. A string in early phases ('pending'/'green'/'passed'/'failed') or null before any attempt; once Phase 3 runs a build it becomes a {ok, attempts, lastError} object (see phase-3-dev.md). run-metrics.mjs reads both the string and object forms.",
             "anyOf": [
-              { "type": "string", "enum": ["pending", "passed", "failed", "green"] },
-              { "type": "null" },
+              {
+                "type": "string",
+                "enum": ["pending", "passed", "failed", "green"]
+              },
+              {
+                "type": "null"
+              },
               {
                 "type": "object",
                 "properties": {
-                  "ok": { "type": "boolean" },
-                  "attempts": { "type": "integer", "minimum": 0 },
-                  "lastError": { "type": ["string", "null"] }
+                  "ok": {
+                    "type": "boolean"
+                  },
+                  "attempts": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "lastError": {
+                    "type": ["string", "null"]
+                  }
                 }
               }
             ]
           }
         }
       }
+    },
+    "worktreeRemovedAt": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "Set when Phase 6 removed the worktree after opening the PR. Its presence is what tells :resume, :status and :log that a worktree-less task is finished-and-tidied rather than broken  -  without it a missing worktree is indistinguishable from a killed run."
+    },
+    "artifactsPath": {
+      "type": ["string", "null"],
+      "description": "Directory the worktree's artefacts were salvaged into before removal (agent-state, phase-tracker, triage-output, .pipeline/, build+test logs, review diff). Phase 7 and :resume read from here when worktreePath is gone."
     }
   }
 }