@mmerterden/multi-agent-pipeline 8.6.0

package/docs/architecture.md

@@ -0,0 +1,181 @@
+# Architecture
+
+## 9-Phase Pipeline Flow
+
+```mermaid
+graph TD
+    INPUT["🎯 Input<br/>(Issue # / Jira URL / free text)"]
+    P0["Phase 0: Init<br/>Project detect, worktree, branch, identity"]
+    P1["Phase 1: Analysis<br/>Codebase scan (parallel Explore agents)"]
+    P2["Phase 2: Planning<br/>Task breakdown, architecture review"]
+    P3["Phase 3: Dev<br/>TDD: RED → GREEN → REFACTOR"]
+    P4["Phase 4: Review<br/>Parallel + Opus triage<br/>(Claude: 2-model · Copilot: 3-model)"]
+    P5["Phase 5: Test<br/>Optional manual testing"]
+    P6["Phase 6: Commit<br/>Git commit, PR creation"]
+    P7["Phase 7: Report<br/>Jira · Wiki+Figma · Confluence · Log · Knowledge"]
+
+    INPUT --> P0
+    P0 --> P1
+    P1 --> P2
+    P2 --> P3
+    P3 --> P4
+    P4 -->|approved| P5
+    P4 -->|fix needed| P3
+    P5 --> P6
+    P6 --> P7
+
+    style INPUT fill:#f9f,stroke:#333
+    style P3 fill:#ffd,stroke:#333
+    style P4 fill:#dff,stroke:#333
+    style P7 fill:#a855f7,stroke:#333,color:#fff
+```
+
+## Operating Modes
+
+```mermaid
+graph LR
+    subgraph Normal ["Normal (Full 8-phase)"]
+        N0[Init] --> N1[Analysis] --> N2[Planning] --> N3[Dev] --> N4[Review] --> N5[Test] --> N6[Commit] --> N7[Report]
+    end
+
+    subgraph Dev ["Dev Mode (--dev, Opus)"]
+        D0[Init] --> D3[Dev<br/>Opus] --> D6[Commit] --> D7[Report]
+    end
+
+    subgraph Autopilot ["Autopilot (skip confirmations)"]
+        A0[Init] --> A1[Analysis] --> A2[Planning] --> A3[Dev] --> A4[Review] --> A6[Commit] --> A7[Report]
+    end
+```
+
+## Review Architecture (Phase 4)
+
+```mermaid
+graph TD
+    DIFF["Code Diff"]
+
+    DIFF --> OPUS["Opus<br/>Security + Architecture"]
+    DIFF --> GPT["GPT-5.4<br/>Quality + Edge Cases"]
+    DIFF --> SON["Sonnet<br/>Correctness + Style"]
+
+    OPUS --> TRIAGE["Opus Triage"]
+    GPT --> TRIAGE
+    SON --> TRIAGE
+
+    TRIAGE -->|PASS| P5["Phase 5: Test"]
+    TRIAGE -->|FIX_REQUIRED| P3["Phase 3: Dev (retry ≤3x)"]
+
+    style TRIAGE fill:#ffd,stroke:#333
+    style P3 fill:#fdd,stroke:#333
+    style P5 fill:#dfd,stroke:#333
+```
+
+## Figma SubPhase Integration (Phase 3)
+
+When `figmaConfigPath` is set, Phase 3 dispatches the Figma-to-SwiftUI pipeline:
+
+```mermaid
+graph TD
+    P3["Phase 3: Dev"]
+
+    P3 -->|figmaConfigPath set| FIGMA
+    P3 -->|default| TDD["Standard TDD<br/>RED → GREEN → REFACTOR"]
+
+    subgraph FIGMA ["Figma Pipeline (17 SubPhases)"]
+        direction TB
+        S0["3.0 Init"] --> S1["3.1 Gather"]
+        S1 --> S2A["3.2A TestingIDs"]
+        S1 --> S2B["3.2B Localization"]
+        S1 --> S2C["3.2C Accessibility"]
+        S1 --> S2D["3.2D Analytics"]
+        S2A --> S3["3.3 Token Mapping"]
+        S2B --> S3
+        S2C --> S3
+        S2D --> S3
+        S3 --> S4A["3.4A Config"]
+        S4A --> S4B["3.4B View"]
+        S4B --> S4C["3.4C Docs"]
+        S4C --> S4D["3.4D Preview"]
+        S4D --> S4E["3.4E Modifiers"]
+        S4E --> S4F["3.4F Wiki"]
+        S4F --> S5A["3.5A ViewInspector"]
+        S5A --> S5B["3.5B Snapshot"]
+        S5B --> S5C["3.5C Unit"]
+        S5C --> S6["3.6 CodeConnect"]
+    end
+
+    style P3 fill:#ffd,stroke:#333
+    style TDD fill:#dfd,stroke:#333
+```
+
+## Component Architecture
+
+```mermaid
+graph TB
+    subgraph "CLI Layer"
+        IDX[index.js<br/>Command router]
+        INS[install.js<br/>Zero-dep installer]
+    end
+
+    subgraph "Pipeline Specs"
+        CMD[commands/<br/>25 sub-commands]
+        AGT[agents/<br/>6 agent definitions]
+        RUL[rules/<br/>12 domain rules]
+        PHS[refs/phases/<br/>8 phase specs]
+        FIG[skills/figma-{ios,android,common}/<br/>37 figma skills]
+        CMP[skills/shared/core/<br/>28 orchestration skills<br/>incl. compliance]
+        EXT[skills/shared/external/<br/>127 curated skills]
+    end
+
+    subgraph "Quality Gates"
+        SCH[schemas/<br/>7 JSON schemas + token-budget]
+        EVL[eval/triage/<br/>10 regression fixtures]
+        SMK[scripts/smoke-*<br/>45 smoke suites]
+    end
+
+    IDX --> INS
+    INS -->|copies to ~/.claude/| CMD
+    INS -->|copies to ~/.claude/| AGT
+    INS -->|copies to ~/.claude/| RUL
+    CMD --> PHS
+    CMD --> FIG
+    SCH --> EVL
+    SCH --> SMK
+```
+
+## Data Flow
+
+```
+User Input → Phase 0 (Init)
+                ↓
+            agent-state.json (created)
+                ↓
+            Phase 1-2 (Analysis + Planning)
+                ↓
+            Phase 3 (Dev) ←──── retry loop (max 3x)
+                ↓                    ↑
+            Phase 4 (Review) ────────┘ (if fix needed)
+                ↓
+            Phase 5-6 (Test + Commit)
+                ↓
+            Phase 7 REPORT (Jira → Wiki+Figma → Confluence → Log → Knowledge)
+                ↓
+            agent-log.md + agent-state.json (final)
+```
+
+## Ecosystem Sync Targets
+
+```mermaid
+graph TD
+    CC["Claude Code<br/>(source of truth)"]
+    COP["Copilot CLI<br/>(instructions + 145 unified skills)"]
+    REPO["Pipeline Repo<br/>(npm package)"]
+    WEB["Website<br/>(optional)"]
+    RC["Remote Control<br/>(optional)"]
+
+    CC -->|instructions + unified skills| COP
+    CC -->|genericized pipeline/| REPO
+    CC -->|version + features| WEB
+    CC -->|pipeline refs| RC
+    REPO -->|npm publish| NPM["GitHub Packages"]
+    WEB -->|auto-deploy| VERCEL["Vercel"]
+```

package/docs/best-practices.md

@@ -0,0 +1,93 @@
+# Best Practices
+
+> Competitor-informed patterns adopted from research across 4 open-source multi-agent pipelines (ralph-loop 116★, claude-pipeline 104★, atelier 13★, ai-first-framework).
+
+## 1. Symlink Distribution (from ralph-loop)
+
+**Problem**: Copying pipeline files on install duplicates ~10K tokens of content per session.
+**Solution**: `--link` flag creates symlinks instead of copies. Updates propagate instantly.
+
+```bash
+npx @mmerterden/multi-agent-pipeline install --link
+```
+
+**Trade-off**: Requires the source package to remain installed. Best for development; use copy mode for production installs.
+
+## 2. FIX_FIRST Pattern (from claude-pipeline)
+
+**Rule**: When a bug or test failure is discovered during development, fix it immediately before continuing with the current task. Never defer fixes to "later".
+
+Applied in Phase 3 (Development):
+
+- If a test fails → fix the failing test before writing new code
+- If lint errors appear → fix them before the next TDD cycle
+- If a build breaks → stop and fix before proceeding
+
+## 3. Wave-Based Parallel Execution (from atelier)
+
+**Problem**: Running all explore agents in parallel can cause coverage overlap and wasted tokens.
+**Solution**: Group parallel work into waves with clear boundaries.
+
+Applied in Phase 1 (Analysis):
+
+- **Wave 1**: 3 explore agents scan independent areas (architecture, security, CI/docs)
+- **Wave 2**: Merge results, identify gaps, launch targeted follow-ups only if needed
+- Never launch more than 5 parallel agents per wave
+
+## 4. Roz-First TDD (from atelier)
+
+**Rule**: Tests are written STRICTLY before implementation. No exceptions.
+
+Applied in Phase 3:
+
+1. RED — Write the failing test
+2. Verify it fails for the RIGHT reason
+3. GREEN — Write minimal code to pass
+4. Verify ALL tests pass
+5. REFACTOR — Clean up without changing behavior
+
+## 5. Deterministic Quality Gates (from claude-pipeline)
+
+**Rule**: Every phase transition must pass an explicit gate. No implicit transitions.
+
+| Gate        | Condition                                  | Blocks   |
+| ----------- | ------------------------------------------ | -------- |
+| Phase 1 → 2 | Analysis complete, no unanswered questions | Planning |
+| Phase 3 → 4 | Build passes, lint clean, tests green      | Review   |
+| Phase 4 → 6 | All blocking findings resolved             | Commit   |
+| Phase 6 → 7 | Push successful, PR created                | Report   |
+
+## 6. 3-Iteration Hard Kill (original)
+
+**Rule**: Any retry loop (build fix, test fix, API call) is killed after 3 attempts. The agent must escalate to the user instead of spinning.
+
+```
+Attempt 1 → fix → retry
+Attempt 2 → different fix → retry
+Attempt 3 → STOP → ask user for guidance
+```
+
+## 7. Layer-Based Memory (from ralph-loop)
+
+**Problem**: Loading full project context at session start wastes tokens.
+**Solution**: Lazy-load reference files only when the current phase needs them.
+
+Applied via modular loading:
+
+- **L0 (always)**: Main command routing (~300 tokens)
+- **L1 (on demand)**: Phase definitions, rules (~2K tokens each)
+- **L2 (rare)**: Platform guides, knowledge base (~5K tokens each)
+
+This reduces wake-up tokens from ~19K to ~800.
+
+## 8. Single Source of Truth (from ai-first)
+
+**Rule**: Every configuration, rule, or standard exists in exactly ONE authoritative location. All other instances are derived via sync.
+
+Applied via `multi-agent-sync`:
+
+- Claude Code commands → source of truth
+- Copilot CLI skills → derived (synced)
+- Pipeline repo → derived (genericized, personal data scrubbed)
+- Website → derived (version + feature counts)
+- Remote Control → derived (pipeline references)

package/docs/features.md

@@ -0,0 +1,274 @@
+# Features — Full Reference
+
+Comprehensive list of every feature the pipeline ships. The top-level `README.md` only highlights the 5–7 most important; this file is the complete catalog.
+
+## Core Pipeline
+
+### 9-Phase Orchestration
+
+```
+Phase 0: Init      Project selection, branch setup, identity, worktree
+Phase 1: Analysis  Stack detection, codebase exploration (parallel Explore agents)
+Phase 2: Planning  Task decomposition, architecture review, user approval
+Phase 3: Dev       TDD cycle: test → code → build (Sonnet)
+Phase 4: Review    Deterministic gates + parallel AI review + Opus triage
+                   (Claude Code: Opus + Sonnet · Copilot CLI: GPT-5.4 + Opus + Sonnet)
+Phase 5: Test      Optional manual testing + on-demand device audits
+Phase 6: Commit    Git commit, push, PR with default reviewers + draft/ready prompt
+Phase 7: Report   External: Jira comment · Wiki + Figma screenshots · Confluence
+                   Internal: agent-log.md + Quality & Metrics + knowledge + memory
+```
+
+Each phase reads its own spec file under `pipeline/commands/multi-agent/refs/phases/phase-N-*.md` — lazy-loaded so the orchestrator only pays the token cost for the phase it's currently in.
+
+### Modifier Flags (orthogonal, combinable)
+
+| Flag        | Effect                                                                              |
+| ----------- | ----------------------------------------------------------------------------------- |
+| `autopilot` | Skip all confirmation prompts; still fails safe on review blockers + build retries. |
+| `--dev`     | Strip to Init → Dev(Opus self-contained) → Commit → Report. No Phase 1/2/4/5.       |
+| `--local`   | No worktree — works directly in `$PROJECT_ROOT` on a local branch.                  |
+
+Compose freely: `--dev --local autopilot` = shortest, least-friction path.
+
+### Stack Auto-Detection
+
+| Platform       | Detection                                    | Guide Loaded             |
+| -------------- | -------------------------------------------- | ------------------------ |
+| iOS/Swift      | `.xcodeproj`, `Package.swift`                | `refs/swiftui-guide.md`  |
+| Android/Kotlin | `build.gradle[.kts]`                         | `refs/android-guide.md`  |
+| Backend        | `requirements.txt`, `package.json`, `go.mod` | `refs/backend-guide.md`  |
+| Frontend       | `package.json` + framework detection         | `refs/frontend-guide.md` |
+| Docker         | `Dockerfile`, `docker-compose.yml`           | `refs/docker-guide.md`   |
+
+Build commands, test runners, lint tools, and review focus areas all adapt to the detected stack.
+
+### Stack Swap
+
+Switch skill sets mid-session without restarting the CLI:
+
+```bash
+/multi-agent stack ios         # SwiftUI, Xcode, ViewInspector
+/multi-agent stack android     # Compose, Gradle, Hilt
+/multi-agent stack backend     # FastAPI, Node.js, Docker
+/multi-agent stack frontend    # React, Next.js, Vue
+/multi-agent stack mobile      # iOS + Android combined
+/multi-agent stack all         # Load everything
+```
+
+### Task Type Detection (v2.0.0)
+
+Phase 0 Step 9 classifies every task before Phase 1 starts. Deterministic priority order: Figma URL → instruction file path → git diff heuristic → Jira issue type → branch name → description keywords → user prompt (autopilot defaults to `feature`).
+
+Result persisted to `agent-state.taskType`:
+
+| Type        | Downstream effects                                                            |
+| ----------- | ----------------------------------------------------------------------------- |
+| `component` | Phase 3 loads figma-to-swiftui skill with SubPhase dispatch                   |
+| `bugfix`    | Phase 4 emphasizes test coverage + regression; Phase 6 uses `fix(...)` prefix |
+| `feature`   | Standard TDD flow; Phase 6 uses `feat(...)` prefix                            |
+| `refactor`  | Phase 4 emphasizes behavior preservation; Phase 6 uses `refactor(...)` prefix |
+| `chore`     | Lightweight flow; Phase 6 uses `chore(...)` prefix                            |
+
+### SubPhase Convention (v2.0.0)
+
+When a specialized skill takes over a main pipeline phase, progress is reported as SubPhases (e.g. `SubPhase 3.0: Init`, `SubPhase 3.1: Gather`). The top-level pipeline stays fixed at 8 phases (0-7 — Phase 6.5 was merged into Phase 7 REPORT in v5.1.0) — specialized work slots into its parent phase without inflating the count.
+
+## PR & Review Flow
+
+### Default Reviewers (v1.6.1, hardened in v2.0.0)
+
+- **Bitbucket**: Fetches via `/rest/default-reviewers/1.0/`. Every PUT must re-send `reviewers`, `fromRef`, `toRef`, `draft` (regression guarded by smoke test).
+- **GitHub**: Honors `CODEOWNERS` + falls back to `prefs.projects[].githubDefaultReviewers`.
+- PR author always filtered out (Bitbucket: 409, GitHub: GraphQL error).
+
+### Draft vs Ready Prompt (v1.7.0)
+
+Phase 6 asks `DRAFT or READY?` before creating the PR and persists the choice in `prefs.projects[].defaultPrMode`.
+
+- Bitbucket: `draft: true` flag (DC 8.x+) with `[DRAFT]` title fallback for older servers.
+- GitHub: `gh pr create --draft` + `gh pr ready` for promotion.
+
+### `channels` Command (v5.7.0 — replaces `enrich`)
+
+Multi-channel reporter — Phase 7 delegates to it, and it's also invocable post-hoc for fixes closed outside the pipeline:
+
+```bash
+/multi-agent:channels                              # current branch, current PR
+/multi-agent:channels https://jira.company/browse/PROJ-12345
+/multi-agent:channels #42 --channels pr            # PR only
+/multi-agent:channels --message "manual fix description"
+/multi-agent:channels DIJITAL-1234 --channels jira,confluence --content test
+```
+
+Multi-select **channels** (Jira / Confluence / Wiki / PR description) × multi-select **content** (normal analysis / test scenarios / auto-diff summary / manual note). Each body runs through the humanizer skill per-channel. Bitbucket PR updates use the reviewer-preserving PUT pattern (title + description + reviewers + fromRef + toRef + version mandatory). Replaces the pre-v5.7 `enrich` command — all its capabilities (diff auto-summarize, manual mode, reviewer-preserving) are preserved; Confluence + Wiki are new.
+
+### Body Preservation Contract (v1.6.1, verified by smoke test in v2.0.0)
+
+Every external-system body (PR description, Jira comment, GitHub issue) uses `jq -n --rawfile body body.md '{description: $body}'` → `curl --data-binary @payload.json`. No literal `\n` strings, no HTML entities (`&`, `<`, `"`). UTF-8 preserved end-to-end. `scripts/smoke-add-detail.sh` runs 14 contract assertions.
+
+### Issue Safety
+
+Never auto-closes issues — uses `Ref: #N` / `Related: #N` / `See: PROJ-12345`, never `Closes` / `Fixes` / `Resolves`. Closure requires team review (configurable, typically 4 approvals).
+
+## Review Quality
+
+### Deterministic Gates (Phase 4 Step 1)
+
+Cheap, objective checks run BEFORE any AI token is spent:
+
+1. Build (acquires xcodebuild lock, isolated DerivedData per worktree)
+2. Lint (SwiftLint / detekt / ruff / eslint — stack-dependent)
+3. Tests pass
+4. Secret scan
+
+If any gate fails, fix first. Don't waste AI tokens reviewing broken code.
+
+### 3-Model Parallel Review + Opus Triage (Phase 4 Steps 2–3)
+
+| Reviewer   | Model               | Focus                             |
+| ---------- | ------------------- | --------------------------------- |
+| Reviewer 1 | `claude-opus-4.6`   | Deep security + architecture      |
+| Reviewer 2 | `gpt-5.4`           | Edge cases, different perspective |
+| Reviewer 3 | `claude-sonnet-4.6` | Quality + correctness + naming    |
+
+All three dispatched in parallel. Each returns structured JSON for deterministic aggregation. Cross-model diversity catches blind spots that any single model family would miss.
+
+**Opus Triage** (Phase 4 Step 3): Evaluates merged raw findings against task scope. Classifies each as `accepted` (fix now), `deferred` (out of scope, log for later), or `rejected` (false positive / noise). Only triage-accepted blocking items loop back to Phase 3.
+
+### Runtime Triage Validator (v2.3.0)
+
+After Opus triage returns, output is validated by `validate-triage.mjs`:
+
+| Exit  | Meaning                                                      |
+| ----- | ------------------------------------------------------------ |
+| **0** | Valid and clean — act on triage output                       |
+| **1** | Invalid structure — retry once, then fallback                |
+| **2** | Over-rejection guard tripped — pause for human               |
+| **3** | Contradiction auto-corrected — proceed with corrected output |
+
+### Bidirectional Approved↔Blocking Auto-Correction (v2.6.1)
+
+If triage returns `approved: false` but has no blocking items, the validator forces `approved: true`. Conversely, if `approved: true` but blocking items exist, it forces `approved: false`. Hardened with `if`/`then` constraint in schema v3.0.0.
+
+### Accessibility Code Review (Phase 4 Step 1.5)
+
+If changes include UI files, reviewers check for:
+
+- Missing `.accessibilityLabel` / `contentDescription` on interactive elements (→ blocking)
+- Small tap targets (<44×44pt iOS / <48×48dp Android) (→ important)
+- Missing identifiers + Dynamic Type support (→ suggestion)
+
+Pure code analysis — no simulator needed. Device-level audits run in Phase 5 when requested.
+
+### Status Enforcement (v1.5.0)
+
+Phase 3 marks issue-tracker status update as MANDATORY with a post-mutation verify step that re-reads the field and retries once on silent `VALIDATION` failures (e.g. stale Projects V2 option IDs after a board rebuild).
+
+## Safety & Hygiene
+
+- **Pre-Commit Secret Detection** (12 patterns): `PreToolUse` hook scans staged files for API keys/tokens, AWS access keys, private keys, `.env` files, service account JSON. Commit **blocked** if found.
+- **Build Queue**: All `xcodebuild` calls acquire a lock. Each worktree uses own `-derivedDataPath`. Stale locks auto-clean after 15 min. Non-Xcode builds don't need the lock.
+- **Context Management**: `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=65` — compaction at 65% usage (prevents degradation in 8-phase sessions).
+- **3-Iteration Hard Kill**: Any retry loop stops after 3 attempts, then pauses for user. No infinite loops.
+
+## Testing & Quality
+
+### Schema-Validated State (v2.0.0)
+
+All critical state files are schema-validated at read and write time:
+
+- `agent-state.schema.json` — validates `$HOME/.claude/logs/multi-agent/.../agent-state.json`
+- `prefs.schema.json` — validates `$HOME/.claude/multi-agent-preferences.json` (extended v2.5.0)
+- `triage-output.schema.json` — validates triage output (v2.3.0, hardened v2.6.1, `if`/`then` constraint v3.0.0)
+
+### Smoke Test Suites (v2.0.0–v2.5.0)
+
+10 suites: add-detail (14 body-preservation assertions), review-triage (validator exit codes), prefs (schema round-trip), state (agent-state lifecycle), metrics (telemetry emission), sync (instruction parity), secret-scan (hook patterns), phase-banner (terminal UI), token-budget (per-phase limits), phase-tracker (progress tracking).
+
+### Adversarial Eval Fixtures (v2.5.0–v2.6.0)
+
+10 fixtures that test triage resilience against adversarial reviewer output: over-rejection, hallucinated findings, contradictions, invalid JSON, schema violations, duplicate findings, scope creep, empty results, timeout simulation, and combined edge cases.
+
+### Sync Parity Check (v2.3.0)
+
+Detects drift between Claude Code instructions (`~/.claude/commands/multi-agent.md`), Copilot CLI instructions (`~/.copilot/copilot-instructions.md`), and the repo's pipeline spec files. Reports discrepancies during Phase 0 Init.
+
+### Token Budget Enforcement (v3.0.0)
+
+Per-phase token budgets prevent runaway sessions. If a phase exceeds its budget, the pipeline pauses and offers: continue (extend budget), skip phase, or abort. Budgets are configurable in `prefs.global.tokenBudgets`.
+
+## Telemetry & Observability
+
+- **Pipeline Metrics** (v2.3.0): Structured metrics to `metrics.jsonl` via `log-metric.sh`. Aggregated by `aggregate-metrics.mjs`.
+- **Cost Telemetry** (v2.5.0): Per-phase token cost tracking (`tokens_in`, `tokens_out`, `model`, `duration_ms`). Omitted fields handled gracefully.
+- **Phase Tracker** (v2.4.0): Cross-CLI visual progress (current phase, elapsed time, iteration count).
+- **Phase Banner** (v2.4.0): Terminal UI for phase transitions with Unicode box-drawing characters.
+- **Per-task Cost Breakdown in agent-log.md** (v8.3.0): Phase 7 appends a 4-column block (Phase · Model · Tokens in/out · Est. USD) to every run's `agent-log.md`. Sourced from `phase-tracker.sh tokens` accumulators × `cost-table.json` prices. Independent of the channels-side `reportContent.costSummary` toggle. The `LOG_METRIC_FORWARD_TO_TRACKER=1` env flag mirrors `tokens_in`/`tokens_out`/`model` from `log-metric.sh` into the tracker so JSONL metrics and the cost block stay in sync from one call site.
+
+### Diff Risk Scoring (v8.3.0)
+
+`pipeline/scripts/diff-risk-score.mjs` runs at Phase 4 Step 1.75 — before reviewer dispatch. Heuristic, deterministic, sub-second, no LLM. Top-N risk-ranked files inject into each reviewer's prompt as a `${PRIORITY_FILES}` block; reviewers read those files first but still review the entire diff.
+
+Signals + weights: `security_path` ×3, `migration` ×4, `public_api` ×2, `no_test_change` ×2.5, `complexity_delta` ×1.5, `ui_critical` ×1.5, `loc_changed` ×1. Toggle via `prefs.global.diffRiskAdvisory` (default ON).
+
+### Test Gap Detection (v8.3.0)
+
+`pipeline/scripts/test-gap-scan.mjs` runs at Phase 5 Step 0. Walks the diff for newly added public symbols and reports those with no paired test. Stack-specific rules ship for iOS, Android, Python, Node.js. iOS Views and Android `@Composable` symbols default to `important`; other public API additions to `suggestion`. Optional gating via `prefs.testGap.blockingThreshold` — when set, the report becomes a Phase 4 rework finding once `important + blocking` count exceeds the threshold.
+
+### Triage Memory (v8.3.0)
+
+Per-repo append-only JSONL corpus at `~/.claude/memory/multi-agent/<repo-slug>/triage-corpus.jsonl`. Phase 7 ingests every triage output (idempotent), Phase 1 enriches the analysis with similar past tasks, Phase 4 triage attaches prior-art hits to each raw finding with an explicit bias hedge. Token-overlap recall, zero deps, Node-18-compatible. `/multi-agent:search "<text>" --semantic` routes the query to the corpus instead of agent-log grep. Toggle via `prefs.global.priorArtEnrichment.enabled` (default ON).
+
+## Learning
+
+### Knowledge Base (per project)
+
+Incremental learning. Phase 7 captures architecture, patterns, gotchas, and decisions into `$HOME/.claude/knowledge/{project}/`. Phase 1 reads it on the next run. Token cost decreases over time as the base grows.
+
+### Memory Capture (cross-session)
+
+Pipeline learns behavioral signals (feedback corrections, project constraints, external references). Phase 7 saves, Phase 1 injects. Max 3 new memories per run. Merge-over-duplicate. Stale memories verified before use.
+
+**What does NOT go in memory**: architecture, code patterns, build gotchas, design decisions — those belong in the knowledge base.
+
+## Integrations
+
+### Figma → SwiftUI
+
+Full component generation pipeline from a Figma URL. Generates `{Name}Configuration.swift`, `{Name}View.swift`, `{Name}+Modifiers.swift`, `{Name}.figma.swift`, `FIGMA.md` with variant matrix. 14-item pre-commit checklist covers design tokens, accessibility, tests, Code Connect.
+
+### UI Bug Hunter + Audits
+
+Automated visual testing and compliance audits via direct Bash (no MCP server dependency):
+
+| Audit                 | When                | Command                      |
+| --------------------- | ------------------- | ---------------------------- |
+| iOS Accessibility     | Phase 5, on request | `swift ui-tree-dumper.swift` |
+| Android Accessibility | Phase 5, on request | `adb shell uiautomator dump` |
+| iOS Biometric         | Phase 5, auth flow  | `xcrun simctl keychain`      |
+| Android Launch Time   | Phase 5, perf       | `adb shell am start -W`      |
+| iOS Archive           | Phase 6, release    | `codesign`, `plutil`, `nm`   |
+| Android APK           | Phase 6, release    | `aapt2`, `apksigner`         |
+
+Audits are **on-demand** — triggered by user, never automatic.
+
+### Jira + Confluence
+
+- Phase 3: transition issue to `In Progress` (verified post-mutation).
+- Phase 7: post analysis + test scenarios as Jira comment (Turkish by default, configurable).
+- Phase 7 (optional): create Confluence page under chosen parent, cached per project.
+
+### Keychain
+
+Token registry maps logical names (`jira`, `bitbucket`, `github`, `confluence`) to Keychain item names. Tokens never land in a config file, never synced to the repo.
+
+## Schemas & Validation
+
+- `pipeline/schemas/agent-state.schema.json` — validates agent state lifecycle (v2.0.0)
+- `pipeline/schemas/prefs.schema.json` — validates preferences (v2.0.0, extended v2.5.0)
+- `pipeline/schemas/triage-output.schema.json` — validates triage output (v2.3.0, hardened v2.6.1, `if`/`then` constraint v3.0.0)
+
+## File Layout (v1.9.0)
+
+`commands/multi-agent/{add-detail,setup,help}.md` → slash commands. `commands/multi-agent/refs/**` → guides, phase specs, rules (`refs:` prefix signals "not an action"). Modifier flags and ops stay inline in `multi-agent.md`.

package/docs/performance.md

@@ -0,0 +1,116 @@
+# Pipeline Performance
+
+The pipeline logs per-event metrics to `~/.claude/logs/multi-agent/metrics.jsonl`
+as it runs. The `aggregate-metrics.mjs` script turns that file into a summary
+you can read, embed in a report, or feed into a dashboard.
+
+## Quick Start
+
+```bash
+# Plain-text summary (the default — fits in a terminal)
+node pipeline/scripts/aggregate-metrics.mjs
+
+# Markdown table (for PR descriptions, wikis, dashboards)
+node pipeline/scripts/aggregate-metrics.mjs --markdown
+
+# JSON (for machine consumption — Phase 7 report uses this)
+node pipeline/scripts/aggregate-metrics.mjs --json
+
+# Filtered — only recent runs
+node pipeline/scripts/aggregate-metrics.mjs --since=2026-04-01
+
+# Per-task or per-phase drill-down
+node pipeline/scripts/aggregate-metrics.mjs --task-id=PROJ-123
+node pipeline/scripts/aggregate-metrics.mjs --phase=4
+```
+
+## What Gets Measured
+
+Each event in `metrics.jsonl` is a single-line JSON object written by
+`log-metric.sh`. Events cover:
+
+- **Review cycles** — how many iterations of Phase 3 → Phase 4 → Phase 3 a task
+  needed before triage approved.
+- **Triage classification** — accepted / deferred / rejected counts per review.
+- **Triage edge cases** — over-rejection guard trips, contradictions, invalid-
+  JSON retries, timeouts.
+- **Phase 3 retries** — build / test / lint retry distribution per task.
+- **Cost per model** — calls, duration, tokens in/out, broken down by model
+  (Opus, Sonnet, GPT-5.4).
+- **Language preference** — distribution of EN vs TR prompts.
+
+## Typical Output (Markdown)
+
+```markdown
+# Pipeline Metrics Summary
+
+_Source: ~/.claude/logs/multi-agent/metrics.jsonl · Events: 421 (0 parse errors) · Unique tasks: 34_
+
+## Reviews
+
+| Metric | Value |
+|--------|-------|
+| Completed | 28 |
+| Cycles per task (avg) | 1.3 |
+| Cycles per task (p95) | 2 |
+
+## Triage Classification
+
+| Category | Count | Rate |
+|----------|-------|------|
+| Raw findings | 167 | — |
+| Accepted | 41 | 0.25 |
+| Deferred | 19 | — |
+| Rejected | 107 | 0.64 |
+
+## Cost Per Model
+
+| Model | Calls | Duration (ms) | Tokens In | Tokens Out |
+|-------|-------|---------------|-----------|------------|
+| `claude-opus-4.6` | 124 | 612430 | 380221 | 92114 |
+| `claude-sonnet-4.6` | 89 | 412318 | 201445 | 58903 |
+| `gpt-5.4` | 88 | 398214 | 194302 | 55128 |
+```
+
+## Interpreting Review-Cycle Metrics
+
+- **`cycles per task avg` > 2.0** — triage is rejecting too many real findings
+  or Phase 3 isn't converging. Inspect the edge-cases table.
+- **Most-common edge case = `over_rejection_guard_tripped`** — the triage
+  prompt lost scope context. Look at `phase-4-review.md:57-91`.
+- **`p95` much higher than `avg`** — a few tasks are looping 3+ times. Usually
+  means one of: bad acceptance criteria in Phase 2, tests that flake, or
+  environment-dependent build failures.
+
+## Phase-by-Phase Token Budget
+
+Phase docs have hard-capped token limits in
+`pipeline/schemas/token-budget.json`. `smoke-token-budget.sh` enforces them.
+Current totals (v3.5.0):
+
+| Phase | Warn | Max | Typical |
+|-------|------|-----|---------|
+| 0 INIT        | 3500 | 4000 | 3434 |
+| 1 ANALYSIS    | 1200 | 1500 | 1315 |
+| 2 PLANNING    |  800 | 1000 |  798 |
+| 3 DEV         | 1500 | 1800 | 1451 |
+| 4 REVIEW      | 1800 | 2200 | 2110 |
+| 5 TEST        |  600 |  800 |  796 |
+| 6 COMMIT      | 2400 | 2800 | 2537 |
+| 7 REPORT      | 1800 | 2200 | 1851 |
+| **Total** | **13600** | **16300** | **~14.3k** |
+
+Lazy loading keeps these off the model's context until each phase actually
+runs — the full 14 k total is never loaded at once.
+
+## Embedding Metrics in Phase 7 Reports
+
+Phase 7 automatically calls `aggregate-metrics.mjs --json` with the current
+task id and embeds the last 30 days' summary into the report body. See the
+template in `phase-7-report.md`.
+
+## Disabling Metrics
+
+Remove or rename `~/.claude/logs/multi-agent/metrics.jsonl`. The pipeline
+will not error — `log-metric.sh` fails silently if the file isn't writable.
+Nothing is sent off-device.