@mmerterden/multi-agent-pipeline 15.3.1 → 15.4.0

package/CHANGELOG.md

@@ -16,6 +16,30 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [15.4.0] - 2026-08-18
+
+### Added
+- **Per-project `testPolicy`** (`tdd` | `tests-after` | `none`): Phase 0 resolves it after project selection for every input type, asking once via a native picker when absent (autopilot defaults to `tdd` and notes it). Phase 3 gates the TDD cycle on it; Phase 5 skips the gap scan under `none` and runs only pre-existing targets. Prefs schema + template carry the field.
+- **Ordered stack-toolkit routing candidates**: the ios/android rows resolve the corporate `-engineering-` variant before its public derivation, and a full probe miss records every candidate tried. The conventions census learns a `CrossDomains` root; screen-creation tasks bind the routed toolkit's `create-screen` workflow.
+- **ios-module-structure 0.3.0 / ios-coding-standard 1.2.0** (authoring source): the settled architecture becomes the standard - UnitDialect slot, unit vocabulary roles, STRUCT-18..21 with checker support, UNIT-01..03 / SAFE-03 / MOD-08; the pre-conversion spellings are named residue.
+
+### Fixed
+- The test-policy step resolves for Jira-ID and URL inputs, not only free-text; STRUCT-18 reports an unbound contracts root as disabled coverage instead of passing silently.
+
+## [15.3.2] - 2026-08-17
+
+### Fixed
+
+- `local` and `local-autopilot` mode docs pointed at the retired `commands/multi-agent.md` dispatcher spelling; they now reference `commands/multi-agent/SKILL.md`, and the Codex installer rewrites the directory-layout spelling to the router skill (dedicated rewrite rule, smoke guard for the new corruption shape, unit tests).
+- The sync spec copies (command tree + Copilot shared-core mirror) disagreed on the Claude source list and file mapping; both now carry `multi-agent-refs/` and `lib/` and the same mapping rows.
+- The dispatcher entry doc now declares the TaskCreate ordering rule and is scanned by `smoke-tasklist-ordering.sh`, closing the one mode (full interactive) the inventory missed.
+- `check-md-links.mjs` resolves `$HOME/.claude/commands/` links against the repo source, so a future layout move cannot leave dangling dispatcher references silently.
+- Install-layout fingerprint fixture regenerated for `usage-report.mjs` and the relocated reference files.
+
+### Changed
+
+- refactor Step 0c (dev-toolkit research) and setup Step 3b (App Store Connect onboarding) moved to on-demand references under `multi-agent-refs/`, keeping both skills inside their token budgets.
+
 ## [15.3.1] - 2026-08-15
 
 ### Changed

package/install/codex.mjs

@@ -82,6 +82,18 @@ export const CODEX_PATH_REWRITES = Object.freeze([
     to: "$HOME/.codex/skills/multi-agent/SKILL.md",
   },
   { from: /~\/\.claude\/commands\/multi-agent\.md/g, to: "~/.codex/skills/multi-agent/SKILL.md" },
+  // Current dispatcher spelling (directory layout). MUST also precede the
+  // sub-command rule: `commands/multi-agent/SKILL.md` would otherwise become
+  // `multi-agent-refs/commands/SKILL.md`, which installRefs deliberately never
+  // writes (the top-level SKILL.md ships as the router skill instead).
+  {
+    from: /\$HOME\/\.claude\/commands\/multi-agent\/SKILL\.md/g,
+    to: "$HOME/.codex/skills/multi-agent/SKILL.md",
+  },
+  {
+    from: /~\/\.claude\/commands\/multi-agent\/SKILL\.md/g,
+    to: "~/.codex/skills/multi-agent/SKILL.md",
+  },
   // Sub-command specs become reference files under the Codex refs tree.
   {
     from: /\$HOME\/\.claude\/commands\/multi-agent\b/g,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "15.3.1",
+  "version": "15.4.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

package/pipeline/commands/multi-agent/SKILL.md

@@ -285,6 +285,10 @@ Quick pointers:
 
 Load `$HOME/.claude/multi-agent-refs/rules.md` for the full contract (Swift-specific rules, reviewer policy, secret scan, subagent contract).
 
+### TaskCreate ordering (strict)
+
+**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied**  -  this binds the full interactive `/multi-agent` run (all 8 phases) exactly like every mode alias. The native widget renders tiles by creation order, not by phase number; out-of-order calls produce visually scrambled tile stacks. Register every tile in order, then flip status via TaskUpdate when a phase actually starts or short-circuits. Full contract: `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+
 ---
 
 ## Status Display

package/pipeline/commands/multi-agent/local/SKILL.md

@@ -40,7 +40,7 @@ Phase 7: Report     → Jira / Wiki / Confluence + log + knowledge/memory
 
 This command routes to the orchestrator with the `--local` flag set. The Phase 0-7 contract from `$HOME/.claude/multi-agent-refs/phases/phase-0-init.md` and the later phase docs applies as-is  -  only the worktree step is skipped, and `state.projects[*].worktreePath` stays `null`.
 
-Read the routing table in `$HOME/.claude/commands/multi-agent.md` and apply Phase 0 Step 8 in local mode (no worktree: continue on the current branch, state file under `.claude/logs/multi-agent/{project}/{taskId}/`).
+Read the routing table in `$HOME/.claude/commands/multi-agent/SKILL.md` and apply Phase 0 Step 8 in local mode (no worktree: continue on the current branch, state file under `.claude/logs/multi-agent/{project}/{taskId}/`).
 
 ## Examples
 

package/pipeline/commands/multi-agent/local-autopilot/SKILL.md

@@ -69,7 +69,7 @@ Run the full pipeline **without a worktree** and **with every confirmation skipp
 
 ## Delegation
 
-Orchestrator routing: the routing table in `$HOME/.claude/commands/multi-agent.md` resolves `local-autopilot` as the union of the `dev-local` + `autopilot` mode mixins. Contract details: `$HOME/.claude/multi-agent-refs/phases/phase-0-init.md` Step 8 (local branch) + `$HOME/.claude/multi-agent-refs/phases/phase-2-planning.md` Step 5 (autopilot gate skip + safety classifier).
+Orchestrator routing: the routing table in `$HOME/.claude/commands/multi-agent/SKILL.md` resolves `local-autopilot` as the union of the `dev-local` + `autopilot` mode mixins. Contract details: `$HOME/.claude/multi-agent-refs/phases/phase-0-init.md` Step 8 (local branch) + `$HOME/.claude/multi-agent-refs/phases/phase-2-planning.md` Step 5 (autopilot gate skip + safety classifier).
 ## Required: outward-facing payload contracts
 
 Before writing anything outward-facing  -  PR body, Jira comment, Confluence page, closing report  -  load `$HOME/.claude/multi-agent-refs/payload-contracts.md`. It names the canonical section set for each payload, the markup dialect per surface (PR body is Markdown, Jira is wiki markup  -  mixing them is a defect), and the token/duration numbers the closing report must carry. Improvising a payload shape from memory is the most common failure of the short modes.

package/pipeline/commands/multi-agent/refactor/SKILL.md

@@ -112,73 +112,7 @@ Procedure:
 
 The pipeline's hands on devices and browsers are MCP tools served by a companion repo (`dev-toolkit-mcp`): Phase 5 test, `manual-test`, `design-check` and `apple-archive-compliance` all call them, and several pipeline skills declare a minimum toolkit version (see `cross-cli-contract.md`). That repo therefore has to track the MCP field, not just its own README. This step researches what current practice is and audits the toolkit against it.
 
-**Resolution**  -  configuration first, never a hardcoded path:
-
-1. `prefs.global.devToolkit` in `~/.claude/multi-agent-preferences.json`:
-
-```jsonc
-{
-  "enabled": true,
-  "label": "<human name>",
-  "localPath": "$HOME/<repo-dir>",              // the companion repo working copy
-  "mcpServerName": "<registered MCP server name>",
-  "packageName": "@<scope>/<package>",
-  "registry": "github-packages",                 // github-packages | npmjs | none
-  "repoUrl": "https://github.com/<owner>/<repo>"
-}
-```
-
-2. If unset, auto-detect from the MCP registration: read `mcpServers` in `~/.claude.json` (including each `projects[*].mcpServers`) and in `~/.claude/settings.json`; for a stdio entry whose command is `node`, take `dirname(args[0])`. Accept it only when that directory is a git repo whose `package.json` depends on `@modelcontextprotocol/sdk`.
-3. If neither resolves, skip this step and report "no dev-toolkit configured". Never guess a path, never clone.
-4. `enabled: false` skips the step.
-
-**Research axes**  -  a finding without a source link is not a finding:
-
-| # | Axis | Where to look | What to extract |
-|---|------|---------------|-----------------|
-| 1 | MCP protocol | spec revisions + `@modelcontextprotocol/sdk` releases | protocol features released since the pinned SDK range that the server does not use yet: tool annotations (`readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`), `outputSchema` + structured content, resource links in results, progress + cancellation, `tools/list_changed`, pagination, elicitation |
-| 2 | Host clients | Claude Code / Copilot CLI / Cursor / Antigravity docs + release notes | per-tool description budget, tool-count ceilings, naming conventions, image and output size limits, permission / allowlist ergonomics |
-| 3 | Peer servers | GitHub search on the same domain terms + `stars:>50` | tool surfaces we lack, conventions peers converged on, and what to discard as out of scope |
-| 4 | Wrapped tooling | `xcrun simctl help`, `idb`, `adb`, `xcodebuild`, Playwright release notes, Apple ITMS + App Store Review Guidelines | deprecated flags still in use, new capabilities worth a tool, audit rules that changed |
-| 5 | Field practice | X / Twitter, Reddit, MCP community threads | what server authors actually changed recently (transport choice, output-token diets, sandboxing, error shape) |
-
-**Audit the toolkit against the findings**  -  run the checks, do not assume:
-
-```bash
-DT="<resolved localPath>"
-node --check "$DT/index.js"
-find "$DT/tools" -name "*.js" -type f -exec node --check {} \;
-
-# stdout carries the JSON-RPC frames: a stray stdout write corrupts the stream
-grep -rn "console\.log(" "$DT/index.js" "$DT/tools" || echo "stdout clean"
-
-# advertised tool counts vs reality (README header + package.json description)
-grep -nE "[0-9]+ tools" "$DT/README.md" "$DT/package.json"
-
-# packaging: every runtime directory must be inside files[]
-node -p "require('$DT/package.json').files.join('\n')"
-ls -d "$DT"/tools/*/
-
-cd "$DT" && npm outdated; npm audit --omit=dev 2>/dev/null | tail -20
-```
-
-Also check: every tool carries a description and an `inputSchema`; token-heavy results (screenshots, UI trees, logs) are truncated or written to a file path instead of inlined; failures return an error result with an actionable message instead of throwing; `engines.node` matches what the SDK needs; `CHANGELOG.md`, a CI workflow and a test harness exist.
-
-Output (plan band E):
-
-```
-| # | Axis | Finding | Source | Adaptation in the toolkit (file) | Effort | Impact | In plan? |
-|---|------|---------|--------|----------------------------------|--------|--------|----------|
-| 1 | Protocol | read-only tools carry no annotations | <spec link> | add `annotations` to the read-only tools in index.js | Low | Medium | Yes (P1) |
-| 2 | Wrapped tooling | uses a simctl flag removed in Xcode <v> | <release notes> | switch tools/<family>/<file>.js to <new flag> | Low | High | Yes (P0) |
-| 3 | Peer servers | peer exposes <surface> | <repo link> | does not fit: outside the pipeline's phases | - | - | No |
-```
-
-Rules for this band:
-
-- Band-E work lands in the toolkit repo, never mirrored into this one. Shipping it is `/multi-agent:sync` Step 3d.
-- A finding that changes the tool surface (new / renamed / removed tool) pairs with a pipeline-side item: bump the minimum toolkit version wherever a pipeline skill declares one.
-- If the current working directory IS the toolkit repo, skip band E and let bands A/B/C cover it  -  never report the same finding twice.
+Full procedure  -  resolution (configuration first, never a hardcoded path; skip when nothing resolves or `enabled` is false), the 5 research axes, the audit command block, and the band-E output table + rules  -  lives in `$HOME/.claude/multi-agent-refs/refactor/dev-toolkit-research.md`. Read it before running this step.
 
 ## Step 0d: RUN-ERRORS  -  what the pipeline actually failed on
 

package/pipeline/commands/multi-agent/setup/SKILL.md

@@ -402,55 +402,7 @@ This builds `platformIdentityRouting` incrementally  -  no separate Step 7 neede
 
 ### Step 3b  -  App Store Connect onboarding (iOS only, optional)
 
-Runs inside Step 3 alongside the other missing credentials, not as a late add-on:
-a user who already has an App Store Connect credential in their keychain gets it
-mapped by Step 1 discovery like any other token, and only the genuinely missing
-pieces reach this flow.
-
-Three of the four entries do not go through the normal Token Save Flow, because
-what they hold is not a pasteable secret:
-
-| Entry | Holds | Flow |
-|---|---|---|
-| `appstore_connect_key_id` | an identifier | plain value, not a secret; still mapped so it is read through the mapping layer |
-| `appstore_connect_issuer_id` | an identifier | same |
-| `appstore_connect_apple_id` | an email address | same |
-| `appstore_connect_password_item` | a keychain ITEM NAME | the password lives in Apple's own keychain item, referenced as `-p @keychain:<item>` and never read by the pipeline |
-
-Ask which tier to configure (picker): **API key** / **Apple ID + app-specific
-password** / **Skip**. Lead with the second when the user says they cannot create
-an API key.
-
-**API key.** The private key is a FILE and is never copied into the credential
-store. It must sit in a directory `altool` already searches:
-
-```bash
-ls ~/.appstoreconnect/private_keys/AuthKey_*.p8 2>/dev/null \
-  || echo "MISSING: put AuthKey_<keyId>.p8 in ~/.appstoreconnect/private_keys/"
-```
-
-**Apple ID + app-specific password.** Use Apple's own keychain helper. The secret
-never enters chat and never becomes a shell argument, per the Token Save Flow rule:
-
-```bash
-# the user exports AC_PASSWORD_ONCE in their own shell, for this one command
-xcrun altool --store-password-in-keychain-item "<item-name>" \
-  -u "<apple-id>" -p @env:AC_PASSWORD_ONCE
-```
-
-Then map only `<item-name>` as `appstore_connect_password_item`.
-
-**Multi-provider accounts.** A corporate Apple ID often belongs to several
-providers, and `altool` fails opaquely without one. Resolve it once with
-`ios_testflight_validate({list_providers: true, <credentials just configured>})`
-and store the answer under
-`prefs.projects[<key>].appStoreConnect.providerPublicId`  -  per-project, since a
-user can ship for more than one team.
-
-**Verify + expiry.** Re-run the `list_providers` probe and report the resolved
-tier. A credential that resolves but is rejected (401/403) follows the
-Expired-token decision in `refs/keychain.md` Rule 1  -  Regenerate / Use a
-different token / Skip and continue  -  never a silent drop.
+Runs inside Step 3 alongside the other missing credentials. The four `appstore_connect_*` entries, their non-secret handling (three hold identifiers / a keychain item name, not pasteable secrets), the API-key vs Apple-ID tier picker, and the verification probes live in `$HOME/.claude/multi-agent-refs/setup/app-store-connect.md`. Read that file when the user opts into App Store Connect onboarding; on Skip, nothing is written.
 
 ### Step 3.5  -  Host Prompt (embedded in Token Save Flow)
 

package/pipeline/commands/multi-agent/sync/SKILL.md

@@ -25,7 +25,7 @@ When invoked, it synchronizes all targets in order. It detects what changed, upd
 
 | # | Target | Path | Direction |
 |---|-------|-----|-----|
-| 1 | Claude Code (source of truth) | `~/.claude/commands/multi-agent.md` + `~/.claude/commands/multi-agent/` + `~/.claude/agents/` + `~/.claude/scripts/` + `~/.claude/lib/` | source |
+| 1 | Claude Code (source of truth) | `~/.claude/commands/multi-agent/` + `~/.claude/multi-agent-refs/` + `~/.claude/agents/` + `~/.claude/scripts/` + `~/.claude/lib/` | source |
 | 2 | Copilot CLI | `~/.copilot/copilot-instructions.md` + `~/.copilot/skills/` | <- from Claude |
 | 2b | Codex CLI | `~/.codex/AGENTS.md` + `~/.codex/skills/multi-agent/` + `~/.codex/multi-agent-refs/` + `~/.codex/agents/*.toml` | <- from Claude (path-rewritten) |
 | 3 | multi-agent-pipeline repo | `~/multi-agent-pipeline/pipeline/` | <- from Claude (genericized) |
@@ -87,7 +87,7 @@ If nothing is stale → report "All targets up to date" and stop.
 
 1. **Read first**  -  understand every target's current state before making any change
 2. **Preserve file structure**  -  each target has its own format:
-   - `multi-agent.md` + phases/: detailed pipeline spec (frontmatter, phases, routing)
+   - `commands/multi-agent/` SKILL tree + `multi-agent-refs/phases/`: detailed pipeline spec (frontmatter, phases, routing)
    - `copilot-instructions.md`: general development instructions + pipeline summary section
    - `multi-agent-pipeline/pipeline/`: generic open-source version (NO personal data)
 3. **Sync the shared sections** (Claude ↔ Copilot):
@@ -105,7 +105,7 @@ If nothing is stale → report "All targets up to date" and stop.
 
 ## Pipeline Repo Sync Rules (CRITICAL)
 
-1. **Source**: `~/.claude/commands/multi-agent.md` + `~/.claude/commands/multi-agent/` + `~/.claude/agents/`
+1. **Source**: `~/.claude/commands/multi-agent/` + `~/.claude/multi-agent-refs/` + `~/.claude/agents/` + `~/.claude/lib/`
 2. **Target**: `~/multi-agent-pipeline/pipeline/`
 3. **Genericization** (must be applied BEFORE writing to the target):
    - Jira project key (`prefs.global.defaultJiraKey`) -> `{JIRA_KEY}`, `PROJ` in examples
@@ -116,7 +116,6 @@ If nothing is stale → report "All targets up to date" and stop.
    - **Verify**: `grep` scan for personal/corporate data inside pipeline/ -> 0 results
 4. **File mapping**:
    ```
-   ~/.claude/commands/multi-agent.md      -> pipeline/commands/multi-agent.md
    ~/.claude/commands/multi-agent/        -> pipeline/commands/multi-agent/
    ~/.claude/multi-agent-refs/            -> pipeline/multi-agent-refs/   (refs + pickers, non-command)
    ~/.claude/commands/sim-test.md         -> pipeline/commands/sim-test.md

package/pipeline/lib/extract-conventions.sh

@@ -86,7 +86,7 @@ scan_roots() {
   local roots=()
   case "$PLATFORM" in
     ios)
-      for d in Domains Common Core App Features Modules; do
+      for d in Domains Common Core CrossDomains App Features Modules; do
         [ -d "$REPO_PATH/$d" ] && roots+=("$REPO_PATH/$d")
       done
       ;;

package/pipeline/multi-agent-refs/features/stack-skill-routing.md

@@ -20,12 +20,18 @@ Phase 3 pre-flight, before any code is written, for **every** `taskType`. Compon
 
 Platform comes from the same mapping component dispatch uses, so the two cannot disagree:
 
-| `state.platform` / detected stack | Toolkit |
+| `state.platform` / detected stack | Toolkit candidates, first enabled wins |
 |---|---|
-| ios, swift | `ai-ios-toolkit` |
-| android, kotlin | `ai-android-toolkit` |
+| ios, swift | `ai-ios-engineering-toolkit`, then `ai-ios-toolkit` |
+| android, kotlin | `ai-android-engineering-toolkit`, then `ai-android-toolkit` |
 | anything else | no toolkit  -  step is a recorded no-op |
 
+A row is an ORDERED candidate list, not one name: the corporate toolkit (where one exists)
+carries the project-specific doctrine and outranks its public derivation, so it resolves first.
+Probe the candidates in order against the enabled plugins and take the first hit. When none is
+enabled, the recorded no-op names every candidate probed - a repo that enabled a corporate
+toolkit the table did not know about must show up as a probe miss, never as silence.
+
 The toolkit is enabled per repo (`.claude/settings.local.json` / `~/.claude/settings.json` `enabledPlugins`). **Not enabled is not an error here**, unlike component dispatch: a backend or web repo legitimately has no toolkit, and halting would make the pipeline unusable outside mobile. Record the no-op and continue.
 
 Two marketplaces may ship the same toolkit name (a public one and a corporate one). Resolve whichever is enabled and record its **name and version** in the ledger entry, because the routing table and the skill set differ between versions  -  a finding that cites a skill has to be traceable to the version that defined it.

package/pipeline/multi-agent-refs/phases/phase-0-init.md

@@ -35,7 +35,7 @@ Read preferences: `PREFS_FILE="$HOME/.claude/multi-agent-preferences.json"` (if
 OUTPUT_LANG=$(jq -r '.global.outputLanguage // "en"' "$PREFS_FILE" 2>/dev/null || echo en)
 ```
 
-From this point on, everything the user reads renders in `$OUTPUT_LANG`: conversational lines, `AskUserQuestion` `question`/`description`, and external payload bodies (PR/Jira/Confluence). English stays only on `label`/`header`, commit messages, branch names, PR titles, identifiers. Full matrix: `rules.md` "Language Application". Skipping this step is why a Turkish session gets an English wall of text  -  or an English picker.
+From this point on, everything the user reads renders in `$OUTPUT_LANG`: conversational lines, `AskUserQuestion` `question`/`description`, and external payload bodies (PR/Jira/Confluence). English stays only on `label`/`header`, commit messages, branch names, PR titles, identifiers. Full matrix: `rules.md` "Language Application".
 
 **Model fallback date gate** (same step, once per run): read `prefs.global.modelFallback`. If `premiumTierUntil` is set and in the past, apply the date-gate trigger from `$HOME/.claude/multi-agent-refs/features/model-fallback.md` - `preferredModel` personas dispatch on `fallbackModel` for this run, with the one-line WARN. Dispatch-error and budget triggers in that contract apply per-dispatch later; nothing else to do here.
 
@@ -238,6 +238,8 @@ Scan `$HOME` (maxdepth 2) for project markers (`.xcodeproj`, `Package.swift`, `b
 - After selection, if the chosen set matches an existing `recentGroups` entry, bump `count` + `lastUsed`. If it's a new combination of ≥2 repos, ask with a native `AskUserQuestion` picker (`question`: "Save this repo combo as a reusable multi-repo group?" in `outputLanguage`; `header`: "Save"; `options`: `{ label: "Save", ... }`, `{ label: "Skip", ... }`)  -  on **Save**, prepend to `recentGroups` (LRU cap 10).
 - Single-repo selection (1 repo) → legacy single-repo path; `state.projects[]` is omitted, scalars are populated as before.
 
+**Test policy (once per project).** Resolve `prefs.projects[{slug}].testPolicy` → `state.testPolicy`; missing → native picker "Should development write tests here?" (`header`: "Tests"): `tdd` (recommended) / `tests-after` / `none`; persist. Autopilot without a record: `tdd`, noted.
+
 #### Step 3  -  Remote Detection + Branch Selection
 
 1. **Check preferences first**: If `prefs.projects[{project}].remoteType` exists, use cached value.

package/pipeline/multi-agent-refs/phases/phase-3-dev.md

@@ -38,7 +38,7 @@ Pre-flight steps (run in order, abort on failure).
 
    `targetFiles` is required  -  without it a skill applied to the wrong files still reads as "applied". Append at the moment of consultation, not at the end of the phase. Phase 4 Step 1.78 treats this as self-report only and resolves criteria independently; it is the one signal separating "applied to the wrong files" from "never opened".
 
-9. **Stack skill routing (every `taskType`, when a stack toolkit plugin is enabled)**: ask the enabled `ai-<platform>-toolkit`'s own `index` skill which skills govern this task, load them BEFORE writing code, and record each into `state.telemetry.skillCalls[]` with `routedBy: "<toolkit>:index@<version>"`. The routing table stays in the plugin  -  a copy here would be the stale one. No toolkit, or none enabled, is a recorded no-op, not a halt. Contract: [`features/stack-skill-routing.md`]($HOME/.claude/multi-agent-refs/features/stack-skill-routing.md).
+9. **Stack skill routing (every `taskType`, when a stack toolkit plugin is enabled)**: ask the routed stack toolkit's own `index` skill which skills govern this task, load them BEFORE writing code, and record each into `state.telemetry.skillCalls[]` with `routedBy: "<toolkit>:index@<version>"`. The routing table stays in the plugin  -  a copy here would be the stale one. A screen-creation task loads the routed toolkit's `workflow/create-screen` when one exists. No toolkit, or none enabled, is a recorded no-op, not a halt. Contract: [`features/stack-skill-routing.md`]($HOME/.claude/multi-agent-refs/features/stack-skill-routing.md).
 
 The analysis document is the SOLE design source in Phase 3. Variant choices, padding values, color tokens, copy strings, accessibility identifiers, and test method names all come from the rendered Pass B cells. If something is missing in the analysis doc, the fix is to re-run `/multi-agent:analysis`, not to fetch from Figma.
 
@@ -112,7 +112,7 @@ For each task (respecting dependency order):
    - New types/tokens in the **common** submodule
    - The component itself in the **uicomponents** submodule
    - Work in BOTH submodules in the same task  -  this is normal and expected
-3. **TDD cycle** (Launch Agent with `model: "sonnet"`):
+3. **TDD cycle** (Launch Agent with `model: "sonnet"`)  -  gated by `state.testPolicy`: `tdd` = the loop below; `tests-after` = skip RED, author the same tests once green; `none` = author no tests (existing ones never weakened), report "tests not written - project policy" rather than a gap.
 
    **RED  -  Write ONE failing test first:**
    - **Rework re-entry**: if `state.reviewIterations[-1].verifyByTest.redTests[]` exists (Phase 4 Step 3.7 ran), those failing repro tests ARE the RED step for their findings  -  make them green, do not write a duplicate failing test and do not delete or weaken them. See `$HOME/.claude/multi-agent-refs/features/verify-by-test.md`.

package/pipeline/multi-agent-refs/phases/phase-5-test.md

@@ -7,7 +7,7 @@ Progress emission per `$HOME/.claude/multi-agent-refs/progress-contract.md`  -
 
 #### Step 0  -  Test Gap Report (advisory)
 
-Before the local-checkout prompt, run the static test-gap detector. Heuristic, deterministic, no LLM, sub-second. The report ends up in `agent-log.md` under "Test Scenarios" and surfaces public symbols added in this branch that have no paired test.
+`state.testPolicy: none` → skip the gap scan (the gap IS the recorded policy) and run only pre-existing test targets; none → recorded no-op. Otherwise, before the local-checkout prompt, run the static test-gap detector. Heuristic, deterministic, no LLM, sub-second. The report ends up in `agent-log.md` under "Test Scenarios" and surfaces public symbols added in this branch that have no paired test.
 
 ```bash
 STACK=$(jq -r '.analysis.stack.primary // "unknown"' "$STATE_FILE")

package/pipeline/multi-agent-refs/refactor/dev-toolkit-research.md

@@ -0,0 +1,72 @@
+# Dev-Toolkit Research (refactor Step 0c)
+
+Loaded on demand by `/multi-agent:refactor` Step 0c. The SKILL.md carries the step intro; this file is the full procedure.
+
+**Resolution**  -  configuration first, never a hardcoded path:
+
+1. `prefs.global.devToolkit` in `~/.claude/multi-agent-preferences.json`:
+
+```jsonc
+{
+  "enabled": true,
+  "label": "<human name>",
+  "localPath": "$HOME/<repo-dir>",              // the companion repo working copy
+  "mcpServerName": "<registered MCP server name>",
+  "packageName": "@<scope>/<package>",
+  "registry": "github-packages",                 // github-packages | npmjs | none
+  "repoUrl": "https://github.com/<owner>/<repo>"
+}
+```
+
+2. If unset, auto-detect from the MCP registration: read `mcpServers` in `~/.claude.json` (including each `projects[*].mcpServers`) and in `~/.claude/settings.json`; for a stdio entry whose command is `node`, take `dirname(args[0])`. Accept it only when that directory is a git repo whose `package.json` depends on `@modelcontextprotocol/sdk`.
+3. If neither resolves, skip this step and report "no dev-toolkit configured". Never guess a path, never clone.
+4. `enabled: false` skips the step.
+
+**Research axes**  -  a finding without a source link is not a finding:
+
+| # | Axis | Where to look | What to extract |
+|---|------|---------------|-----------------|
+| 1 | MCP protocol | spec revisions + `@modelcontextprotocol/sdk` releases | protocol features released since the pinned SDK range that the server does not use yet: tool annotations (`readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`), `outputSchema` + structured content, resource links in results, progress + cancellation, `tools/list_changed`, pagination, elicitation |
+| 2 | Host clients | Claude Code / Copilot CLI / Cursor / Antigravity docs + release notes | per-tool description budget, tool-count ceilings, naming conventions, image and output size limits, permission / allowlist ergonomics |
+| 3 | Peer servers | GitHub search on the same domain terms + `stars:>50` | tool surfaces we lack, conventions peers converged on, and what to discard as out of scope |
+| 4 | Wrapped tooling | `xcrun simctl help`, `idb`, `adb`, `xcodebuild`, Playwright release notes, Apple ITMS + App Store Review Guidelines | deprecated flags still in use, new capabilities worth a tool, audit rules that changed |
+| 5 | Field practice | X / Twitter, Reddit, MCP community threads | what server authors actually changed recently (transport choice, output-token diets, sandboxing, error shape) |
+
+**Audit the toolkit against the findings**  -  run the checks, do not assume:
+
+```bash
+DT="<resolved localPath>"
+node --check "$DT/index.js"
+find "$DT/tools" -name "*.js" -type f -exec node --check {} \;
+
+# stdout carries the JSON-RPC frames: a stray stdout write corrupts the stream
+grep -rn "console\.log(" "$DT/index.js" "$DT/tools" || echo "stdout clean"
+
+# advertised tool counts vs reality (README header + package.json description)
+grep -nE "[0-9]+ tools" "$DT/README.md" "$DT/package.json"
+
+# packaging: every runtime directory must be inside files[]
+node -p "require('$DT/package.json').files.join('\n')"
+ls -d "$DT"/tools/*/
+
+cd "$DT" && npm outdated; npm audit --omit=dev 2>/dev/null | tail -20
+```
+
+Also check: every tool carries a description and an `inputSchema`; token-heavy results (screenshots, UI trees, logs) are truncated or written to a file path instead of inlined; failures return an error result with an actionable message instead of throwing; `engines.node` matches what the SDK needs; `CHANGELOG.md`, a CI workflow and a test harness exist.
+
+Output (plan band E):
+
+```
+| # | Axis | Finding | Source | Adaptation in the toolkit (file) | Effort | Impact | In plan? |
+|---|------|---------|--------|----------------------------------|--------|--------|----------|
+| 1 | Protocol | read-only tools carry no annotations | <spec link> | add `annotations` to the read-only tools in index.js | Low | Medium | Yes (P1) |
+| 2 | Wrapped tooling | uses a simctl flag removed in Xcode <v> | <release notes> | switch tools/<family>/<file>.js to <new flag> | Low | High | Yes (P0) |
+| 3 | Peer servers | peer exposes <surface> | <repo link> | does not fit: outside the pipeline's phases | - | - | No |
+```
+
+Rules for this band:
+
+- Band-E work lands in the toolkit repo, never mirrored into this one. Shipping it is `/multi-agent:sync` Step 3d.
+- A finding that changes the tool surface (new / renamed / removed tool) pairs with a pipeline-side item: bump the minimum toolkit version wherever a pipeline skill declares one.
+- If the current working directory IS the toolkit repo, skip band E and let bands A/B/C cover it  -  never report the same finding twice.
+

package/pipeline/multi-agent-refs/setup/app-store-connect.md

@@ -0,0 +1,54 @@
+# App Store Connect Onboarding (setup Step 3b)
+
+Loaded on demand by `/multi-agent:setup` Step 3b (iOS only, optional). The SKILL.md carries the step intro; this file is the full flow.
+
+Runs inside Step 3 alongside the other missing credentials, not as a late add-on:
+a user who already has an App Store Connect credential in their keychain gets it
+mapped by Step 1 discovery like any other token, and only the genuinely missing
+pieces reach this flow.
+
+Three of the four entries do not go through the normal Token Save Flow, because
+what they hold is not a pasteable secret:
+
+| Entry | Holds | Flow |
+|---|---|---|
+| `appstore_connect_key_id` | an identifier | plain value, not a secret; still mapped so it is read through the mapping layer |
+| `appstore_connect_issuer_id` | an identifier | same |
+| `appstore_connect_apple_id` | an email address | same |
+| `appstore_connect_password_item` | a keychain ITEM NAME | the password lives in Apple's own keychain item, referenced as `-p @keychain:<item>` and never read by the pipeline |
+
+Ask which tier to configure (picker): **API key** / **Apple ID + app-specific
+password** / **Skip**. Lead with the second when the user says they cannot create
+an API key.
+
+**API key.** The private key is a FILE and is never copied into the credential
+store. It must sit in a directory `altool` already searches:
+
+```bash
+ls ~/.appstoreconnect/private_keys/AuthKey_*.p8 2>/dev/null \
+  || echo "MISSING: put AuthKey_<keyId>.p8 in ~/.appstoreconnect/private_keys/"
+```
+
+**Apple ID + app-specific password.** Use Apple's own keychain helper. The secret
+never enters chat and never becomes a shell argument, per the Token Save Flow rule:
+
+```bash
+# the user exports AC_PASSWORD_ONCE in their own shell, for this one command
+xcrun altool --store-password-in-keychain-item "<item-name>" \
+  -u "<apple-id>" -p @env:AC_PASSWORD_ONCE
+```
+
+Then map only `<item-name>` as `appstore_connect_password_item`.
+
+**Multi-provider accounts.** A corporate Apple ID often belongs to several
+providers, and `altool` fails opaquely without one. Resolve it once with
+`ios_testflight_validate({list_providers: true, <credentials just configured>})`
+and store the answer under
+`prefs.projects[<key>].appStoreConnect.providerPublicId`  -  per-project, since a
+user can ship for more than one team.
+
+**Verify + expiry.** Re-run the `list_providers` probe and report the resolved
+tier. A credential that resolves but is rejected (401/403) follows the
+Expired-token decision in `refs/keychain.md` Rule 1  -  Regenerate / Use a
+different token / Skip and continue  -  never a silent drop.
+

package/pipeline/multi-agent-refs/tracker-contract.md

@@ -142,7 +142,7 @@ Mode-specific phase sets:
 
 Note: in `--dev` modes the omitted phases (1, 2  -  plus 5 in the autopilot/local variants) **do not get TaskCreate calls at all**  -  they're not part of the mode's phase set. Phase 4 is in every mode's set as of v14.0.0, so it is always registered. The "[SKIPPED]" pattern above only applies if a phase that IS in the set is conditionally skipped at runtime. The authoritative per-mode set is the `for p in ...` init block in each mode's own entry doc, generated by `gen-mode-dispatch.mjs`; this table mirrors those blocks.
 
-**Enforcement**: `smoke-tasklist-ordering.sh` scans every mode entry point doc (`commands/multi-agent.md`, `commands/multi-agent/{autopilot,local,local-autopilot,dev,dev-autopilot,dev-local,dev-local-autopilot}.md` + Copilot mirrors) for the explicit "in phase-number order" rule. Inventory drift fails the smoke.
+**Enforcement**: `smoke-tasklist-ordering.sh` scans the dispatcher (`commands/multi-agent/SKILL.md`) and every mode entry point doc (`commands/multi-agent/{dev,autopilot,local,local-autopilot,dev-autopilot,dev-local,dev-local-autopilot,resume-local}/SKILL.md` + the Copilot full-inline orchestrator mirror) for the explicit "in phase-number order" rule. Inventory drift fails the smoke.
 
 ### Other CLIs  -  call render after every state change
 

package/pipeline/preferences-template.json

@@ -94,6 +94,7 @@
     }
   },
   "projects": {},
+  "_projectsComment": "Per-project overrides by slug. Notable: testPolicy (tdd | tests-after | none) - how the dev phase authors tests; asked once by Phase 0 when absent.",
   "_figmaConfigTemplate": {
     "_comment": "Copy this to ~/.claude/projects/{slug}/figma-config.json and fill in values. See pipeline/schemas/figma-project-config.schema.json for full schema.",
     "schemaVersion": "1.0.0",

package/pipeline/schemas/prefs.schema.json

@@ -1545,6 +1545,11 @@
           "type": "object",
           "additionalProperties": false,
           "properties": {
+            "testPolicy": {
+              "type": "string",
+              "enum": ["tdd", "tests-after", "none"],
+              "description": "How Phase 3 authors tests in this project: tdd (default; failing test first), tests-after (implementation first, tests authored at the end), none (no unit/UI test authoring; existing tests are kept and run). Asked once by Phase 0 when absent; autopilot defaults to tdd and notes it."
+            },
             "defaultReviewers": {
               "type": "array",
               "items": {

package/pipeline/schemas/token-budget.json

@@ -36,6 +36,6 @@
       "warn_tokens": 5600
     }
   },
-  "total_max_tokens": 53100,
+  "total_max_tokens": 53350,
   "note": "Token estimate = ceil(chars / 4). Per-phase budget rule: warn = current+10% (rounded to nearest 50), max = current+25%. Gives ~6 edit cycles of headroom before warn trips  -  intentionally quiet under normal maintenance, loud when a phase grows unusually. Only the active phase is loaded (lazy). Recalibrated at v10.0.0 after the validator/consistency/simplifier/lesson gate contracts landed in phases 1-4. Recalibrated again at v10.9.0 after the verify-by-test (Phase 4 Step 3.7), update-check (Phase 0 Step 0.6), immutable-test (Phase 3 GREEN) and redTests re-entry contracts landed  -  Step 3.7 prose was compressed to a pointer into refs/features/verify-by-test.md before the recalibration. Total bumped 50000 -> 51000 at v12.5.0 after the worktree residue/traversal-prune contract (Phase 0 + Phase 5 heal) and the Reflexion causal-diagnosis contract (Phase 4 lesson memory) landed; the prose was compressed first (161 tokens reclaimed) and every per-phase max still passes  -  only the aggregate needed room. Recalibrated again at v13.6.0 after the install-relative path correction: an instruction that names `pipeline/scripts/x` resolves only from a repo checkout, and a run happens in the user's worktree, so 157 references across these docs moved to `$HOME/.claude/...` at +5 bytes each  -  196 tokens of pure correctness cost. Same discipline as before: prose was compressed FIRST (149 tokens reclaimed, by pointing Phase 1's Figma tier table at the Phase 0 probe that already resolved it and Phase 4's Codex constraints at the always-loaded AGENTS.md block), and only then were the budgets moved. Five warn lines had been permanently amber, which makes the amber tier useless as a signal, so every warn was reset to the documented current+10% and the four maxes that the new warn would have collided with were reset to current+25%. Aggregate 51000 -> 51500. Total bumped 51500 -> 52200 at v14.0.0 after Phase 4 Review entered the four --dev mode phase sets and the criteria-resolution contract (Step 1.78) landed. Same discipline as every prior bump: prose was compressed FIRST, 820 tokens reclaimed, before the number moved. Two of those compressions are structural rather than cosmetic - the hardcoded SwiftUI interaction list in Step 1.5 and the SwiftUI convention paragraph in Step 2.8 were transcriptions of rules that now live in a scoped registry, so keeping them here would have re-created the drift this release exists to remove, and the third moved the Step 1.78 full contract into refs/features/skill-conformance.md leaving a pointer. What remains is contract text that cannot be inferred: the manifest's four consumer-visible parts, the conformance checklist the reviewers must return, and the fail-closed semantics. Every per-phase max still passes (phase-4 12405/14750); only the aggregate needed room. Total bumped 52200 -> 52700 at v14.1.0 after two more contracts landed: stack skill routing (Phase 3 pre-flight step 9) and worktree finalize (Phase 6 step 9). Compression came first, as always, and twice: 224 tokens out of Phase 3 by pointing its criteria-ledger and routing steps at their feature files instead of restating them, and 190 out of Phase 6 by moving the finalize contract into refs/features/worktree-finalize.md and leaving the invocation plus the exit-3 semantics. Both new contracts follow the pattern the earlier ones set: the phase doc carries the call and the decision, the feature file carries the reasoning, and the feature files are outside this budget because it loops only the eight phase-N-* keys. Every per-phase max still passes (phase-3 7677/8950, phase-6 5223/6150 and both under warn); only the aggregate needed room. Total bumped 52700 -> 52750 for the Phase 0 Step 3 branch-persistence correction: the step wrote the legacy `projects[].branches` while the TTL filter two sections below read `global.recentBranches`, and both spots named a `{name, lastUsed}` shape the schema rejects (`branch` required, `additionalProperties: false`), so the recent-branch picker option could never populate and a literal implementation would have failed prefs validation. Naming the right target, the right key and the legacy field to avoid costs 41 tokens over the one line it replaces. Compression came first and was applied three times to the replacement text itself, from 120 tokens down to 66, by moving the rationale out of the phase doc entirely: the reasoning now lives where it is enforced, in the migrate-prefs carry-forward comment and the smoke-pref-migration f7 block, leaving the phase doc with only the instruction. 50 was the smallest step that clears it; phase-0-init sits at 10893/12400, far under its own max, so this is purely an aggregate ceiling. v15.0.0: total 52750 -> 53100, the stack-skill tables in phase-1/2/4 now carry plugin-namespaced names (ai-<stack>-toolkit:<skill>) - functional prefixes, ~170 tokens."
 }

package/pipeline/skills/shared/core/multi-agent/SKILL.md

@@ -28,7 +28,7 @@ If user gives wrong format for the project, warn:
 
 ## Input Parsing
 
-Classify user input into one of 5 types (matches the colon-form `multi-agent.md` contract; cross-CLI parity is enforced by `smoke-cross-cli-behavior.sh`):
+Classify user input into one of 5 types (matches the `commands/multi-agent/SKILL.md` dispatcher contract; cross-CLI parity is enforced by `smoke-cross-cli-behavior.sh`):
 
 | # | Pattern | Type | Action |
 |---|---------|------|--------|

package/pipeline/skills/shared/core/multi-agent-refactor/SKILL.md

@@ -114,73 +114,7 @@ Procedure:
 
 The pipeline's hands on devices and browsers are MCP tools served by a companion repo (`dev-toolkit-mcp`): Phase 5 test, `manual-test`, `design-check` and `apple-archive-compliance` all call them, and several pipeline skills declare a minimum toolkit version (see `cross-cli-contract.md`). That repo therefore has to track the MCP field, not just its own README. This step researches what current practice is and audits the toolkit against it.
 
-**Resolution**  -  configuration first, never a hardcoded path:
-
-1. `prefs.global.devToolkit` in `~/.claude/multi-agent-preferences.json`:
-
-```jsonc
-{
-  "enabled": true,
-  "label": "<human name>",
-  "localPath": "$HOME/<repo-dir>",              // the companion repo working copy
-  "mcpServerName": "<registered MCP server name>",
-  "packageName": "@<scope>/<package>",
-  "registry": "github-packages",                 // github-packages | npmjs | none
-  "repoUrl": "https://github.com/<owner>/<repo>"
-}
-```
-
-2. If unset, auto-detect from the MCP registration: read `mcpServers` in `~/.claude.json` (including each `projects[*].mcpServers`) and in `~/.claude/settings.json`; for a stdio entry whose command is `node`, take `dirname(args[0])`. Accept it only when that directory is a git repo whose `package.json` depends on `@modelcontextprotocol/sdk`.
-3. If neither resolves, skip this step and report "no dev-toolkit configured". Never guess a path, never clone.
-4. `enabled: false` skips the step.
-
-**Research axes**  -  a finding without a source link is not a finding:
-
-| # | Axis | Where to look | What to extract |
-|---|------|---------------|-----------------|
-| 1 | MCP protocol | spec revisions + `@modelcontextprotocol/sdk` releases | protocol features released since the pinned SDK range that the server does not use yet: tool annotations (`readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`), `outputSchema` + structured content, resource links in results, progress + cancellation, `tools/list_changed`, pagination, elicitation |
-| 2 | Host clients | Claude Code / Copilot CLI / Cursor / Antigravity docs + release notes | per-tool description budget, tool-count ceilings, naming conventions, image and output size limits, permission / allowlist ergonomics |
-| 3 | Peer servers | GitHub search on the same domain terms + `stars:>50` | tool surfaces we lack, conventions peers converged on, and what to discard as out of scope |
-| 4 | Wrapped tooling | `xcrun simctl help`, `idb`, `adb`, `xcodebuild`, Playwright release notes, Apple ITMS + App Store Review Guidelines | deprecated flags still in use, new capabilities worth a tool, audit rules that changed |
-| 5 | Field practice | X / Twitter, Reddit, MCP community threads | what server authors actually changed recently (transport choice, output-token diets, sandboxing, error shape) |
-
-**Audit the toolkit against the findings**  -  run the checks, do not assume:
-
-```bash
-DT="<resolved localPath>"
-node --check "$DT/index.js"
-find "$DT/tools" -name "*.js" -type f -exec node --check {} \;
-
-# stdout carries the JSON-RPC frames: a stray stdout write corrupts the stream
-grep -rn "console\.log(" "$DT/index.js" "$DT/tools" || echo "stdout clean"
-
-# advertised tool counts vs reality (README header + package.json description)
-grep -nE "[0-9]+ tools" "$DT/README.md" "$DT/package.json"
-
-# packaging: every runtime directory must be inside files[]
-node -p "require('$DT/package.json').files.join('\n')"
-ls -d "$DT"/tools/*/
-
-cd "$DT" && npm outdated; npm audit --omit=dev 2>/dev/null | tail -20
-```
-
-Also check: every tool carries a description and an `inputSchema`; token-heavy results (screenshots, UI trees, logs) are truncated or written to a file path instead of inlined; failures return an error result with an actionable message instead of throwing; `engines.node` matches what the SDK needs; `CHANGELOG.md`, a CI workflow and a test harness exist.
-
-Output (plan band E):
-
-```
-| # | Axis | Finding | Source | Adaptation in the toolkit (file) | Effort | Impact | In plan? |
-|---|------|---------|--------|----------------------------------|--------|--------|----------|
-| 1 | Protocol | read-only tools carry no annotations | <spec link> | add `annotations` to the read-only tools in index.js | Low | Medium | Yes (P1) |
-| 2 | Wrapped tooling | uses a simctl flag removed in Xcode <v> | <release notes> | switch tools/<family>/<file>.js to <new flag> | Low | High | Yes (P0) |
-| 3 | Peer servers | peer exposes <surface> | <repo link> | does not fit: outside the pipeline's phases | - | - | No |
-```
-
-Rules for this band:
-
-- Band-E work lands in the toolkit repo, never mirrored into this one. Shipping it is `/multi-agent:sync` Step 3d.
-- A finding that changes the tool surface (new / renamed / removed tool) pairs with a pipeline-side item: bump the minimum toolkit version wherever a pipeline skill declares one.
-- If the current working directory IS the toolkit repo, skip band E and let bands A/B/C cover it  -  never report the same finding twice.
+Full procedure  -  resolution (configuration first, never a hardcoded path; skip when nothing resolves or `enabled` is false), the 5 research axes, the audit command block, and the band-E output table + rules  -  lives in `$HOME/.claude/multi-agent-refs/refactor/dev-toolkit-research.md`. Read it before running this step.
 
 ## Step 0d: RUN-ERRORS  -  what the pipeline actually failed on
 

package/pipeline/skills/shared/core/multi-agent-sync/SKILL.md

@@ -18,7 +18,7 @@ When invoked, it synchronizes all targets in order. It detects what changed, upd
 
 | # | Target | Path | Direction |
 |---|-------|-----|-----|
-| 1 | Claude Code (source of truth) | `~/.claude/commands/multi-agent.md` + `~/.claude/commands/multi-agent/` + `~/.claude/agents/` + `~/.claude/scripts/` | source |
+| 1 | Claude Code (source of truth) | `~/.claude/commands/multi-agent/` + `~/.claude/multi-agent-refs/` + `~/.claude/agents/` + `~/.claude/scripts/` + `~/.claude/lib/` | source |
 | 2 | Copilot CLI | `~/.copilot/copilot-instructions.md` + `~/.copilot/skills/` | <- from Claude |
 | 2b | Codex CLI | `~/.codex/AGENTS.md` + `~/.codex/skills/multi-agent/` + `~/.codex/multi-agent-refs/` + `~/.codex/agents/*.toml` | <- from Claude (path-rewritten) |
 | 3 | multi-agent-pipeline repo | `~/multi-agent-pipeline/pipeline/` | <- from Claude (genericized) |
@@ -56,7 +56,7 @@ If nothing is stale -> report "All targets up to date" and stop.
 
 1. **Read first**  -  Understand the current state of all targets before making changes
 2. **Preserve file structure**  -  Each target has its own format:
-   - `multi-agent.md` + phases/: detailed pipeline spec (frontmatter, phases, routing)
+   - `commands/multi-agent/` SKILL tree + `multi-agent-refs/phases/`: detailed pipeline spec (frontmatter, phases, routing)
    - `copilot-instructions.md`: general development instructions + pipeline summary section
    - `multi-agent-pipeline/pipeline/`: generic open-source version (NO personal data)
 3. **Sync shared sections** (Claude <-> Copilot):
@@ -71,7 +71,7 @@ If nothing is stale -> report "All targets up to date" and stop.
 
 ## Pipeline Repo Sync Rules (CRITICAL)
 
-1. **Source**: `~/.claude/commands/multi-agent.md` + `~/.claude/commands/multi-agent/` + `~/.claude/agents/`
+1. **Source**: `~/.claude/commands/multi-agent/` + `~/.claude/multi-agent-refs/` + `~/.claude/agents/` + `~/.claude/lib/`
 2. **Target**: `~/multi-agent-pipeline/pipeline/`
 3. **Genericization** (must be applied BEFORE writing to the target):
    - Jira project key (`prefs.global.defaultJiraKey`) -> `{JIRA_KEY}`, `PROJ` in examples
@@ -82,8 +82,8 @@ If nothing is stale -> report "All targets up to date" and stop.
    - **Verify**: scan for personal/corporate data inside pipeline/ with `grep` -> 0 results
 4. **File mapping**:
    ```
-   ~/.claude/commands/multi-agent.md      -> pipeline/commands/multi-agent.md
    ~/.claude/commands/multi-agent/        -> pipeline/commands/multi-agent/
+   ~/.claude/multi-agent-refs/            -> pipeline/multi-agent-refs/   (refs + pickers, non-command)
    ~/.claude/commands/sim-test.md         -> pipeline/commands/sim-test.md
    ~/.claude/agents/*.md                  -> pipeline/agents/
    ```

package/pipeline/skills/shared/external/ios-coding-standard/references/rules.yml

@@ -1,4 +1,4 @@
-version: 1.1.0
+version: 1.2.0
 updated: 2026-07-29
 owner: iOS platform
 description: >
@@ -454,9 +454,11 @@ rules:
     enforcement: lint
     rationale: readability
     check: >
-      Scene, ViewModel, LocalizedText, CoordinatorEvent, AnalyticsTracking, UseCase, Repository
-      (+protocol +mock), Mapper + models  -  each present when its responsibility exists. Report a
-      missing file whose responsibility leaked elsewhere AND a ceremonial empty file.
+      Scene, ViewModel, AnalyticsTracking, UseCase, Repository (+protocol +mock), Mapper +
+      models  -  each present when its responsibility exists. In a converted module the screen's
+      Output enum lives contract-side, not here, and a module-local CoordinatorEvent or
+      LocalizedText aggregator is pre-conversion residue reported as debt. Report a missing file
+      whose responsibility leaked elsewhere AND a ceremonial empty file.
 
   - id: STRUCT-03
     title: Every screen sits at the same depth with the same internal grouping
@@ -509,11 +511,12 @@ rules:
       not a defect.
     check: >
       What this rule protects is that a reader finds a screen's exits under ONE name across the
-      module, not that a particular name wins. Both shapes in use are legitimate: a typed
-      `CoordinatorEvent` enum with a handler alias, or an `Output` enum with a closure. Each
-      enumerates every navigation exit in one place, which is the property that matters.
-      The finding is a module that uses both, or a screen whose exits are spread across an enum
-      and loose ad-hoc callbacks. Report the spelling per screen and the count of each.
+      module. The settled shape is an `Output` enum consumed through a plain closure, with the
+      enum living in the flow-contracts target. A `CoordinatorEvent` enum with a handler alias
+      is the pre-conversion spelling: legitimate only in a module that has not converted yet, a
+      debt finding in one that has, and never a choice for new code. The hard finding is a module
+      that uses both, or a screen whose exits are spread across an enum and loose ad-hoc
+      callbacks. Report the spelling per screen and the count of each.
 
   - id: NAME-02
     title: Our models use RequestModel/ResponseModel; transport suffixes stop at the data layer
@@ -1815,3 +1818,70 @@ rules:
       accept_from_vocabulary: IndexLabel
     rationale: readability
     check: One spelling for "at this position" across the module; two make the call sites read as two concepts.
+
+  # ── UNIT  -  the settled screen dialect ────────────────────────────────────
+  - id: UNIT-01
+    title: A new screen's view model is the unit type, never the deprecated scene base
+    severity: blocking
+    enforcement: scan
+    mechanism: >
+      grep the diff's ADDED files for a subclass of the deprecated pre-unit scene base; grep the
+      declaration of the unit generic (ViewModel<) for the four type parameters.
+    rationale: flexibility
+    check: >
+      The unit dialect  -  ViewModel<State, ViewAction, Action, Output> with explicit conformer
+      typealiases  -  is the only legal shape for new screen code. The pre-unit base class is
+      deprecated at its declaration; existing screens convert on touch, and that migration is its
+      own work. The finding is a NEW file building on the deprecated base, or a unit view model
+      missing its typealias block (the all-compiler-version spelling).
+
+  - id: UNIT-02
+    title: Unit state is written only inside the reducer
+    severity: important
+    enforcement: scan
+    mechanism: 'custom regex: assignments to the unit state outside next(_:on:) in ViewModel files'
+    rationale: readability
+    check: >
+      The unit's state moves in one place  -  the reducer  -  so a reader replays a screen's
+      behaviour from a single function. A state write from an action handler, a task body or a
+      view callback bypasses that replay and is the finding, wherever it compiles.
+
+  - id: UNIT-03
+    title: Dependencies are observation-ignored, defaulted parameters
+    severity: important
+    enforcement: lint
+    mechanism: 'custom regex: stored service/use-case/analytics properties in view models'
+    rationale: flexibility
+    check: >
+      Every dependency is an @ObservationIgnored stored property injected as an init parameter
+      whose default resolves from the container. Tests then inject doubles with no container
+      setup, and observation never tracks a service handle. A dependency resolved inline at the
+      call site, or a stored property observation can see, is the finding.
+
+  - id: SAFE-03
+    title: A field reset that must erase the value writes the value before clear()
+    severity: important
+    enforcement: scan
+    mechanism: 'custom regex: .clear() on a form field with no value write in the surrounding statement group'
+    rationale: flexibility
+    check: >
+      The shared form field's clear() resets STATE only  -  the value survives it. Every reset
+      path that must also erase what was typed (switching an entry method, finishing a secure
+      flow, leaving a screen that held credentials) writes value = "" (a picker: deselect())
+      first, then clear(), in that order  -  the value write may fire a validation policy and the
+      trailing clear() leaves the field pristine. A bare clear() on such a path has shipped
+      stale identifiers and surviving passwords before; treat it as the finding unless the reset
+      demonstrably must keep the value.
+
+  - id: MOD-08
+    title: Screens bind the shared formatters and rule facades; a hand-rolled one is a finding
+    severity: important
+    enforcement: scan
+    mechanism: 'custom regex: DateFormatter(/NumberFormatter( construction and digit/dial-code string surgery inside Screens/**'
+    rationale: flexibility
+    check: >
+      Dates, money, grouped amounts, dial-code spellings and validation bounds each have one
+      shared home  -  the core formatter families and the module's form-rules facade. A screen
+      that constructs its own formatter or re-derives a bound duplicates a wire contract that
+      already has an owner, and the copies drift apart silently. The finding is the construction
+      site; the fix is binding, not re-deriving.

package/pipeline/skills/shared/external/ios-module-structure/SKILL.md

@@ -73,3 +73,24 @@ surface has not chosen a different dialect, it is missing the surface, so that s
 
 The test when you are tempted to add one: can you write the second value's paragraph without it
 reading as an excuse? If not, it is a rule.
+
+## Multi-target packages
+
+A domain that outgrows one target splits into one target per flow inside a single package, and
+the tree rules then apply PER TARGET. What the shape adds, and what the overlay binds for it:
+
+- `screen.root` binds with a leading `Sources/*/` so every target's `Screens/` is walked; a
+  target with no screens simply matches nothing.
+- Each screen-bearing target carries its own dependency configurator - registration, validation
+  pins, and the store entry the composition root aggregates - bound as `target.configurator`
+  and proven by STRUCT-21. Registration lives with the target, never pooled in a sibling.
+- The flow-contracts side mirrors the split: one contracts sub-folder per target, named
+  `<Module><Target>FlowContracts`-style, under the module's contracts target
+  (`contracts.root` + STRUCT-18 prove each screen's pair).
+- A scaffold target - empty configurator, a route enum with an empty destination switch, no
+  screens yet - is a legitimate recorded state, not a finding: it reserves the flow's seams so
+  the first screen lands as a fill-in, not a redesign.
+- Tests mirror per target (`Tests/<Target>Tests/`), so the source/test mirror is a set of
+  prefix pairs; a single-swap `source.root`/`test.root` binding cannot express it and stays
+  unbound until the checker learns per-target templates.
+

package/pipeline/skills/shared/external/ios-module-structure/modules/_TEMPLATE.yml

@@ -79,6 +79,13 @@ dialect:
 # Leave a role empty when the module genuinely has no such thing - the rules that read it are then
 # reported as lost coverage, which is the honest answer.
 roles:
+#  Unit-dialect vocabulary (bind when UnitDialect is adopted):
+#    screen.viewstate:        "Presentation/Models/*ViewState.swift"
+#    screen.viewaction:       "Presentation/Models/*ViewAction.swift"
+#    screen.viewmodelaction:  "Presentation/Models/*ViewModelAction.swift"
+#    screen.viewmodelstate:   "Presentation/Models/*ViewModelState.swift"
+#  Multi-target packages (STRUCT-21):
+#    target.configurator:     "Sources/*/Configuration/*DependencyConfigurator.swift"
   screen.root: # e.g. "Sources/*/Screens/*"
   screen.entry:
   screen.viewmodel:
@@ -110,6 +117,20 @@ vocabulary:
   BareVerbs: [] # verbs a presentation type may not use alone
   ForbiddenTypeSuffixes: [] # last words that describe no role
 
+#  UnitDialect: adopted | pre-unit
+#    Count view models subclassing the unit generic vs the deprecated pre-unit base.
+#    pre-unit is a RECORDED migration state, reported as debt - a new module binds adopted.
+
+# --- Contracts ---------------------------------------------------------
+# Only for a CONVERTED module whose screens are reached through a flow-contracts target.
+# root is relative to the module root; leave the whole block out for a pre-conversion module
+# and STRUCT-18 reports lost coverage instead of guessing. Bind the two contract roles under
+# roles: with {screen}-substituted patterns, e.g.
+#   contracts.output:    "{screen}Output.swift"
+#   contracts.providing: "{screen}ScreenProviding.swift"
+contracts: {}
+#  root: ../../CrossDomains/Contracts/Sources/<Module>FlowContracts
+
 # --- Limits ------------------------------------------------------------
 limits:
   source_target:

package/pipeline/skills/shared/external/ios-module-structure/references/rules.yml

@@ -1,5 +1,5 @@
-version: 0.1.0
-updated: 2026-08-13
+version: 0.3.0
+updated: 2026-08-18
 owner: iOS platform
 description: >
   The ios-module-structure rule registry. Where a declaration lives, what its file is called, and what
@@ -61,10 +61,30 @@ roles:
     description: the type holding the screen's behaviour and service calls.
   screen.state:
     description: the type holding the screen's UI state, when the module separates it from the view model.
+  screen.viewstate:
+    description: the unit dialect's view-facing state value, one declaration per file.
+  screen.viewaction:
+    description: the unit dialect's view-action vocabulary, one declaration per file.
+  screen.viewmodelaction:
+    description: the unit dialect's own-action vocabulary, one declaration per file.
+  screen.viewmodelstate:
+    description: the unit dialect's reducer-owned state, one declaration per file.
+  target.configurator:
+    description: >
+      a screen-bearing target's dependency configurator - the registration + validation home a
+      multi-target package carries once per target.
   screen.analytics:
     description: the screen's analytics surface.
   screen.factory:
     description: the seam another module calls to build the screen.
+  contracts.output:
+    description: >
+      the screen's Output enum in the module's flow-contracts target - every navigation exit,
+      nothing else. Lives OUTSIDE the module tree; the overlay's contracts.root names where.
+  contracts.providing:
+    description: >
+      the screen's vending seam (ScreenProviding protocol) in the flow-contracts target,
+      beside its Output. Lives OUTSIDE the module tree; the overlay's contracts.root names where.
   screen.mapper:
     description: the wire-to-domain translation for the screen.
   service.dir:
@@ -128,7 +148,8 @@ module_overlay_slots:
       governs: [STRUCT-05]
       values:
         per-screen-factory: each screen ships its own construction seam.
-        shared-factory: one factory per module builds every screen.
+        shared-factory: one factory per module builds every screen - pre-conversion residue;
+          a converted module binds per-screen-factory, and a NEW module may not choose this.
       note: >
         Both put construction behind a seam, which is the property STRUCT-05 protects. Counting
         factories against screens tells you which one the module chose.
@@ -136,7 +157,8 @@ module_overlay_slots:
       governs: [STRUCT-06]
       values:
         separate-state-type: UI state lives in its own type beside the view model.
-        view-model-owned: the view model holds UI state directly.
+        view-model-owned: the view model holds UI state directly - pre-conversion residue for
+          form screens; the settled shape is the separate state type.
       note: >
         Unbound, STRUCT-06 is disabled - "the view model holds a form field" is only a finding in a
         module that decided it should not.
@@ -177,6 +199,16 @@ module_overlay_slots:
         copy-layer: a per-screen type owns every string the screen shows.
       note: Both keep copy findable; mixing them is what costs.
 
+    - id: UnitDialect
+      governs: [STRUCT-19, STRUCT-20]
+      question: which view-model generation do this module's screens ride?
+      values:
+        adopted: screens ride the unit view model (the State/ViewAction/Action/Output generic)
+          with the one-declaration-per-file vocabulary under the presentation models folder.
+        pre-unit: screens still ride the deprecated pre-unit scene base. Legitimate only as a
+          recorded migration state - the run reports it as debt, and a NEW module may not
+          choose it.
+
 # ---------------------------------------------------------------------------
 # Rules
 # ---------------------------------------------------------------------------
@@ -349,8 +381,11 @@ rules:
     check: >
       The entry file holds its properties, its init, one body and its previews. A second view
       member on it is a fragment that either belongs in the body's composition or belongs beside
-      the screen as an extracted view. The exception is a fragment the type system pins to the call
-      site - an alert's content, a modifier-constrained builder - which cannot be moved.
+      the screen as an extracted view. Moving those members into a view-composition extension
+      file (a "+ViewBuilder" / "+Subviews" companion) is the same finding relocated, not a fix -
+      that pattern is retired; the extracted subview pair is its replacement. The exception is a
+      fragment the type system pins to the call site - an alert's content, a modifier-constrained
+      builder - which cannot be moved.
 
   - id: STRUCT-11
     title: A cross-screen folder holds no type named after one screen
@@ -557,3 +592,82 @@ rules:
       A scripted implementation that also carries its own payload literals mixes the decision of
       which scenario to answer with the content of the answer. The tool can surface the size ratio;
       the split itself is a judgement.
+
+  - id: STRUCT-18
+    title: A converted screen ships its contract pair in the flow-contracts target
+    severity: important
+    enforcement: scan
+    predicate: contract_pair_required
+    params:
+      output_role: contracts.output
+      providing_role: contracts.providing
+    applies_when: >
+      the overlay binds contracts.root (the path of the module's flow-contracts target, relative
+      to the module root) AND both contracts.output and contracts.providing. Unbound, DISABLED -
+      a pre-conversion module has no contract side, and the run reports the lost coverage instead
+      of guessing one.
+    rationale: module boundaries
+    check: >
+      A converted flow's screen is reachable only through its contract seam: an Output enum naming
+      every navigation exit and a providing protocol vending the built screen. Both live in the
+      flow-contracts target, not in the module, so the module tree alone cannot prove a screen is
+      actually wired. Each screen directory must have a matching directory under contracts.root
+      holding both files; a screen without one is invisible to every consumer of the seam.
+
+  - id: STRUCT-19
+    title: A unit screen carries the four-file vocabulary, one declaration per file
+    severity: important
+    enforcement: lint
+    predicate: file_required_in_dir
+    params:
+      slot: UnitDialect
+      slot_value: adopted
+      role: screen.viewmodelstate
+      companion_roles: [screen.viewstate, screen.viewaction, screen.viewmodelaction]
+    applies_when: >
+      the module binds UnitDialect to adopted AND the four unit vocabulary roles. Unbound or
+      pre-unit, DISABLED - and the pre-unit binding itself is reported as recorded debt.
+    rationale: readability
+    check: >
+      The unit dialect spells a screen's contract as four value files beside the presentation
+      models - view state, view action, own action, reducer state - each a single declaration in
+      a file of its own name. A vocabulary member folded into the view model file or sharing a
+      file with a sibling hides the screen's surface from the reader who navigates by name.
+
+  - id: STRUCT-20
+    title: An adopted module's view models ride the unit generic, never the deprecated base
+    severity: blocking
+    enforcement: scan
+    predicate: forbidden_pattern
+    params:
+      slot: UnitDialect
+      slot_value: adopted
+      subject_role: screen.viewmodel
+      pattern: ':\s*BaseViewModel\b'
+    applies_when: >
+      the module binds UnitDialect to adopted. In a pre-unit module this rule is DISABLED - the
+      migration converts screens on touch and drowning it in findings would hide the ones that
+      matter - but the binding is reported as debt every run.
+    rationale: flexibility
+    check: >
+      The pre-unit scene base is deprecated at its declaration. In a module that declared itself
+      adopted, any view model still subclassing it is a regression, not a leftover - the overlay
+      said this module is done.
+
+  - id: STRUCT-21
+    title: Every screen-bearing target carries its dependency configurator
+    severity: important
+    enforcement: lint
+    predicate: target_configurator_required
+    params:
+      role: target.configurator
+    applies_when: >
+      the overlay binds target.configurator. Unbound, DISABLED and reported - a single-target
+      module may register at its screens instead, and that is a dialect, not a defect.
+    rationale: module boundaries
+    check: >
+      In a multi-target package each target that ships screens owns one registration home: the
+      configurator that registers its repositories, use cases and screen seams, validates them,
+      and exposes the store entry the composition root aggregates. A screen-bearing target
+      without one leaves its seams registered from another target - reachable, but owned by
+      nobody the reader can find.

package/pipeline/skills/shared/external/ios-module-structure/scripts/check_structure.py

@@ -68,6 +68,7 @@ class Bindings:
 
     def __init__(self, overlay, registry):
         self.roles = dict(overlay.get("roles") or {})
+        self.contracts = dict(overlay.get("contracts") or {})
         self.dialect = {k: v for k, v in (overlay.get("dialect") or {}).items()
                         if v and not k.endswith("_evidence")}
         self.vocabulary = dict(overlay.get("vocabulary") or {})
@@ -223,10 +224,57 @@ def p_file_required_in_dir(screen, root, rule, params, b):
         if not any(trigger_re.search(read(p)) for p in iter_glob(screen, trigger_pattern)):
             return []
 
-    wanted = expand(pattern, screen=screen.name)
-    if iter_glob(screen, wanted):
+    findings = []
+    for role_name in [params["role"]] + list(params.get("companion_roles") or []):
+        role_pattern = b.role(role_name)
+        if not role_pattern:
+            return []
+        wanted = expand(role_pattern, screen=screen.name)
+        if not iter_glob(screen, wanted):
+            findings.append({"path": str(screen), "line": 0, "detail": wanted})
+    return findings
+
+
+def module_target_configurator(root, rule, params, b, screens):
+    pattern = b.role(params["role"])
+    if not pattern:
+        return []
+    screen_units = {}
+    for screen in screens:
+        rel = screen.relative_to(root).parts
+        unit = rel[1] if rel[0] == "Sources" and len(rel) > 2 else rel[0]
+        screen_units.setdefault(unit, screen)
+    hits = iter_glob(root, pattern)
+    covered = set()
+    for hit in hits:
+        rel = hit.relative_to(root).parts
+        covered.add(rel[1] if rel[0] == "Sources" and len(rel) > 2 else rel[0])
+    return [{"path": str(screen_units[u]), "line": 0,
+             "detail": f"no configurator matched {pattern} for target {u}"}
+            for u in sorted(screen_units) if u not in covered]
+
+
+def p_contract_pair_required(screen, root, rule, params, b):
+    croot = b.contracts.get("root")
+    if not croot:
         return []
-    return [{"path": str(screen), "line": 0, "detail": wanted}]
+    base = (root / croot).resolve()
+    if not base.is_dir():
+        return [{"path": str(screen), "line": 0,
+                 "detail": f"contracts.root does not resolve: {croot}"}]
+    matches = [d for d in base.rglob(screen.name) if d.is_dir()]
+    if not matches:
+        return [{"path": str(screen), "line": 0,
+                 "detail": f"no contract directory named {screen.name} under {croot}"}]
+    findings = []
+    for role_key in (params["output_role"], params["providing_role"]):
+        pattern = b.role(role_key)
+        if not pattern:
+            return []
+        wanted = expand(pattern, screen=screen.name)
+        if not any(iter_glob(d, wanted) for d in matches):
+            findings.append({"path": str(screen), "line": 0, "detail": wanted})
+    return findings
 
 
 def p_prefix_collision(screen, root, rule, params, b):
@@ -524,6 +572,8 @@ PREDICATES = {
     "prefix_collision": p_prefix_collision,
     "dir_required_in_dir": p_dir_required_in_dir,
     "file_required_in_dir": p_file_required_in_dir,
+    "contract_pair_required": p_contract_pair_required,
+    "target_configurator_required": p_none,  # module-level; dispatched before the per-screen loop
     "pair_required_in_dir": p_pair_required_in_dir,
     "sibling_required": p_sibling_required,
     "forbidden_pattern": p_forbidden_pattern,
@@ -553,10 +603,13 @@ def rule_status(rule, bindings):
         wanted = params.get("slot_value")
         if wanted and bound != wanted:
             return False, f"slot {slot} is {bound}"
-    for key in ("role", "subject_role", "sibling_role", "container_role", "left_role", "right_role"):
+    for key in ("role", "subject_role", "sibling_role", "container_role", "left_role", "right_role",
+                "output_role", "providing_role"):
         name = params.get(key)
         if name and not bindings.role(name):
             return False, f"role {name} unbound"
+    if rule.get("predicate") == "contract_pair_required" and not bindings.contracts.get("root"):
+        return False, "contracts.root unbound"
     if params.get("vocabulary_key") and not bindings.vocabulary.get(params["vocabulary_key"]):
         return False, f"vocabulary {params['vocabulary_key']} unbound"
     if params.get("accept_from_vocabulary") and not bindings.vocabulary.get(params["accept_from_vocabulary"]):
@@ -608,6 +661,15 @@ def run(root, registry, bindings, only_rule=None, only_screen=None):
                 })
             continue
 
+        if rule.get("predicate") == "target_configurator_required":
+            for hit in module_target_configurator(root, rule, params, bindings, screens):
+                findings.append({
+                    "rule_id": rule["id"], "severity": rule["severity"], "screen": "(targets)",
+                    "path": str(Path(hit["path"]).relative_to(root)), "line": 0,
+                    "message": rule["title"], "detail": hit["detail"],
+                })
+            continue
+
         if rule.get("predicate") == "prefix_collision":
             for hit in module_prefix_collision(root, rule, params, bindings, screens):
                 findings.append({