@mmerterden/multi-agent-pipeline 8.6.2 → 10.2.0

package/pipeline/preferences-template.json

@@ -43,7 +43,12 @@
       "autoDiff": false,
       "manualNote": false
     },
-    "wikiScope": ["main", "ios", "screenshots", "index"],
+    "wikiScope": [
+      "main",
+      "ios",
+      "screenshots",
+      "index"
+    ],
     "autopilotReportTimeoutSeconds": 1800,
     "promptLanguage": "en",
     "outputLanguage": "en",
@@ -52,6 +57,19 @@
       "samplePct": 10,
       "model": "sonnet",
       "blockOnDisagreement": false
+    },
+    "modelFallback": {
+      "enabled": true,
+      "premiumTierUntil": null,
+      "fallbackModel": "sonnet",
+      "onDispatchError": true
+    },
+    "costBudget": {
+      "enabled": true,
+      "maxUsd": 5.0,
+      "warnPct": 80,
+      "onExceed": "warn",
+      "pricingModel": "opus"
     }
   },
   "projects": {},
@@ -71,8 +89,14 @@
       "mcpEnabled": false
     },
     "submodules": {
-      "common": { "path": "", "branch": "develop" },
-      "uicomponents": { "path": "", "branch": "develop" },
+      "common": {
+        "path": "",
+        "branch": "develop"
+      },
+      "uicomponents": {
+        "path": "",
+        "branch": "develop"
+      },
       "wiki": null
     },
     "board": {
@@ -129,4 +153,4 @@
       "overrides": {}
     }
   }
-}
+}

package/pipeline/rules/app-store-guidelines.md

@@ -6,7 +6,7 @@
 - Ensure all metadata, screenshots, and previews are complete and accurate
 - Provide a demo account if your app requires login
 - Enable backend services during review
-- Use TestFlight for beta distribution — not the App Store
+- Use TestFlight for beta distribution  -  not the App Store
 - Include detailed App Review notes for non-obvious features or IAPs
 
 ### 1. Safety
@@ -18,7 +18,7 @@
 
 ### 2. Performance
 
-- Submit only final builds — no placeholder content
+- Submit only final builds  -  no placeholder content
 - Screenshots must show app in use; name limit 30 chars
 - No battery drain, no crypto mining, no unrelated background processes
 - Use only public APIs; must function on IPv6-only networks

package/pipeline/rules/code-style.md

@@ -17,12 +17,12 @@ globs: "**/*.swift"
 
 - MARK comments to organize: `// MARK: - Properties`, `// MARK: - Lifecycle`
 - Extension per protocol conformance
-- Max function length: ~40 lines — split if longer
-- Max file length: ~400 lines — split into extensions
+- Max function length: ~40 lines  -  split if longer
+- Max file length: ~400 lines  -  split into extensions
 
 ### Patterns
 
-- Guard early, return early — avoid deep nesting
+- Guard early, return early  -  avoid deep nesting
 - Use `[weak self]` in escaping closures, then `guard let self` inside
 - Prefer `let` over `var`
 - Prefer value types (struct/enum) over reference types (class) when possible
@@ -31,7 +31,7 @@ globs: "**/*.swift"
 ### Don'ts
 
 - No force unwraps (`!`) except IBOutlets
-- No force casts (`as!`) — use `as?` with guard
+- No force casts (`as!`)  -  use `as?` with guard
 - No implicitly unwrapped optionals except IBOutlets and test setup
-- No magic numbers — use named constants
-- No `print()` — use `os_log` or `Logger`
+- No magic numbers  -  use named constants
+- No `print()`  -  use `os_log` or `Logger`

package/pipeline/rules/figma-pipeline.md

@@ -2,6 +2,104 @@
 
 Skill set under `pipeline/skills/figma-ios/` (iOS), `pipeline/skills/figma-android/` (Android), and `pipeline/skills/figma-common/` (shared). Activated when the task contains a Figma URL and target files are `.swift` (iOS) or `.kt` (Android).
 
+### MUST: Figma access - 3-tier fallback chain (BLOCKING, pipeline-wide)
+
+When any task references a Figma frame (URL, node ID, or free-text "from the design"), the pipeline MUST resolve a Figma ground-truth artefact via the chain below before any UI line is written, every phase that consumes or verifies the reference (Phase 0 intake, Phase 1 analysis, Phase 2 planning, Phase 3 dev, Phase 4 review, Phase 5 manual test, Phase 7 channels). Skipping the chain has cost multiple rebuild rounds across projects.
+
+The three tiers run in strict priority order. A tier is "available" when its required credentials / inputs are present AND a probe call succeeds. Lower tiers are tried only when the higher tier is unreachable.
+
+#### Tier 1 - Figma MCP (preferred)
+
+Tools:
+- `mcp__claude_ai_Figma__get_design_context(fileKey, nodeId)`: primary; returns code + screenshot + `CodeConnectSnippet` blocks naming the exact target component.
+- `mcp__claude_ai_Figma__get_screenshot(fileKey, nodeId)`: pixel render for visual diff against the implementation.
+- `mcp__claude_ai_Figma__get_metadata(fileKey, nodeId)`: when the frame structure is unknown.
+
+Auth failure is NOT a skip path. Run `mcp__claude_ai_Figma__authenticate` + `mcp__claude_ai_Figma__complete_authentication` and retry once. If the retry also fails, do NOT silently fall through to Tier 2  -  surface an `AskUserQuestion` (`question` + `description` in `outputLanguage`; `label` + `header` English):
+- **Recreate the MCP token** - the `figma_mcp` credential is dead; re-onboard it via the Token Save Flow (`setup.md`), then retry Tier 1.
+- **Continue with Figma PAT** - proceed to Tier 2 (REST) for this run.
+
+Only on the explicit "Continue with Figma PAT" choice (or when no `figma_mcp` token is mapped at all) does the chain move to Tier 2.
+
+The MCP token itself resolves through `prefs.global.keychainMapping.figma_mcp` (relevant for MCP server config bootstrap; the `mcp__claude_ai_Figma__*` tool calls themselves run through Anthropic-managed MCP auth, but the token MUST be onboarded so the auth flow has something to bind to).
+
+#### Tier 2 - Figma Personal Access Token via REST API (fallback)
+
+Token retrieval goes through `~/.claude/lib/credential-store.sh get <logical-key>` where `<logical-key>` is read from `prefs.global.keychainMapping.figma_pat` (or whichever per-user logical name the mapping resolves to). The literal Keychain service name is NEVER embedded in any synced file under `~/.claude/commands/` or `~/.copilot/skills/`; see the Synced Command Hygiene rule.
+
+Endpoints:
+- Design context (frame metadata + structure):
+  `GET https://api.figma.com/v1/files/{fileKey}/nodes?ids={nodeId}` with header `X-Figma-Token: $TOKEN`.
+- Screenshot render:
+  `GET https://api.figma.com/v1/images/{fileKey}?ids={nodeId}&format=png&scale=2` with the same header. The response is a signed URL valid for 30 days; download it locally before the URL expires.
+
+If the REST call returns 401 / 403 (the PAT is expired or revoked), do NOT silently fall through to Tier 3  -  run the Expired-token decision (`refs/keychain.md` Rule 1) for `figma_pat`: **Regenerate** / **Use a different token** / **Skip and continue**. Only on the explicit "Skip and continue" choice (or when no `figma_pat` is mapped) does the chain move to Tier 3.
+
+Tier 2 does NOT return a Code Connect snippet (the REST API has no equivalent). When operating on Tier 2, the canonical-component decision falls back to the repo's `*.figma.swift` / `*.figma.kt` mappings (search by `fileKey` + `nodeId`); if none match, record an Open Question for the design team and pick the closest existing primitive WITH user confirmation.
+
+#### Tier 3 - User-attached screenshot (last resort)
+
+When the user supplies screenshots inline in chat or via task attachments and Tiers 1 + 2 are both unreachable, treat the screenshot as the visual ground truth and document the limitation. Tier 3 produces a degraded evidence record: `codeConnectSnippets` is empty, the canonical-component decision is "tier-3 best-fit pending design review", and the Phase 4 reviewer flag is set to `review_blocking` until a human signs off on the component choice.
+
+#### Halt condition
+
+If all three tiers fail (no MCP auth AND no REST token AND no screenshot), HALT the run and ask the user how to proceed. Never substitute primitives, never guess from Confluence prose, never derive layout from a text description.
+
+#### URL parsing
+
+`figma.com/design/{fileKey}/...?node-id={id}`: convert `-` to `:` in node IDs. Branch URL `figma.com/design/{fileKey}/branch/{branchKey}/...` uses `branchKey` as the effective `fileKey`.
+
+#### Code Connect snippet rules (Tier 1 + Tier 2 when the repo mapping fills the gap)
+
+- The `CodeConnectSnippet` block (Tier 1) or the matching `*.figma.swift` / `*.figma.kt` row (Tier 2) names the exact target component the design team mapped. Use that component name verbatim.
+- Sound-alike alternatives are forbidden. Picking a similarly-named component because it appears more flexible introduces visual drift on avatar icons, field grouping (one rounded box vs two), separators, character counters, button heights, header styles, inline-error layout.
+- If the chosen component is missing a modifier (placeholder, counter toggle, height override, error-state binding), add the modifier to the component in its `+Modifiers.swift` (or platform equivalent). Do not fork, do not silently render the wrong visual, do not extract a custom wrapper inside the consumer domain.
+
+Architecture notes must cite the exact node IDs (Tier 1 or Tier 2) or attach the user-provided screenshot reference (Tier 3) for every UI atom row. Visual feedback that arose from skipping the chain ("expandable broken", "placeholder missing", "counter showing", "wrong avatar icon") is treated as a blocker review finding, not a normal iteration.
+
+#### Generic checklist before writing any UI line
+
+1. Establish the tier in use and persist it as `state.figmaAccess.tier` (1, 2, or 3). Tier 3 forces a review-blocking flag.
+2. Call the tier-appropriate fetcher for every frame variant (default, filled, error, indicator-on, RTL, etc.).
+3. Resolve the canonical component name: Tier 1 from `CodeConnectSnippet`, Tier 2 from repo `*.figma.swift` / `*.figma.kt`, Tier 3 from explicit user confirmation.
+4. Compare screenshot to mental render: avatar icon, indicator chip placement, field grouping, separator vs gap, placeholder copy, counter visibility, button height, header style, inline error colour and location.
+5. Map design tokens (CSS vars on Tier 1, screenshot inspection on Tier 3) onto project token namespaces (`Spacing*`, `Color*`, `Radius*`, `Typography*`); never invent numeric or hex values.
+6. Re-run the chain when the spec changes or the user reports visual drift; do not assume the prior fetch is current.
+
+## MUST: No MCP outside analysis phase (BLOCKING, pipeline-wide)
+
+The 3-tier fallback chain above governs Figma access in `/multi-agent:analysis` only. Once the analysis document is rendered (Phase 1 of the analysis subcommand), the analysis doc + repo Code Connect mappings (`*.figma.swift` / `*.figma.kt`) are the sole design source for every downstream phase. Calling `mcp__claude_ai_Figma__*` tools, hitting `api.figma.com`, or fetching a `figma.com/design/...` URL during Phase 2, 3, 4, 5, 6, or 7 is a violation.
+
+### Phase access matrix
+
+| Phase | Sub-command examples | Figma MCP allowed | Figma REST allowed | Reason |
+|---|---|---|---|---|
+| Analysis Phase 1 | `/multi-agent:analysis` Phase 1 fetch | yes | yes (Tier 2 fallback) | Single source of design ground truth |
+| Plan (Phase 2) | `/multi-agent`, `/multi-agent:local`, `/multi-agent:autopilot`, `/multi-agent:local-autopilot` | no | no | Plan reads analysis doc Section 14 + Section 6 |
+| Dev (Phase 3) | every mode that runs Phase 3 (8 modes total) | no | no | Reads analysis doc + Code Connect mapping |
+| Review (Phase 4) | `/multi-agent:review`, every full-pipeline mode | no | no | Reviewer cites analysis doc Section 21 References |
+| Test (Phase 5) | `/multi-agent:test`, `/multi-agent:manual-test`, every full mode | no | no | Variant list comes from analysis Section 13.6 + 15.2 |
+| Commit (Phase 6) | every mode | no | no | PR body links to analysis doc URL, no design fetch |
+| Report (Phase 7) | `/multi-agent:channels`, every full mode | no | no | Channels embed analysis doc, no design fetch |
+
+### Halt condition
+
+If Phase 2+ encounters a need to look at the design (missing variant, ambiguous padding, unknown copy), the run halts and the user is instructed to re-run `/multi-agent:analysis` to regenerate the doc with the missing piece. Never silently call MCP as a fallback.
+
+### Why
+
+Re-fetching Figma in dev phases:
+- Burns MCP tokens (slow + costly)
+- Duplicates the work analysis already did
+- Splits the design source of truth (analysis doc says X, MCP says Y if Figma edited mid-run)
+- Defeats the analysis -> dev contract: the analysis doc is supposed to be self-contained
+
+### Verification
+
+The pipeline ships a smoke gate `pipeline/scripts/smoke-no-mcp-in-dev-phases.sh` that reads `state.telemetry.mcpCalls[]`. If any entry has `phase >= 2`, the gate fails. CI runs this gate after every run as a regression check.
+
+Memory: [[mcp-only-in-analysis]]
+
 ### Phase Order (platform-agnostic)
 
 ```
@@ -18,7 +116,7 @@ Template: `preferences-template.json` → `_figmaConfigTemplate` section.
 
 ### Variable System
 
-All skill files use `{variableName}` placeholders — no hardcoded project values.
+All skill files use `{variableName}` placeholders  -  no hardcoded project values.
 Variables resolved from `figma-config.json` by the orchestrator at Phase 0.
 Placeholder catalog ships alongside each skill's `SKILL.md`.
 
@@ -92,7 +190,7 @@ Phase 3.3: figma-iteration-commit     → Batch iteration commit (if iterating)
 | Wiki | enabled/disabled | `wiki.enabled` |
 | Figma API | MCP / REST fallback | `figma.mcpEnabled` |
 
-Provider interfaces are defined inline in the platform skill sets — see `pipeline/skills/figma-common/`, `pipeline/skills/figma-ios/`, and `pipeline/skills/figma-android/`.
+Provider interfaces are defined inline in the platform skill sets  -  see `pipeline/skills/figma-common/`, `pipeline/skills/figma-ios/`, and `pipeline/skills/figma-android/`.
 
 ### Optional Features (graceful skip when disabled)
 

package/pipeline/rules/kotlin-android.md

@@ -17,10 +17,10 @@ globs: "**/*.kt"
 
 - State: `MutableStateFlow` in ViewModel, `collectAsStateWithLifecycle()` in UI
 - Navigation: Type-safe with `@Serializable` route objects (Navigation 2.8+)
-- Side effects: `LaunchedEffect`, `DisposableEffect`, `SideEffect` — never in body
+- Side effects: `LaunchedEffect`, `DisposableEffect`, `SideEffect`  -  never in body
 - Stability: Mark data classes `@Immutable` or `@Stable` for recomposition optimization
 - Remember: Always `remember {}` for expensive computations
-- ViewModel: Never pass ViewModel to child composables — pass state + lambdas
+- ViewModel: Never pass ViewModel to child composables  -  pass state + lambdas
 
 ### Architecture
 
@@ -70,12 +70,12 @@ fun HomeContent(uiState: HomeUiState, onRefresh: () -> Unit) { ... }
 
 ### Don'ts
 
-- No `!!` force unwrap — use `?.let`, `requireNotNull`, or `checkNotNull`
-- No mutable state exposed from ViewModel — use `StateFlow` + `asStateFlow()`
-- No `Thread.sleep()` — use `delay()` in coroutines
-- No `android.util.Log` in production — use Timber
-- No hardcoded strings in Composables — use `stringResource()`
-- No business logic in Composables — put in ViewModel or UseCase
+- No `!!` force unwrap  -  use `?.let`, `requireNotNull`, or `checkNotNull`
+- No mutable state exposed from ViewModel  -  use `StateFlow` + `asStateFlow()`
+- No `Thread.sleep()`  -  use `delay()` in coroutines
+- No `android.util.Log` in production  -  use Timber
+- No hardcoded strings in Composables  -  use `stringResource()`
+- No business logic in Composables  -  put in ViewModel or UseCase
 
 ### Testing
 

package/pipeline/rules/security.md

@@ -3,10 +3,10 @@
 ### Secure Data Storage
 
 ```swift
-// FORBIDDEN — UserDefaults for sensitive data
+// FORBIDDEN  -  UserDefaults for sensitive data
 UserDefaults.standard.set(authToken, forKey: "token")
 
-// CORRECT — Keychain
+// CORRECT  -  Keychain
 let query: [String: Any] = [
     kSecClass as String: kSecClassGenericPassword,
     kSecAttrAccount as String: "authToken",
@@ -21,13 +21,13 @@ SecItemAdd(query as CFDictionary, nil)
 // FORBIDDEN
 let apiKey = "sk-abc123..."
 
-// CORRECT — Info.plist (gitignored) or server-side
+// CORRECT  -  Info.plist (gitignored) or server-side
 let apiKey = Bundle.main.infoDictionary?["API_KEY"] as? String
 ```
 
 ### Network Security
 
-- ATS enabled — no HTTP without exception justification
+- ATS enabled  -  no HTTP without exception justification
 - Certificate pinning for sensitive endpoints
 - Never log request/response bodies in production
 

package/pipeline/rules/tdd.md

@@ -8,7 +8,7 @@ NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.
 
 1. **RED**: Write ONE minimal failing test
 2. **Verify RED**: Confirm it fails for the RIGHT reason
-3. **GREEN**: Simplest code to pass — nothing more
+3. **GREEN**: Simplest code to pass  -  nothing more
 4. **Verify GREEN**: Confirm pass AND other tests still pass
 5. **REFACTOR**: Remove duplication, improve names
 

package/pipeline/rules/testing.md

@@ -21,7 +21,7 @@ globs: "**/*Tests.swift,**/*Test.swift,**/Tests/**"
 
 - Prefer Swift Testing (`@Test`, `#expect`) for new tests
 - XCTest for UI tests and existing test suites
-- No `sleep()` in tests — use expectations/async
+- No `sleep()` in tests  -  use expectations/async
 
 ### Coverage
 
@@ -31,7 +31,7 @@ globs: "**/*Tests.swift,**/*Test.swift,**/Tests/**"
 
 ### Don'ts
 
-- No network calls in unit tests — use mocks/stubs
-- No file system dependencies — use temporary directories
-- No test interdependencies — each test must be isolated
-- No `XCTAssertTrue(result != nil)` — use `XCTAssertNotNil(result)`
+- No network calls in unit tests  -  use mocks/stubs
+- No file system dependencies  -  use temporary directories
+- No test interdependencies  -  each test must be isolated
+- No `XCTAssertTrue(result != nil)`  -  use `XCTAssertNotNil(result)`

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

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/agent-state.schema.json",
-  "title": "Multi-Agent Pipeline — agent-state.json",
+  "title": "Multi-Agent Pipeline  -  agent-state.json",
   "description": "Canonical state file for a single pipeline run. Written to $HOME/.claude/logs/multi-agent/{project}/{task-id}/agent-state.json and read by every phase. Versioned so older runs can be migrated or ignored.",
   "type": "object",
   "additionalProperties": false,
@@ -22,17 +22,17 @@
     "schemaVersion": {
       "type": "string",
       "enum": ["2.0.0", "2.1.0"],
-      "description": "v2.0.0: single-repo only (scalar project/projectRoot/worktreePath). v2.1.0: adds optional projects[] array for multi-repo tasks — single-repo fields remain for backward compat; when projects[] has >1 entries, multi-repo mode is active."
+      "description": "v2.0.0: single-repo only (scalar project/projectRoot/worktreePath). v2.1.0: adds optional projects[] array for multi-repo tasks  -  single-repo fields remain for backward compat; when projects[] has >1 entries, multi-repo mode is active."
     },
     "taskId": {
       "type": "string",
-      "description": "Canonical task id — Jira key (PROJ-12345), GitHub issue number (#316), or free-text slug.",
+      "description": "Canonical task id  -  Jira key (PROJ-12345), GitHub issue number (#316), or free-text slug.",
       "minLength": 1
     },
     "shortId": {
       "type": "integer",
       "minimum": 1,
-      "description": "Auto-incremented local short id from .worktrees/.multi-agent-counter — unique per machine, not per project."
+      "description": "Auto-incremented local short id from .worktrees/.multi-agent-counter  -  unique per machine, not per project."
     },
     "jiraId": {
       "type": ["string", "null"],
@@ -51,7 +51,7 @@
     },
     "project": {
       "type": "string",
-      "description": "Project slug — used to partition logs and knowledge base."
+      "description": "Project slug  -  used to partition logs and knowledge base."
     },
     "projectRoot": {
       "type": "string",
@@ -81,16 +81,40 @@
     },
     "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'."
+    },
+    "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.",
+      "properties": {
+        "mcpCalls": {
+          "type": "array",
+          "description": "One entry per MCP tool invocation during the run. The gate fails if any entry has phase >= 2.",
+          "items": {
+            "type": "object",
+            "required": ["tool", "phase"],
+            "properties": {
+              "tool": { "type": "string", "description": "MCP tool name, e.g. mcp__claude_ai_Figma__get_design_context." },
+              "phase": { "type": "integer", "minimum": 0, "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." }
+            }
+          }
+        }
+      }
+    },
     "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, 2, 4, 5 are skipped."
     },
     "localMode": {
       "type": "boolean",
       "default": false,
-      "description": "--local flag — no worktree, direct branch in projectRoot."
+      "description": "--local flag  -  no worktree, direct branch in projectRoot."
     },
     "instructionDriven": {
       "type": "boolean",
@@ -125,37 +149,41 @@
               "description": "Files produced or modified by this phase. Used for semantic revert."
             },
             "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" },
             "clarificationRounds": {
               "type": "integer",
               "minimum": 0,
               "maximum": 2,
-              "description": "v5.3.0 Phase 2 Plan Approval Gate — number of clarification question/answer rounds the orchestrator ran before producing the first plan. Cap 2; hitting the cap produces a 'best-effort' plan instead of asking more questions. Only emitted in normal mode (skipped for --dev, autopilot, --dev autopilot)."
+              "description": "v5.3.0 Phase 2 Plan Approval Gate  -  number of clarification question/answer rounds the orchestrator ran before producing the first plan. Cap 2; hitting the cap produces a 'best-effort' plan instead of asking more questions. Only emitted in normal mode (skipped for --dev, autopilot, --dev autopilot)."
             },
             "clarificationQuestions": {
               "type": "array",
               "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)."
+              "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" },
-              "description": "v5.3.0 Phase 2 — ordered log of user answers aligned with clarificationQuestions (same length)."
+              "description": "v5.3.0 Phase 2  -  ordered log of user answers aligned with clarificationQuestions (same length)."
             },
             "planIterations": {
               "type": "integer",
               "minimum": 1,
-              "description": "v5.3.0 Phase 2 Plan Approval Gate — how many plan revisions the user requested before approving. 1 = approved on first show; N = user sent N-1 free-text edit requests and the plan was re-rendered each time."
+              "description": "v5.3.0 Phase 2 Plan Approval Gate  -  how many plan revisions the user requested before approving. 1 = approved on first show; N = user sent N-1 free-text edit requests and the plan was re-rendered each time."
             },
             "planApprovedAt": {
               "type": ["string", "null"],
               "format": "date-time",
-              "description": "v5.3.0 Phase 2 Plan Approval Gate — timestamp when the user approved the plan. Null when the gate is not applicable (--dev, autopilot, --dev autopilot) or the task was aborted at the gate."
+              "description": "v5.3.0 Phase 2 Plan Approval Gate  -  timestamp when the user approved the plan. Null when the gate is not applicable (--dev, autopilot, --dev autopilot) or the task was aborted at the gate."
             },
             "planEditRequests": {
               "type": "array",
               "items": { "type": "string" },
-              "description": "v5.3.0 Phase 2 — free-text edit instructions the user typed between plan renders. Preserved verbatim for audit; Opus parses them conversationally to revise the plan."
+              "description": "v5.3.0 Phase 2  -  free-text edit instructions the user typed between plan renders. Preserved verbatim for audit; Opus parses them conversationally to revise the plan."
             }
           }
         }
@@ -165,19 +193,24 @@
       "type": "array",
       "items": {
         "type": "object",
-        "additionalProperties": false,
+        "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"] }
+          "decision": { "type": "string", "enum": ["fix", "accept", "escalate"] },
+          "reviewers": { "type": "array" },
+          "triage": { "type": "object" },
+          "accepted": { "type": "array" },
+          "validatorResult": {}
         }
       }
     },
     "confluenceSpace": {
       "type": ["string", "null"],
-      "description": "Cached Confluence space key for the project — avoids re-asking on every run."
+      "description": "Cached Confluence space key for the project  -  avoids re-asking on every run."
     },
     "confluenceParentId": {
       "type": ["string", "null"],
@@ -189,7 +222,7 @@
       "properties": {
         "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." },
+        "version": { "type": "integer", "minimum": 0, "description": "Bitbucket PR version  -  must increment by 1 per PUT." },
         "draft": { "type": "boolean" },
         "reviewers": {
           "type": "array",
@@ -262,9 +295,19 @@
             "description": "v2.1.0+ push-must-succeed retry counter. Increments per rebase-retry."
           },
           "buildStatus": {
-            "type": "string",
-            "enum": ["pending", "passed", "failed"],
-            "description": "Latest Phase 3 build outcome for this repo."
+            "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": "object",
+                "properties": {
+                  "ok": { "type": "boolean" },
+                  "attempts": { "type": "integer", "minimum": 0 },
+                  "lastError": { "type": ["string", "null"] }
+                }
+              }
+            ]
           }
         }
       }

package/pipeline/schemas/analysis-output.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/analysis-output.schema.json",
   "version": "1.0.0",
-  "title": "Multi-Agent Pipeline — Phase 1 analysis output",
+  "title": "Multi-Agent Pipeline  -  Phase 1 analysis output",
   "description": "Contract for the Explorer subagent's summary in Phase 1. Drives Phase 2 task decomposition and Phase 4 review focus. Explorer must not mutate the codebase; output is read-only research.",
   "type": "object",
   "additionalProperties": false,
@@ -48,12 +48,17 @@
           "mitigation": { "type": ["string", "null"] }
         }
       },
-      "description": "Known hazards surfaced by exploration — concurrency hotspots, deprecated APIs, tech debt, missing tests."
+      "description": "Known hazards surfaced by exploration  -  concurrency hotspots, deprecated APIs, tech debt, missing tests."
     },
     "summary": {
       "type": "string",
       "minLength": 20,
       "description": "≤200 word plain-language summary for Phase 2 planning + user approval."
+    },
+    "priorArt": {
+      "type": "array",
+      "description": "Advisory only. Up to 3 similar past-task triage matches injected AFTER the explorer returns (priorArtEnrichment). Not produced by the explorer and never required; present so the enriched object still validates under additionalProperties:false.",
+      "items": { "type": "object" }
     }
   }
 }