@mmerterden/multi-agent-pipeline 20.35.0 → 20.37.0

package/pipeline/multi-agent-refs/features/analysis-command-notes.md

@@ -0,0 +1,53 @@
+# Analysis command notes: scope, profiles, template, outputs and tracker detail
+
+Read by `/multi-agent:analysis` before Phase 0. The command file keeps the step skeleton, the side-effect contract, the gates and the hard rules; this file holds the scope, the profile table, the template rules, output naming and source-handling notes. Every question asked follows `$HOME/.claude/multi-agent-refs/picker-contract.md`. The engine contracts themselves live in the `analysis/` refs the command names.
+
+## Scope
+
+This command is **independent** from the orchestrator's Phase 1 analysis (which is a stack/findings detector inside `/multi-agent`). It produces a stakeholder-ready, platform-agnostic feature-spec document - up to 23 sections, trimmed to whatever the evidence supports - before any implementation starts. Each per-platform file is rendered by projecting concept-layer content onto repo-extracted conventions (Pass B).
+
+this command produces a *development* analysis  -  what to build, the architecture plan, files to add, the test plan, and which existing components to reuse. It is NOT a design / screen-anatomy specification. The design itself is already produced elsewhere (figma-to-swiftui builds the components and binds them via Code Connect), so the analysis consumes those existing bindings as the source of truth for "what already exists" (see Phase 1b.1) instead of re-deriving the design. Do not grow this command toward exhaustive per-screen layout / gesture / state documentation; keep it development-focused.
+
+## Profiles
+
+Phase 0 Step 1b asks which analysis standard the document follows (Locked 31), and the answer selects the template. Both profiles read the same evidence: intake, fetching, repo evidence and convention extraction are shared, so the two cannot drift into two products.
+
+| Profile | Template | Shape |
+|---|---|---|
+| `global` (default) | `analysis-template.md` | Development handoff, 23 sections. Business rules with Gherkin acceptance criteria, architecture plan, files to add, test plan. Zero-evidence sections drop (Locked 2). |
+| `corporate` | `analysis-template-corporate.md` | Requirements document. `IG -> UC -> FG` spine with three traceability matrices, current and target state with impact analysis, then Technical Analysis and Development Analysis. The Part A backbone always renders, carrying `N/A` or `EKLENECEK` (Locked 32). |
+
+One run emits one profile. A missing input never blocks either profile: the gap is written as `EKLENECEK` and raised as a Section 20 open question rather than halting the run.
+
+**Stack is optional** (Locked 34). When no platform is selected the run still completes: everything that does not need a target repository renders in full, and only the development layer plus the Pass B projection are skipped, with a Section 20 row recording why. The output is a single file at `~/Desktop/multiAgentAnalysis/<feature-name>/<feature>.md` instead of one per repo: without a repo there is no working tree for the usual `analysis/` path to be relative to, and the current working directory is never written to. The Phase 3.5 picker shows the resolved path and accepts an override.
+
+## Template
+
+v3 template at `$HOME/.claude/multi-agent-refs/analysis-template.md`. The document renders up to 23 main sections + footer, minus any dropped by the omission table. The analysis doc is a development handoff, so low-signal sections are default-drop: **19 Alternatives** (render only for a real 2+-option architectural decision), **22 Glossary** (render only on request or >5 unfamiliar domain terms), and **18 Rollout** (compact checklist only, dropped when the pipeline's own commit/PR/rollout phase covers it). Sections are chosen from evidence; there is no second mode (ADR-0015, `docs/adr/0015-one-pipeline-no-depth-answer.md` in the pipeline repo). Section omission rule (Locked 2): zero-evidence and default-drop sections omit entirely; a rendered section keeps its canonical template number, so the rendered set has gaps.
+
+Numbering is plain Arabic numerals: `## 1. Geliştirme Özeti` / `## 1. Summary`, `## 2. Hedefler ve Karşı Hedefler` / `## 2. Goals and Non-Goals`. No special section characters; the section sign codepoint (U+00A7) is banned by `feedback_no-section-sign`.
+
+The template is platform-agnostic (Locked 22). It speaks in concepts (state holder, view, navigator, use case, repository, DTO, state model, DI register, localization key, accessibility identifier, test method). Pass B (Phase 2b) projects each concept onto the selected platform using `state.analysisSpec.evidence.conventions[<repo>]` extracted at Phase 1c. Every projected cell carries a footnote pointing to its evidence source (Locked 24).
+
+## Phase summaries
+
+- **Phase 0**: sequential `AskUserQuestion` steps filling `state.analysisSpec.*`: analysis name, analysis profile, account, platform multi-select, repos per platform, the six-question source batch (Figma / Swagger / Confluence / Jira / Standards / Firebase) and the two coverage opt-ins. Every step prints its breadcrumb.
+- **Phases 1 to 1c**: fetch every declared source in parallel, collect the 13-bucket repo evidence, build the Code Connect index, and extract the seven convention groups.
+- **Phases 3 to 5**: render one markdown file per platform, run the humanizer pass, gate on the validator and the references coverage gate, ask for the output destination, dispatch to Local / Confluence / Jira, report and stop.
+- **Resume**: `analysis/resume.md` holds the `state.analysisSpec.phase` enumeration and the re-entry rule per paused phase.
+
+## Notes
+
+- The minimum possible output (per per-platform file) is `1. Scope` + `7. Development Plan` (both always-present).
+- If Confluence or Jira POST returns 401 / 403 during Phase 4, surface the error and offer Local fallback (the local drafts in `/tmp/` are still on disk; copying them into the repo working tree is always available).
+- The `analysis/` directory is not in `.gitignore`; the user can `git add analysis/` manually. No auto-commit.
+- **Per-platform file naming**: `analysis/<feature>-<platform>.md`. The `<platform>` slug is lowercase, one of `ios | android | web | backend` for a repo-backed run, or `mobile | web` for the channels a repo-less run derives from its evidence (Locked 34). `web` is the pre-`web` spelling and is still read back for older state and documents. The `<feature>` slug preserves the user's feature name with whitespace replaced by `-` (e.g. `User Profile` -> `UserProfile` or `Item-Status` depending on input shape; the renderer trims and de-duplicates dashes).
+- **Standards binding (the Standards question)**: When `evidence.standards[]` is non-empty, every decision in Section 13 (Architecture Plan, corporate Section 17) must cite the binding source in its 13.7 Standards-binding table. The renderer enforces this by failing render if any architectural decision has no `cite:` reference; the user is prompted to either tighten the source or add a Risk row acknowledging the missing citation.
+- **Firebase ingestion (the Firebase question)**: Console URLs are never fetched (auth-gated). Only `:names` and `:schema` inputs feed `evidence.firebase[]`. Section 11 Analytics (corporate Section 13) emits per-platform snippets but the events table itself is shared across all per-platform files (the rules / event vocabulary is one product invariant).
+- **Wiki access fallback chain**: Phase 1 `wiki` fetcher tries (a) `git clone .wiki.git`, (b) `gh api repos/.../contents/<file>.md`, (c) raw `WebFetch` of the page URL. Only after all three fail does the entry land in `fetchErrors[]`.
+- **Local-file safety**: `local-file` reads are scoped to `~/`, `/Users/`, and the repo's working tree. Paths outside these prefixes are rejected with `WARN: refusing to read <path>; outside allowed roots` to avoid accidental ingestion of unrelated files.
+- **Standards vs Confluence vs Document split**: the Confluence question collects feature-specific spec pages and the Document question the same spec delivered as a `.docx` / `.pdf` / `.md` / `.txt` file  -  both describe what the feature IS and both land in `evidence.documents[]`. The Standards question collects cross-cutting documentation that constrains the development plan (architecture, coding conventions, navigation pattern). A source pasted in more than one of the three is de-duplicated (by URL, or by `realpath` for a local file) and the Standards entry wins, because it retains the binding flag.
+- **Workspace coding documentation default**: when the Standards question's option 2 (Auto-detect) is selected, the probe also reads `prefs.projects[<project>].confluenceStandardsParent` (if set) and looks for child pages whose title starts with `Coding`, `Standards`, `Architecture`, or `Navigation`. If that fetch fails with auth, log a hint that the user should host an offline mirror at `prefs.projects[<project>].standardsFile` (canonical local fallback).
+- **Mixed paste handling**: the Standards and Firebase Other inputs accept comma-separated mixed entries. Whitespace is trimmed; entries are de-duplicated by canonicalised string (lowercase scheme + host + path for URLs; `realpath` for local files; lowercase exact match for event names).
+- **Repo-evidence reuse policy**: Phase 1b's catalogue is consulted by Pass B Section 7 rendering. The `direct-match` tag is the strongest signal; a `same-domain` row becomes an advisory note ("consider adapting existing X in the same feature directory"); `cross-cutting` items become a sentence in the section preamble ("reuse the cross-feature X from Common/"). See Locked decision 11.
+

package/pipeline/multi-agent-refs/garbage-collect/phases.md

@@ -0,0 +1,60 @@
+# garbage-collect: what each phase covers
+
+Read by `/multi-agent:garbage-collect` when a phase's output needs explaining,
+or before answering what a sweep would or would not touch.
+
+## /tmp scratch (phase 1)
+
+Each run writes ephemeral scratch under `/tmp`: picker state
+(`multi-agent-picker-*`), PR/review diffs (`multi-agent-review-*`), issue
+progress bodies (`issue-progress-*`), channel payloads (`channels-*`),
+external-context bundles (`context-links-*` / `context-by-type-*`), and analysis
+drafts (`analysis-*`). Most are never cleaned up, so a long-lived machine
+accumulates them. `gc-tmp.sh` sweeps the known prefixes only.
+
+## Worktree residue (phase 2)
+
+`gc-worktrees.sh` covers: stale worktree admin entries (`git worktree prune`,
+applied immediately - it only drops bookkeeping for dirs that are already gone),
+orphan `.worktrees/*` dirs no longer registered as worktrees, gitlink residue in
+the index (`.worktrees/{id}` recorded as a "Subproject commit" entry by a
+pre-guard `git add -A`), and a missing `.worktrees/` line in
+`.git/info/exclude`.
+
+## Offloaded payloads (phase 3)
+
+`offload-ref.sh` parks build logs, diffs and test output under
+`.multi-agent/refs/<node_id>.md`. In worktree modes that directory dies with the
+worktree; when the run chose a local workspace it lands in the real checkout,
+and because it is gitignored it never shows up in `git status`. Only files
+matching the node-id shape are touched - anything else in that directory is left
+alone, and files inside the grace window are spared so a sweep cannot pull a ref
+out from under a running phase.
+
+## Abandoned runs (phase 4, `--abandoned`)
+
+Nothing else collects these. `gc-worktrees.sh` skips registered worktrees on
+purpose, because a registered worktree belongs to a live run - and a run that
+stopped never stops being "live".
+
+The output has four kinds of line and they are not interchangeable:
+
+| Line | Meaning |
+|---|---|
+| `would remove` / `would remove worktree` | reapable: stopped past its age limit, or finished with its worktree left behind |
+| `would stash` | uncommitted work found - it goes into a stash entry labelled `autopilot/abandoned/<task-id>` (`git stash list`) and the worktree is **kept** |
+| `would mark abandoned` | the state is stale but there is no worktree left to remove |
+| `unattributed` | a worktree with no run state. **Never removed, whatever the flags.** `.worktrees/` is not exclusively ours, and nothing distinguishes a hand-made worktree from a pipeline one whose log was pruned. Report the list and its size; the user decides |
+
+A path outside `<repo>/.worktrees/` is never removed because a state file can
+record the repo root as its `worktreePath`.
+
+## Scope of each phase
+
+The /tmp phase only touches `/tmp` scratch; the worktree phase only touches the
+current repo's `.worktrees/` residue and index; the payload phase only touches
+node-id files under `.multi-agent/refs/`. Persistent per-task logs live under
+`~/.claude/logs/multi-agent/` and are cleaned by `/multi-agent:prune-logs`. The
+per-repo memory stores under `~/.claude/memory/multi-agent/` are durable
+knowledge, not scratch: they are removed only by `/multi-agent:uninstall
+--all-data`, or one entry at a time with `learnings-ledger.mjs forget`.

package/pipeline/multi-agent-refs/help/en.md

@@ -88,6 +88,7 @@ Status & Resume:
   /multi-agent:serve          Contract server for a client: 127.0.0.1, token, stops when idle
   /multi-agent:office-on      Open the office in your browser: live runs and agents, PRs, keys, memory, system, jobs; its orientation room explains the rest
   /multi-agent:office-status  Is the panel running, its URL (never the token), its last actions
+  /multi-agent:office-pair    Pair a phone: show the QR, wait, compare the code with you, enrol it
   /multi-agent:office-off     Stop the panel's server (it runs until you do)
 
 Post-Hoc & Side-Channel:

package/pipeline/multi-agent-refs/help/tr.md

@@ -87,6 +87,7 @@ Status & Resume:
   /multi-agent:serve          İstemci için sözleşme sunucusu: 127.0.0.1, token, boşta durur
   /multi-agent:office-on      Ofisi tarayıcıda aç: canlı koşular ve ajanlar, PR'lar, anahtarlar, hafıza, sistem, işler; gerisini oryantasyon odası anlatır
   /multi-agent:office-status  Panel çalışıyor mu, adresi (token asla), son işlemleri
+  /multi-agent:office-pair    Telefonu eşle: QR'ı göster, bekle, kodu seninle karşılaştır, kaydet
   /multi-agent:office-off     Panelin sunucusunu durdur (sen durdurana kadar çalışır)
 
 Post-Hoc & Side-Channel:

package/pipeline/multi-agent-refs/ios-coding-standard/plan.md

@@ -0,0 +1,71 @@
+# ios-coding-standard: plan contents
+
+Read by `/multi-agent:ios-coding-standard` before writing the Phase 4 plan. The
+plan contains, in order:
+
+1. **Coverage ledger**  -  total targets · audited · skipped with reasons. Not 100% accounted for
+   means the plan is not deliverable.
+2. **Summary**  -  counts by severity and source, resolved vocabulary, branch to create.
+3. **Sensitive-data inventory** (Phase 2d)  -  first, because it is the highest-risk content.
+4. **Screen × role matrix** `[STRUCT-02]`  -  screens as rows, manifest roles as columns, cells
+   `✓ / missing / misplaced`. The structural map a newcomer reads first.
+5. **Type placement table** `[STRUCT-05]`  -  type · location · consumer count · correct tier ·
+   move required. Paired with the nested-type list `[STRUCT-01]`: owner · nested type · kind ·
+   reference count · verdict.
+6. **Visibility report** `[VIS-01, VIS-02]`  -  over-exposed declarations per file, non-final
+   classes with no subclass.
+7. **Boundary report** `[MOD-*]`  -  import graph (allowed vs forbidden, with coupling depth) ·
+   manifest graph (declared vs legal for the role, plus dead edges) · **removability delta**
+   ("removing X touches N files: ...") · inbound test (tests compile with no sibling present).
+8. **Testability seam report** `[TEST-*]`  -  types reaching for the environment, logic requiring a
+   view to execute, doubles whose signatures have drifted.
+9. **Change-cost probe** `[FLEX-*]`  -  pick two plausible upcoming changes (a new variant of an
+   existing screen; a new field on a shared entity) and state what each costs in files today.
+10. **Findings table**  -  rule ID · `file:line` · current state · proposed fix · severity · source ·
+    onboarding impact.
+11. **Per-file work**  -  grouped per file, blocking → important → suggestion; within a severity,
+    highest onboarding impact first.
+12. **Behaviour-preservation guard**  -  splitting files, adding MARKs, extracting extensions and
+    moving types must not change behaviour. Anything requiring a behaviour change (a missing
+    analytics event, a wrong result type, a timezone fix, a storage migration) goes in a
+    **separate group**, reviewed and tested on its own, never inside a mechanical split commit.
+13. **Tooling delegation & the ratchet**  -  the section that decides whether any of this survives.
+    - Classify each applied rule by its registry `enforcement`. For every `lint` / `format` /
+      `scan` rule, state the concrete mechanism and whether that toolchain exists in the repo
+      (`LintToolchain`). **When it does not exist, saying so is a finding**, ranked above most
+      individual violations it would have caught.
+    - Recommend **baseline-and-ratchet, never big-bang**: grandfather existing violations, surface
+      only new ones, drain the backlog behind a green build. Order the plan the same way  -  stop
+      the bleeding, then clean up.
+    - Custom lint rule identifiers **are** the registry IDs (`sec_01_no_plaintext_persistence`,
+      `mod_01_no_sibling_import`) so a violation points straight at the rule entry.
+    - **Linting is local-only by decision**  -  the skill's `references/lint-local.sh` with `references/swiftlint.draft.yml`, config
+      and baseline kept outside the repository; no committed config, no build phase, no CI job.
+      State this honestly in the plan rather than describing a gate that does not exist: a
+      pre-PR habit catches less than a wall, so the residual risk is real and belongs in the
+      report. Adopting it project-wide remains an open decision  -  record it as one so it stays
+      visible instead of quietly lapsing.
+    - Never imply the audit substitutes for the linter, or the linter for a gate. The audit finds
+      the debt once; the linter keeps a developer honest; only a gate stops it returning.
+14. **Numeric exit criteria**  -  target and today's measured value side by side: lint violations
+    per 1k lines (<1) · public-surface ratio, public declarations ÷ externally consumed symbols
+    (≈1) · forbidden cross-module imports (0) · removability delta · files over threshold and
+    files >120 lines with no sectioning (0) · screens missing a manifest role (0) · escape-hatch
+    count `[CONC-03]` (flat or falling) · exception-marker count (flat or falling) · dead code (0)
+    · screens with logic and no mirrored tests (0) · unclassified sensitive symbols (0).
+15. **Exception ledger**  -  every `// standard:exception(<ID>)` in the module: rule · reason ·
+    expiry · expired yes/no.
+16. **Open Questions**  -  Phase 2b dimensions with no majority, and unclassifiable symbols.
+17. **Suggested commit slicing**  -  one commit per file-group / concern.
+18. **Scope guard**  -  only this module is touched; definition of done is the module's own
+    verification path.
+
+## Onboarding summary
+
+Then write a **separate one-page onboarding summary** beside the plan, aimed at a developer
+joining next week rather than at whoever does the remediation: the ten always/never lines
+specialised to this module, the screen file manifest, the placement ladder, the sensitive-data
+classes in play, and the verification command. Nobody learns a codebase from a 40-finding audit -
+this page is the actual deliverable, and the audit is how you earn the right to write it
+accurately. Derive it from `references/STANDARD.md section 0`, do not re-invent it.
+

package/pipeline/multi-agent-refs/ios-coding-standard/resolve-and-scan.md

@@ -0,0 +1,135 @@
+# ios-coding-standard: resolve and scan detail
+
+<!-- toc -->
+- [Phase 2](#phase-2)
+- [Phase 3](#phase-3)
+- [Verification reality](#verification-reality)
+<!-- /toc -->
+
+Read by `/multi-agent:ios-coding-standard` at the start of Phase 2 and again
+before Phase 3. The rules themselves live in the `ai-ios-toolkit:ios-coding-standard`
+skill (`references/rules.yml`); this file is procedure only.
+
+## Phase 2
+
+Module roles from Phase 1 decide which dependency edges are legal: **feature** ·
+**core/common** · **seam** (cross-module contracts/bridges/navigation) ·
+**composition root** (legitimately knows every module).
+
+### 2a. The registry is the standard  -  in-module prose docs are NOT consulted
+
+The skill's `references/rules.yml` (+ a project `modules/<Module>.yml` overlay) is the single
+source of truth. Module prose docs are being retired so there is one place a rule can live;
+consulting them re-creates the split this command exists to remove. If such a file exists and
+contradicts the registry, that is a finding against the file, not against the code.
+
+The only in-repo inputs are **code and manifests**: sources, tests, `Package.swift`, `Info.plist`,
+the specs the generator reads, and the module registry from Phase 1.
+
+### 2b. Per-module overlay, then inference
+
+1. **`modules/<Module>.yml`** beside the project's own config carries what code cannot state: the vocabulary
+   bindings, the module's role, prohibitions that currently have **zero** instances, deliberate
+   carve-outs, name locks, and the real verification command. Registry-backed, so its findings may
+   be `blocking`.
+   *Why prohibitions need to be written down:* inference reads dominant patterns, and a rule
+   obeyed everywhere has no counter-example to infer from. A ban at 100% compliance is invisible
+   to a scan  -  it survives only if the overlay states it.
+2. **Repo-level rules** (root `CLAUDE.md`, contributing docs) apply to every module.
+3. **The module's own dominant pattern is its de-facto convention.** Count variants per dimension;
+   the minority instances are the finding. Internal consistency beats conformity to a sibling.
+4. No majority (even split, single instance) → not a finding. Record an Open Question.
+
+Findings from step 3 are tagged `inferred` and capped at **suggestion**. Only registry- or
+overlay-backed rules may be `blocking`.
+
+**When the overlay is missing**, generate a draft from code evidence, print it for confirmation,
+and mark every slot it could not derive  -  a frozen UI target, a name lock, a carve-out and an
+operational constraint all look like ordinary code from the outside. Do not guess them; list them
+as Open Questions.
+
+### 2c. Vocabulary
+
+Bind each slot to a real symbol by grepping the module, then the reference module. **An unbound
+slot disables its rules**  -  never invent a name, never import a sibling's.
+
+`HandlerName` · `EventParam` · `CoordinatorType` · `ResultType` / `ErrorType` / `ErrorFactory` ·
+`DIResolver` / `DIConfigurator` · `RequestModelSuffix` / `ResponseModelSuffix` / `TransportSuffix` ·
+`MapperShape` · `SafeEnumProtocol` / `UnknownCase` · `CopySurface` · `AnalyticsSurface` ·
+`A11yIdentifierSource` · `GeneratedServiceRoot` · `SharedComponentsDir` / `SharedEntitiesDir` ·
+`MicroComponentLibrary` · `FrozenUITarget` · `DesignTokenNamespaces` · `CalendarDayHelper` ·
+`LoggerAPI` · `FileHeaderShape` · `ScreenRoot` · `ScreenRoleSuffixes` · `AsyncStyle` ·
+`CompositionRoot` · `SeamLayer` · `ModuleEntrySurface` · `ConcurrencyPosture` · `LintToolchain` ·
+`CredentialStore` (the module's Keychain wrapper, if any).
+
+Print the resolved table before scanning so a wrong binding is caught early.
+
+### 2d. Sensitive-data inventory  -  required before any SEC rule runs
+
+The `SEC-*` rules are written against the **data classes** in `references/rules.yml →
+sensitive_data_classes`, never against one module's field names. Resolve the module's concrete
+instances of each class: grep entities, request/response models, storage calls and analytics
+events for the values the module actually handles, and map each to its class.
+
+Produce the inventory as a table  -  **class · concrete symbols · where it enters · required
+lifetime (transient / survives-restart / survives-reinstall) · where it is actually stored ·
+where it is logged · where it leaves (network, analytics, pasteboard, another module)**.
+
+The **lifetime column is the one that decides SEC-01**, and it is filled by walking
+`references/rules.yml → persistence_decision`, not by looking at what the code currently does. Compare it
+against the storage column and report both mismatches:
+- required transient but persisted anywhere (including the Keychain) → **over-persistence**;
+- required to survive a restart but stored outside the Keychain → **under-protection**.
+
+Then generate the SEC lint patterns *from this inventory*, so the checks match this module's real
+vocabulary. A class with no instance here yields no finding; a symbol you cannot classify, or one
+whose required lifetime nobody can state, is an Open Question, not a silent pass.
+
+This table is a deliverable in its own right, independent of whether any violation is found.
+
+
+## Phase 3
+
+### Coverage gate  -  on disk, not in memory
+
+Before scanning, write `.<module>-audit-coverage.tsv` to the scratch dir: one row per target
+(every screen under `ScreenRoot`, every shared component, every entity, every file in every
+target) with columns `path · status · rules-applied`. Mark rows as you go.
+
+- Each target is **audited** or **explicitly skipped with a reason** (generated, fixture,
+  vendored). No third state.
+- **The run is incomplete while any row is unmarked**  -  and the file, not a claim, is the proof.
+  Chunk the module if it is too large for one pass; the checklist survives a context reset.
+- No sampling. A partial audit reported as complete certifies the unscanned screens as clean.
+
+### Grep hygiene
+
+Registry `mechanism` patterns are line-based and match doc comments. Filter
+`^[[:space:]]*//`  -  BSD grep does not understand `\s`, so a `\s*//` filter silently lets `/// ...`
+through  -  then open each surviving hit and confirm it is real code. Report pre-filter and
+post-verification counts separately; a table padded with comment matches destroys trust.
+
+### Judgement rules need evidence, not assertion
+
+For any rule marked `enforcement: judgement`, a finding must carry the measurement its `check`
+names  -  a reference count, a call-site count, a consumer count, a file list. **No count, no
+finding.** This is what keeps a subjective rule from becoming an opinion.
+
+Every judgement rule has a worked ✗/✓ pair in `EXAMPLES.md`, keyed by ID. Cite it in the finding's
+proposed fix rather than re-describing the shape  -  the developer applying the fix should be
+reading the same picture the audit used.
+
+### Module-specific overrides
+
+The module's own docs win over the registry, including where they contradict a sibling module.
+Never apply one module's dialect to another. List every override honoured, so the reader sees why
+a registry rule was not raised.
+
+## Verification reality
+
+Verification reality is per-module - establish it, do not assume it. Some
+targets cannot be compiled from the CLI (asset symbol generation, UIKit-dependent
+packages, a dependency failing earlier in the graph); there, verification is
+Xcode and a manifest dump validates the manifest only. Never trust a piped
+build's exit code - a pipe reports the tail's status. Record the module's actual
+verification command in the plan.

package/pipeline/multi-agent-refs/jira/picker-detail.md

@@ -0,0 +1,71 @@
+# jira picker: list format and maturity detail
+
+Read by `/multi-agent:jira` when rendering the issue list (step 3/4), when the
+maturity check (step 3.5/4) returns a description or blocker case, and when
+writing the picker state file.
+
+## Issue list format
+
+Priority badge prefix, status suffix:
+
+```
+[3/4] Pick issue (24 found, priority-sorted):
+  > [Blocker] PROJ-12345  -  Login crash on iOS 17           (In Progress)
+    [Critical] PROJ-12340  -  Payment fails for refunds       (In Review)
+    [High]    PROJ-12338  -  Dark mode polish                 (To Do)
+    [Medium]  PROJ-12330  -  Add empty state                  (To Do)
+    [ - ]       PROJ-12300  -  Refactor LoginViewModel          (To Do)
+```
+
+## Maturity shape
+
+`~/.claude/lib/issue-fetcher.sh` returns:
+
+```jsonc
+"maturity": {
+  "score":    0..100,
+  "blockers": ["status_closed", "already_resolved", "description_empty"],
+  "warnings": ["short_description", "no_repro_steps", "no_acceptance_criteria", "description_empty_parent_available"],
+  "summary":  "..."
+}
+```
+
+## Empty description and the parent candidate
+
+Development sub-tasks are often filed with no description of their own, with
+the real requirements on the parent issue. Before scoring, `issue-fetcher.sh`
+fetches the issue's `parent` (single hop, no chasing the parent's parent). If
+the issue's own description is empty and the parent's is not, it does **not**
+auto-substitute - it exposes `descriptor.parentKey` +
+`descriptor.parentDescription` as a candidate and adds
+`description_empty_parent_available` to `warnings` (not `blockers`) instead of
+the plain `description_empty` blocker. If the parent is also empty or
+unreachable, `description_empty` still blocks.
+
+## Picker state file
+
+`/tmp/multi-agent-picker-{taskId}.json`, read by `multi-repo-pipeline.sh bridge`:
+
+```json
+{
+  "taskId":"PROJ-12345-{timestamp}",
+  "shortId":<int>,
+  "branch":"<feature|bugfix>/PROJ-12345",
+  "baseBranch":"develop",
+  "issueRef":{...},
+  "primary":{"name":"...","cloneUrl":"...","provider":"github|bitbucket"},
+  "extras":[{...}],
+  "worktreeRoot":"~/.worktrees/PROJ-12345-{timestamp}",
+  "commitType":"<feat|fix>",
+  "identity":{"name":"...","email":"..."}
+}
+```
+
+## Blocker follow-up detail
+
+An edit is a reason to re-check, never proof the gap closed - the check re-runs
+on the new content, and only a DIFFERENT gap set ever earns a second comment.
+Read the item's existing comments FIRST and derive the prior ask from the newest
+one of ours (`priorFromComments`): a scan is a new run with a fresh state file,
+so state alone would make every scan a first ask. Full contract:
+`features/maturity-followup.md`.

package/pipeline/multi-agent-refs/orchestrator/copilot-pipeline.md

@@ -0,0 +1,88 @@
+# Copilot CLI orchestrator - project detection, routing and phase summaries
+
+Detail behind the Copilot CLI orchestrator skill (`skills/shared/core/multi-agent/SKILL.md`). The skill keeps the routing skeleton, the hard rules and the gates; this file carries the project table, the full routing rows and the per-phase routing summaries. Each phase's specification is `$HOME/.claude/multi-agent-refs/phases/phase-N-<name>.md`; where a summary here and a phase ref disagree, the phase ref wins.
+
+## Project detection
+
+Detect the project from cwd FIRST, then validate the input format:
+
+| cwd contains | Project | Accepted Input | Rejected Input |
+|--------------|---------|----------------|----------------|
+| `/my-ios-app` | my-app | `"PROJ-XXX" "branch"` | GitHub Issue URL |
+| `/my-figma-app` | figma | `"https://github.com/.../issues/N"` | Jira ID + branch |
+| Other | generic | Both formats | - |
+
+If the user gives the wrong format for the project, warn:
+
+- my-ios-app + GitHub URL: "This project expects a Jira ID + branch. Example: multi-agent \"PROJ-12345\" \"feature/PROJ-12345-desc\""
+- my-figma-app + Jira: "This project expects a GitHub Issue URL. Example: multi-agent \"https://github.com/my-org/my-figma-app/issues/316\""
+
+## Input types
+
+Five types, matching the `commands/multi-agent/SKILL.md` dispatcher contract (cross-CLI parity is enforced by `smoke-cross-cli-behavior.sh`):
+
+| # | Pattern | Type | Action |
+|---|---------|------|--------|
+| 1 | `#N` or bare `316` | github-issue-number | Fetch via gh after project selection |
+| 2 | `https://github.com/.../issues/N` | github-issue-url | Extract org/repo/N, fetch via gh |
+| 3 | `https://{JIRA_HOST}/browse/{JIRA_KEY}-XXXXX` | jira-url | Extract ID, fetch via Jira API |
+| 4 | `{JIRA_KEY}-XXXXX` (bare) | jira-id | Fetch via Jira API |
+| 5 | Anything else | free-text | No external fetch |
+
+All types enter the same Phase 0 flow.
+
+## Routing rows
+
+| Input Pattern | Action |
+|---------------|--------|
+| `"PROJ-XXX" "branch"` | my-app only: Jira ID + branch name, auto-assigned incremental ID |
+| `"https://github.com/..."` | figma only: parse the issue, extract Jira from title/body, auto-create the branch |
+| `status` | Show all tasks with ID, phase, status |
+| `log [id]` | Show agent-log.md for the task (latest if no id) |
+| `resume [id]` | Resume a paused/failed task from the last successful phase |
+| `kill [id]` | Stop the task, delete worktree + branch + logs; asks to confirm first |
+| `clear-logs` | Superseded: redirect only |
+| `purge` | Delete ALL worktrees, branches, logs, state, counter: full reset |
+| `review` | Skip phases 0-3, review the current diff only |
+| `autopilot` flag | Add to any pipeline command: skip user confirmations except destructive ops |
+| No args / `help` | Usage guide |
+
+Every task gets an auto-incremented short ID (`#1`, `#2`), stored in `agent-state.json`.
+
+## Autopilot matrix
+
+`multi-agent "PROJ-12345" "feature/PROJ-12345-desc" autopilot` skips interactive confirmations and runs end-to-end.
+
+| Phase | Normal | Autopilot |
+|-------|--------|-----------|
+| Phase 1 (Plan Approval Gate) | Clarification (max 2 rounds) + approval loop; the user replies `onayla` / `iptal` / free-text | Gate skip: log the plan, go straight to Phase 2 |
+| Phase 3 (User test) | "Want to test it?" then wait | Skip, straight to Phase 4 |
+| Phase 4 (Commit) | "Want to commit?" then wait | Automatic commit + push |
+| Phase 4 (PR) | "Want to open a PR?" then wait | Automatically create the PR |
+
+`"autopilot": true` is added to `agent-state.json` and survives a resume.
+
+## Persona models
+
+| Persona | `preferredModel` |
+|---|---|
+| `explorer` | `sonnet` |
+| `code-reviewer` | `fable` (Reviewer 1; Phase 3 sets Reviewer 2 `opus`, Reviewer 3 `sonnet`) |
+| `security-auditor` | `opus` |
+| `ios-architect` / `android-architect` / `backend-architect` | `fable` |
+
+Each persona file carries its own `modelRationale`. Observability: emit a `phase.agent.dispatch` OTel span with `{persona, resolved_model, override_source}` when `MULTI_AGENT_OTEL_SPANS=1` (see `phase-tracker.sh`).
+
+## Phase summaries
+
+**Phase 1: Plan.** Two halves, one approval gate. 1a Analysis (`explorer`, Sonnet): parallel explore agents scan related files, patterns and impact areas, then log `Phase 1: Plan (analysis) - {N} files identified`. 1b Planning (Fable): task breakdown into todos with dependencies, `ios-architect` review for structural changes, an approach per todo, then the Plan Approval Gate (`phases/phase-1-plan.md` Step 5). 5a clarification runs only when the description is ambiguous (vague acceptance, UI task without Figma, API task without an endpoint contract, `ambiguityScore >= 2`, parent-story scope drift), max 2 rounds, then a "best-effort" banner. 5b approval loop: `onayla` / `iptal` / free-text edit; an edit makes Fable revise and re-render, no iteration cap. Persist `clarificationRounds`, `clarificationQuestions`, `clarificationAnswers`, `planIterations`, `planApprovedAt`, `planEditRequests` to `state.phases["1"]`.
+
+**Phase 2: Dev (Sonnet).** Per todo in dependency order: mark `in_progress`, TDD (failing test, verify RED, minimal code, verify GREEN, refactor), build via a task agent, on failure fix and rebuild (max 3, `retryCount` in `agent-state.json`), mark `done`, log `Phase 2: {todo-id} - Test ok, Build ok`.
+
+**Phase 3: Review (parallel + triage).** Step 0 diff risk scoring is advisory: `node $HOME/.claude/scripts/diff-risk-score.mjs --base "$BASE_BRANCH" --top 5`, injected as `${PRIORITY_FILES}`; off when `prefs.global.diffRiskAdvisory = false`. Reviewers by host: Claude Code runs `claude-fable-5-1` (security + architecture), `claude-opus-5-5` (edge cases), `claude-sonnet-5-5` (quality); Copilot CLI runs `gpt-5.4`, `claude-opus-4.7`, `claude-sonnet-4.6` (no Fable). Triage is one top-tier pass (`claude-fable-5-1` on Claude Code, `claude-opus-4.7` on Copilot CLI). Blocking findings go back to Phase 2 (max 3 iterations), important ones are fixed and re-reviewed, suggestions applied when reasonable.
+
+**Phase 4: Commit & PR.** Per-project steps and the GitHub issue body update: `orchestrator/phase-4-5-projects.md`.
+
+**Phase 5: Report.** Finalize `agent-log.md` with: timeline table (phase, agent, model, duration, status, detail), agent activity report, token estimate, per-phase time distribution, review iterations, files changed (`git diff --stat`), review consensus, and test scenarios in Turkish for Jira (precondition, steps, expected result). Then print a compact terminal summary: task id and status, total time, agent calls, files changed, commit and PR, the wiki page when one was pushed, and the path to the full report under `~/.claude/logs/multi-agent/{project}/{task-id}/agent-log.md`. Log `Phase 5: Report complete`. The wiki + Figma screenshot step runs only for a component implementation with a GitHub issue: `orchestrator/phase-4-5-projects.md`.
+
+**Localization scope.** Phase labels are English on every host. Reviewer-count qualifiers such as `(parallel + triage)` stay English. Out of scope for localization (always English, per `prefs.schema.json`): reviewer and triage system prompts, commit messages, PR titles and bodies, Jira comments, wiki content and log payloads inside `agent-log.md`.

package/pipeline/multi-agent-refs/orchestrator/dispatcher.md

@@ -2,6 +2,7 @@
 
 <!-- toc -->
 - [Canonical invocation](#canonical-invocation)
+- [Routing and loading tables](#routing-and-loading-tables)
 - [Routing detail](#routing-detail)
 - [Agent definitions](#agent-definitions)
 - [jira Command](#jira-command)
@@ -12,7 +13,7 @@
 - [Global Paths](#global-paths)
 <!-- /toc -->
 
-> Loaded by `commands/multi-agent/SKILL.md` (the `/multi-agent` dispatcher). The SKILL keeps the routing tables, the loading table and the rules; this file carries the per-CLI invocation table, the agent definitions, the `jira` / `issue` / Direct-ID step lists, the Interactive Launcher prompts, the status table and the global paths. Read the matching section before routing one of those inputs.
+> Loaded by `commands/multi-agent/SKILL.md` (the `/multi-agent` dispatcher). The SKILL keeps a compact routing table and the rules; this file carries the full routing and loading tables, the per-CLI invocation table, the agent definitions, the `jira` / `issue` / Direct-ID step lists, the Interactive Launcher prompts, the status table and the global paths. Read the matching section before routing one of those inputs.
 
 ## Canonical invocation
 
@@ -33,6 +34,100 @@ The space-form (`multi-agent <subcommand>`) is still routed by this dispatcher
 for backward compatibility, but the colon (Claude) / dash (Copilot) forms are
 the canonical invocations and the only forms surfaced in autocomplete.
 
+## Routing and loading tables
+
+The full tables behind the dispatcher's compact routing table. Route first, then `Read` only the file the routed action needs.
+
+### Routing
+
+| Input Pattern | Action |
+|---------------|--------|
+| `#N`, `316` | GitHub Issue #  -  parse, select project, start pipeline |
+| `https://github.com/.../issues/N` | GitHub Issue URL  -  fetch, auto-detect or ask project |
+| `https://{JIRA_HOST}/browse/{JIRA_KEY}-XXXXX` | Jira URL  -  fetch, select project, start pipeline |
+| `{JIRA_KEY}-XXXXX` | Jira ID  -  fetch, select project, start pipeline |
+| Free-text | Bug/feature description  -  select project, start pipeline |
+| `jira` | 4-step picker (hesap → proje → issue → dev-context)  -  `commands/multi-agent/jira/SKILL.md` delegate |
+| `issue` | 4-step picker (hesap → repo → issue → dev-context)  -  `commands/multi-agent/issue/SKILL.md` delegate |
+| `status` | List all tasks (scan `$HOME/.claude/logs/multi-agent/`) |
+| `log [id]` | Show task log |
+| `resume [id]` | Resume paused task |
+| `kill [id]` | Delete worktree (logs preserved). Confirm first |
+| `clear-logs` | **Superseded  -  redirect, do not run.** Say so and route to `prune-logs`. It targeted `.worktrees/PROJ-*/agent-log.md`, a path nothing has written to since logs moved to `$HOME/.claude/logs/multi-agent/{project}/{task-id}/`; running it would report deleting nothing as success. |
+| `purge` | Worktree + logs + counter  -  full reset (double confirm) |
+| `review [#N\|repo#N\|PR-url\|branch]` | Parallel review of a PR or branch diff; with no input (interactive) lists open GitHub + Bitbucket PRs to multi-select. Posts per-finding inline comments + approve/needs-work on PRs. No worktree. |
+| `review-jira [KEY\|url]` | Grade a Jira issue's readiness for the pipeline (scope / AC / repro / design / API / stack), then post the gaps as a Jira comment. Read-only on code. |
+| `review-issue [#N\|repo#N\|url]` | Grade a GitHub issue's readiness for the pipeline, then post the gaps as an issue comment. Read-only on code. |
+| `analysis ["<feature>"]` | Standalone feature-spec analysis; stops after the document. No worktree, no commits, no dev chain. |
+| `complaint-analysis ["<run-name>"] [--file <path>] [<jira-id\|confluence-url> ...]` | Customer-complaint triage to a report and a verdict; read-only on code. No worktree, commits or dev chain. |
+| `build-optimize` | iOS-only Xcode build performance wrapper; recommend-first plan. Fail-fast on non-iOS stacks. |
+| `channels [PR-url\|#N\|Jira-url\|Jira-id] [--channels pr,jira,confluence,wiki] [--content normal,test,auto-diff,note] [--message "..."]` | Post the task report to multi-select channels with multi-select content; Phase 5 delegates here, also post-hoc. No worktree. |
+| `create-jira ["desc"] [figma-url] [swagger-url]` | Create a standards-compliant Jira issue (Task / Bug / Story) with full draft preview + explicit approval before create. No worktree, no commits. |
+| `test` or `test [args]` | UI Bug Hunter  -  screenshot + tap + analyze on booted simulator via MCP (read `$HOME/.claude/commands/sim-test.md`). `/multi-agent:test` also resolves here via the `commands/multi-agent/test/SKILL.md` delegate. |
+| `test-dark-mode` · `test-accessibility` · `test-dynamic-type` · `test-screenshots [locale]` | Fixed-scenario aliases for the four parameterless / single-parameter `test` scenarios, so the tag autocompletes instead of having to be quoted. Each delegates to the same `sim-test.md` with its scenario pinned; behaviour is identical to the quoted form, which is not deprecated. |
+| `store-ready [repo] [--archive=\|--ipa=\|--aab=\|--apk=] [--skip-sweep]` | Pre-submission store readiness for a built package, iOS and Android, local-only. Validates only, never ships a build. |
+| `manual-test [#id]` | Phase 5 standalone Manual Test  -  checks out the task branch, prints Xcode / SourceTree hints, waits for user verdict (`ok` / `fix: ...`). |
+| `design-check [scope]` | Mock-mode vs Figma design audit (iOS / Android, local-only) with a coverage gate. No commits, no CI. |
+| `stack [ios\|android\|backend\|mobile\|all]` | Swap skills for next conversation. No arg = show current stack. |
+| `language [en\|tr]` | Show or set the assistant `outputLanguage` (explanations and chat replies). `promptLanguage` is locked to `en` and is not toggleable. No arg = show current `outputLanguage`. With `en` or `tr` = set and persist `outputLanguage`. Commits and branch names stay English; PR, Jira and wiki bodies follow it. |
+| `setup` | Keychain token + Git Identity onboarding |
+| `autopilot` | Skip user confirmations, auto commit/PR |
+| No args / `help` | Show usage guide |
+
+### Loading
+
+`commands/multi-agent/{cmd}/SKILL.md` files are invocable actions (each its own `/multi-agent:<name>` slash command); `$HOME/.claude/multi-agent-refs/**` are internal references read by the dispatcher, never invoked directly, and live outside `commands/` so they never appear in slash-command autocomplete.
+
+| Route | File to Read |
+|-------|-------------|
+| Pipeline task (any input type) | `$HOME/.claude/multi-agent-refs/phases.md` + `$HOME/.claude/multi-agent-refs/_account-picker.md` + `_repo-picker.md` + `_dev-context.md` |
+| `jira` | `$HOME/.claude/commands/multi-agent/jira/SKILL.md` (4-step picker) |
+| `issue` | `$HOME/.claude/commands/multi-agent/issue/SKILL.md` (4-step picker) |
+| Direct ID (`{JIRA_KEY}-N`, `#N`, gh URL, repo#N, free-text) | `$HOME/.claude/multi-agent-refs/_input-parser.md` → `_account-picker.md` → `lib/issue-fetcher.sh` (maturity check) → `_dev-context.md` |
+| `setup` | `$HOME/.claude/commands/multi-agent/setup/SKILL.md` |
+| `help` | `$HOME/.claude/commands/multi-agent/help/SKILL.md` |
+| `channels` | `$HOME/.claude/commands/multi-agent/channels/SKILL.md` |
+| `sync` | `$HOME/.claude/commands/multi-agent/sync/SKILL.md` |
+| `clear-logs` | Handled inline  -  redirect to `prune-logs`, see the routing note |
+| `review` | `$HOME/.claude/commands/multi-agent/review/SKILL.md` |
+| `review-jira` | `$HOME/.claude/commands/multi-agent/review-jira/SKILL.md` (loads `$HOME/.claude/multi-agent-refs/readiness-review.md`) |
+| `review-issue` | `$HOME/.claude/commands/multi-agent/review-issue/SKILL.md` (loads `$HOME/.claude/multi-agent-refs/readiness-review.md`) |
+| `analysis` | `$HOME/.claude/commands/multi-agent/analysis/SKILL.md` |
+| `complaint-analysis` | `$HOME/.claude/commands/multi-agent/complaint-analysis/SKILL.md` |
+| `build-optimize` | `$HOME/.claude/commands/multi-agent/build-optimize/SKILL.md` |
+| `create-jira` | `$HOME/.claude/commands/multi-agent/create-jira/SKILL.md` (loads `$HOME/.claude/multi-agent-refs/generate-issue.md`) |
+| `stack` | `$HOME/.claude/commands/multi-agent/stack/SKILL.md` |
+| `language` | Handled inline  -  set/show outputLanguage in preferences |
+| SwiftUI component task (iOS) | `$HOME/.claude/multi-agent-refs/swiftui-guide.md` |
+| Jetpack Compose task (Android) | `$HOME/.claude/multi-agent-refs/android-guide.md` |
+| Backend API task | `$HOME/.claude/multi-agent-refs/backend-guide.md` |
+| Web component task | `$HOME/.claude/multi-agent-refs/web-guide.md` |
+| Phase 1 or Phase 5 (knowledge) | `$HOME/.claude/multi-agent-refs/knowledge.md` |
+| Token lookup needed | `$HOME/.claude/multi-agent-refs/keychain.md` |
+| Audit tools (Phase 3) | `$HOME/.claude/multi-agent-refs/audit-guide.md` |
+| `test` | `$HOME/.claude/commands/sim-test.md` (colon-form `/multi-agent:test` uses the delegate at `commands/multi-agent/test/SKILL.md`) |
+| `test-dark-mode` · `test-accessibility` · `test-dynamic-type` · `test-screenshots` | `$HOME/.claude/commands/sim-test.md`, scenario pinned by the command name (delegates at `commands/multi-agent/test-*/SKILL.md`) |
+| `manual-test` | `$HOME/.claude/commands/multi-agent/manual-test/SKILL.md` |
+| `design-check` | `$HOME/.claude/commands/multi-agent/design-check/SKILL.md` |
+
+**Modifier flag** (`autopilot`) and **ops** (`status`, `log`, `resume`, `kill`, `purge`, `review`) are parsed inline by this file  -  no separate spec files, they compose with the pipeline or do one-shot work.
+
+Guide selection (auto, from the Phase 1 detected stack):
+- iOS detected -> load `swiftui-guide.md`
+- Android detected -> load `android-guide.md`
+- Python/Node.js/Go detected -> load `backend-guide.md`
+- React/Vue/Next.js detected -> load `web-guide.md`
+- Multiple stacks -> load all relevant guides
+
+### Lib scripts
+
+Under `~/.claude/lib/`:
+- `account-resolver.sh`  -  keychain account inventory
+- `issue-fetcher.sh`  -  Jira/GitHub fetch + maturity scoring
+- `repo-cache.sh`  -  TTL-cached repo list
+- `submodule-detector.sh`  -  `.gitmodules` parse → dev-context suggestions
+- `multi-repo-pipeline.sh`  -  worktree/branch/commit/PR orchestration
+
 ## Routing detail
 
 The full action descriptions for the routing rows the dispatcher keeps short.