@mmerterden/multi-agent-pipeline 20.36.0 → 20.37.1

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

@@ -26,6 +26,13 @@ shorten the time to first productive PR, or close a real risk?"
 Render assistant-facing prose in `outputLanguage`. External payloads (branch names, plan file,
 dev task) stay English.
 
+Procedure detail, read when the phase starts:
+
+```
+$HOME/.claude/multi-agent-refs/ios-coding-standard/resolve-and-scan.md   (Phases 2 and 3)
+$HOME/.claude/multi-agent-refs/ios-coding-standard/plan.md               (Phase 4)
+```
+
 ---
 
 ## Phase 1  -  Discover and pick the module
@@ -36,9 +43,7 @@ dev task) stay English.
    `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.
-   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).
+   Classify each module's role: **feature** · **core/common** · **seam** · **composition root**.
 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
@@ -47,189 +52,43 @@ dev task) stay English.
 
 ## Phase 2  -  Resolve what applies to THIS module
 
-### 2a. The registry is the standard  -  in-module prose docs are NOT consulted
-
-The skill's `references/rules.yml` (+ a project `modules/<Module>.yml` overlay) is the single source of truth. **Do not read, cite, or
-derive rules from a module's own `*-CLAUDE.md`, `docs/` set or any other in-repo prose.** They are
-being retired precisely so there is one place a rule can live; consulting them re-creates the
-split this command exists to remove. If such a file exists and contradicts the registry, that is a
-finding against the file, not against the code.
-
-The only in-repo inputs are **code and manifests**: sources, tests, `Package.swift`, `Info.plist`,
-the specs the generator reads, and the module registry from Phase 1.
-
-### 2b. Per-module overlay, then inference
-
-1. **`modules/<Module>.yml`** beside the project's own config carries what code cannot state: the vocabulary
-   bindings, the module's role, prohibitions that currently have **zero** instances, deliberate
-   carve-outs, name locks, and the real verification command. Registry-backed, so its findings may
-   be `blocking`.
-   *Why prohibitions need to be written down:* inference reads dominant patterns, and a rule
-   obeyed everywhere has no counter-example to infer from. A ban at 100% compliance is invisible
-   to a scan  -  it survives only if the overlay states it.
-2. **Repo-level rules** (root `CLAUDE.md`, contributing docs) apply to every module.
-3. **The module's own dominant pattern is its de-facto convention.** Count variants per dimension;
-   the minority instances are the finding. Internal consistency beats conformity to a sibling.
-4. No majority (even split, single instance) → not a finding. Record an Open Question.
-
-Findings from step 3 are tagged `inferred` and capped at **suggestion**. Only registry- or
-overlay-backed rules may be `blocking`.
-
-**When the overlay is missing**, generate a draft from code evidence, print it for confirmation,
-and mark every slot it could not derive  -  a frozen UI target, a name lock, a carve-out and an
-operational constraint all look like ordinary code from the outside. Do not guess them; list them
-as Open Questions.
-
-### 2c. Vocabulary
-
-Bind each slot to a real symbol by grepping the module, then the reference module. **An unbound
-slot disables its rules**  -  never invent a name, never import a sibling's.
-
-`HandlerName` · `EventParam` · `CoordinatorType` · `ResultType` / `ErrorType` / `ErrorFactory` ·
-`DIResolver` / `DIConfigurator` · `RequestModelSuffix` / `ResponseModelSuffix` / `TransportSuffix` ·
-`MapperShape` · `SafeEnumProtocol` / `UnknownCase` · `CopySurface` · `AnalyticsSurface` ·
-`A11yIdentifierSource` · `GeneratedServiceRoot` · `SharedComponentsDir` / `SharedEntitiesDir` ·
-`MicroComponentLibrary` · `FrozenUITarget` · `DesignTokenNamespaces` · `CalendarDayHelper` ·
-`LoggerAPI` · `FileHeaderShape` · `ScreenRoot` · `ScreenRoleSuffixes` · `AsyncStyle` ·
-`CompositionRoot` · `SeamLayer` · `ModuleEntrySurface` · `ConcurrencyPosture` · `LintToolchain` ·
-`CredentialStore` (the module's Keychain wrapper, if any).
-
-Print the resolved table before scanning so a wrong binding is caught early.
-
-### 2d. Sensitive-data inventory  -  required before any SEC rule runs
-
-The `SEC-*` rules are written against the **data classes** in `references/rules.yml →
-sensitive_data_classes`, never against one module's field names. Resolve the module's concrete
-instances of each class: grep entities, request/response models, storage calls and analytics
-events for the values the module actually handles, and map each to its class.
-
-Produce the inventory as a table  -  **class · concrete symbols · where it enters · required
-lifetime (transient / survives-restart / survives-reinstall) · where it is actually stored ·
-where it is logged · where it leaves (network, analytics, pasteboard, another module)**.
-
-The **lifetime column is the one that decides SEC-01**, and it is filled by walking
-`references/rules.yml → persistence_decision`, not by looking at what the code currently does. Compare it
-against the storage column and report both mismatches:
-- required transient but persisted anywhere (including the Keychain) → **over-persistence**;
-- required to survive a restart but stored outside the Keychain → **under-protection**.
-
-Then generate the SEC lint patterns *from this inventory*, so the checks match this module's real
-vocabulary. A class with no instance here yields no finding; a symbol you cannot classify, or one
-whose required lifetime nobody can state, is an Open Question, not a silent pass.
-
-This table is a deliverable in its own right, independent of whether any violation is found.
+- **The registry is the standard.** `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.** A file that contradicts the registry is a
+  finding against the file. The only in-repo inputs are code and manifests.
+- **Overlay, then inference.** Overlay- and registry-backed findings may be `blocking`; findings
+  inferred from the module's dominant pattern are tagged `inferred` and capped at **suggestion**.
+  No majority → Open Question, not a finding. A missing overlay gets a draft from code evidence,
+  printed for confirmation, with every slot it could not derive listed as an Open Question.
+- **Vocabulary.** Bind each slot to a real symbol by grepping. **An unbound slot disables its
+  rules**  -  never invent a name, never import a sibling's. Print the resolved table before scanning.
+- **Sensitive-data inventory, required before any SEC rule runs.** Map the module's real symbols to
+  `sensitive_data_classes`; the lifetime column, filled from `persistence_decision`, decides
+  SEC-01. A symbol you cannot classify is an Open Question, not a silent pass.
 
 ## 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
-
-Before scanning, write `.<module>-audit-coverage.tsv` to the scratch dir: one row per target
-(every screen under `ScreenRoot`, every shared component, every entity, every file in every
-target) with columns `path · status · rules-applied`. Mark rows as you go.
-
-- Each target is **audited** or **explicitly skipped with a reason** (generated, fixture,
-  vendored). No third state.
-- **The run is incomplete while any row is unmarked**  -  and the file, not a claim, is the proof.
-  Chunk the module if it is too large for one pass; the checklist survives a context reset.
-- No sampling. A partial audit reported as complete certifies the unscanned screens as clean.
+Apply the rules that survived Phase 2 binding, plus the module's own `validation` gate. Tag every
+finding: **rule ID · severity · source (`registry` / `doc` / `inferred`) · onboarding impact**.
 
-### Grep hygiene
-
-Registry `mechanism` patterns are line-based and match doc comments. Filter
-`^[[:space:]]*//`  -  BSD grep does not understand `\s`, so a `\s*//` filter silently lets `/// ...`
-through  -  then open each surviving hit and confirm it is real code. Report pre-filter and
-post-verification counts separately; a table padded with comment matches destroys trust.
-
-### Judgement rules need evidence, not assertion
-
-For any rule marked `enforcement: judgement`, a finding must carry the measurement its `check`
-names  -  a reference count, a call-site count, a consumer count, a file list. **No count, no
-finding.** This is what keeps a subjective rule from becoming an opinion.
-
-Every judgement rule has a worked ✗/✓ pair in `EXAMPLES.md`, keyed by ID. Cite it in the finding's
-proposed fix rather than re-describing the shape  -  the developer applying the fix should be
-reading the same picture the audit used.
-
-### Module-specific overrides
-
-The module's own docs win over the registry, including where they contradict a sibling module.
-Never apply one module's dialect to another. List every override honoured, so the reader sees why
-a registry rule was not raised.
+- **Coverage gate on disk**: `.<module>-audit-coverage.tsv`, one row per target, each **audited**
+  or **explicitly skipped with a reason**. The run is incomplete while any row is unmarked. No
+  sampling.
+- **Grep hygiene**: filter comment lines, confirm every hit, report pre-filter and verified counts.
+- **Judgement rules**: no count, no finding; cite the `EXAMPLES.md` pair by ID.
 
 ## 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
-   means the plan is not deliverable.
-2. **Summary**  -  counts by severity and source, resolved vocabulary, branch to create.
-3. **Sensitive-data inventory** (Phase 2d)  -  first, because it is the highest-risk content.
-4. **Screen × role matrix** `[STRUCT-02]`  -  screens as rows, manifest roles as columns, cells
-   `✓ / missing / misplaced`. The structural map a newcomer reads first.
-5. **Type placement table** `[STRUCT-05]`  -  type · location · consumer count · correct tier ·
-   move required. Paired with the nested-type list `[STRUCT-01]`: owner · nested type · kind ·
-   reference count · verdict.
-6. **Visibility report** `[VIS-01, VIS-02]`  -  over-exposed declarations per file, non-final
-   classes with no subclass.
-7. **Boundary report** `[MOD-*]`  -  import graph (allowed vs forbidden, with coupling depth) ·
-   manifest graph (declared vs legal for the role, plus dead edges) · **removability delta**
-   ("removing X touches N files: ...") · inbound test (tests compile with no sibling present).
-8. **Testability seam report** `[TEST-*]`  -  types reaching for the environment, logic requiring a
-   view to execute, doubles whose signatures have drifted.
-9. **Change-cost probe** `[FLEX-*]`  -  pick two plausible upcoming changes (a new variant of an
-   existing screen; a new field on a shared entity) and state what each costs in files today.
-10. **Findings table**  -  rule ID · `file:line` · current state · proposed fix · severity · source ·
-    onboarding impact.
-11. **Per-file work**  -  grouped per file, blocking → important → suggestion; within a severity,
-    highest onboarding impact first.
-12. **Behaviour-preservation guard**  -  splitting files, adding MARKs, extracting extensions and
-    moving types must not change behaviour. Anything requiring a behaviour change (a missing
-    analytics event, a wrong result type, a timezone fix, a storage migration) goes in a
-    **separate group**, reviewed and tested on its own, never inside a mechanical split commit.
-13. **Tooling delegation & the ratchet**  -  the section that decides whether any of this survives.
-    - Classify each applied rule by its registry `enforcement`. For every `lint` / `format` /
-      `scan` rule, state the concrete mechanism and whether that toolchain exists in the repo
-      (`LintToolchain`). **When it does not exist, saying so is a finding**, ranked above most
-      individual violations it would have caught.
-    - Recommend **baseline-and-ratchet, never big-bang**: grandfather existing violations, surface
-      only new ones, drain the backlog behind a green build. Order the plan the same way  -  stop
-      the bleeding, then clean up.
-    - Custom lint rule identifiers **are** the registry IDs (`sec_01_no_plaintext_persistence`,
-      `mod_01_no_sibling_import`) so a violation points straight at the rule entry.
-    - **Linting is local-only by decision**  -  the skill's `references/lint-local.sh` with `references/swiftlint.draft.yml`, config
-      and baseline kept outside the repository; no committed config, no build phase, no CI job.
-      State this honestly in the plan rather than describing a gate that does not exist: a
-      pre-PR habit catches less than a wall, so the residual risk is real and belongs in the
-      report. Adopting it project-wide remains an open decision  -  record it as one so it stays
-      visible instead of quietly lapsing.
-    - Never imply the audit substitutes for the linter, or the linter for a gate. The audit finds
-      the debt once; the linter keeps a developer honest; only a gate stops it returning.
-14. **Numeric exit criteria**  -  target and today's measured value side by side: lint violations
-    per 1k lines (<1) · public-surface ratio, public declarations ÷ externally consumed symbols
-    (≈1) · forbidden cross-module imports (0) · removability delta · files over threshold and
-    files >120 lines with no sectioning (0) · screens missing a manifest role (0) · escape-hatch
-    count `[CONC-03]` (flat or falling) · exception-marker count (flat or falling) · dead code (0)
-    · screens with logic and no mirrored tests (0) · unclassified sensitive symbols (0).
-15. **Exception ledger**  -  every `// standard:exception(<ID>)` in the module: rule · reason ·
-    expiry · expired yes/no.
-16. **Open Questions**  -  Phase 2b dimensions with no majority, and unclassifiable symbols.
-17. **Suggested commit slicing**  -  one commit per file-group / concern.
-18. **Scope guard**  -  only this module is touched; definition of done is the module's own
-    verification path.
+tree must stay clean) with the 18 sections of `plan.md`, in order. Hard rules from it:
 
-Then write a **separate one-page onboarding summary** beside the plan, aimed at a developer
-joining next week rather than at whoever does the remediation: the ten always/never lines
-specialised to this module, the screen file manifest, the placement ladder, the sensitive-data
-classes in play, and the verification command. Nobody learns a codebase from a 40-finding audit -
-this page is the actual deliverable, and the audit is how you earn the right to write it
-accurately. Derive it from `references/STANDARD.md section 0`, do not re-invent it.
+- A coverage ledger short of 100% accounted for means the plan is not deliverable.
+- Behaviour changes go in a **separate group**, never inside a mechanical split commit.
+- Linting is **local-only by decision**; never describe a gate that does not exist, and never imply
+  the audit substitutes for the linter or the linter for a gate.
 
+Then write the one-page onboarding summary beside the plan (`plan.md`, "Onboarding summary").
 Show a concise version of the plan to the user too.
 
 ## Phase 5  -  Hand off
@@ -248,11 +107,9 @@ 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
-  compiled from the CLI (asset symbol generation, UIKit-dependent packages, a dependency failing
-  earlier in the graph); there, verification is Xcode and a manifest dump validates the manifest
-  only. Never trust a piped build's exit code  -  a pipe reports the tail's status. Record the
-  module's actual verification command in the plan.
+- **Verification reality is per-module  -  establish it, do not assume it.** Never trust a piped
+  build's exit code. Record the module's actual verification command in the plan
+  (`resolve-and-scan.md`, "Verification reality").
 - One module per run. Several modules means several runs and several plans, never one
   cross-module churn commit.
 - If the audit wants a rule the registry lacks, add it to the skill's `references/rules.yml` as `status: proposed` with a

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

@@ -20,12 +20,13 @@ Lets you switch to the task branch for manual testing in Xcode before the PR is
 2. **Check the state**  -  the task must have completed Phase 2 (Dev) or later
    - Phase < 2 → "No code has been written yet, run `resume #N` first"
 
-3. **Remove the worktree and switch to the branch**:
+3. **Hand the branch over**. Make the WIP commit yourself (Standard path item 3 of Phase 4 Step 2 folds it back), then let the script hold the run artefacts and the project root's current branch, remove the worktree and check the branch out. `{worktree-path}` and `{jiraId}` come from the task's state (`worktreePath`, `jiraId`):
    ```bash
-   cd {project-root}
-   git worktree remove .worktrees/PROJ-{id} 2>/dev/null
-   git checkout {branch-name}
+   git -C "{worktree-path}" add -A
+   git -C "{worktree-path}" diff --cached --quiet || git -C "{worktree-path}" commit -m "WIP: {jiraId}  -  changes for user test"
+   bash $HOME/.claude/scripts/user-test-handoff.sh checkout --task "{jiraId}" --worktree "{worktree-path}" --root "{project-root}" --branch "{branch-name}"
    ```
+   A refused commit stops here with nothing moved. Script exits: 3 the project root has uncommitted changes; 5 the worktree or a submodule holds uncommitted, unpushed or stashed work (a submodule with no remote needs one added); both move nothing. 6 a handoff is already held, or git refused part way: run `restore` below (if it answers 7, nothing had moved). 1 the worktree is not on the branch.
 
 4. **Give test instructions**:
    ```
@@ -41,7 +42,11 @@ Lets you switch to the task branch for manual testing in Xcode before the PR is
      ❌ "fix: ..." → the worktree is recreated and the fix is applied
    ```
 
-5. **Wait for the user's response**
+5. **Wait for the user's response**, then hand the branch back before acting on it:
+   ```bash
+   bash $HOME/.claude/scripts/user-test-handoff.sh restore --task "{jiraId}" --worktree "{worktree-path}" --root "{project-root}" --branch "{branch-name}"
+   ```
+   Exit 3: the user edited files on the branch in the project root. Ask them to `git stash`, run `restore` again, then `git -C "{worktree-path}" stash pop`; a commit made there instead would stop Phase 4 from folding the checkpoints. Exit 6: the project root could not leave the branch (an untracked file in the way) or the worktree could not be re-added; the message names the cause, the hold is kept, and `restore` runs again once it is cleared. Exit 7: nothing was held, so the worktree was never removed.
 
 6. **Based on the result**:
    - **OK** → an "ok" is a claim, and the pass has to be substantiated before it is recorded. First write `$WORKTREE/.pipeline/manual-test.json`, one entry per acceptance criterion taken from the analysis doc test plan, the plan tasks, or the user's own words:
@@ -53,5 +58,5 @@ Lets you switch to the task branch for manual testing in Xcode before the PR is
      node $HOME/.claude/scripts/evidence-gate.mjs --claim manual --status passed \
        --evidence "$WORKTREE/.pipeline/manual-test.json"
      ```
-     Exit 1 means the "ok" is not accepted: name the criterion that lacks evidence and wait for the next reply. Exit 0 → recreate the worktree, proceed to Phase 4. Full contract: `$HOME/.claude/multi-agent-refs/phases/phase-3-review.md` step 5.
-   - **Fix needed** → recreate the worktree, apply the fix
+     Exit 1 means the "ok" is not accepted: name the criterion that lacks evidence and wait for the next reply. Exit 0 → proceed to Phase 4. Full contract: `$HOME/.claude/multi-agent-refs/phases/phase-3-review.md` step 5.
+   - **Fix needed** → apply the fix in the restored worktree

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

@@ -15,6 +15,8 @@ Deep-analyses the current project, extracts the global best-practices worth adop
 
 **Input**: $ARGUMENTS (optional  -  `backlog` runs Step 0e alone; otherwise an area to focus on: "security", "performance", "tests", "bugs", "best-practices", "drift", "multi-agent-toolkit", etc.)
 
+Procedures, output tables, the band list and the focus filter live in `$HOME/.claude/multi-agent-refs/refactor/sweep.md`. Read it before Step 0; each step below names the section it uses.
+
 ## Flow
 
 ```
@@ -22,229 +24,80 @@ Step 0:  BEST-PRACTICES  Research the field, extract the best approaches, ADAPT
 Step 0b: DRIFT           Check upstream-derived skills for updates we have not pulled -> plan band D
 Step 0c: DEV-TOOLKIT     Research current MCP practice + audit the companion multi-agent-toolkit repo -> plan band E
 Step 0d: RUN-ERRORS      Read the local run-error ledger, rank recurring failures -> plan band F
+Step 0e: BACKLOG         Decide the open observations recorded mid-task -> plan band G
 Step 1:  SCAN            Walk the project structure (files, LOC, dependencies, CI, tests)
 Step 2:  ANALYZE         10 categories + an explicit BUG HUNT (real defects, not just scores) -> plan bands B, C
 Step 3:  SCORE           Each category /10, overall /100
-Step 4:  PLAN            Merge bands A (best-practice) + B (bugs) + C (improvements) + D (drift) + E (multi-agent-toolkit) + F (run-errors)
+Step 4:  PLAN            Merge every band into one table
 Step 5:  ASK             "Start the work?"  -  wait for user approval
 Step 6:  IMPLEMENT       Apply approved items one by one (lint, test, commit)
 Step 7:  VERIFY          Confirm every test + lint passes
 Step 8:  ASK SYNC        "Run /multi-agent:sync?"  -  wait for user approval
 ```
 
-Plan bands (all five feed the single Step 4 table):
-- **A - Best-practice**: the best field approaches, adapted so they actually fit this repo.
-- **B - Bug**: real defects found in the code (correctness, security, data-loss, crashes).
-- **C - Improvement**: quality/perf/DX gaps surfaced by the 10-category analysis.
-- **D - Drift**: upstream updates to skills we derived from an external source.
-- **E - Dev-toolkit**: current-practice gaps in the companion multi-agent-toolkit MCP server (the pipeline's device and browser hands), applied in that repo.
-- **F - Run-errors**: recurring real failures the pipeline actually hit across past runs, read from the local run-error ledger. These are lived evidence, not speculation - a failure that recurs across users or tasks is a prioritized improvement area.
-
-## Step 0: BEST-PRACTICES  -  research the field, adapt to us
-
-Do not copy features blindly. The goal is the best *approaches*, reshaped so they are applicable to THIS project's stack, size, and constraints.
-
-1. **Identify the domain** of the current project (read README + package/build manifests): what kind of project is it (CLI, SDK, app, pipeline, library), what stack, who uses it.
-2. **Research the best-in-class** for that exact domain. When `ai-analyst-toolkit` is enabled, run the first three bullets through its skills (`evidence-github`, `evidence-registry`, `signal-community`) rather than ad-hoc searching: they carry the query forms and the citation format, and they keep the evidence / signal line straight - a GitHub PR is a fact, a forum thread is one person's experience. Not enabled is a recorded no-op and the manual searches below still apply.
-   - **GitHub**: search the domain terms + `stars:>50`; read the top repos' READMEs, architecture docs, CI configs, test layout.
-   - **X / Twitter**: search the domain terms + "best practices" / "we switched to" / "lesson learned"; capture what practitioners and tool authors actually recommend right now (WebFetch/WebSearch on `x.com` / `twitter.com` threads).
-   - **Reddit**: relevant subreddits for real-world pain points and adopted patterns.
-   - **Web**: "<domain> best practices <current-year>", official style guides, and the platform's own guidance.
-3. **For each candidate approach, record**:
-   - what it is, who does it well (source link)
-   - the concrete benefit
-   - **adaptation**: exactly how it would look in OUR repo (which file/dir/script), and what has to change for it to fit  -  not a generic "add tests" but "add a flow-assertion helper in `test/helpers/`"
-   - effort (Low/Med/High) and impact (Low/Med/High/Critical)
-4. **Discard** approaches that do not fit our stack, our scale, or our constraints  -  and say WHY (so the user sees the filter working, not just the survivors).
-
-Output (plan band A):
-```
-| Source | Approach | Adaptation to our repo | Effort | Impact | In plan? |
-|--------|----------|------------------------|--------|--------|----------|
-| <repo> | <what>   | <concrete change here> | Low    | High   | Yes (P1) |
-| <repo> | <what>   | does not fit: <reason> | -      | -      | No       |
-```
-Roll the high-impact + low/med-effort survivors into the Step 4 plan as band-A items.
+## Step 0: BEST-PRACTICES
 
-## Step 0b: DRIFT  -  upstream-derived skill check
+Do not copy features blindly. Identify the domain, research the best-in-class (through `ai-analyst-toolkit` skills when enabled), record each candidate with its source, benefit, concrete adaptation to OUR repo, effort and impact, and discard what does not fit with the reason stated. Procedure and band-A table: `sweep.md` "Step 0".
 
-Some skills/components in this project (or in the marketplace plugins it ships) were derived from an upstream source. Upstream keeps evolving  -  it fixes bugs and adds features. This step detects upstream drift so we can decide whether to pull the improvements back.
+## Step 0b: DRIFT  -  upstream-derived skill check
 
 Rules that hold for every entry:
 - The upstream mapping is **configuration, never hardcoded**: `global.derivedSkillSources` in `~/.claude/multi-agent-preferences.json`. Missing or empty -> **skip** and report "no derived-skill sources configured". Never invent a source.
 - **The plugin cache is a mirror, not the authority.** Never let the cache alone produce an "up to date" verdict; report it as **`unverified (cache only)`**. An unreachable upstream is recorded as "upstream unreachable" and the run continues.
 - Each drifted entry becomes a band-D plan item. Do not auto-apply upstream changes  -  they go through Step 5 approval like everything else, and after porting, bump the entry's `derivedFromVersion`.
 
-Full procedure: `$HOME/.claude/multi-agent-refs/refactor/drift.md`. Read it when `global.derivedSkillSources` has at least one entry (entry schema, source resolution order, version manifest, comparison, band-D table).
+Full procedure: `$HOME/.claude/multi-agent-refs/refactor/drift.md`. Read it when `global.derivedSkillSources` has at least one entry.
 
-## Step 0c: DEV-TOOLKIT  -  current MCP practice for the companion toolkit
+## Step 0c: DEV-TOOLKIT
 
-The pipeline's hands on devices and browsers are MCP tools served by a companion repo (`multi-agent-toolkit-mcp`): Phase 3 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.
+Audit the companion `multi-agent-toolkit-mcp` repo against current MCP practice. Resolution is configuration first, never a hardcoded path; skip when nothing resolves or `enabled` is false. Read `$HOME/.claude/multi-agent-refs/refactor/toolkit-research.md` before running this step.
 
-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/toolkit-research.md`. Read it before running this step.
+## Step 0d: RUN-ERRORS
 
-## Step 0d: RUN-ERRORS  -  what the pipeline actually failed on
+Read `$HOME/.claude/logs/multi-agent/errors-ledger.jsonl`. Missing, unreadable or empty means skip band F silently  -  it is additive signal, never a gate. With a focus area, still read it. A tag that stopped recurring after a version bump is resolved: report it, do not re-raise it. Never quote a user's identity as blame. Read `$HOME/.claude/multi-agent-refs/refactor/run-errors.md` when the ledger exists.
 
-Before speculating about improvements, read what real runs already failed on. When usage logging is enabled, every terminated run appends its errors to a local ledger at `$HOME/.claude/logs/multi-agent/errors-ledger.jsonl`. A missing, unreadable or empty ledger means skip band F silently  -  it is additive signal, never a gate. If `$ARGUMENTS` names a focus area, still read the ledger  -  a recurring run error in that area is the strongest possible signal. A tag that stopped recurring after a version bump is resolved: report it, do not re-raise it. Never quote a user's identity as blame.
-
-Full procedure: `$HOME/.claude/multi-agent-refs/refactor/run-errors.md`. Read it when the ledger exists (record shape, grouping and ranking, transcript mining, band-F table).
-
-## Step 0e: BACKLOG  -  friction this pipeline already noticed
-
-Every other band in this command derives its findings from scratch, which is right for a sweep and has one consequence nobody chose: a friction noticed mid-task is gone by the next run unless it was fixed within the hour. Most are not, because stopping mid-task to fix them is the wrong call. So they are written down when noticed and decided here.
+## Step 0e: BACKLOG
 
 ```bash
 node "$HOME/.claude/scripts/observations.mjs" scan --status open --json
 ```
 
-Exit 3 is `SCAN BROKEN`  -  files on disk, none parsed. That is a broken reader, not an empty queue: halt the band and say so rather than reporting "0 open".
-
-Split every open observation into actionable / sibling-propagation / to-decline, and resolve the sibling surfaces mechanically with `skill-siblings.mjs`, never from memory  -  a command is authored in `commands/`, mirrored into `skills/shared/core/`, and installed again into three host trees, so a fix applied to one copy drifts from the rest with every gate still green. Output as plan band G, same table shape as the other bands.
-
-`/multi-agent:refactor backlog` runs this band alone. The full sweep is unchanged and still includes it. Buckets, the status vocabulary, why `parked` needs a named unblocking event, and how to write an observation: `$HOME/.claude/multi-agent-refs/refactor/observations.md`.
+Exit 3 is `SCAN BROKEN`  -  files on disk, none parsed. Halt the band and say so rather than reporting "0 open". Split every open observation into actionable / sibling-propagation / to-decline, and resolve sibling surfaces mechanically with `skill-siblings.mjs`, never from memory. Output as plan band G. `/multi-agent:refactor backlog` runs this band alone. Buckets, statuses and how to write an observation: `$HOME/.claude/multi-agent-refs/refactor/observations.md`.
 
 ## Step 1: SCAN
 
-```
-- file count, LOC (cloc or wc -l)
-- package.json / Package.swift / build.gradle analysis
-- dependency count (runtime vs dev)
-- Is there a CI/CD pipeline? (.github/workflows/, fastlane/, Makefile)
-- Is there test infrastructure? How many tests? Coverage?
-- Is a linter/formatter config in place?
-- Do README, LICENSE, SECURITY.md, CHANGELOG.md exist?
-- Git state: branch count, last commit date, tags
-```
+Walk files, LOC, manifests, dependencies, CI, tests, linters, repo docs and git state (`sweep.md` "Step 1").
 
 ## Step 2: ANALYZE  -  10 categories + BUG HUNT
 
-### 2a. 10 categories (quality lens)
-
-| # | Category | What to check |
-|---|----------|---------------|
-| 1 | **Architecture** | Layer separation, modularity, SOLID, dependency direction |
-| 2 | **Code Quality** | Naming, magic numbers, dead code, complexity, DRY |
-| 3 | **Security** | Hardcoded secrets, input validation, Keychain, ATS, ATT |
-| 4 | **Tests** | Coverage, test pyramid, edge cases, mock/stub quality |
-| 5 | **CI/CD** | Build matrix, lint job, release automation, artifact caching |
-| 6 | **Docs** | README quality, JSDoc / Swift docs, API docs, CHANGELOG |
-| 7 | **Performance** | Bundle size, lazy loading, memory leaks, unnecessary re-renders |
-| 8 | **Accessibility** | a11y labels, tap targets, VoiceOver, Dynamic Type |
-| 9 | **Dependency Management** | Outdated deps, vulnerability scan, lockfile, version pinning |
-| 10 | **DevEx** | Onboarding time, script ergonomics, error messages, debug tooling |
-
-### 2b. BUG HUNT (real defects, not scores)
-
-Category scores measure quality; they do not find the bug that ships. Run an explicit defect hunt IN ADDITION to the scoring:
-
-- Dispatch focused review agents (Agent tool, `code-reviewer` persona where available) over the highest-risk surfaces: recently changed files, error/edge-path handling, concurrency, external input parsing, resource cleanup, off-by-one boundaries.
-- For each candidate defect, record: **file:line**, the concrete failure scenario (inputs/state -> wrong output/crash), and severity.
-- **Verify before reporting**: only list a bug you can trace to a real failure path; drop the plausible-but-unprovable ones. Match the bar you would apply to a third party's code.
-
-Output (plan band B) - every confirmed defect becomes a P0/P1 item:
-```
-| # | Severity | File:line | Defect | Failure scenario |
-|---|----------|-----------|--------|------------------|
-| 1 | Blocking | src/x.ts:42 | unchecked nil deref | empty response -> crash |
-```
-
-Improvement areas surfaced by 2a that are not outright bugs become band-C items.
+2a scores the 10 categories (`sweep.md` "Step 2a"). 2b runs an explicit defect hunt IN ADDITION to the scoring (`sweep.md` "Step 2b"). **Verify before reporting**: only list a bug you can trace to a real failure path with `file:line` and a concrete failure scenario; drop the plausible-but-unprovable ones, at the bar you would apply to a third party's code. Confirmed defects are band B (P0/P1); non-bug gaps from 2a are band C.
 
 ## Step 3: SCORE
 
-Each category is scored out of 10. Output:
+Each category /10, total /100 (`sweep.md` "Step 3").
 
-```
-+---------------------+-------+
-| Category            | Score |
-+---------------------+-------+
-| Architecture        | 9/10  |
-| Code Quality        | 8/10  |
-| Security            | 9/10  |
-| Tests               | 7/10  |
-| CI/CD               | 8/10  |
-| Docs                | 7/10  |
-| Performance         | 9/10  |
-| Accessibility       | 6/10  |
-| Dependency Mgmt     | 8/10  |
-| DevEx               | 9/10  |
-+---------------------+-------+
-| TOTAL               | 80/100|
-+---------------------+-------+
-```
+## Step 4: PLAN
 
-## Step 4: PLAN  -  one merged, prioritized table
-
-Merge all five bands into a single plan. Tag each row with its band (A best-practice / B bug / C improvement / D drift / E multi-agent-toolkit) so the source is visible.
-
-```
-| # | Priority | Band | Category | Item | Impact |
-|---|----------|------|----------|------|--------|
-| 1 | P0 | B | Security | Remove hardcoded API key (src/x:12) | Critical |
-| 2 | P0 | B | Tests | Fix nil-deref on empty response (src/y:42) | High |
-| 3 | P1 | A | CI/CD | Adopt matrix build (adapt: .github/workflows/ci.yml) | Medium |
-| 4 | P1 | D | Skills | Port upstream <plugin> 0.3.0 fixes into <localPath> | Medium |
-| 5 | P1 | E | Toolkit | Add read-only annotations to the multi-agent-toolkit device tools | Medium |
-| 6 | P2 | C | DevEx | Rename npm scripts for consistency | Low |
-```
-
-Priority levels:
-- **P0**: bugs, security holes, broken functionality  -  must fix
-- **P1**: clear quality improvement or high-value adopted best-practice / drift port  -  should be done
-- **P2**: nice-to-have  -  if time allows
+One merged table, every row tagged with its band, priorities P0 / P1 / P2 (`sweep.md` "Step 4").
 
 ## Step 5: ASK  -  user approval
 
-After showing the plan, ask:
-
 > "Found X items (P0: N, P1: M, P2: K) across bugs, best-practices, improvements, upstream drift, and multi-agent-toolkit practice. Should I start the work?"
 
-Options:
-- "Yes, do all"
-- "Only P0"
-- "P0 + P1 only"
-- "Only bugs (band B)"
-- "Only the multi-agent-toolkit (band E)"
-- (the user may pick specific items)
+Options: "Yes, do all" / "Only P0" / "P0 + P1 only" / "Only bugs (band B)" / "Only the multi-agent-toolkit (band E)" / specific items.
 
 **Never start the work without approval.**
 
 ## Step 6: IMPLEMENT
 
-Apply the approved items one by one:
-
-1. For each item:
-   - apply the change (for band D, port the upstream diff into `localPath`, then bump that entry's `derivedFromVersion` in preferences)
-   - band-E items are applied inside the toolkit repo, never mirrored here: edit there, re-run its gates (`node --check`, the `tools/list` handshake, advertised tool count matching reality), then commit there with that repo's own convention. Publishing is `/multi-agent:sync` Step 3d  -  do not publish from this step.
-   - run the relevant tests
-   - on success, move to the next
-   - on failure, roll back and notify the user
-2. After all changes are done:
-   - run the full lint + test suite
-   - on success, commit
-
-Commit format: `refactor(scope): {short description}`
+Apply approved items one by one, testing each and rolling back on failure (`sweep.md` "Step 6"). Band-E items are applied and committed inside the toolkit repo, never mirrored here, and never published from this step. Commit format: `refactor(scope): {short description}`.
 
 ## Step 7: VERIFY
 
-```bash
-# Lint
-npm run lint 2>/dev/null || swift build 2>/dev/null
-
-# Test
-npm test 2>/dev/null || swift test 2>/dev/null || xcodebuild test 2>/dev/null
-
-# Result
-echo "Lint: PASS/FAIL"
-echo "Test: PASS/FAIL (X/Y passed)"
-```
-
-If any band-E item was applied, verify the toolkit repo too  -  syntax check every file it loads, handshake the server and confirm `tools/list` still answers, and confirm the advertised tool counts (README header, `package.json` description) match the count the server reports.
+Full lint + test must pass; band-E work also re-verifies the toolkit (`sweep.md` "Step 7").
 
 ## Step 8: ASK SYNC
 
-After every approved item is applied, ask:
-
 > "Work is complete. Should I run /multi-agent:sync?"
 
 Options:
@@ -254,18 +107,4 @@ Options:
 
 ## Focus filter
 
-If $ARGUMENTS is set, focus on that band/category only:
-
-| Input | Focus |
-|-------|-------|
-| `bugs` | Bug hunt only (band B) |
-| `best-practices` | Field research + adapted plan only (band A) |
-| `drift` | Upstream derived-skill drift only (band D) |
-| `multi-agent-toolkit` | Companion MCP toolkit research + audit only (band E) |
-| `security` | Security analysis only |
-| `tests` | Test coverage and quality only |
-| `performance` | Performance optimisation only |
-| `docs` | Docs only |
-| `ci` | CI/CD pipeline only |
-| `deps` | Dependency updates only |
-| (empty) | Everything (default) |
+If $ARGUMENTS is set, focus on that band/category only; the mapping is `sweep.md` "Focus filter". Empty runs everything.