@mmerterden/multi-agent-pipeline 15.3.2 → 15.4.0

package/CHANGELOG.md

@@ -16,6 +16,16 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "15.3.2",
+  "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/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/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/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({