@mmerterden/multi-agent-pipeline 13.2.0 → 13.3.0

package/pipeline/commands/multi-agent/ios-coding-standard/SKILL.md

@@ -5,17 +5,17 @@ argument-hint: "[module name or path]"
 allowed-tools: Skill, Bash, Read, Edit, Write, AskUserQuestion
 ---
 
-# multi-agent ios-coding-standard — Module audit → plan → dev handoff
+# multi-agent ios-coding-standard  -  Module audit → plan → dev handoff
 
-**Input**: $ARGUMENTS — optionally a module name or path. When absent, Phase 1 discovers and asks.
+**Input**: $ARGUMENTS  -  optionally a module name or path. When absent, Phase 1 discovers and asks.
 
 This routine is the **procedure**. The rules live in the `ios-coding-standard` skill, whose registry is
 `references/rules.yml` and whose teaching doc is `references/STANDARD.md`. Load that
 skill first; it is installed on every host and carried by the iOS stack plugin, so
-there is one registry rather than a copy per CLI. Never restate a rule here — cite its ID. A rule that is not in the
+there is one registry rather than a copy per CLI. Never restate a rule here  -  cite its ID. A rule that is not in the
 registry is not a rule; if the audit needs one, propose it as `status: proposed` and say so.
 
-Read-only + planning. This routine never edits source — the dev pipeline does.
+Read-only + planning. This routine never edits source  -  the dev pipeline does.
 
 **Goal.** A developer new to the repo can open any file in the module and understand it without a
 guided tour, and nothing sensitive leaks on the way. Rank every finding by "does fixing this
@@ -26,26 +26,26 @@ dev task) stay English.
 
 ---
 
-## Phase 1 — Discover and pick the module
+## Phase 1  -  Discover and pick the module
 
 1. Repo root via `git rev-parse --show-toplevel`.
-2. **Discover module roots** — any directory with a `Package.swift`, a `Sources/` subtree or an
+2. **Discover module roots**  -  any directory with a `Package.swift`, a `Sources/` subtree or an
    `.xcodeproj`. Sweep the container dirs that exist (`Domains/`, `Packages/`, `Modules/`,
    `Features/`, `Core/`, `Common/`, top-level module dirs) one level deep, then two if empty.
 3. Record per module: name · path · Swift files · lines · governance docs present · SPM targets.
-   Keep this **module registry** for the whole run — `MOD-*` greps every import against it.
+   Keep this **module registry** for the whole run  -  `MOD-*` greps every import against it.
    Classify each module's role, because the role decides which dependency edges are legal:
    **feature** · **core/common** · **seam** (cross-module contracts/bridges/navigation) ·
    **composition root** (legitimately knows every module).
 4. If `$ARGUMENTS` resolves to a module, skip the prompt. Otherwise `AskUserQuestion`
    (single-select, `outputLanguage`), documented modules first, each option showing file/line
    counts and `docs: yes/no`. If the list exceeds the question limit, group the smallest into an
-   "other" option and ask again — never truncate silently.
+   "other" option and ask again  -  never truncate silently.
 5. Scope = the whole module's sources across all its targets, unless the user narrows it.
 
-## Phase 2 — Resolve what applies to THIS module
+## Phase 2  -  Resolve what applies to THIS module
 
-### 2a. The registry is the standard — in-module prose docs are NOT consulted
+### 2a. The registry is the standard  -  in-module prose docs are NOT consulted
 
 The skill's `references/rules.yml` (+ a project `modules/<Module>.yml` overlay) is the single source of truth. **Do not read, cite, or
 derive rules from a module's own `*-CLAUDE.md`, `docs/` set or any other in-repo prose.** They are
@@ -64,7 +64,7 @@ the specs the generator reads, and the module registry from Phase 1.
    be `blocking`.
    *Why prohibitions need to be written down:* inference reads dominant patterns, and a rule
    obeyed everywhere has no counter-example to infer from. A ban at 100% compliance is invisible
-   to a scan — it survives only if the overlay states it.
+   to a scan  -  it survives only if the overlay states it.
 2. **Repo-level rules** (root `CLAUDE.md`, contributing docs) apply to every module.
 3. **The module's own dominant pattern is its de-facto convention.** Count variants per dimension;
    the minority instances are the finding. Internal consistency beats conformity to a sibling.
@@ -74,14 +74,14 @@ Findings from step 3 are tagged `inferred` and capped at **suggestion**. Only re
 overlay-backed rules may be `blocking`.
 
 **When the overlay is missing**, generate a draft from code evidence, print it for confirmation,
-and mark every slot it could not derive — a frozen UI target, a name lock, a carve-out and an
+and mark every slot it could not derive  -  a frozen UI target, a name lock, a carve-out and an
 operational constraint all look like ordinary code from the outside. Do not guess them; list them
 as Open Questions.
 
 ### 2c. Vocabulary
 
 Bind each slot to a real symbol by grepping the module, then the reference module. **An unbound
-slot disables its rules** — never invent a name, never import a sibling's.
+slot disables its rules**  -  never invent a name, never import a sibling's.
 
 `HandlerName` · `EventParam` · `CoordinatorType` · `ResultType` / `ErrorType` / `ErrorFactory` ·
 `DIResolver` / `DIConfigurator` · `RequestModelSuffix` / `ResponseModelSuffix` / `TransportSuffix` ·
@@ -94,14 +94,14 @@ slot disables its rules** — never invent a name, never import a sibling's.
 
 Print the resolved table before scanning so a wrong binding is caught early.
 
-### 2d. Sensitive-data inventory — required before any SEC rule runs
+### 2d. Sensitive-data inventory  -  required before any SEC rule runs
 
 The `SEC-*` rules are written against the **data classes** in `references/rules.yml →
 sensitive_data_classes`, never against one module's field names. Resolve the module's concrete
 instances of each class: grep entities, request/response models, storage calls and analytics
 events for the values the module actually handles, and map each to its class.
 
-Produce the inventory as a table — **class · concrete symbols · where it enters · required
+Produce the inventory as a table  -  **class · concrete symbols · where it enters · required
 lifetime (transient / survives-restart / survives-reinstall) · where it is actually stored ·
 where it is logged · where it leaves (network, analytics, pasteboard, another module)**.
 
@@ -117,13 +117,13 @@ whose required lifetime nobody can state, is an Open Question, not a silent pass
 
 This table is a deliverable in its own right, independent of whether any violation is found.
 
-## Phase 3 — Scan
+## Phase 3  -  Scan
 
 Apply the rules in `references/rules.yml` that survived Phase 2 binding, plus the module's own `validation`
 gate. Tag every finding: **rule ID · severity · source (`registry` / `doc` / `inferred`) ·
 onboarding impact (high/medium/low)**.
 
-### Coverage gate — on disk, not in memory
+### Coverage gate  -  on disk, not in memory
 
 Before scanning, write `.<module>-audit-coverage.tsv` to the scratch dir: one row per target
 (every screen under `ScreenRoot`, every shared component, every entity, every file in every
@@ -131,25 +131,25 @@ target) with columns `path · status · rules-applied`. Mark rows as you go.
 
 - Each target is **audited** or **explicitly skipped with a reason** (generated, fixture,
   vendored). No third state.
-- **The run is incomplete while any row is unmarked** — and the file, not a claim, is the proof.
+- **The run is incomplete while any row is unmarked**  -  and the file, not a claim, is the proof.
   Chunk the module if it is too large for one pass; the checklist survives a context reset.
 - No sampling. A partial audit reported as complete certifies the unscanned screens as clean.
 
 ### Grep hygiene
 
 Registry `mechanism` patterns are line-based and match doc comments. Filter
-`^[[:space:]]*//` — BSD grep does not understand `\s`, so a `\s*//` filter silently lets `/// …`
-through — then open each surviving hit and confirm it is real code. Report pre-filter and
+`^[[:space:]]*//`  -  BSD grep does not understand `\s`, so a `\s*//` filter silently lets `/// ...`
+through  -  then open each surviving hit and confirm it is real code. Report pre-filter and
 post-verification counts separately; a table padded with comment matches destroys trust.
 
 ### Judgement rules need evidence, not assertion
 
 For any rule marked `enforcement: judgement`, a finding must carry the measurement its `check`
-names — a reference count, a call-site count, a consumer count, a file list. **No count, no
+names  -  a reference count, a call-site count, a consumer count, a file list. **No count, no
 finding.** This is what keeps a subjective rule from becoming an opinion.
 
 Every judgement rule has a worked ✗/✓ pair in `EXAMPLES.md`, keyed by ID. Cite it in the finding's
-proposed fix rather than re-describing the shape — the developer applying the fix should be
+proposed fix rather than re-describing the shape  -  the developer applying the fix should be
 reading the same picture the audit used.
 
 ### Module-specific overrides
@@ -158,79 +158,79 @@ The module's own docs win over the registry, including where they contradict a s
 Never apply one module's dialect to another. List every override honoured, so the reader sees why
 a registry rule was not raised.
 
-## Phase 4 — Produce the plan
+## Phase 4  -  Produce the plan
 
 No findings → report compliant and stop. Otherwise write
 `<ModulePath>/ios-coding-standard-plan-<module>.md` (or the repo's scratch/docs dir if the module
 tree must stay clean), containing, in order:
 
-1. **Coverage ledger** — total targets · audited · skipped with reasons. Not 100% accounted for
+1. **Coverage ledger**  -  total targets · audited · skipped with reasons. Not 100% accounted for
    means the plan is not deliverable.
-2. **Summary** — counts by severity and source, resolved vocabulary, branch to create.
-3. **Sensitive-data inventory** (Phase 2d) — first, because it is the highest-risk content.
-4. **Screen × role matrix** `[STRUCT-02]` — screens as rows, manifest roles as columns, cells
+2. **Summary**  -  counts by severity and source, resolved vocabulary, branch to create.
+3. **Sensitive-data inventory** (Phase 2d)  -  first, because it is the highest-risk content.
+4. **Screen × role matrix** `[STRUCT-02]`  -  screens as rows, manifest roles as columns, cells
    `✓ / missing / misplaced`. The structural map a newcomer reads first.
-5. **Type placement table** `[STRUCT-05]` — type · location · consumer count · correct tier ·
+5. **Type placement table** `[STRUCT-05]`  -  type · location · consumer count · correct tier ·
    move required. Paired with the nested-type list `[STRUCT-01]`: owner · nested type · kind ·
    reference count · verdict.
-6. **Visibility report** `[VIS-01, VIS-02]` — over-exposed declarations per file, non-final
+6. **Visibility report** `[VIS-01, VIS-02]`  -  over-exposed declarations per file, non-final
    classes with no subclass.
-7. **Boundary report** `[MOD-*]` — import graph (allowed vs forbidden, with coupling depth) ·
+7. **Boundary report** `[MOD-*]`  -  import graph (allowed vs forbidden, with coupling depth) ·
    manifest graph (declared vs legal for the role, plus dead edges) · **removability delta**
-   ("removing X touches N files: …") · inbound test (tests compile with no sibling present).
-8. **Testability seam report** `[TEST-*]` — types reaching for the environment, logic requiring a
+   ("removing X touches N files: ...") · inbound test (tests compile with no sibling present).
+8. **Testability seam report** `[TEST-*]`  -  types reaching for the environment, logic requiring a
    view to execute, doubles whose signatures have drifted.
-9. **Change-cost probe** `[FLEX-*]` — pick two plausible upcoming changes (a new variant of an
+9. **Change-cost probe** `[FLEX-*]`  -  pick two plausible upcoming changes (a new variant of an
    existing screen; a new field on a shared entity) and state what each costs in files today.
-10. **Findings table** — rule ID · `file:line` · current state · proposed fix · severity · source ·
+10. **Findings table**  -  rule ID · `file:line` · current state · proposed fix · severity · source ·
     onboarding impact.
-11. **Per-file work** — grouped per file, blocking → important → suggestion; within a severity,
+11. **Per-file work**  -  grouped per file, blocking → important → suggestion; within a severity,
     highest onboarding impact first.
-12. **Behaviour-preservation guard** — splitting files, adding MARKs, extracting extensions and
+12. **Behaviour-preservation guard**  -  splitting files, adding MARKs, extracting extensions and
     moving types must not change behaviour. Anything requiring a behaviour change (a missing
     analytics event, a wrong result type, a timezone fix, a storage migration) goes in a
     **separate group**, reviewed and tested on its own, never inside a mechanical split commit.
-13. **Tooling delegation & the ratchet** — the section that decides whether any of this survives.
+13. **Tooling delegation & the ratchet**  -  the section that decides whether any of this survives.
     - Classify each applied rule by its registry `enforcement`. For every `lint` / `format` /
       `scan` rule, state the concrete mechanism and whether that toolchain exists in the repo
       (`LintToolchain`). **When it does not exist, saying so is a finding**, ranked above most
       individual violations it would have caught.
     - Recommend **baseline-and-ratchet, never big-bang**: grandfather existing violations, surface
-      only new ones, drain the backlog behind a green build. Order the plan the same way — stop
+      only new ones, drain the backlog behind a green build. Order the plan the same way  -  stop
       the bleeding, then clean up.
     - Custom lint rule identifiers **are** the registry IDs (`sec_01_no_plaintext_persistence`,
       `mod_01_no_sibling_import`) so a violation points straight at the rule entry.
-    - **Linting is local-only by decision** — the skill's `references/lint-local.sh` with `references/swiftlint.draft.yml`, config
+    - **Linting is local-only by decision**  -  the skill's `references/lint-local.sh` with `references/swiftlint.draft.yml`, config
       and baseline kept outside the repository; no committed config, no build phase, no CI job.
       State this honestly in the plan rather than describing a gate that does not exist: a
       pre-PR habit catches less than a wall, so the residual risk is real and belongs in the
-      report. Adopting it project-wide remains an open decision — record it as one so it stays
+      report. Adopting it project-wide remains an open decision  -  record it as one so it stays
       visible instead of quietly lapsing.
     - Never imply the audit substitutes for the linter, or the linter for a gate. The audit finds
       the debt once; the linter keeps a developer honest; only a gate stops it returning.
-14. **Numeric exit criteria** — target and today's measured value side by side: lint violations
+14. **Numeric exit criteria**  -  target and today's measured value side by side: lint violations
     per 1k lines (<1) · public-surface ratio, public declarations ÷ externally consumed symbols
     (≈1) · forbidden cross-module imports (0) · removability delta · files over threshold and
     files >120 lines with no sectioning (0) · screens missing a manifest role (0) · escape-hatch
     count `[CONC-03]` (flat or falling) · exception-marker count (flat or falling) · dead code (0)
     · screens with logic and no mirrored tests (0) · unclassified sensitive symbols (0).
-15. **Exception ledger** — every `// standard:exception(<ID>)` in the module: rule · reason ·
+15. **Exception ledger**  -  every `// standard:exception(<ID>)` in the module: rule · reason ·
     expiry · expired yes/no.
-16. **Open Questions** — Phase 2b dimensions with no majority, and unclassifiable symbols.
-17. **Suggested commit slicing** — one commit per file-group / concern.
-18. **Scope guard** — only this module is touched; definition of done is the module's own
+16. **Open Questions**  -  Phase 2b dimensions with no majority, and unclassifiable symbols.
+17. **Suggested commit slicing**  -  one commit per file-group / concern.
+18. **Scope guard**  -  only this module is touched; definition of done is the module's own
     verification path.
 
 Then write a **separate one-page onboarding summary** beside the plan, aimed at a developer
 joining next week rather than at whoever does the remediation: the ten always/never lines
 specialised to this module, the screen file manifest, the placement ladder, the sensitive-data
-classes in play, and the verification command. Nobody learns a codebase from a 40-finding audit —
+classes in play, and the verification command. Nobody learns a codebase from a 40-finding audit -
 this page is the actual deliverable, and the audit is how you earn the right to write it
-accurately. Derive it from `references/STANDARD.md § 0`, do not re-invent it.
+accurately. Derive it from `references/STANDARD.md section 0`, do not re-invent it.
 
 Show a concise version of the plan to the user too.
 
-## Phase 5 — Hand off
+## Phase 5  -  Hand off
 
 `AskUserQuestion` (single-select, `outputLanguage`):
 
@@ -245,10 +245,10 @@ verifies, and commits only when asked. This routine ends at the handoff.
 
 ## Notes
 
-- **Verification reality is per-module — establish it, do not assume it.** Some targets cannot be
+- **Verification reality is per-module  -  establish it, do not assume it.** Some targets cannot be
   compiled from the CLI (asset symbol generation, UIKit-dependent packages, a dependency failing
   earlier in the graph); there, verification is Xcode and a manifest dump validates the manifest
-  only. Never trust a piped build's exit code — a pipe reports the tail's status. Record the
+  only. Never trust a piped build's exit code  -  a pipe reports the tail's status. Record the
   module's actual verification command in the plan.
 - One module per run. Several modules means several runs and several plans, never one
   cross-module churn commit.

package/pipeline/multi-agent-refs/cross-cli-contract.md

@@ -34,7 +34,38 @@ Categories:
 
 Component work is **no longer a bundled pipeline skill set**. Claude Code dispatches `taskType === "component"` to the enabled `ai-<platform>-engineering-toolkit` **marketplace plugin** (`create-component`, fallback `create-ui-component`) via the Skill tool  -  full contract in `$HOME/.claude/multi-agent-refs/component-dispatch.md`. The pipeline no longer ships `pipeline/skills/figma-ios|figma-android|figma-common`; the pipeline-unique component skills (iterate loops, performance harness, validate/review, commit, adapters, wiki) were absorbed into the `ai-ios-engineering-toolkit` plugin so component skills live in one place.
 
-**Intentional cross-CLI divergence.** Copilot CLI has no marketplace-plugin loader, so it retains its own standalone `~/.copilot/skills/figma-*` copies as a frozen fallback. Component/figma dispatch is therefore **not** byte-identical across CLIs, and figma-skill *inventory* parity is **no longer enforced**  -  this is a deliberate exception to the parity rule, not drift.
+**How each host receives the plugin's skills.** Only Claude Code loads the marketplace
+plugin natively. The other two are served by the installer, so all three end up with the
+same active skill set:
+
+| Host | Delivery | Discovery |
+|---|---|---|
+| Claude Code | the marketplace plugin, loaded natively | matched on description |
+| Copilot CLI | `install/copilot.mjs` copies the **enabled** stack plugin's authored skills (`index`, `reference/`, `workflow/`, `tools/`) into `~/.copilot/skills/` | matched on description |
+| Codex CLI | `install/codex.mjs` copies the same set **plus** `skills/shared/external` into `~/.codex/multi-agent-refs/skills/` as reference files | located by path; the AGENTS.md block carries the `ls` / `grep` recipe |
+
+Three rules make that work:
+
+1. **`knowledge/` is never copied to Copilot.** A stack plugin's `knowledge/` tree is
+   generated from this pipeline's `skills/shared/external`, which the installer already
+   lays down there. Copying it again would duplicate ~5 MB the host has.
+2. **Only the ENABLED plugins are delivered.** `fix-bug` and `branch-and-pr` exist in
+   four stack plugins, `component`, `state` and `create-component` in three, and the
+   destination is flat  -  delivering every stack would be last-write-wins, so an iOS
+   repo could end up running the Android `create-component`. The enabled list in
+   `~/.claude/settings.json` is the source of truth, exactly as on Claude Code;
+   `--platform` is the fallback when no such list exists.
+3. **Codex takes refs, not list entries.** Measured on 0.145: one plugin declaring 142
+   skills surfaced 75 and evicted an unrelated user skill, and every plugin-provided
+   skill renders with an empty description, so a block entry buys nothing even when it
+   fits. Parity on that host is **reachability**, not an identical listing.
+
+> This section previously claimed Copilot "retains its own standalone
+> `~/.copilot/skills/figma-*` copies as a frozen fallback". `install/copilot.mjs` pruned
+> exactly those directories, so the fallback did not exist: `create-screen`,
+> `figma-validate`, `figma-review`, `component`, `state` and `navigation` were all
+> absent, and a component task on Copilot had nothing to dispatch to. The contract
+> documented a safety net the installer deleted.
 
 What still MUST match across CLIs for component tasks: the `taskType === "component"` classification, the `state.phases["3"].subphases[]` shape the dispatch layer writes, and `--dev` elision semantics. Resolution/routing is Claude-plugin vs Copilot-local-copy by design.
 

package/pipeline/scripts/build-stack-plugins.mjs

@@ -35,9 +35,14 @@ import {
 import { join } from "node:path";
 
 const args = process.argv.slice(2);
+// Accepts both `--key value` and `--key=value`. The `=` form used to fall through to
+// the default, which meant a run meant for a throwaway checkout silently retargeted
+// the user's real marketplace instead - a wrong-target write, reported as success.
 const getArg = (k, d) => {
+  const eq = args.find((a) => a.startsWith(`${k}=`));
+  if (eq) return eq.slice(k.length + 1);
   const i = args.indexOf(k);
-  return i >= 0 ? args[i + 1] : d;
+  return i >= 0 && args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : d;
 };
 const HOME = process.env.HOME;
 const PLUGINS_REPO = getArg("--plugins-repo", join(HOME, "multi-agent-plugins"));
@@ -102,6 +107,29 @@ const isDir = (p) => {
 };
 const listDirs = (p) => (existsSync(p) ? readdirSync(p).filter((n) => isDir(join(p, n))) : []);
 
+/**
+ * Cheap content fingerprint for a skill directory: every file's relative path and
+ * size. Enough to notice an edit without hashing megabytes on every run, and it is
+ * only used to decide whether a version bump is warranted.
+ */
+function treeFingerprint(dir) {
+  const parts = [];
+  const walk = (d, rel) => {
+    for (const e of readdirSync(d, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const full = join(d, e.name);
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(full, r);
+      else if (e.isFile()) parts.push(`${r}:${statSync(full).size}`);
+    }
+  };
+  try {
+    walk(dir, "");
+  } catch {
+    return "";
+  }
+  return parts.join("|");
+}
+
 // --- 1. enumerate authoring source ---------------------------------------
 if (!existsSync(EXTERNAL)) {
   console.error(`source not found: ${EXTERNAL}`);
@@ -180,13 +208,31 @@ for (const [plugin, want] of Object.entries(desired)) {
   const have = new Set(listDirs(kdir));
   const toAdd = [...want].filter((s) => !have.has(s)).sort();
   const toRemove = [...have].filter((s) => !want.has(s)).sort();
-  const changed = toAdd.length > 0 || toRemove.length > 0;
+  const setChanged = toAdd.length > 0 || toRemove.length > 0;
 
-  if (!DRY && changed) {
+  // Re-copy EVERY wanted skill, not just the newly added ones.
+  //
+  // This used to copy only on a set change, which quietly broke the single-source
+  // claim: editing a skill in shared/external left the plugin serving the old text
+  // forever, because the set had not changed. Found by editing a promoted skill and
+  // seeing the plugin copy stay stale while the generator reported "all plugins up
+  // to date".
+  //
+  // cpSync overwrites, so a full re-copy is idempotent and cheap relative to a
+  // publish. Removals still need the explicit delete.
+  let contentChanged = false;
+  if (!DRY) {
     if (!existsSync(kdir)) mkdirSync(kdir, { recursive: true });
-    for (const s of toAdd) cpSync(join(EXTERNAL, s), join(kdir, s), { recursive: true });
+    for (const s of want) {
+      const from = join(EXTERNAL, s);
+      const to = join(kdir, s);
+      const before = existsSync(to) ? treeFingerprint(to) : "";
+      cpSync(from, to, { recursive: true });
+      if (treeFingerprint(to) !== before) contentChanged = true;
+    }
     for (const s of toRemove) rmSync(join(kdir, s), { recursive: true, force: true });
   }
+  const changed = setChanged || contentChanged;
 
   // regenerate plugin.json skills[]: keep non-knowledge entries, rebuild knowledge set
   const pj = JSON.parse(readFileSync(pjPath, "utf8"));