@mmerterden/multi-agent-pipeline 20.36.0 → 20.37.1

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

@@ -30,6 +30,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
@@ -40,9 +47,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
@@ -51,189 +56,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
@@ -252,11 +111,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/commands/multi-agent/jira/SKILL.md

@@ -14,7 +14,7 @@ confirm: none
 
 **Input**: $ARGUMENTS
 
-Fully interactive. Only one optional flag: `autopilot`.
+Fully interactive; one optional flag: `autopilot`.
 
 ## Flow
 
@@ -56,35 +56,20 @@ printf 'Authorization: Bearer %s\n' "$TOKEN" | curl -s -H @- \
 2. `status` → "In Progress" > "In Review" > "To Do" > others
 3. `created` → newest first
 
-**Format** (priority badge prefix, status suffix):
-```
-[3/4] Pick issue (24 found, priority-sorted):
-  > [Blocker] PROJ-12345  -  Login crash on iOS 17           (In Progress)
-    [Critical] PROJ-12340  -  Payment fails for refunds       (In Review)
-    [High]    PROJ-12338  -  Dark mode polish                 (To Do)
-    [Medium]  PROJ-12330  -  Add empty state                  (To Do)
-    [ - ]       PROJ-12300  -  Refactor LoginViewModel          (To Do)
-```
+**Format**: priority badge prefix, status suffix. Example list and the
+maturity shape: `$HOME/.claude/multi-agent-refs/jira/picker-detail.md`; read it
+before rendering the list.
 
 - AskUserQuestion (multiSelect=false)
 - Output: selected `KEY` (e.g. `PROJ-12345`)
 
-> **Rule**: Sort by priority for visibility, but don't force the user. No "P1 must come first" coercion  -  just signal.
+> **Rule**: the sort signals priority; it never forces a pick.
 
 ### [3.5/4] Maturity check (auto)
 
-After issue selection, inspect `maturity` from `~/.claude/lib/issue-fetcher.sh`:
+After issue selection, inspect `maturity` (`score`, `blockers`, `warnings`, `summary`) from `~/.claude/lib/issue-fetcher.sh`.
 
-```jsonc
-"maturity": {
-  "score":    0..100,
-  "blockers": ["status_closed", "already_resolved", "description_empty"],
-  "warnings": ["short_description", "no_repro_steps", "no_acceptance_criteria", "description_empty_parent_available"],
-  "summary":  "..."
-}
-```
-
-> **Empty description → parent candidate**: development sub-tasks are often filed with no description of their own, with the real requirements on the parent issue. Before scoring, `issue-fetcher.sh` fetches the issue's `parent` (single hop, no chasing the parent's parent). If the issue's own description is empty and the parent's isn't, it does **not** auto-substitute  -  it exposes `descriptor.parentKey` + `descriptor.parentDescription` as a candidate and adds `description_empty_parent_available` to `warnings` (not `blockers`) instead of the plain `description_empty` blocker. If the parent is also empty or unreachable, `description_empty` still blocks exactly as before.
+> **Empty description → parent candidate**: the fetcher never auto-substitutes a parent's description; it offers it as `description_empty_parent_available` (a warning). How the candidate is found: `jira/picker-detail.md`.
 >
 > When `description_empty_parent_available` is present, ask a tailored question instead of the generic "Continue?" below:
 > - `question` (outputLanguage): "Bu issue'nun (`{KEY}`) açıklaması boş, ama parent'ın (`{parentKey}`) açıklaması var. Parent'ın açıklamasından devam edilsin mi?" / "This issue's (`{KEY}`) description is empty, but its parent (`{parentKey}`) has one. Continue using the parent's description?" - show a short excerpt of `parentDescription` for context.
@@ -94,7 +79,7 @@ After issue selection, inspect `maturity` from `~/.claude/lib/issue-fetcher.sh`:
 > - **Decline** → same as a `description_empty` blocker: halt, advise fixing the issue's own description.
 > - **Autopilot**: auto-accepts "Use parent's description" (same "warnings auto-continue" rule as any other warning), logs the auto-accept + parent key to `agent-log.md`.
 >
-> **Sibling sub-tasks**: the fetcher also reads the parent's other sub-tasks into `descriptor.relatedIssues[]`. Show them as their own labelled block, never substituted into `description`. When the issue's description and the parent's are both empty but a sibling has content, `description_empty_sibling_available` replaces the `description_empty` blocker  -  same question, sibling key. Contract: `$HOME/.claude/multi-agent-refs/features/jira-context.md`.
+> **Sibling sub-tasks**: the fetcher also reads the parent's other sub-tasks into `descriptor.relatedIssues[]`. Show them as their own labelled block, never substituted into `description`. Both descriptions empty but a sibling has content: `description_empty_sibling_available` replaces the blocker  -  same question, sibling key. Contract: `$HOME/.claude/multi-agent-refs/features/jira-context.md`.
 
 | Outcome | Behavior |
 |---|---|
@@ -111,14 +96,12 @@ with a summary; an autopilot run with `prefs.global.maturityFollowup.autopilotCo
 on posts ONE comment on the item asking for what is missing, then halts on the circuit
 breaker with `state.waitingFor = "maturity"` so `resume` re-enters THIS step with the item
 re-fetched. Both defaults keep today's behaviour: the comment is off, the halt is the halt.
-An edit is a reason to re-check, never proof the gap closed - the check re-runs on the new
-content, and only a DIFFERENT gap set ever earns a second comment. Read the item's existing
-comments FIRST and derive the prior ask from the newest one of ours (`priorFromComments`):
-a scan is a new run with a fresh state file, so state alone would make every scan a first ask.
+Only a DIFFERENT gap set ever earns a second comment; read the item's existing comments
+first (`priorFromComments`, detail in `jira/picker-detail.md`).
 
-> **Resolution check**: If Jira `resolution` is set (`Fixed`, `Done`, `Won't Do`, `Resolved`...), `already_resolved` is added  -  the issue was closed already. To reopen, clear `resolution` in Jira first.
+> **Resolution check**: any set Jira `resolution` (`Fixed`, `Done`, `Won't Do`...) adds `already_resolved`. To reopen, clear `resolution` in Jira first.
 
-> **fixVersions**: When `descriptor.fixVersions` is non-empty (e.g. `["v1.48.0"]`) and a matching `release/v1.48.0` branch exists in `prefs.projects[*].branches`, suggest that branch. Otherwise fall back to `develop`/cwd current.
+> **fixVersions**: When `descriptor.fixVersions` is non-empty and a matching `release/<version>` branch exists in `prefs.projects[*].branches`, suggest that branch. Otherwise fall back to `develop`/cwd current.
 
 The fetcher renders `maturity.summary` in `prefs.global.outputLanguage`; every other descriptor field is machine-readable and stays English.
 
@@ -128,21 +111,9 @@ The fetcher renders `maturity.summary` in `prefs.global.outputLanguage`; every o
 
 ## Pipeline launch
 
-1. **Write picker state** to `/tmp/multi-agent-picker-{taskId}.json`:
-   ```json
-   {
-     "taskId":"PROJ-12345-{timestamp}",
-     "shortId":<int>,
-     "branch":"<feature|bugfix>/PROJ-12345",
-     "baseBranch":"develop",
-     "issueRef":{...},
-     "primary":{"name":"...","cloneUrl":"...","provider":"github|bitbucket"},
-     "extras":[{...}],
-     "worktreeRoot":"~/.worktrees/PROJ-12345-{timestamp}",
-     "commitType":"<feat|fix>",
-     "identity":{"name":"...","email":"..."}
-   }
-   ```
+1. **Write picker state** to `/tmp/multi-agent-picker-{taskId}.json` (`taskId`,
+   `shortId`, `branch`, `baseBranch`, `issueRef`, `primary`, `extras`,
+   `worktreeRoot`, `commitType`, `identity`; full shape in `jira/picker-detail.md`).
 
 2. **Bridge to agent-state.json v2.1.0**  -  picker → Phase 0:
    ```bash
@@ -155,8 +126,7 @@ The fetcher renders `maturity.summary` in `prefs.global.outputLanguage`; every o
    ~/.claude/lib/multi-repo-pipeline.sh prepare /tmp/multi-agent-picker-{taskId}.json
    ```
 
-4. **Phase 0 entry**  -  pipeline reads the bridged `agent-state.json` and skips
-   redundant Jira/GitHub fetches.
+4. **Phase 0 entry**  -  reads the bridged `agent-state.json`, no refetch.
 
 `autopilot` arg → start with `MULTI_AGENT_AUTOPILOT=1`.
 

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

@@ -21,12 +21,13 @@ Lets you switch to the task branch for manual testing in Xcode before the PR is
 2. **Check state**  -  the task must have completed Phase 2 (Dev) or later
    - Phase < 3 → "No code 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 main repo'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/{JIRA-KEY}-{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 main repo 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.
 
    Then mark the tracker as waiting (this CONTINUES the task's existing `tracker-state.json`; never `init` here - see `$HOME/.claude/multi-agent-refs/tracker-contract.md` "Continuation runs"). On Claude Code in a fresh session, first rebuild the TaskList from state per the same contract:
    ```bash
@@ -49,12 +50,16 @@ Lets you switch to the task branch for manual testing in Xcode before the PR is
      ❌ "fix: ..." → recreate the worktree and apply the fix
    ```
 
-5. **Wait for the user's reply**
+5. **Wait for the user's reply**, 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 main repo. 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 main repo 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. **Branch on the answer**:
    - **OK** → first write `$WORKTREE/.pipeline/manual-test.json` (one entry per acceptance criterion from the analysis doc test plan, the plan tasks, or the user's own words):
      ```json
      {"criteria":[{"spec":"<quote>","source":"analysis 15.2 | plan task 3 | user","observed":"<what was seen>","verdict":"pass|fail|not-tested","reason":"<required when not-tested>","screenshot":"<path or null>"}],"verdict":"passed|failed"}
      ```
-     then run `node $HOME/.claude/scripts/evidence-gate.mjs --claim manual --status passed --evidence "$WORKTREE/.pipeline/manual-test.json"`, adding `--require-screenshot` when `state.visualEvidence.required` is true (a passing criterion then has to name a screenshot that is actually on disk). Exit 1 means the "ok" is not accepted: name the criterion that is missing evidence and wait for the next reply. Exit 0 → `phase-tracker.sh update 3 completed` + `phase-tracker.sh meta 3 Result "local test passed (user)"`, recreate the worktree, continue to Phase 4. Full contract: `$HOME/.claude/multi-agent-refs/phases/phase-3-review.md` step 5, whose "UI flow video, when Phase 2 produced none" block applies here too: invoked standalone, this command is the only phase that ran, so if `visualEvidence.required` is set and `visualEvidence.video.file` is empty, the recording has to happen here or nowhere.
-   - **Fix needed** → `phase-tracker.sh now 3 "applying fix: <summary>"`, recreate the worktree, apply the fix
+     then run `node $HOME/.claude/scripts/evidence-gate.mjs --claim manual --status passed --evidence "$WORKTREE/.pipeline/manual-test.json"`, adding `--require-screenshot` when `state.visualEvidence.required` is true (a passing criterion then has to name a screenshot that is actually on disk). Exit 1 means the "ok" is not accepted: name the criterion that is missing evidence and wait for the next reply. Exit 0 → `phase-tracker.sh update 3 completed` + `phase-tracker.sh meta 3 Result "local test passed (user)"`, continue to Phase 4. Full contract: `$HOME/.claude/multi-agent-refs/phases/phase-3-review.md` step 5. The UI flow video rule in `$HOME/.claude/multi-agent-refs/audit-guide.md` "Phase 3 evidence flows" applies here too: invoked standalone, this command is the only phase that ran, so if `visualEvidence.required` is set and `visualEvidence.video.file` is empty, the recording has to happen here or nowhere.
+   - **Fix needed** → `phase-tracker.sh now 3 "applying fix: <summary>"`, apply the fix in the restored worktree