@mmerterden/multi-agent-pipeline 16.23.0 → 16.25.0

package/pipeline/multi-agent-refs/generate-issue.md

@@ -241,11 +241,11 @@ curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application
 ```
 4. **Screenshot / image attachments** (only when opted in during preview  -  Figma render and/or user-pasted images):
 ```bash
-curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "X-Atlassian-Token: no-check" \
-  -F "file=@/tmp/generate-issue-$$-figma.png" \
-  "https://$ACCOUNT_JIRA_HOST/rest/api/2/issue/${NEW_KEY}/attachments"
+bash "$HOME/.claude/scripts/jira-attach.sh" "$NEW_KEY" /tmp/generate-issue-$$-figma.png
 ```
 
+One uploader, shared with visual evidence: two copies of this call is two places for `X-Atlassian-Token: no-check` to go missing, which fails as a 403 that reads like an auth problem. It prints `<filename>\t<url>` per file.
+
 ### [12/12] Report
 
 ```

package/pipeline/multi-agent-refs/phases/phase-0-init.md

@@ -93,6 +93,8 @@ Probe order:
 1. **Tier 1 (Figma MCP)**: check the host serves `mcp__claude_ai_Figma__*` before probing. Absent → set `state.figmaAccess.tier1Unavailable = "host"` and fall through to Tier 2 with no probe, no re-auth retry, no MCP-token question. Present → probe `get_metadata(fileKey, nodeId)` on the first frame; on auth failure run `authenticate` + `complete_authentication` and retry once, and only a *second* failure raises the recreate-or-continue question. Success → `state.figmaAccess.tier = 1`.
 2. **Tier 2 (Figma REST)**: when Tier 1 fails, resolve the PAT via `~/.claude/lib/credential-store.sh get <logical-key>` where `<logical-key>` = `prefs.global.keychainMapping.figma`. Probe `GET https://api.figma.com/v1/files/{fileKey}/nodes?ids={nodeId}` with header `X-Figma-Token: $TOKEN`. HTTP 200 → `state.figmaAccess.tier = 2`. Token missing / 401 / 403 → fall through.
 3. **Tier 3 (User-attached screenshot)**: when Tiers 1 + 2 both fail, scan the task payload for inline screenshots or attachments. Present → `state.figmaAccess.tier = 3` and `state.figmaAccess.reviewBlocking = true` (Phase 4 enforces this).
+
+Save the issue's image attachments to `$WORKTREE/.pipeline/evidence/` as `state.visualEvidence.before[]`: pre-fix evidence, never re-photographed, and none present is a recorded gap rather than a search. See `$HOME/.claude/multi-agent-refs/features/visual-evidence.md`.
 4. **Halt**: all three tiers fail → emit a single AskUserQuestion asking the user how to proceed (provide PAT, paste a screenshot, abort). Never proceed with text-derived guesses.
 
 Record the cause, not just the downshift. `tier1Unavailable = "host"` means the tier never existed here - routine on Copilot and Codex, where the installer registers only `multi-agent-toolkit`. `"auth"` means it existed and the credential failed, which on Claude Code points at a dead `figma_mcp` token worth surfacing in Phase 7. Conflating them costs two wasted MCP round trips and a question the user cannot act on. On those two hosts a mapped `figma` PAT is the primary path, not a fallback.

package/pipeline/multi-agent-refs/phases/phase-3-dev.md

@@ -234,6 +234,10 @@ Gated by `prefs.global.devCritic.enabled` (default: `false`). When enabled, afte
 
 ---
 
+#### Step 3.55  -  Visual evidence capture (UI changes only)
+
+When `state.visualEvidence.required`, capture the fixed state with the build that just went green: `capture-evidence.sh after --task "$TASK_ID" --platform "$PLATFORM" --label <slug>`. Here, not Phase 5, which every autopilot and `--local` entry drops. Exit 4 is a gap, not a failure. See `$HOME/.claude/multi-agent-refs/features/visual-evidence.md`.
+
 #### Step 3.6  -  Code-simplifier pass (required diff shrink, before Phase 4 handoff)
 
 After the build/test green step and BEFORE Phase 4 handoff, run one diff-shrink round (bloated diffs waste Phase 4 reviewer tokens and unfocus the PR).

package/pipeline/multi-agent-refs/phases/phase-5-test.md

@@ -138,6 +138,7 @@ Before or during user testing, run device-level audits via Bash if user requests
 
 | Check               | When              | Command                                   |
 | ------------------- | ----------------- | ----------------------------------------- |
+| UI flow video       | `state.visualEvidence.required` | 3 tiers, cap from `capture-evidence.sh limits` (`visualEvidence.maxVideoSeconds`)  -  `$HOME/.claude/multi-agent-refs/features/visual-evidence.md` |
 | Accessibility audit | UI changes        | `mcp__multi-agent-toolkit__{ios,android}_accessibility_audit` |
 | Biometric test      | Auth flow changes | ios: `mcp__multi-agent-toolkit__ios_biometric` (android: manual) |
 | Launch time         | Perf-sensitive changes | ios: app-launch instrument · android: `mcp__multi-agent-toolkit__android_launch_time` |

package/pipeline/multi-agent-refs/phases/phase-6-commit.md

@@ -136,7 +136,7 @@ Branch **deterministically**, no implicit fallback. Read `agent-state.json` and
 
 Generate a structured PR description based on task type. The PR body targets **code reviewers**  -  it should be technical: what changed, why, architecture decisions, how to verify.
 
-Two inputs are read from state and the worktree before writing, not recalled from the conversation: `$WORKTREE/.pipeline/scope-check.json` (Phase 3 Step 3.7) supplies the `## Changes` bullets from `files[].reason` and the "Follow-ups not done in this PR" list under `## Related` from `notDone[]`; `state.diffRisk.signals` (Phase 4 Step 1.75) decides whether the conditional `## Risk and Security` section is required. When a high-stakes signal is present and the section is missing, this step blocks until it is written; a placeholder answer ("TBD") counts as missing.
+Two inputs are read from state and the worktree before writing, not recalled from the conversation: `$WORKTREE/.pipeline/scope-check.json` (Phase 3 Step 3.7) supplies the `## Changes` bullets from `files[].reason` and the "Follow-ups not done in this PR" list under `## Related` from `notDone[]`; `state.diffRisk.signals` (Phase 4 Step 1.75) decides whether the conditional `## Risk and Security` section is required. When a high-stakes signal is present and the section is missing, this step blocks until it is written; a placeholder answer ("TBD") counts as missing. `state.visualEvidence.required` blocks the same way: every required artefact is either attached or carries a recorded reason in `gaps[]` - the gate is against silence, not against an honest "no image on the ticket".
 
 **required**: Run all generated text (PR body, commit message) through the `humanizer` skill before posting. This removes AI-generated patterns (inflated language, filler phrases, repetitive structure) and makes the output sound like a developer wrote it.
 

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

@@ -272,7 +272,9 @@
         },
         "docPath": {
           "type": "array",
-          "items": { "type": "string" },
+          "items": {
+            "type": "string"
+          },
           "description": "One emitted path per selected platform."
         },
         "frontMatter": {
@@ -604,7 +606,9 @@
             },
             "failing": {
               "type": "array",
-              "items": { "type": "string" },
+              "items": {
+                "type": "string"
+              },
               "description": "Identifiers of tests already failing before this run. Empty on a red status means the output could not be parsed into names: the evidence is then the logPath alone, and Phase 4 reports 'inherited red, not attributable' rather than inventing a set."
             },
             "logPath": {
@@ -655,17 +659,28 @@
             "additionalProperties": true,
             "description": "Written by Phase 4 Step 3.8 from review-delta.mjs: how this round's accepted findings relate to the previous round's rework mandate. Absent on iteration 1 and on runs from before the delta existed.",
             "properties": {
-              "previousIteration": { "type": "integer", "minimum": 1 },
+              "previousIteration": {
+                "type": "integer",
+                "minimum": 1
+              },
               "new": {
                 "type": "array",
                 "items": {
                   "type": "object",
                   "additionalProperties": true,
                   "properties": {
-                    "fingerprint": { "type": "string" },
-                    "severity": { "type": ["string", "null"] },
-                    "file": { "type": ["string", "null"] },
-                    "issue": { "type": ["string", "null"] }
+                    "fingerprint": {
+                      "type": "string"
+                    },
+                    "severity": {
+                      "type": ["string", "null"]
+                    },
+                    "file": {
+                      "type": ["string", "null"]
+                    },
+                    "issue": {
+                      "type": ["string", "null"]
+                    }
                   }
                 }
               },
@@ -675,10 +690,18 @@
                   "type": "object",
                   "additionalProperties": true,
                   "properties": {
-                    "fingerprint": { "type": "string" },
-                    "severity": { "type": ["string", "null"] },
-                    "file": { "type": ["string", "null"] },
-                    "issue": { "type": ["string", "null"] }
+                    "fingerprint": {
+                      "type": "string"
+                    },
+                    "severity": {
+                      "type": ["string", "null"]
+                    },
+                    "file": {
+                      "type": ["string", "null"]
+                    },
+                    "issue": {
+                      "type": ["string", "null"]
+                    }
                   }
                 }
               },
@@ -688,10 +711,18 @@
                   "type": "object",
                   "additionalProperties": true,
                   "properties": {
-                    "fingerprint": { "type": "string" },
-                    "severity": { "type": ["string", "null"] },
-                    "file": { "type": ["string", "null"] },
-                    "issue": { "type": ["string", "null"] }
+                    "fingerprint": {
+                      "type": "string"
+                    },
+                    "severity": {
+                      "type": ["string", "null"]
+                    },
+                    "file": {
+                      "type": ["string", "null"]
+                    },
+                    "issue": {
+                      "type": ["string", "null"]
+                    }
                   }
                 }
               },
@@ -701,10 +732,18 @@
                   "type": "object",
                   "additionalProperties": true,
                   "properties": {
-                    "fingerprint": { "type": "string" },
-                    "severity": { "type": ["string", "null"] },
-                    "file": { "type": ["string", "null"] },
-                    "issue": { "type": ["string", "null"] }
+                    "fingerprint": {
+                      "type": "string"
+                    },
+                    "severity": {
+                      "type": ["string", "null"]
+                    },
+                    "file": {
+                      "type": ["string", "null"]
+                    },
+                    "issue": {
+                      "type": ["string", "null"]
+                    }
                   }
                 }
               },
@@ -714,24 +753,40 @@
                   "type": "object",
                   "additionalProperties": true,
                   "properties": {
-                    "fingerprint": { "type": "string" },
-                    "severity": { "type": ["string", "null"] },
-                    "file": { "type": ["string", "null"] },
-                    "issue": { "type": ["string", "null"] }
+                    "fingerprint": {
+                      "type": "string"
+                    },
+                    "severity": {
+                      "type": ["string", "null"]
+                    },
+                    "file": {
+                      "type": ["string", "null"]
+                    },
+                    "issue": {
+                      "type": ["string", "null"]
+                    }
                   }
                 }
               },
               "recurrence": {
                 "type": "object",
-                "additionalProperties": { "type": "integer", "minimum": 1 },
+                "additionalProperties": {
+                  "type": "integer",
+                  "minimum": 1
+                },
                 "description": "fingerprint -> consecutive rework cycles the finding has survived."
               },
               "plateau": {
                 "type": "boolean",
                 "description": "The still-present set is unchanged from the previous delta and non-empty."
               },
-              "tripped": { "type": "boolean" },
-              "computedAt": { "type": "string", "format": "date-time" }
+              "tripped": {
+                "type": "boolean"
+              },
+              "computedAt": {
+                "type": "string",
+                "format": "date-time"
+              }
             }
           },
           "reviewers": {
@@ -768,7 +823,9 @@
               },
               "labelToModel": {
                 "type": "object",
-                "additionalProperties": { "type": "string" },
+                "additionalProperties": {
+                  "type": "string"
+                },
                 "description": "Source A|B|C -> model name. \"unknown\" for a reviewer entry that declared no model."
               }
             }
@@ -789,25 +846,51 @@
       "description": "Autopilot circuit-breaker record (refs/features/autopilot-circuit-breaker.md). Written only when a trigger trips: trigger 2 by Phase 4 Step 3.8 (a mandate finding survived identicalFindingCycles rework cycles), trigger 3 by the Phase 3 re-entry hard-kill. /multi-agent:resume clears tripped and keeps counters.",
       "required": ["tripped"],
       "properties": {
-        "tripped": { "type": "boolean" },
-        "trigger": { "type": ["integer", "null"], "minimum": 1, "maximum": 5 },
-        "detail": { "type": "string" },
+        "tripped": {
+          "type": "boolean"
+        },
+        "trigger": {
+          "type": ["integer", "null"],
+          "minimum": 1,
+          "maximum": 5
+        },
+        "detail": {
+          "type": "string"
+        },
         "checkpoint": {
           "type": "object",
           "additionalProperties": false,
           "properties": {
-            "phase": { "type": "integer", "minimum": 0, "maximum": 7 },
-            "step": { "type": "string" },
-            "iteration": { "type": "integer", "minimum": 1 }
+            "phase": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 7
+            },
+            "step": {
+              "type": "string"
+            },
+            "iteration": {
+              "type": "integer",
+              "minimum": 1
+            }
           }
         },
-        "trippedAt": { "type": "string", "format": "date-time" },
+        "trippedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
         "counters": {
           "type": "object",
           "additionalProperties": false,
           "properties": {
-            "identicalFindingCycles": { "type": "integer", "minimum": 0 },
-            "reworkCycles": { "type": "integer", "minimum": 0 }
+            "identicalFindingCycles": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "reworkCycles": {
+              "type": "integer",
+              "minimum": 0
+            }
           }
         }
       }
@@ -817,13 +900,26 @@
       "additionalProperties": true,
       "description": "Totals from diff-risk-score.mjs, persisted by Phase 4 Step 1.75 so Phase 6 (PR risk section), Phase 7 and run-metrics.mjs read the same numbers the review scope decision used.",
       "properties": {
-        "files": { "type": "integer", "minimum": 0 },
-        "loc_added": { "type": "integer", "minimum": 0 },
-        "loc_removed": { "type": "integer", "minimum": 0 },
-        "max_score": { "type": "number" },
+        "files": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "loc_added": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "loc_removed": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "max_score": {
+          "type": "number"
+        },
         "signals": {
           "type": "array",
-          "items": { "type": "string" },
+          "items": {
+            "type": "string"
+          },
           "description": "Distinct signal names seen across files (security_path, migration, public_api, no_test_change, test_lines_removed, ...)."
         }
       }
@@ -1001,6 +1097,137 @@
     "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."
+    },
+    "visualEvidence": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "description": "Before/after screenshots and the UI flow video for a UI change, attached to the Jira issue and rendered in the Phase 7 comment and the PR body. Required decided mechanically from taskType plus the changed-file list. Contract: multi-agent-refs/features/visual-evidence.md.",
+      "properties": {
+        "required": {
+          "type": "boolean"
+        },
+        "requiredBy": {
+          "type": "string",
+          "description": "Which rule made it required, e.g. 'bugfix + ui-file-changed'."
+        },
+        "platform": {
+          "type": "string",
+          "enum": ["ios", "android", "web", "other"]
+        },
+        "before": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+              "file": {
+                "type": "string",
+                "description": "Local path under $WORKTREE/.pipeline/evidence/."
+              },
+              "source": {
+                "type": "string",
+                "enum": ["ticket", "capture"]
+              },
+              "capturedAt": {
+                "type": "string",
+                "description": "Phase that produced it, e.g. 'phase-3'."
+              },
+              "jiraFilename": {
+                "type": "string",
+                "description": "Attachment filename the Jira comment references."
+              },
+              "url": {
+                "type": "string",
+                "description": "Jira attachment content URL."
+              }
+            }
+          },
+          "description": "Images taken from the issue's own attachments. The pipeline never rebuilds the pre-fix state to photograph it; no ticket image means no before, recorded as a gap."
+        },
+        "after": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+              "file": {
+                "type": "string",
+                "description": "Local path under $WORKTREE/.pipeline/evidence/."
+              },
+              "source": {
+                "type": "string",
+                "enum": ["ticket", "capture"]
+              },
+              "capturedAt": {
+                "type": "string",
+                "description": "Phase that produced it, e.g. 'phase-3'."
+              },
+              "jiraFilename": {
+                "type": "string",
+                "description": "Attachment filename the Jira comment references."
+              },
+              "url": {
+                "type": "string",
+                "description": "Jira attachment content URL."
+              }
+            }
+          },
+          "description": "Captured in Phase 3 after the build+test gate, because Phase 5 is dropped by every autopilot and --local entry."
+        },
+        "videoTier": {
+          "type": ["integer", "null"],
+          "enum": [1, 2, 3, null],
+          "description": "1 = the repo's own UI test target drove the flow, 2 = MCP-driven flow, 3 = no runnable build."
+        },
+        "video": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "file": {
+              "type": "string",
+              "description": "Local path under $WORKTREE/.pipeline/evidence/."
+            },
+            "source": {
+              "type": "string",
+              "enum": ["ticket", "capture"]
+            },
+            "capturedAt": {
+              "type": "string",
+              "description": "Phase that produced it, e.g. 'phase-3'."
+            },
+            "jiraFilename": {
+              "type": "string",
+              "description": "Attachment filename the Jira comment references."
+            },
+            "url": {
+              "type": "string",
+              "description": "Jira attachment content URL."
+            },
+            "seconds": {
+              "type": "number",
+              "description": "Recorded duration; capped at 60."
+            }
+          }
+        },
+        "gaps": {
+          "type": "array",
+          "description": "Every artefact that is required and absent, with its reason. A recorded reason satisfies the Phase 6 blocker; silence does not.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "what": {
+                "type": "string",
+                "enum": ["before", "after", "video"]
+              },
+              "reason": {
+                "type": "string"
+              }
+            },
+            "required": ["what", "reason"]
+          }
+        }
+      }
     }
   }
 }