@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

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

@@ -1,9 +1,9 @@
 ### Phase 6: Commit & PR
 
-> **TLDR** — Commit with conventional message + ticket ID, push, open PR. Order: (1) identity confirm → (2) commit → (3) push → (4) fetch default reviewers → (5) ask DRAFT-or-READY → (6) build payload with heredoc+rawfile → (7) POST with `reviewers`+`fromRef`+`toRef`+`draft` required on Bitbucket (missing fields wipe defaults).
+> **TLDR**  -  Commit with conventional message + ticket ID, push, open PR. Order: (1) identity confirm → (2) commit → (3) push → (4) fetch default reviewers → (5) ask DRAFT-or-READY → (6) build payload with heredoc+rawfile → (7) POST with `reviewers`+`fromRef`+`toRef`+`draft` required on Bitbucket (missing fields wipe defaults).
 
 <!-- progress-contract: applied -->
-Progress emission per `refs/progress-contract.md` — lines for each per-repo squash, commit, push attempt (including retries), PR body generate, PR create, Jira comment post.
+Progress emission per `refs/progress-contract.md`  -  lines for each per-repo squash, commit, push attempt (including retries), PR body generate, PR create, Jira comment post.
 >
 > ```
 >   commit ──► push ──► fetch default reviewers ──► draft/ready prompt
@@ -15,11 +15,13 @@ Progress emission per `refs/progress-contract.md` — lines for each per-repo sq
 
 #### Input contract
 
-Phase 6 consumes the latest Phase 4 triage output object conforming to `pipeline/schemas/triage-output.schema.json` (`accepted`, `deferred`, `rejected` buckets) plus the working-tree mutations from Phase 3. The commit body cites only `accepted` findings that were resolved; `deferred` items must be linked in the PR description as follow-up work, never silently dropped. If the triage output reports any unresolved blocking accepted finding, Phase 6 refuses to commit — the pipeline returns to Phase 3 for rework.
+Phase 6 consumes the latest Phase 4 triage output object conforming to `pipeline/schemas/triage-output.schema.json` (`accepted`, `deferred`, `rejected` buckets) plus the working-tree mutations from Phase 3. The commit body cites only `accepted` findings that were resolved; `deferred` items must be linked in the PR description as follow-up work, never silently dropped. If the triage output reports any unresolved blocking accepted finding, Phase 6 refuses to commit  -  the pipeline returns to Phase 3 for rework.
 
-#### Step 0 — Multi-Repo Integration Build
+The "Build passes" checklist item below is evidence-gated, not self-asserted: Phase 6 trusts the `buildStatus.ok` that Phase 3 / Phase 4 recorded through `pipeline/scripts/evidence-gate.mjs` (a pass without a substantiating build/test log is treated as unverified and blocks the commit). The secret scanner (`pre-commit-check.sh`) runs on the staged diff as the final pre-commit gate.
 
-**Fires only when** `state.projects.length >= 2` (multi-repo task). Single-repo tasks skip this step silently — no prompt, no overhead.
+#### Step 0  -  Multi-Repo Integration Build
+
+**Fires only when** `state.projects.length >= 2` (multi-repo task). Single-repo tasks skip this step silently  -  no prompt, no overhead.
 
 Full contract: `refs/multi-repo-integration-build.md`. Summary:
 
@@ -27,13 +29,13 @@ Full contract: `refs/multi-repo-integration-build.md`. Summary:
 2. Look up `prefs.global.multiRepoIntegrationHosts[]` for matching `repoSet`.
 3. **Match found** → auto-run: submodule update → resolve package deps → build host scheme → evaluate errors → proceed / block / offer retry.
 4. **No match** → learn-once prompt: `[1] register host / [2] mark combo as noHost / [3] skip this run only`. Persist choice. Run immediately if host registered.
-5. **Autopilot** refuses to prompt on unknown combos — logs a visible skip and proceeds. Teach via a normal-mode run once.
+5. **Autopilot** refuses to prompt on unknown combos  -  logs a visible skip and proceeds. Teach via a normal-mode run once.
 
-Tracker: `phase-tracker.sh sub 6 0 "Integration build" <status>` — visible in live tracker. Progress line `→ integrating <host-scheme> with <N> submodules`.
+Tracker: `phase-tracker.sh sub 6 0 "Integration build" <status>`  -  visible in live tracker. Progress line `→ integrating <host-scheme> with <N> submodules`.
 
 Why: codegen mismatches (nested vs flat keys, missing entries) only surface when the full dependency chain builds together. Building repos in isolation gives false confidence and produces post-merge fix PRs.
 
-#### Step 1 — Identity Confirmation
+#### Step 1  -  Identity Confirmation
 
 ```
 Want to use a different author/email?
@@ -43,7 +45,7 @@ Current: {identity.name} <{identity.email}>
 
 If yes -> show identity picker (same as Phase 0 Step 6), update git config in worktree.
 
-#### Step 2 — Instruction-Driven vs Standard
+#### Step 2  -  Instruction-Driven vs Standard
 
 Branch **deterministically**, no implicit fallback. Read `agent-state.json` and evaluate both conditions:
 
@@ -51,53 +53,53 @@ Branch **deterministically**, no implicit fallback. Read `agent-state.json` and
 | ------------------- | ---------------------------------------- | ----------------------------------- |
 | `true`              | **yes** (file readable)                  | → Instruction-driven path           |
 | `true`              | **no** (missing / unreadable)            | → **Log error, fall back to standard** + set `state.instructionDrivenFallback: true` for Phase 7 audit. Do NOT silently ignore. |
-| `false`             | —                                        | → Standard path                     |
+| `false`             |  -                                         | → Standard path                     |
 
 **Instruction-driven path:**
 
 1. Ask: "Want to commit?" (skip in autopilot)
 2. Read commit instruction file (e.g. `.instructions/figma/figma-iteration-commit/SKILL.md`)
 3. Follow its flow (build validation, test, submodule commits, push, PR, issue management)
-4. Log: "Phase 6: instruction-driven commit — file={instructionFiles.commit}"
+4. Log: "Phase 6: instruction-driven commit  -  file={instructionFiles.commit}"
 
 **Standard path (also used as fallback when instructionDriven=true but file missing):**
 
 1. **Local checkout test prompt** (skip in autopilot): If still in worktree AND Phase 5 was skipped, ask the user. Per `refs/rules.md` Language Application matrix: `AskUserQuestion.label` and `header` stay English (UI button + chip contract); `question` and `description` follow `outputLanguage`. Render the picker accordingly:
-   - `question` (in `outputLanguage`) — semantically: "Run a quick WIP-checkout test before commit?"
+   - `question` (in `outputLanguage`)  -  semantically: "Run a quick WIP-checkout test before commit?"
    - `header` (English, ≤12 chars): `"WIP checkout"`
    - `options` (description in `outputLanguage`, label in English):
-     - label: `"No — continue to commit (Recommended)"`, description (in `outputLanguage`): proceed straight to commit + push + PR
-     - label: `"Yes — WIP checkout"`, description (in `outputLanguage`): pause so the user can checkout the branch locally and poke around
-   - Default: option 1 (No — continue to commit)
-   - If user picks "Yes — WIP checkout": follow Phase 5 Steps 2-6. On `"fix:"` → Phase 3. On `"ok"` → resume Phase 6.
+     - label: `"No  -  continue to commit (Recommended)"`, description (in `outputLanguage`): proceed straight to commit + push + PR
+     - label: `"Yes  -  WIP checkout"`, description (in `outputLanguage`): pause so the user can checkout the branch locally and poke around
+   - Default: option 1 (No  -  continue to commit)
+   - If user picks "Yes  -  WIP checkout": follow Phase 5 Steps 2-6. On `"fix:"` → Phase 3. On `"ok"` → resume Phase 6.
 2. Commit confirm prompt (skip in autopilot). Same language matrix:
    - `question` in `outputLanguage` (semantic: "Commit now?")
    - labels English: `"Commit"`, `"Pause and resume later"`
    - No → Pause, user can `resume` later. Yes → continue:
 3. If WIP commit exists from Phase 5 or Step 1: `git reset HEAD~1` to unstage, then re-commit properly
-4. Stage changes: `git add` with specific files (NOT `git add -A` — avoid sensitive files, `.worktrees/`, agent files)
+4. Stage changes: `git add` with specific files (NOT `git add -A`  -  avoid sensitive files, `.worktrees/`, agent files)
 5. **Multi-submodule check**: If project has submodules (e.g. uicomponents + common):
    - Detect which submodules have changes: `git -C {worktree} diff --name-only | cut -d'/' -f1-3 | sort -u`
    - For EACH submodule with changes: stage, commit, push separately
    - Commit message uses same convention but scope reflects submodule: `{type}({submodule-scope}): {description} [{jiraId}]`
-6. Commit with convention: `{type}({scope}): {description} [{jiraId}]` or `[#{shortId}]`. **Local-only repos** (state field `projects[i].provider == "local"`) carry the same conventional prefix but drop the `[{jiraId}]` suffix — there is no tracker to reference. The taskId (`LOCAL-…`) goes in the commit body footer instead: `Local-Task: {taskId}`.
-7. Push to remote — **skip per-repo when `projects[i].provider == "local"`** (no `git push`, no upstream config). Log `Phase 6: local-only commit {sha} (no push)` for that repo.
+6. Commit with convention: `{type}({scope}): {description} [{jiraId}]` or `[#{shortId}]`. **Local-only repos** (state field `projects[i].provider == "local"`) carry the same conventional prefix but drop the `[{jiraId}]` suffix  -  there is no tracker to reference. The taskId (`LOCAL-...`) goes in the commit body footer instead: `Local-Task: {taskId}`.
+7. Push to remote  -  **skip per-repo when `projects[i].provider == "local"`** (no `git push`, no upstream config). Log `Phase 6: local-only commit {sha} (no push)` for that repo.
 8. Ask: "Want to open a Pull Request?"
-   - **Skip the prompt entirely when `state.offlineOnly == true`** (all repos local — no PR target exists). Proceed to Phase 7 with `pr.status = "skipped-offline"` for each project.
+   - **Skip the prompt entirely when `state.offlineOnly == true`** (all repos local  -  no PR target exists). Proceed to Phase 7 with `pr.status = "skipped-offline"` for each project.
    - In mixed mode (some local, some remote), only prompt for the remote-backed repos; local ones auto-skip.
    - No -> Phase 7
    - Yes -> Create PR with technical description (see below)
-9. **Issue body update** (GitHub Issue only): if the issue body has a `### Pull Requests` section and/or a `### Progress` table, fill in the PR URL(s) (one row per submodule — e.g. `- **common:** {url}`, `- **uicomponents:** {url}`) and flip the Implementation / Testing / Code Connect flags from Pending to Done using whatever marker the template uses (match in place, do NOT introduce new markers). Apply with `gh issue edit {issueNo} --body "{updated body}"` and preserve every other section unchanged.
-10. **NEVER close or resolve the issue** — neither GitHub Issue nor Jira. Issues require team review (4 approvals) before closing. Only post a comment with commit/PR URLs.
-11. Log: "Phase 6: Commit {sha} — PR #{number}"
+9. **Issue body update** (GitHub Issue only): if the issue body has a `### Pull Requests` section and/or a `### Progress` table, fill in the PR URL(s) (one row per submodule  -  e.g. `- **common:** {url}`, `- **uicomponents:** {url}`) and flip the Implementation / Testing / Code Connect flags from Pending to Done using whatever marker the template uses (match in place, do NOT introduce new markers). Apply with `gh issue edit {issueNo} --body "{updated body}"` and preserve every other section unchanged.
+10. **NEVER close or resolve the issue**  -  neither GitHub Issue nor Jira. Issues require team review (4 approvals) before closing. Only post a comment with commit/PR URLs.
+11. Log: "Phase 6: Commit {sha}  -  PR #{number}"
 
-#### Step 3 — PR Description (technical detail for reviewers)
+#### Step 3  -  PR Description (technical detail for reviewers)
 
-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.
+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.
 
 **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.
 
-**IMPORTANT — Issue auto-close prevention**: Never use these keywords in PR title, body, or commit messages — they auto-close the issue on merge:
+**IMPORTANT  -  Issue auto-close prevention**: Never use these keywords in PR title, body, or commit messages  -  they auto-close the issue on merge:
 
 - GitHub: `Closes`, `Close`, `Closed`, `Fixes`, `Fix`, `Fixed`, `Resolves`, `Resolve`, `Resolved` (case-insensitive, followed by `#N`)
 - Bitbucket: similar patterns
@@ -122,7 +124,7 @@ gh pr create --base {baseBranch} --head {branch} $REVIEWERS \
 {1-3 bullet points: what changed and why}
 
 ## Jira
-{jiraId} — {jira summary or link}
+{jiraId}  -  {jira summary or link}
 
 ## Technical Details
 ### Changes
@@ -132,7 +134,7 @@ gh pr create --base {baseBranch} --head {branch} $REVIEWERS \
 {Any structural decisions: new files, moved code, pattern changes}
 
 ### Dependencies
-{New imports, framework changes, package updates — or "None"}
+{New imports, framework changes, package updates  -  or "None"}
 
 ## How to Test
 1. {Step-by-step manual test instructions}
@@ -160,7 +162,7 @@ Same `gh pr create` pattern with component-specific body sections:
 
 **Bitbucket PR** (when remote is Bitbucket):
 
-CRITICAL: PR description **MUST** preserve real newlines. Never embed `\n` literally — Bitbucket saves it verbatim. Never use HTML entities. Pattern: heredoc → `jq --rawfile` → `curl --data-binary @file`.
+CRITICAL: PR description **MUST** preserve real newlines. Never embed `\n` literally  -  Bitbucket saves it verbatim. Never use HTML entities. Pattern: heredoc → `jq --rawfile` → `curl --data-binary @file`.
 
 Required payload fields: `title`, `description` (via rawfile), `fromRef` (id + repo slug + project key), `toRef` (same structure), `state: "OPEN"`, `open: true`, `closed: false`, `locked: false`, `reviewers: []`.
 
@@ -189,20 +191,20 @@ GitHub auto-requests reviews from `CODEOWNERS` when branch protection requires i
 
 Steps:
 
-1. Check CODEOWNERS exists (`.github/CODEOWNERS`, `CODEOWNERS`, `docs/CODEOWNERS` — `git cat-file -e`)
+1. Check CODEOWNERS exists (`.github/CODEOWNERS`, `CODEOWNERS`, `docs/CODEOWNERS`  -  `git cat-file -e`)
 2. If CODEOWNERS present → let GitHub auto-request; create PR with no extra reviewers
 3. If no CODEOWNERS → resolve reviewers from (in order): branch protection `required_pull_request_reviews` via `gh api`, then `prefs.projects[{project}].githubDefaultReviewers[]`, then skip
 4. Create PR: `gh pr create --repo {owner}/{repo} --base {baseBranch} --head {branch} --title "..." --body-file pr-body.md ${REVIEWER_USERS:+--reviewer "$REVIEWER_USERS"} ${REVIEWER_TEAMS:+--reviewer "$REVIEWER_TEAMS"}`
 
-PR author cannot appear in `--reviewer` — strip from list.
+PR author cannot appear in `--reviewer`  -  strip from list.
 
-**Preferences entry** (set once per project, persists): `"githubDefaultReviewers": ["@alice", "@bob", "my-org/backend-team"]` under `projects.{name}`. Save user picks — prepend, dedup, max 10.
+**Preferences entry** (set once per project, persists): `"githubDefaultReviewers": ["@alice", "@bob", "my-org/backend-team"]` under `projects.{name}`. Save user picks  -  prepend, dedup, max 10.
 
-**Common rule:** never hardcode reviewer IDs — derive from repo config or preferences.
+**Common rule:** never hardcode reviewer IDs  -  derive from repo config or preferences.
 
 ##### Draft vs ready-for-review
 
-Before creating PR, ask: "DRAFT or READY? [1/2], default 1" — DRAFT blocks merge/delays notifications, READY notifies reviewers + CI. Skip in `autopilot` → default READY.
+Before creating PR, ask: "DRAFT or READY? [1/2], default 1"  -  DRAFT blocks merge/delays notifications, READY notifies reviewers + CI. Skip in `autopilot` → default READY.
 
 - **Bitbucket**: `"draft": true` in payload (DC 8.x+). Promote: `draft: false` PUT. Older: prefix title `[DRAFT]`.
 - **GitHub**: `--draft`. Promote: `gh pr ready {N}`.
@@ -218,22 +220,22 @@ Before creating PR, ask: "DRAFT or READY? [1/2], default 1" — DRAFT blocks mer
 
 #### v2.1.0+ Multi-Repo Mode
 
-Active when `state.projects[].length > 1`. The single-repo flow above is preserved verbatim — multi-repo is an extension, not a replacement.
+Active when `state.projects[].length > 1`. The single-repo flow above is preserved verbatim  -  multi-repo is an extension, not a replacement.
 
 ##### Per-repo commit (shared message, per-repo scope)
 
 For each repo in `state.projects[]` (sequentially, in dependency order from Phase 2):
 
-1. `cd "$WT_PATH"` — switch into the repo's worktree.
+1. `cd "$WT_PATH"`  -  switch into the repo's worktree.
 2. Build the commit message using the **shared subject** + **per-repo scope** rule:
    ```
    {type}({repo-scope}): {shared subject} [{tracker-id}]
 
-   Part of multi-repo change — see sibling PR(s) in repo `{other repo names}`.
+   Part of multi-repo change  -  see sibling PR(s) in repo `{other repo names}`.
    ```
    `repo-scope` is the repo's short name (e.g. `common`, `uicomponents`). The subject and `[tracker-id]` are identical across all repos.
-3. `git add` (specific files only — same rules as single-repo Step 5)
-4. `git -C "$WT_PATH" commit -m "$MESSAGE"` (heredoc body) — using identity already pinned in Phase 0 Step 8.
+3. `git add` (specific files only  -  same rules as single-repo Step 5)
+4. `git -C "$WT_PATH" commit -m "$MESSAGE"` (heredoc body)  -  using identity already pinned in Phase 0 Step 8.
 5. Capture `state.projects[i].commit = "<sha>"`.
 
 ##### Push-must-succeed policy (gated by `prefs.global.settings.pushMustSucceed`, default `true`)
@@ -258,7 +260,7 @@ For each repo (sequentially), per push attempt:
 5. After settings.pushRetryMax failures, prompt user:
      [1] Resolve conflict manually in $WT_PATH, then resume #{taskId}
      [2] Switch to a different base branch (re-prompt baseBranch, restart push loop)
-     [3] Skip this repo — leave commit local, mark state.projects[i].pushStatus = "skipped"
+     [3] Skip this repo  -  leave commit local, mark state.projects[i].pushStatus = "skipped"
      [4] Pause Phase 6, exit cleanly
 ```
 
@@ -294,7 +296,7 @@ update_sibling_links "${PR_URLS[@]}"
 
 `update_sibling_links` does an UPDATE call per PR (Bitbucket: PUT with `version+1`; GitHub: `gh pr edit --body-file`). Idempotent: re-running with the same set is a no-op.
 
-##### GitHub issue body — list all PRs
+##### GitHub issue body  -  list all PRs
 
 Step 9's "Issue body update" extends to multi-repo: instead of a single `### Pull Requests` line, write one row per repo:
 
@@ -304,7 +306,7 @@ Step 9's "Issue body update" extends to multi-repo: instead of a single `### Pul
 - **uicomponents:** {pr-2-url}
 ```
 
-Match the existing template's table/list shape — do not introduce new markers (per existing single-repo rule).
+Match the existing template's table/list shape  -  do not introduce new markers (per existing single-repo rule).
 
 ##### `recentGroups` update on success
 
@@ -314,7 +316,7 @@ After ALL repos in the task have `pushStatus ∈ {"pushed", "rebase-pushed"}`:
 2. If found: `entry.count += 1`, `entry.lastUsed = ISO timestamp`, bump to front of array (LRU).
 3. If not found: prepend a new entry `{ label: <auto-generated>, repos: [...], count: 1, lastUsed: ... }`. Cap the array at 10 (drop oldest).
 
-A task ending with one or more `pushStatus === "skipped"` repos does NOT bump `recentGroups` count — only fully-successful multi-repo tasks earn LRU bumps.
+A task ending with one or more `pushStatus === "skipped"` repos does NOT bump `recentGroups` count  -  only fully-successful multi-repo tasks earn LRU bumps.
 
 ##### Telemetry
 

package/pipeline/commands/multi-agent/refs/phases/phase-7-report.md

@@ -1,13 +1,13 @@
 ### Phase 7: Report
 
-> **TLDR** — Close the loop in two halves: **External delivery** delegated to `/multi-agent:channels` (multi-select kanal + content — always pauses in autopilot, 30-min timeout ends session). **Internal capture** stays inline: `agent-log.md` finalization, telemetry emission, knowledge base + memory update. Channels command is the single source of truth for Jira/Confluence/Wiki/PR-description delivery — full contract in `commands/multi-agent/channels.md`.
+> **TLDR**  -  Close the loop in two halves: **External delivery** delegated to `/multi-agent:channels` (multi-select kanal + content  -  always pauses in autopilot, 30-min timeout ends session). **Internal capture** stays inline: `agent-log.md` finalization, telemetry emission, knowledge base + memory update. Channels command is the single source of truth for Jira/Confluence/Wiki/PR-description delivery  -  full contract in `commands/multi-agent/channels.md`.
 
 <!-- progress-contract: applied -->
-Progress emission per `refs/progress-contract.md` — lines for channels dispatch entry, per-adapter result, agent-log finalization, telemetry emission, knowledge+memory write.
+Progress emission per `refs/progress-contract.md`  -  lines for channels dispatch entry, per-adapter result, agent-log finalization, telemetry emission, knowledge+memory write.
 
 ## Sub-step Tracking (required)
 
-Phase 7 has **3 ordered sub-steps** (reduced from 5 in v5.7 — external delivery consolidated under channels). Register all of them in the tracker at Phase 7 entry.
+Phase 7 has **3 ordered sub-steps** (reduced from 5 in v5.7  -  external delivery consolidated under channels). Register all of them in the tracker at Phase 7 entry.
 
 ```bash
 bash ~/.claude/scripts/phase-tracker.sh update 7 in_progress
@@ -24,19 +24,19 @@ On entry: `phase-tracker.sh sub 7 <N> "<name>" in_progress`. On exit: `completed
 
 Phase 7 is the single exception to the autopilot zero-interaction rule. Full contract in `refs/phases/modes.md`:
 
-- **Normal / `--dev` / `autopilot`** — ALL modes pause at the channels multi-select menu.
-- **30-min timeout** — if user does not respond, session ends cleanly. External delivery is aborted (no silent apply of defaults — prevents accidental Jira comments / Confluence pages). Internal capture (Steps 2 + 3 below) STILL runs so `agent-log.md` + knowledge base are persisted.
-- **Resumable** — state written as `{phase: 7, waitingFor: "user-channels-choice", channelsInput: <state-bundle>}`. User can `/multi-agent:resume <task-id>` any time later; channels menu re-opens with same inputs.
-- **Timeout log line:** `Phase 7: channels menu timeout (30 min) — session ended, resume with /multi-agent:resume {taskId}`.
+- **Normal / `--dev` / `autopilot`**  -  ALL modes pause at the channels multi-select menu.
+- **30-min timeout**  -  if user does not respond, session ends cleanly. External delivery is aborted (no silent apply of defaults  -  prevents accidental Jira comments / Confluence pages). Internal capture (Steps 2 + 3 below) STILL runs so `agent-log.md` + knowledge base are persisted.
+- **Resumable**  -  state written as `{phase: 7, waitingFor: "user-channels-choice", channelsInput: <state-bundle>}`. User can `/multi-agent:resume <task-id>` any time later; channels menu re-opens with same inputs.
+- **Timeout log line:** `Phase 7: channels menu timeout (30 min)  -  session ended, resume with /multi-agent:resume {taskId}`.
 
 ---
 
-## Step 1 — External Delivery (delegated to channels)
+## Step 1  -  External Delivery (delegated to channels)
 
-Phase 7 builds a state bundle and invokes `/multi-agent:channels` (Claude Code) or `multi-agent-channels` (Copilot CLI). This is the ONLY external-delivery step — no inline Jira/Confluence/Wiki/PR-description logic lives in Phase 7 any more.
+Phase 7 builds a state bundle and invokes `/multi-agent:channels` (Claude Code) or `multi-agent-channels` (Copilot CLI). This is the ONLY external-delivery step  -  no inline Jira/Confluence/Wiki/PR-description logic lives in Phase 7 any more.
 
 > **Local-only short-circuit**: when `state.offlineOnly == true` (all repos
-> are local — see Phase 0), Step 1 is **skipped entirely**. No channels menu,
+> are local  -  see Phase 0), Step 1 is **skipped entirely**. No channels menu,
 > no Jira/Wiki/Confluence/PR adapters, no autopilot pause. The tracker
 > records `step1.status = "skipped-offline"` and the run jumps straight to
 > the internal capture sub-steps (agent-log finalization, telemetry,
@@ -61,7 +61,17 @@ Phase 7 builds a state bundle and invokes `/multi-agent:channels` (Claude Code)
 
 Channels command reads this bundle, skips its own target-resolution step, goes straight to the multi-select menu.
 
-### Menu (identical to post-hoc `/channels` call — single source of truth)
+### Figma evidence embedding (when `state.evidence.figma[]` is non-empty)
+
+For every UI atom touched by the diff, the PR description, Jira comment, and Confluence page body MUST embed the Figma frame reference and screenshot URL. Channels adapters read `state.evidence.figma[]` and render a `## Figma reference` block per channel:
+
+- **PR description**  -  one row per frame: `<canonicalComponentName>  <fileKey>:<nodeId>  [screenshot](<screenshotUrl>)`.
+- **Jira comment**  -  same row shape; image macros may be added when the Jira project allows direct image embedding (see `refs/channels/jira.md`).
+- **Confluence page**: frame screenshots are uploaded as page attachments (cache locally first because Tier 2 signed URLs expire after 30 days) and referenced inline via `<ac:image><ri:attachment ri:filename="frame-<nodeId>.png"/></ac:image>`.
+
+Tier 3 rows append `(tier 3: pending design review)` after the canonical component name so reviewers know the choice is provisional. The block is suppressed when `state.evidence.figma[]` is empty (non-UI tasks).
+
+### Menu (identical to post-hoc `/channels` call  -  single source of truth)
 
 ```
 Kanallar: [x] PR  [x] Jira  [ ] Confluence  [ ] Wiki
@@ -87,9 +97,9 @@ Tracker: `phase-tracker.sh sub 7 1 "Channels dispatch" completed` (or `failed` i
 
 ---
 
-## Step 1.5 — GitHub Issue channel (when tracker is a GitHub issue)
+## Step 1.5  -  GitHub Issue channel (when tracker is a GitHub issue)
 
-Runs only when `state.tracker.kind === "github-issue"`. The Issue adapter is mandatory whenever the run was triggered from a GitHub issue — no exceptions, no "I'll just update the flags" shortcut. Full template + rules: `refs/channels/issue-comment.md`.
+Runs only when `state.tracker.kind === "github-issue"`. The Issue adapter is mandatory whenever the run was triggered from a GitHub issue  -  no exceptions, no "I'll just update the flags" shortcut. Full template + rules: `refs/channels/issue-comment.md`.
 
 Two paired actions, in order:
 
@@ -99,14 +109,14 @@ bash ~/.claude/scripts/phase-tracker.sh sub 7 1.5 "Issue comment" in_progress
 gh issue comment "$ISSUE_NUMBER" --repo "$ORG/$REPO" --body-file /tmp/channels-${TASK_ID}-issue.md
 bash ~/.claude/scripts/phase-tracker.sh sub 7 1.5 "Issue comment" completed
 
-# 2. Sync the Progress flag table from agent-state.json. Idempotent — the
+# 2. Sync the Progress flag table from agent-state.json. Idempotent  -  the
 #    script no-ops if the body already matches.
 bash ~/.claude/scripts/phase-tracker.sh sub 7 1.6 "Progress flag sync" in_progress
 bash ~/.claude/scripts/update-issue-progress.sh "$TASK_ID"
 bash ~/.claude/scripts/phase-tracker.sh sub 7 1.6 "Progress flag sync" completed
 ```
 
-Order matters: comment first (timestamp marks the run), flags second (one logical body diff). If the comment fails, do NOT update flags — the channel is incomplete and the user needs to retry.
+Order matters: comment first (timestamp marks the run), flags second (one logical body diff). If the comment fails, do NOT update flags  -  the channel is incomplete and the user needs to retry.
 
 The Progress flag values come from `state.flags`:
 
@@ -117,25 +127,25 @@ The Progress flag values come from `state.flags`:
 | `codeConnect`    | Code Connect   |
 | `wiki`           | Wiki           |
 
-Each value is `true` (🟢), `"yellow"` (🟡), or `false`/missing (⚪). Phase 3 / 5 / 6 are responsible for setting these honestly — Phase 7 only mirrors what's already in state.
+Each value is `true` (🟢), `"yellow"` (🟡), or `false`/missing (⚪). Phase 3 / 5 / 6 are responsible for setting these honestly  -  Phase 7 only mirrors what's already in state.
 
 **Hard rule (per `refs/channels/issue-comment.md`):** never run only one of the two actions. The comment is the human-readable audit; flags are the machine-readable status. Either both or neither.
 
 ---
 
-## Step 2 — Finalize Report (internal)
+## Step 2  -  Finalize Report (internal)
 
 Write `agent-log.md` with ALL sections:
 
 ```markdown
-# {jiraId} — {Task Title}
+# {jiraId}  -  {Task Title}
 
 **Branch**: {branch-name} | **Project**: {project}
 **Started**: {datetime} | **Finished**: {datetime} | **Status**: Complete
 
 ## Plan Todo Rollup (when `prefs.global.planTodos.enabled`)
 
-Rendered via `pipeline/lib/plan-todos.sh list "$TASK_ID"`. Inline the resulting markdown checklist verbatim — one line per todo with status marker ([x] / [~] / [/] / [!]), ID, task text, and notes when present. Status summary one-liner ("4/6 done, 1 skipped, 1 failed") goes at the top from `plan-todos.sh status`.
+Rendered via `pipeline/lib/plan-todos.sh list "$TASK_ID"`. Inline the resulting markdown checklist verbatim  -  one line per todo with status marker ([x] / [~] / [/] / [!]), ID, task text, and notes when present. Status summary one-liner ("4/6 done, 1 skipped, 1 failed") goes at the top from `plan-todos.sh status`.
 
 Skipped sections: when `planTodos.enabled` is false or no `plan.todos[]` was emitted, the Plan Todo block is omitted (no empty header). Phase 3 task-by-task progress still appears in the Timeline section either way.
 
@@ -184,7 +194,9 @@ pipeline/scripts/log-metric.sh "$TASK_ID" 7 task.completed \
 
 **Aggregate before reporting**: run `aggregate-metrics.mjs --since=$(date -u -v-30d +%Y-%m-%d)` and embed output in agent-log.md. Use `--json` for Jira. Aggregator handles missing files gracefully.
 
-**Cost Breakdown emission (mandatory):** as part of agent-log compose, append the per-task cost block produced by `render-agent-log-cost.sh`. Best-effort — exit 2 (no tracker data) silently skipped:
+**Per-run outcome metrics (evidence corpus):** also emit `run-metrics.mjs --state <agent-state.json>` and append/persist its JSON. It records the numbers that actually answer "did this run go well" - review iterations (rework loops), first-pass-clean, reviewer signal-to-noise (accepted / raw findings), consensus verdict, build outcome. Accumulating these across real runs is the real-world validation that golden tasks + benchmarks only approximate; keep the corpus so the pipeline's quality can be measured, not asserted.
+
+**Cost Breakdown emission (mandatory):** as part of agent-log compose, append the per-task cost block produced by `render-agent-log-cost.sh`. Best-effort  -  exit 2 (no tracker data) silently skipped:
 
 ```bash
 COST_BLOCK=$(bash pipeline/scripts/render-agent-log-cost.sh "$TASK_ID" 2>/dev/null) && \
@@ -193,7 +205,7 @@ COST_BLOCK=$(bash pipeline/scripts/render-agent-log-cost.sh "$TASK_ID" 2>/dev/nu
 
 This is independent of the channels-side `reportContent.costSummary` (which gates the PR-body Cost Summary). agent-log always carries the breakdown when telemetry is present.
 
-**Triage memory ingest (mandatory):** after Phase 4 produces a final triage output, persist the accepted/deferred/rejected rows into the per-repo triage corpus so Phase 1 enrichment and Phase 4 prior-art lookup can recall them on future tasks. Idempotent — re-running on the same task writes 0 rows.
+**Triage memory ingest (mandatory):** after Phase 4 produces a final triage output, persist the accepted/deferred/rejected rows into the per-repo triage corpus so Phase 1 enrichment and Phase 4 prior-art lookup can recall them on future tasks. Idempotent  -  re-running on the same task writes 0 rows.
 
 ```bash
 TRIAGE_PATH="$WORKTREE/triage-output.json"
@@ -206,21 +218,35 @@ if [ -f "$TRIAGE_PATH" ]; then
 fi
 ```
 
-Best-effort. The corpus is JSONL at `~/.claude/memory/multi-agent/<repo-slug>/triage-corpus.jsonl` (per-repo isolation — never cross-leaks between projects). Disabled when `prefs.global.priorArtEnrichment.ingestOnComplete = false`.
+Best-effort. The corpus is JSONL at `~/.claude/memory/multi-agent/<repo-slug>/triage-corpus.jsonl` (per-repo isolation  -  never cross-leaks between projects). Disabled when `prefs.global.priorArtEnrichment.ingestOnComplete = false`.
+
+**Learnings ledger distill (on by default via `prefs.global.learningsLedger.enabled`):** distill this run's rejected findings into durable rejected-preference entries so future reviewers stop re-raising them, and record any durable architectural fact the analysis surfaced. Idempotent (dedup by kind + statement). Safety: `from-triage` skips blocking-severity rejections - a wrong rejection of a blocking issue must never permanently suppress that class; use `learnings-ledger.mjs forget` to clear a bad/stale entry.
+
+```bash
+if [ -f "$TRIAGE_PATH" ]; then
+  node pipeline/scripts/learnings-ledger.mjs from-triage \
+    --triage "$TRIAGE_PATH" --task "$TASK_ID" >/dev/null 2>&1 || true
+fi
+# Optionally capture a durable architectural fact the analysis established:
+# node pipeline/scripts/learnings-ledger.mjs add --kind fact \
+#   --statement "<one-line fact>" --scope "<path-glob>" --task "$TASK_ID" >/dev/null 2>&1 || true
+```
+
+The ledger is JSONL at `~/.claude/memory/multi-agent/<repo-slug>/learnings-ledger.jsonl`, next to the triage corpus, per-repo isolated. Its brief is replayed into Phase 1 analysis and Phase 4 triage on future runs.
 
 Print compact summary to terminal:
 
 ```
 {jiraId} complete
 Total: Xm Ys | Agents: N calls | Files: N changed
-Channels: PR ✓ · Jira ✓ · Confluence – · Wiki ✓ (3 files)
+Channels: PR ✓ · Jira ✓ · Confluence - · Wiki ✓ (3 files)
 Commit: abc1234 | PR: #87
 Full report: $HOME/.claude/logs/multi-agent/{project}/{task-id}/agent-log.md
 ```
 
 Tracker: `phase-tracker.sh sub 7 2 "Log+Telemetry" completed`.
 
-## Step 3 — Knowledge Capture (incremental learning)
+## Step 3  -  Knowledge Capture (incremental learning)
 
 Extract reusable knowledge from this task and **append** to `$HOME/.claude/knowledge/{project-name}/`:
 
@@ -231,7 +257,7 @@ Extract reusable knowledge from this task and **append** to `$HOME/.claude/knowl
 | `gotchas.md`      | Build errors/solutions, edge cases, workarounds | Phase 3 retries, Phase 4 blocking |
 | `decisions.md`    | Architectural decisions + rationale             | Phase 2 plan + Phase 4            |
 
-**Rules:** Only save reusable knowledge (task-specific details stay in agent-log). Read existing files before appending — no duplicates. Add date: `<!-- captured: {date}, task: {jiraId} -->`. Conflicting info → update old entry, don't delete.
+**Rules:** Only save reusable knowledge (task-specific details stay in agent-log). Read existing files before appending  -  no duplicates. Add date: `<!-- captured: {date}, task: {jiraId} -->`. Conflicting info → update old entry, don't delete.
 
 **Entry format:**
 
@@ -249,7 +275,7 @@ Extract reusable knowledge from this task and **append** to `$HOME/.claude/knowl
 
 **Per-repo memory synthesis (opt-in via `prefs.global.perRepoMemory`):**
 
-After the knowledge-capture pass, dispatch a scoped synthesis subagent (sonnet, 10 turns max) that reads the current run's `agent-log.md` + the existing MEMORY.md index, and returns 0–3 new memory entries as a JSON array. Each entry: `{type: "user|feedback|project|reference", slug, title, description, body}`. The orchestrator then loops:
+After the knowledge-capture pass, dispatch a scoped synthesis subagent (sonnet, 10 turns max) that reads the current run's `agent-log.md` + the existing MEMORY.md index, and returns 0-3 new memory entries as a JSON array. Each entry: `{type: "user|feedback|project|reference", slug, title, description, body}`. The orchestrator then loops:
 
 ```bash
 for entry in $(jq -c '.[]' memory-synthesis.json); do
@@ -265,7 +291,7 @@ done
 - **project**: only if someone named a new deadline, constraint, or stakeholder that wasn't already in the task description
 - **reference**: only if an external system URL / dashboard / channel was mentioned as the source of truth for some concern
 - **user**: only if the user disclosed new context about their role, expertise, or team layout
-- **Otherwise return `[]`** — blank is the correct default. Do not save derivable facts (code structure, git history, command outputs).
+- **Otherwise return `[]`**  -  blank is the correct default. Do not save derivable facts (code structure, git history, command outputs).
 
 Zero new memories is normal and expected. A typical run produces one or none.
 
@@ -281,7 +307,7 @@ If user does not respond at the channels multi-select menu within 30 minutes (wa
 
 1. Channels command aborts its interactive prompt, returns `{status: "timeout"}`.
 2. Phase 7 records `phase-tracker.sh sub 7 1 "Channels dispatch" timeout`.
-3. **Internal capture still runs** — Steps 2 + 3 write `agent-log.md` (with `channels: timeout` in summary), emit telemetry, update knowledge base.
+3. **Internal capture still runs**  -  Steps 2 + 3 write `agent-log.md` (with `channels: timeout` in summary), emit telemetry, update knowledge base.
 4. Session exits cleanly. State persisted: `state.phase=7, state.waitingFor="user-channels-choice", state.channelsTimeout=true`.
 5. Resume contract: `/multi-agent:resume <task-id>` re-opens the channels menu with the original state bundle (pipeline log, PR metadata, prefs pre-ticks).
 

package/pipeline/commands/multi-agent/refs/phases.md

@@ -1,4 +1,4 @@
-# Multi-Agent Pipeline — Phase Reference
+# Multi-Agent Pipeline  -  Phase Reference
 
 ## Phase Files
 
@@ -21,17 +21,17 @@
 ```
 Normal:    0-Init -> 1-Analysis -> 2-Planning -> 3-Dev -> 4-Review -> 5-Test -> 6-Commit -> 7-Report
 --dev:     0-Init ------------------------------------------> 3-Dev -----------> 6-Commit -> 7-Report
---local:   Same as above but no worktree — works directly on local branch
+--local:   Same as above but no worktree  -  works directly on local branch
 ```
 
 ## Visual Phase Tracker
 
-Two channels run in parallel at every phase boundary. Both are required in their target CLIs — skipping either is the #1 source of "I see no progress" complaints.
+Two channels run in parallel at every phase boundary. Both are required in their target CLIs  -  skipping either is the #1 source of "I see no progress" complaints.
 
 | Mechanism                        | Available in     | Status        | Style                                                |
 | -------------------------------- | ---------------- | ------------- | ---------------------------------------------------- |
 | **`phase-tracker.sh`** (state)   | Every CLI        | required     | Drives `tracker-state.json`; powers `:resume`/`:log`/`:status` |
-| **`TaskCreate` / `TaskUpdate`**  | Claude Code only | required here | Native sticky TaskList widget — the only progress signal Claude Code surfaces |
+| **`TaskCreate` / `TaskUpdate`**  | Claude Code only | required here | Native sticky TaskList widget  -  the only progress signal Claude Code surfaces |
 | **`phase-tracker.sh render`**    | Every other CLI  | required here | Bordered ANSI card printed as last tool result so the user sees the phase table |
 | **`phase-banner.sh`**            | Every CLI        | Optional      | One-shot ANSI banner per phase boundary (extra emphasis) |
 
@@ -71,7 +71,7 @@ pipeline/scripts/phase-tracker.sh sub <N> 1 "<sub name>" in_progress  # advance
 pipeline/scripts/phase-tracker.sh sub <N> 1 "<sub name>" completed    # done
 ```
 
-State persists at `$HOME/.claude/logs/multi-agent/<task_id>/tracker-state.json` — atomic writes mean concurrent worktrees don't corrupt each other.
+State persists at `$HOME/.claude/logs/multi-agent/<task_id>/tracker-state.json`  -  atomic writes mean concurrent worktrees don't corrupt each other.
 
 ### Optional banner (single-event flair)
 
@@ -85,35 +85,35 @@ pipeline/scripts/phase-banner.sh sub   <N> 2     "<sub>" "<detail>"
 
 Banner status enum on `end`: `done` | `failed` | `skipped`. Anything else exits 64.
 
-### TaskCreate registration (Claude Code — required)
+### TaskCreate registration (Claude Code  -  required)
 
-In Claude Code the agent MUST register one TaskCreate tile per phase at Phase 0 startup (one per phase that the current mode runs — full pipeline = 0..7, `--dev` = 0/3/6/7). Capture the returned `taskId`, persist it via `phase-tracker.sh meta <N> tasklist_id "<taskId>"` so `:resume` can rebuild the widget.
+In Claude Code the agent MUST register one TaskCreate tile per phase at Phase 0 startup (one per phase that the current mode runs  -  full pipeline = 0..7, `--dev` = 0/3/6/7). Capture the returned `taskId`, persist it via `phase-tracker.sh meta <N> tasklist_id "<taskId>"` so `:resume` can rebuild the widget.
 
 Per phase boundary:
 
 ```text
-# Phase entry — flip the tile to in_progress alongside the state update
+# Phase entry  -  flip the tile to in_progress alongside the state update
 TaskUpdate({ taskId: <saved>, status: "in_progress" })
 bash phase-tracker.sh update <N> in_progress
 
-# Active sub-step inside a phase — keeps the spinner header live
+# Active sub-step inside a phase  -  keeps the spinner header live
 TaskUpdate({ taskId: <saved>, activeForm: "Editing TopBarView.swift" })
 TaskUpdate({ taskId: <saved>, activeForm: "Running xcodebuild test" })
 
-# Phase exit — flip both channels
+# Phase exit  -  flip both channels
 TaskUpdate({ taskId: <saved>, status: "completed" })
 bash phase-tracker.sh update <N> completed
 ```
 
-`--dev` mode does NOT TaskCreate phases 1/2/4 at all — those phases are not part of the `--dev` set (`0:Init 3:Dev 5:Test 6:Commit 7:Report`). Only register tiles for the active mode's phase set. (Earlier guidance suggested pre-marking 1/2/4 with `[SKIPPED]` activeForm; that produces visually scrambled tile stacks — see the v8.3.1 ordering rule below.)
+`--dev` mode does NOT TaskCreate phases 1/2/4 at all  -  those phases are not part of the `--dev` set (`0:Init 3:Dev 5:Test 6:Commit 7:Report`). Only register tiles for the active mode's phase set. (Earlier guidance suggested pre-marking 1/2/4 with `[SKIPPED]` activeForm; that produces visually scrambled tile stacks  -  see the v8.3.1 ordering rule below.)
 
-**(strict) TaskCreate ordering**: All TaskCreate calls MUST fire in strict phase-number order BEFORE any TaskUpdate is applied. The native widget renders by creation order, not by phase number — out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN — register the tile in order with default `pending` status, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `refs/tracker-contract.md` § "TaskCreate ordering (strict)".
+**(strict) TaskCreate ordering**: All TaskCreate calls MUST fire in strict phase-number order BEFORE any TaskUpdate is applied. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order with default `pending` status, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
-**Copilot CLI / Cursor / Windsurf / plain shell**: do NOT call TaskCreate — the tool does not exist on these CLIs. Instead, after every state update, call `bash phase-tracker.sh render` so the bordered ANSI card prints as the last tool result. That's the equivalent visual signal there.
+**Copilot CLI / Cursor / Windsurf / plain shell**: do NOT call TaskCreate  -  the tool does not exist on these CLIs. Instead, after every state update, call `bash phase-tracker.sh render` so the bordered ANSI card prints as the last tool result. That's the equivalent visual signal there.
 
 ## Preferences File
 
-Path: `$HOME/.claude/multi-agent-preferences.json` — persistent state across sessions.
+Path: `$HOME/.claude/multi-agent-preferences.json`  -  persistent state across sessions.
 
 ## Host Configuration
 
@@ -133,7 +133,7 @@ For operations (status, kill, resume, purge): read operations.md.
 
 ## Token Budget
 
-Each phase doc is lazy-loaded — only the current phase's spec is in context. Budget enforced by `smoke-token-budget.sh`.
+Each phase doc is lazy-loaded  -  only the current phase's spec is in context. Budget enforced by `smoke-token-budget.sh`.
 
 | Phase       | File                | Max Tokens | Warn  |
 | ----------- | ------------------- | ---------- | ----- |
@@ -183,5 +183,5 @@ When a specialized skill takes over a main pipeline phase, progress is reported
 
 **Why SubPhases, not separate phases:**
 
-- Main pipeline stays a fixed 8-phase contract (0-7) regardless of task type. Wiki, Confluence, and Figma screenshots all live as SubPhases under Phase 7 Report — external delivery grouped logically, internal report + knowledge after.
-- Conditional phases are a code smell — they force every reader to learn which phase runs when.
+- Main pipeline stays a fixed 8-phase contract (0-7) regardless of task type. Wiki, Confluence, and Figma screenshots all live as SubPhases under Phase 7 Report  -  external delivery grouped logically, internal report + knowledge after.
+- Conditional phases are a code smell  -  they force every reader to learn which phase runs when.