@mmerterden/multi-agent-pipeline 20.36.0 → 20.37.1

package/pipeline/multi-agent-refs/features/commit-multi-repo.md

@@ -0,0 +1,63 @@
+# Phase 4 Commit  -  Multi-Repo Mode
+
+> Loaded on demand from `phases/phase-4-commit.md`. Conditional on
+> `state.projects[].length > 1`; a single-repo run never needs it. The
+> Push-must-succeed policy stays in the phase doc because every run uses it.
+
+Active when `state.projects[].length > 1`. The single-repo flow in the phase doc is preserved verbatim  -  multi-repo is an extension, not a replacement.
+
+## Per-repo commit (shared message, per-repo scope)
+
+For each repo in `state.projects[]` (sequentially, in dependency order from Phase 1):
+
+1. `cd "$WT_PATH"`  -  switch into the repo's worktree.
+2. Build the commit message using the **shared subject** + **per-repo scope** rule:
+   ```
+   {type}({repo-scope}): {shared subject} [{tracker-id}]
+
+   Part of multi-repo change  -  see sibling PR(s) in repo `{other repo names}`.
+   ```
+   `repo-scope` is the repo's short name (e.g. `common`, `uicomponents`). The subject and `[tracker-id]` are identical across all repos.
+3. Fold this repo's checkpoint commits first: `bash $HOME/.claude/scripts/checkpoint-fold.sh --repo "$WT_PATH" --task "{tracker-id}" --base "$BASE_BRANCH"`. Then `git add` (specific files only  -  same rules as the single-repo staging step, item 4 of the Standard path in `phases/phase-4-commit.md` Step 2)
+4. `git -C "$WT_PATH" commit -m "$MESSAGE"` (heredoc body)  -  using identity already pinned in Phase 0 Step 8.
+5. Capture `state.projects[i].commit = {"sha": "<sha>"}`.
+
+Push each repo through the Push-must-succeed policy in `phases/phase-4-commit.md`, then continue here.
+
+## Per-repo PR with cross-links
+
+After all repos are pushed, open PRs sequentially, one per `state.projects[]` entry, each through its remote's usual path (gh / Bitbucket REST) with the per-stack body template (Standard / UI Component / etc). Append to each body:
+
+```
+## Sibling PRs (multi-repo task)
+This PR is part of a multi-repo change. Sibling PRs (review together):
+- <url of each PR opened before this one>
+```
+
+After the last PR opens, `update_sibling_links`: go back to the first N-1 PRs and add the sibling URLs that were not yet known when they were created.
+
+**Then finalize each repo's worktree**, serially and only now  -  `update_sibling_links` updates one PR per repo and the loop `cd`s per repo, so removing repo 1's worktree mid-loop breaks 2..N. Run `worktree-finalize.sh` once per repo with that repo's `--worktree` / `--project-root` / `--project`; each skips or removes independently.
+
+`update_sibling_links` does an UPDATE call per PR (Bitbucket: the `channels/pr.md` PUT payload, current `version`; GitHub: `gh pr edit --body-file`). Idempotent.
+
+## GitHub issue body  -  list all PRs
+
+Step 10's "Issue body update" extends to multi-repo: instead of a single `### Pull Requests` line, write one row per repo:
+
+```
+### Pull Requests
+- **common:** {pr-1-url}
+- **uicomponents:** {pr-2-url}
+```
+
+Match the existing template's table/list shape  -  do not introduce new markers (per existing single-repo rule).
+
+## `recentGroups` update on success
+
+After ALL repos in the task have `pushStatus ∈ {"pushed", "rebase-pushed"}`:
+
+1. Find the matching `recentGroups[]` entry by **order-independent compare** of `repos` array (sort + JSON.stringify).
+2. If found: `entry.count += 1`, `entry.lastUsed = ISO timestamp`, bump to front of array (LRU).
+3. If not found: prepend a new entry `{ label: <auto-generated>, repos: [...], count: 1, lastUsed: ... }`. Cap the array at 10 (drop oldest).
+
+A task ending with one or more `pushStatus === "skipped"` repos does NOT bump `recentGroups` count  -  only fully-successful multi-repo tasks earn LRU bumps.

package/pipeline/multi-agent-refs/features/dev-multi-repo.md

@@ -0,0 +1,51 @@
+# Phase 2 Dev  -  Multi-Repo Mode
+
+> Loaded on demand from `phases/phase-2-dev.md`. Conditional on
+> `state.projects[].length > 1` (set by Phase 0 multi-select); a single-repo run
+> never needs it. Token forwarding and the build-log offload stay in the phase
+> doc because every run uses them.
+
+Active when `state.projects[].length > 1`. The single-repo flow in the phase doc is preserved verbatim  -  this file adds the deltas.
+
+**Todo tagging**: Phase 1 plan items in multi-repo mode carry a `repo` field naming the target project root. The dev agent uses this tag to dispatch each todo:
+
+```json
+{
+  "id": "T-3",
+  "title": "Add tokenResolver public API",
+  "repo": "common",                         // ← matches state.projects[i].name
+  "files": ["Sources/Common/TokenResolver.swift"],
+  "tdd": { "test": "...", "code": "..." }
+}
+```
+
+If a todo has no `repo` tag in multi-repo mode → log warning + ask user, do not auto-pick.
+
+**Per-todo worktree switch**: Before each todo's TDD cycle, resolve `WT_PATH = state.projects[ findIndex(name === todo.repo) ].worktreePath` and run **all** subsequent commands with `git -C "$WT_PATH"` and `cd "$WT_PATH"` for build/test. Identity (`user.name`/`user.email`) was already pinned per worktree by Phase 0 Step 8  -  no re-config needed here.
+
+**Status update (single ticket, multi-repo)**: The Jira/GitHub issue is shared across all repos in the group  -  call the status-update API exactly **once per todo** (not once per repo per todo). The post-mutation verify rule still applies.
+
+**Build serialization**:
+- Xcode worktrees still share `BUILD_LOCK = /tmp/claude-xcodebuild.lock`  -  multi-repo just means more callers contending for the same lock; the existing `mkdir`-based queue handles it correctly.
+- Non-Xcode repos may build in parallel across worktrees  -  but ONLY when builds are independent. If repo B's build depends on repo A's freshly-published artifact (e.g. SPM local path dependency), serialize them in dependency order. Plan items declare dependencies via Phase 1's `dependsOn` field; multi-repo dispatch respects that order.
+
+**Failure isolation**: A build/test failure in one repo's worktree must NOT silently leave the other repos in a half-built state. On failure:
+1. Capture the failure into `state.projects[i].buildStatus = { ok: false, attempts: N, lastError: "..." }`
+2. The ENTIRE Phase 2 retries within that repo's worktree (max 3, same as single-repo)
+3. After 3 attempts, escalate; do NOT proceed to Phase 3 with any unbuilt repo
+
+**Recording a pass (default-FAIL evidence gate):** before setting `buildStatus.ok = true`, the build output must be tee'd to a log and that log must substantiate the success  -  a zero exit code alone is not trusted. Run the evidence gate; on exit 1, do NOT record a pass:
+```bash
+<build-command> 2>&1 | tee "{worktreePath}/.build.log" \
+  | bash $HOME/.claude/scripts/offload-ref.sh --phase 2 --label build --root "$WORKTREE"
+node $HOME/.claude/scripts/evidence-gate.mjs --claim build --status passed --evidence "$WORKTREE/.build.log"
+```
+Non-zero from the gate: the build pass is unverified, so treat it as a failure and keep `buildStatus.ok=false`.
+This closes the gap where an agent records "built" without ever producing build output.
+The offload pipe is explained in the phase doc ("Why the pipe").
+
+**Telemetry**: Per-repo metrics in addition to per-task metrics:
+```bash
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 2 build.completed repo=common duration_ms=$D status=ok
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 2 build.completed repo=uicomponents duration_ms=$D status=ok
+```

package/pipeline/multi-agent-refs/features/test-gap.md

@@ -0,0 +1,40 @@
+# Phase 3 User Test  -  Test Gap Report detail
+
+> Loaded on demand from `phases/phase-3-review.md` (User test, Step 0) when the
+> gap scan produced a report. The phase doc keeps the call and the skip rules;
+> this file carries the report shape, severities, gating and telemetry.
+
+## What the report contains
+
+Per `$HOME/.claude/schemas/test-gap.schema.json`:
+
+| Field | Meaning |
+|---|---|
+| `gaps[].sourcePath` | source file with the unprotected symbol |
+| `gaps[].symbol` | symbol name |
+| `gaps[].kind` | rule id (e.g. `public_func`, `composable_fun`, `named_export`) |
+| `gaps[].severity` | `blocking` / `important` / `suggestion` (see severity table below) |
+| `gaps[].expectedTestPaths` | likely test paths the user should land at, in priority order |
+| `gaps[].hint` | stack-specific testing reminder (e.g. swiftui-qa.md 3-layer) |
+
+## Severity defaults
+
+| Symbol kind | Severity |
+|---|---|
+| `composable_fun`, `view_struct`, `config_struct`, `interface`, `objc_export`, `public_proto` | important |
+| Other public API additions (`public_func`, `open_fun`, `named_export`, `default_export`, ...) | suggestion |
+
+## Gating (opt-in)
+
+If `prefs.testGap.blockingThreshold` is set and `gapBySeverity.important + gapBySeverity.blocking` exceeds it, Phase 3 surfaces the report as a Phase 3 rework finding and loops back. **Default off**  -  gaps render as advisory under "Test Gap Report" only.
+
+## Telemetry
+
+```bash
+LOG_METRIC_FORWARD_TO_TRACKER=0 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 test_gap.scanned \
+  stack=$SCAN_STACK \
+  sources=$(jq '.totals.sourcesScanned' <<< "$GAP_JSON") \
+  gaps=$(jq '.totals.gapCount' <<< "$GAP_JSON")
+```
+
+(No tracker forwarding  -  the scanner has no token cost.)

package/pipeline/multi-agent-refs/features/worktree-finalize.md

@@ -10,7 +10,7 @@ Removing it at PR-open is only safe because of the salvage, so the two are one s
 
 ## What it will not do
 
-**No `git checkout` of the task branch.** `git worktree remove` leaves the branch as an ordinary local branch: the ref, its commits, and the ability to `git checkout <branch>` later all survive untouched. Checking it out here would move the user's HEAD out from under them and can collide with their own uncommitted work on another branch. Phase 5 removes-then-checks-out on purpose, because it is handing the branch over for manual testing; this step is not.
+**No `git checkout` of the task branch.** `git worktree remove` leaves the branch as an ordinary local branch: the ref, its commits, and the ability to `git checkout <branch>` later all survive untouched. Checking it out here would move the user's HEAD out from under them and can collide with their own uncommitted work on another branch. Phase 3's user test removes-then-checks-out on purpose, because it is handing the branch over for manual testing; this step is not.
 
 **No `git branch -D`.** The branch is the deliverable.
 

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/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`.