@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/commands/multi-agent/refs/frontend-guide.md

@@ -0,0 +1,136 @@
+## Frontend Development Guide
+
+When the task involves frontend development (React, Next.js, Vue), follow these patterns.
+
+### Component Architecture
+
+| File                                      | When          | Content                            |
+| ----------------------------------------- | ------------- | ---------------------------------- |
+| `{Name}.tsx`                              | Always        | Component with props interface     |
+| `{Name}.module.css` or `{Name}.styles.ts` | Styled        | CSS modules or styled-components   |
+| `{Name}.test.tsx`                         | Always        | Unit + integration tests           |
+| `{Name}.stories.tsx`                      | Reusable      | Storybook stories for all variants |
+| `use{Name}.ts`                            | Complex state | Custom hook for state/logic        |
+
+### React Component Pattern
+
+```tsx
+// Props interface — explicit, documented
+interface ButtonProps {
+  label: string;
+  variant?: "primary" | "secondary" | "ghost";
+  size?: "sm" | "md" | "lg";
+  disabled?: boolean;
+  loading?: boolean;
+  onClick: () => void;
+}
+
+// Component — single responsibility
+export function Button({
+  label,
+  variant = "primary",
+  size = "md",
+  disabled = false,
+  loading = false,
+  onClick,
+}: ButtonProps) {
+  return (
+    <button
+      className={cn(styles.button, styles[variant], styles[size])}
+      disabled={disabled || loading}
+      onClick={onClick}
+      aria-busy={loading}
+    >
+      {loading ? <Spinner size={size} /> : label}
+    </button>
+  );
+}
+```
+
+### State Management
+
+```tsx
+// Simple state — useState/useReducer
+const [count, setCount] = useState(0);
+
+// Complex state — custom hook
+function useAuth() {
+  const [user, setUser] = useState<User | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    authService
+      .getCurrentUser()
+      .then(setUser)
+      .finally(() => setLoading(false));
+  }, []);
+
+  return { user, loading, isAuthenticated: !!user };
+}
+
+// Server state — React Query / SWR
+const { data, isLoading, error } = useQuery({
+  queryKey: ["users", userId],
+  queryFn: () => fetchUser(userId),
+});
+```
+
+### Token Discipline
+
+| Bad                | Good                                         |
+| ------------------ | -------------------------------------------- |
+| `padding: '16px'`  | `padding: tokens.spacing.md` or CSS variable |
+| `color: '#E31837'` | `color: var(--color-primary)`                |
+| `fontSize: '14px'` | `fontSize: tokens.typography.body.size`      |
+| `"Submit"` inline  | `t('form.submit')` (i18n)                    |
+
+### Accessibility
+
+Every interactive element MUST have:
+
+- Semantic HTML (`<button>`, `<nav>`, `<main>`, not `<div onClick>`)
+- `aria-label` when visual label is absent
+- `aria-describedby` for supplementary info
+- Keyboard navigation support (focus management)
+- Color contrast ratio >= 4.5:1
+
+```tsx
+<button aria-label="Close dialog" aria-describedby="dialog-description" onClick={onClose}>
+  <CloseIcon aria-hidden="true" />
+</button>
+```
+
+### Testing
+
+```tsx
+// Component test — React Testing Library
+test("renders button with label", () => {
+  render(<Button label="Submit" onClick={vi.fn()} />);
+  expect(screen.getByRole("button", { name: "Submit" })).toBeInTheDocument();
+});
+
+test("calls onClick when clicked", async () => {
+  const onClick = vi.fn();
+  render(<Button label="Submit" onClick={onClick} />);
+  await userEvent.click(screen.getByRole("button"));
+  expect(onClick).toHaveBeenCalledOnce();
+});
+
+test("shows loading state", () => {
+  render(<Button label="Submit" loading onClick={vi.fn()} />);
+  expect(screen.getByRole("button")).toHaveAttribute("aria-busy", "true");
+});
+```
+
+### Quality Checklist
+
+1. No magic numbers — design tokens or CSS variables
+2. Semantic HTML — correct elements, not div-soup
+3. Accessibility — ARIA labels, keyboard nav, contrast
+4. Responsive — works on mobile, tablet, desktop
+5. i18n — all strings via translation keys
+6. Error boundaries — graceful error handling
+7. Loading states — skeleton/spinner for async operations
+8. Tests — component + hook tests, no implementation details
+9. Performance — memoization where needed (React.memo, useMemo, useCallback)
+10. Build passes — zero warnings, TypeScript strict mode

package/pipeline/commands/multi-agent/refs/issue-jira-triad.md

@@ -0,0 +1,104 @@
+# Issue → Jira → Wiki Triad
+
+> **TLDR** — When a GitHub issue triggers the pipeline and has no Jira ID, the `autoJiraFromGithubIssue` policy decides whether to auto-create a Jira task (and patch the GitHub issue body with the new Jira link). Phase 7 then posts a humanizer'd wiki-content summary back as a Jira comment, closing the loop. Autopilot treats `ask` as `always`.
+
+This doc is referenced from `refs/phases/phase-0-init.md` Step 1 (GitHub issue input) and `refs/phases/phase-7-report.md` Step 2 (component wiki). Keeps the phase docs tight and gives the triad contract a stable home.
+
+## The triad at a glance
+
+```
+GitHub issue (no Jira link)
+     │
+     ▼  Phase 0 Step 1  — auto-create policy
+Jira issue (new, linked both ways)
+     │
+     ▼  Phase 3 — component implementation
+wiki markdown in pipeline/skills/…
+     │
+     ▼  Phase 7 Report Step 2 — wiki capture + Jira comment post
+Jira comment (humanizer'd component summary)
+```
+
+## Phase 0 auto-create policy
+
+Inputs:
+
+- `state.inputType === "github-issue-url"` or `"github-issue-number"` — not `jira-*`, not `free-text`.
+- `state.jiraId` is null (no `{JIRA_KEY}-XXXXX` found in the issue body).
+- `prefs.global.autoJiraFromGithubIssue` — enum `ask` | `always` | `never`.
+- `state.mode` — `autopilot` overrides `ask` to `always` (no interactive fallback when user isn't watching).
+
+Decision table:
+
+| preference | interactive | autopilot |
+|---|---|---|
+| `ask`    | prompt `Create Jira issue for this? (y/n)` | treat as `always` |
+| `always` | silently create + log | silently create + log |
+| `never`  | skip + log | skip + log |
+
+**Create path:**
+
+1. Emit progress line `→ creating Jira issue for GH{issueNo}`.
+2. Resolve Jira token via `keychainMapping.jira`. Token missing → run Token Save Flow from `setup.md` inline (clipboard-based; user can add now or skip). Skip → treat as `never` for this run.
+3. Derive Jira fields from the GitHub issue:
+   - `summary` ← GitHub issue title (truncate to 255 chars).
+   - `description` ← GitHub issue body, prefixed with `h3. From GitHub\n[GH{issueNo}|{url}]\n\n`.
+   - `issueType` — infer from labels: `bug` → Bug, `enhancement` → Story, default Task.
+   - `project` — `figmaConfig.jira.projectKey`, or `prefs.global.defaultJiraKey`, or prompt (cached after first use).
+   - `priority` — derive from labels if present (`priority:high` → High, etc.); else leave unset (Jira default).
+4. `POST {jira.baseUrl}/rest/api/2/issue` with the derived payload.
+5. On success: store new Jira key in `state.jiraId`. Emit `→ created Jira {newKey}`.
+6. Patch the GitHub issue body: append a line `Jira: [{newKey}]({jira.baseUrl}/browse/{newKey})` so the bidirectional link is visible on GitHub without refetching the pipeline state.
+
+**Skip path** (`never` or user declined): Branch falls back to `feature/GH{issueNo}-{kebab}`; Phase 7 later emits `→ no Jira linked (policy: {preference})`.
+
+**Failure isolation:** Jira API 5xx or network error → log the error, warn the user, and **continue with no Jira link** (do not halt Phase 0). Rationale: a transient Jira outage should not block code work; user can link manually post-hoc.
+
+## Phase 7 wiki → Jira comment
+
+Runs after Phase 7 Report Step 2 (wiki capture) has produced markdown and only when:
+
+- `state.jiraId` is non-null (from Phase 0 scan or auto-create).
+- `prefs.global.wikiToJiraComment !== false` (default true).
+- Step 2 actually wrote files (skipped taskTypes don't trigger this).
+
+Flow:
+
+1. Emit `→ posting wiki summary to Jira {jiraId}`.
+2. Read the first N lines of the primary wiki markdown file (the component's overview page — one of `writtenPaths[0]`).
+3. Render as Jira comment: title line (`h3. Component docs — {componentName}`) + an overview paragraph + a link to the full page (wiki URL, if the adapter returned `pushedRemote`).
+4. **Run through the humanizer skill** — same policy as Step 4 Confluence: user-facing content must read naturally.
+5. `POST {jira.baseUrl}/rest/api/2/issue/{jiraId}/comment`.
+6. Log: `Phase 7: wiki summary posted to Jira {jiraId}`.
+
+On failure: log + continue. Wiki is already written; the Jira comment is an augmentation. Don't regress Phase 7 over a Jira 5xx.
+
+## Autopilot behaviour
+
+Autopilot forces:
+
+- `autoJiraFromGithubIssue: ask` → `always` (no user to prompt).
+- `wikiToJiraComment` obeys its preference (default `true`) — no prompting either way.
+
+Rationale: autopilot is explicit consent for side-effect creation; muting Jira activity would defeat the purpose.
+
+## Preferences involved
+
+| key | type | default | controls |
+|---|---|---|---|
+| `prefs.global.autoJiraFromGithubIssue` | enum ask/always/never | `ask` | Phase 0 auto-create decision |
+| `prefs.global.wikiToJiraComment` | bool | `true` | Phase 7 wiki → Jira comment post |
+| `figmaConfig.jira.projectKey` | string | — | Target project for new issues (falls back to `prefs.global.defaultJiraKey`) |
+| `prefs.global.keychainMapping.jira` | string | — | Jira token keychain lookup |
+
+## Cross-CLI parity
+
+Both Claude Code and Copilot CLI implementations MUST:
+
+- Resolve the `autoJiraFromGithubIssue` enum the same way.
+- Derive Jira fields from GitHub issue metadata identically (title → summary, body → description with `h3. From GitHub` prefix, label → issueType mapping).
+- Patch the GitHub issue body with the `Jira: [KEY](url)` line after create.
+- Treat failures as non-blocking with the same log shape.
+- Run the humanizer skill on the wiki-summary Jira comment.
+
+`smoke-issue-jira-triad.sh` asserts every contract item.

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

@@ -0,0 +1,80 @@
+## Keychain Token Registry
+
+Tokens live in the platform-native credential store (macOS Keychain / Linux libsecret / Windows Credential Manager). Key names are resolved via **preferences mapping** — never hardcoded.
+
+### Rule 1 — Never prompt for a token mid-run
+
+The pipeline NEVER prompts the user mid-phase for a token value. If a token is needed for the current operation:
+
+1. Read the mapped key from `prefs.global.keychainMapping.<service>`.
+2. Resolve via `~/.claude/lib/credential-store.sh get "$KEY_NAME"`.
+3. **If the credential store returns empty / missing**: pause the current adapter, surface a structured error (`{ status: "blocked", reason: "missing-token", service: "<id>", expected_key: "<name>" }`), and direct the user to `/multi-agent:setup` (the inline Token Save Flow). Resume from the same step after setup. **Do NOT** ask the user to paste the token in chat.
+4. **If the credential returns 401 / invalid**: surface the same structured error with `reason: "expired-token"`. Open the Save Flow with the "expired" trigger.
+
+Reasons:
+- Asking for a token in chat leaks it into the conversation transcript and any audit log.
+- The user has already configured the keychain; missing/expired is a setup issue, not a per-run issue.
+- The structured error gives the orchestrator a clear path: pause → setup → resume.
+
+The smoke gate `pipeline/scripts/smoke-no-token-prompt.sh` greps the pipeline source for hardcoded "enter token" / "paste token" / "API key:" prompts and fails the build if any are introduced. Token I/O is exclusively `credential-store.sh` calls.
+
+**Retrieve pattern (always use mapping):**
+
+```bash
+PREFS_FILE="$HOME/.claude/multi-agent-preferences.json"
+
+# Read mapped key name for a service, fallback to standard name
+KEY_NAME=$(jq -r '.global.keychainMapping.<service_id> // "<standard_key_name>"' "$PREFS_FILE")
+TOKEN=$(~/.claude/lib/credential-store.sh get "$KEY_NAME" 2>/dev/null)
+```
+
+The shell driver auto-delegates to `~/.claude/scripts/keychain.py` on macOS / Linux for deterministic behaviour (writes both `-l` (label) and `-s` (service) attributes; reads tolerate either convention so manually-added personal tokens are findable).
+
+**Standard key names (convention for new tokens):**
+
+| Service ID         | Context            | Standard Key Name                  | Type              |
+| ------------------ | ------------------ | ---------------------------------- | ----------------- |
+| `jira`             | Jira issue fetch   | `${USER}_Jira_Access_Token`        | PAT               |
+| `bitbucket_token`  | Bitbucket PR/push  | `${USER}_Bitbucket_Access_Token`   | App Password      |
+| `bitbucket_user`   | Bitbucket username | `${USER}_Bitbucket_Username`       | Plain text        |
+| `github`           | GitHub issue/PR    | `${USER}_Github_Access_Token`      | PAT (+ `gh auth`) |
+| `confluence`       | Confluence docs    | `${USER}_Confluence_Access_Token`  | PAT               |
+| `figma`            | Figma              | `${USER}_Figma_Access_Token`       | PAT               |
+| `figma_mcp`        | Figma MCP          | `${USER}_Figma_Mcp_Access_Token`   | OAuth             |
+| `fortify`          | Fortify            | `${USER}_Fortify_Access_Token`     | API Token         |
+| `firebase`         | Firebase           | `${USER}_Firebase_Access_Json`     | JSON (base64)     |
+| `jenkins`          | Jenkins CI         | `${USER}_Jenkins_Access_Token`     | API Token         |
+| —                  | Git Identity       | Stored in preferences JSON         | Not Keychain      |
+
+**Key name mapping lives in preferences:**
+
+```json
+{
+  "global": {
+    "keychainMapping": {
+      "jira": "${USER}_Jira_Access_Token",
+      "bitbucket_token": "${USER}_Bitbucket_Access_Token",
+      "bitbucket_user": "${USER}_Bitbucket_Username",
+      "github": "${USER}_Github_Access_Token",
+      "confluence": "${USER}_Confluence_Access_Token",
+      "figma": "${USER}_Figma_Access_Token",
+      "figma_mcp": "${USER}_Figma_Mcp_Access_Token",
+      "fortify": "${USER}_Fortify_Access_Token",
+      "firebase": "${USER}_Firebase_Access_Json",
+      "jenkins": "${USER}_Jenkins_Access_Token"
+    }
+  }
+}
+```
+
+**Key naming rule:**
+- **Existing tokens**: actual key names may differ from standard names (e.g. `MyGithubPAT` instead of `${USER}_Github_Access_Token`). These are NEVER renamed — the mapping in preferences resolves the difference. Run `/multi-agent setup` to discover and map existing keys.
+- **New tokens**: ALWAYS created with the standard key name from the table above. This ensures cross-machine consistency for new installations.
+
+**Multiple keys for same service**: If Keychain contains more than one entry for a service (e.g. multiple Firebase keys), list all found entries and ask the user which one to use. Never assume — always ask.
+
+**Adding a new token (uses standard key name automatically):**
+
+```bash
+bash "$HOME/.claude/scripts/keychain-save.sh" <service-id>
+```

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

@@ -0,0 +1,112 @@
+## Project Knowledge Base
+
+An incrementally growing knowledge system for each project, enabling knowledge transfer across sessions.
+
+### Directory Structure
+
+```
+$HOME/.claude/knowledge/
+  my-app/
+    architecture.md    — module map, file relationships, dependency graph
+    patterns.md        — naming, conventions, recurring structures
+    gotchas.md         — build errors, edge cases, workarounds
+    decisions.md       — architectural decisions and rationale (ADR-lite)
+  another-project/
+    architecture.md
+    patterns.md
+    gotchas.md
+    decisions.md
+  ...
+```
+
+### How It Works
+
+```
+Task 1 (first time): Phase 1 -> full Explore -> Phase 7 -> create knowledge
+Task 2:             Phase 1 -> read knowledge -> targeted Explore -> Phase 7 -> update knowledge
+Task 3:             Phase 1 -> read knowledge -> minimal Explore -> Phase 7 -> update knowledge
+  ...
+Task N:             Phase 1 -> knowledge sufficient -> SKIP Explore -> Phase 7 -> update knowledge
+```
+
+Each task teaches the project a bit more. Token cost decreases over time.
+
+### Knowledge vs CLAUDE.md vs Auto Memory
+
+| Layer                                       | Who Writes            | Scope                                      | Lifetime                 |
+| ------------------------------------------- | --------------------- | ------------------------------------------ | ------------------------ |
+| `$PROJECT_ROOT/CLAUDE.md`                   | User                  | Project rules, build commands              | Persistent (in git)      |
+| Auto Memory (`~/.claude/projects/`)         | Claude (automatic)    | User preferences, feedback                 | Persistent (global)      |
+| **Knowledge Base** (`~/.claude/knowledge/`) | Multi-agent (Phase 7) | Architecture, patterns, gotchas, decisions | Persistent (per-project) |
+
+They all complement each other — no conflicts.
+
+### Knowledge in --dev Mode
+
+In `--dev` mode Phase 1 is skipped but knowledge **is still read**:
+
+- Knowledge files are added to the prompt before the Opus agent starts in Phase 3
+- Knowledge capture is still performed in Phase 7 (simplified report)
+
+### Knowledge Maintenance
+
+Knowledge files grow over time. Maintenance rules:
+
+- Every entry has a `<!-- captured: {date}, task: {id} -->` tag
+- 90-day-old entries are considered "stale" — not used without verification
+- Stale check: orchestrator checks file mtime during Phase 1 knowledge injection
+- Stale entries are added to the prompt with a "STALE — verify before relying" tag
+- `clear-logs` does not touch knowledge — only deletes logs and state
+- `purge` does not touch knowledge either — separate command: `/multi-agent clear-knowledge {project}`
+
+---
+
+## Skill Injection Strategy
+
+When calling sub-agents, inject task-specific context from previous phases:
+
+### Phase -> Agent -> Context Flow
+
+```
+Phase 1: Analysis
+  -- Explore agents (parallel) -> codebase scan
+
+Phase 2: Planning
+  -- Architecture review agent
+       Context: task description + Phase 1 findings + affected modules
+
+Phase 3: Dev
+  -- Sonnet agent (TDD)
+       Context: Phase 2 plan + task dependencies
+
+Phase 4: Review (CLI-aware parallel + triage)
+  Claude Code (2 parallel):
+    |-- Reviewer (opus)   -> security + architecture
+    +-- Reviewer (sonnet) -> quality + correctness + edge cases
+  Copilot CLI (3 parallel):
+    |-- Reviewer (opus)    -> security + architecture
+    |-- Reviewer (gpt-5.4) -> edge cases, cross-provider diversity
+    +-- Reviewer (sonnet)  -> quality + correctness + naming
+       Context for ALL: Phase 1 files + Phase 2 decisions + Phase 3 diff
+       Then: single Opus triage pass filters false-positives
+```
+
+### Context-Aware Agent Prompting
+
+When launching review agents in Phase 4, include:
+
+```
+"Review this diff for {task-id}. Focus areas based on analysis:
+ - {files changed summary from Phase 1}
+ - {architecture decisions from Phase 2}
+ - {specific risk areas identified}"
+```
+
+When launching architecture agent in Phase 2, include:
+
+```
+"Evaluate architecture for {task-id}. Context:
+ - {task description}
+ - {affected modules from Phase 1}
+ - {existing patterns found by explore agents}"
+```

package/pipeline/commands/multi-agent/refs/multi-repo-integration-build.md

@@ -0,0 +1,207 @@
+# Multi-Repo Integration Build — Learn Once, Auto-Apply
+
+> **TLDR** — When a task touches ≥2 repos that have a producer→consumer dependency (e.g. shared codegen library + consuming UI library), the pipeline MUST build the **host project** that integrates them before commit/PR. Codegen mismatches (nested vs flat keys, missing entries, overwritten files) only surface when the full dependency chain builds together. Building repos in isolation gives false confidence.
+>
+> The pipeline **learns** the host per repo-combo once, persists to `prefs.global.multiRepoIntegrationHosts`, and auto-applies on subsequent runs.
+
+---
+
+## Why this exists
+
+Codegen outputs (identifiers, localization keys, tokens) in Repo A get referenced by source code in Repo B. Repo B is consumed as a submodule or SPM/Gradle dependency by host Repo C. Changes in A or B can silently break C if key structures diverge (e.g. nested enum vs flat access pattern). Skipping integration build has caused post-merge build failures that required additional fix PRs and wasted review cycles.
+
+---
+
+## When this rule fires
+
+In Phase 6 (Commit & PR), **before** the pre-commit local checkout prompt, if `state.projects.length >= 2`:
+
+1. Compute `repoSet` = sorted array of touched repo names.
+2. Look up `prefs.global.multiRepoIntegrationHosts` for an entry whose `repoSet` (sorted) equals this combo.
+3. Match found → **auto-run** the learned build (steps below).
+4. No match → **learn-once prompt** (below), then run.
+
+Single-repo tasks skip this step entirely — no prompt, no overhead.
+
+---
+
+## Learn-once prompt (first encounter of a combo)
+
+```
+This task touched N repos: <name>, <name>, <name>
+Do any of these need a host project (submodule consumer) built together
+to verify codegen / interface integration?
+
+  [1] Yes — register host project now (will auto-run on future runs)
+  [2] No  — this combo is independent (save as "no host" so we don't re-ask)
+  [3] Skip this run only (no learning)
+
+Select [1-3]:
+```
+
+**On [1]** — ask follow-ups:
+
+```
+Host project path (absolute): _______________________
+Platform: [ios | android | mixed]
+Scheme / target / module: _____________________________  (iOS: xcodebuild scheme · Android: gradle module)
+Submodule paths to refresh (space-separated, relative to host):
+  _____________________________________________________
+Dependency resolve command (press enter for defaults):
+  default ios:     xcodebuild -resolvePackageDependencies -skipMacroValidation
+  default android: ./gradlew dependencies --refresh-dependencies
+Build command (press enter for defaults):
+  default ios:     xcodebuild -scheme <S> -destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=latest' build -skipMacroValidation
+  default android: ./gradlew :<module>:assembleDebug
+```
+
+Persist to `prefs.global.multiRepoIntegrationHosts[]`:
+
+```json
+{
+  "repoSet": ["<repo-a>", "<repo-b>"],
+  "hostPath": "/absolute/path/to/host",
+  "platform": "ios",
+  "hostScheme": "<Scheme>",
+  "submodulePaths": [
+    "<submodule-path-a>",
+    "<submodule-path-b>"
+  ],
+  "resolveCommand": "xcodebuild -project <HostProject>.xcodeproj -scheme <Scheme> -resolvePackageDependencies -skipMacroValidation",
+  "buildCommand": "xcodebuild -project <HostProject>.xcodeproj -scheme <Scheme> -destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=latest' build -skipMacroValidation",
+  "lastUsed": "2026-04-20T15:30:00Z",
+  "count": 1,
+  "lastResult": "success"
+}
+```
+
+**On [2]** — persist a negative entry so the combo never re-asks:
+
+```json
+{ "repoSet": ["<repo-a>", "<repo-b>"], "noHost": true, "lastUsed": "..." }
+```
+
+**On [3]** — no write, re-ask next time.
+
+---
+
+## Auto-run steps (when host is learned)
+
+Progress-contract line `→ integrating <host-scheme> with <N> submodules`. Tracker sub-step on Phase 6 to show live status: `phase-tracker.sh sub 6 0 "Integration build" in_progress`.
+
+```bash
+HOST="$(jq -r --arg key "$repoSet_sorted_joined" \
+  '.global.multiRepoIntegrationHosts[]
+   | select((.repoSet | sort | join(",")) == $key)' "$PREFS_FILE")"
+
+HOST_PATH=$(echo "$HOST" | jq -r '.hostPath')
+RESOLVE_CMD=$(echo "$HOST" | jq -r '.resolveCommand')
+BUILD_CMD=$(echo "$HOST" | jq -r '.buildCommand')
+
+cd "$HOST_PATH"
+
+# 1. Pull latest submodules to pick up this task's changes
+for sm in $(echo "$HOST" | jq -r '.submodulePaths[]'); do
+  git submodule update --remote "$sm"
+done
+
+# 2. Resolve package dependencies (flush stale SPM/Gradle cache)
+eval "$RESOLVE_CMD"
+
+# 3. Run the host build, capture only error lines
+BUILD_ERRORS=$(eval "$BUILD_CMD" 2>&1 | grep -E "error:|FAILURE:|error FS" || true)
+
+# 4. Evaluate + decide
+if [ -z "$BUILD_ERRORS" ]; then
+  phase-tracker.sh sub 6 0 "Integration build" completed
+  log "Phase 6.0: Integration build — clean"
+  # proceed to pre-commit checkout prompt + commit
+else
+  phase-tracker.sh sub 6 0 "Integration build" failed
+  log "Phase 6.0: Integration build — NEW errors detected"
+  # show errors, ask user
+fi
+```
+
+Update `lastUsed`, `count++`, `lastResult` after each run.
+
+---
+
+## Error evaluation contract
+
+Three outcomes after the build:
+
+1. **Zero errors** → sub-step `completed`, proceed to pre-commit prompt.
+2. **New errors from our changes** → sub-step `failed`, STOP. Print the error lines, ask:
+   ```
+   Integration build failed with N new errors. Pipeline can go back to
+   Phase 3 to fix, or you can fix manually and tell the pipeline to retry.
+
+   [1] Return to Phase 3: Dev with these errors as input (auto-fix attempt)
+   [2] Pause — I'll fix manually, then /multi-agent resume
+   [3] Override — proceed to commit anyway (logs a warning in Phase 7 report)
+
+   Select [1-3]:
+   ```
+3. **Pre-existing errors (unrelated to this task)** → if the pipeline has a baseline error count (from a clean pre-change build), compare deltas. When `current_errors <= baseline`, treat as **no new errors** and proceed; log the pre-existing count in Phase 7 Report.
+
+---
+
+## Autopilot behavior
+
+Autopilot skips the "Override / pause" prompt. If `count` < 3 on this combo (new / low-confidence), autopilot treats a build failure as BLOCKING and returns to Phase 3 automatically (option 1). If `count >= 3` and `lastResult == success`, a new failure is treated as blocking the same way — but with lower surprise since we've seen this combo succeed before.
+
+The learn-once prompt itself also skips under autopilot: instead, autopilot logs `"Phase 6.0: SKIPPED — no learned host for this combo, autopilot refuses to prompt. Run in normal mode once to teach."` and proceeds. This is explicit and recoverable.
+
+---
+
+## Phase 7 knowledge capture
+
+When a learn-once prompt writes a new entry, Phase 7 Step 5 (knowledge + memory) ALSO writes a project-scoped memory:
+
+```
+Type: reference
+Name: multi-repo integration host — {combo}
+Body: For tasks touching {repoA} + {repoB}, the integration build runs in {hostPath} via
+      scheme {hostScheme}. Established {date}. Full config lives in
+      prefs.global.multiRepoIntegrationHosts.
+```
+
+Memories that reference integration hosts NEVER get auto-pruned — even if a combo goes many runs without firing, the knowledge is stable and worth keeping indexed for future teammates.
+
+---
+
+## Generic rule (for copilot-instructions.md)
+
+> **Post-Development Integration Build (Multi-Repo)**
+>
+> When a task touches multiple repositories that have a producer→consumer dependency (e.g. shared library + consuming component library), the pipeline MUST build the **consumer/host project** after all changes are complete — before commit/PR.
+>
+> **When this applies:**
+> - Code generation outputs (identifiers, localization keys, tokens) in Repo A are referenced by source code in Repo B
+> - Repo B is consumed as a submodule or SPM/Gradle dependency by a host project (Repo C)
+> - Changes in Repo A or B can silently break Repo C if key structures diverge (e.g. nested enum vs flat access pattern)
+>
+> **Required steps (after dev, before commit):**
+> 1. Identify the host project — the project that integrates all touched repos as submodules or package dependencies. Check `prefs.global.multiRepoIntegrationHosts` first; ask the user once if unknown.
+> 2. Update submodules to point at the latest feature branch / merged commit.
+> 3. Resolve package dependencies (flush stale SPM/Gradle/CocoaPods cache).
+> 4. Build the host project's relevant scheme / target.
+> 5. Evaluate: new errors from our changes → fix before proceeding; pre-existing errors unrelated → document and proceed; zero new errors → continue to commit/PR.
+>
+> **Why this exists:** codegen mismatches only surface when the full dependency chain is built together. Building repos in isolation gives false confidence. Skipping this step has caused post-merge build failures requiring fix PRs + wasted review cycles.
+
+---
+
+## Schema
+
+`prefs.schema.json` adds `global.multiRepoIntegrationHosts` — see `pipeline/schemas/prefs.schema.json` for the authoritative definition. Required fields: `repoSet` (array ≥2), one of `(hostPath + platform)` OR `(noHost: true)`. Optional: `hostScheme`, `submodulePaths`, `resolveCommand`, `buildCommand`, `lastUsed`, `count`, `lastResult`.
+
+## Smoke coverage
+
+`smoke-multi-repo-integration.sh` verifies:
+- Match logic: sorted `repoSet` equality
+- Negative-entry handling (`noHost: true`)
+- Autopilot refuses to prompt, skips gracefully
+- Schema validator accepts valid entries, rejects malformed (empty repoSet, missing hostPath without noHost)
+- Memory write on first learn