@mmerterden/multi-agent-pipeline 19.1.4 → 20.1.0

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

@@ -65,8 +65,8 @@ Run every step automatically:
 ```
 Step 0: DOCTOR      doctor.mjs  -  exit 2 or 4 stops the sync
 Step 1.5: DETECT    Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 60 sub-command skills)
-Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + 60 specs as refs + 8 agent TOML)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 58 sub-command skills)
+Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + 57 specs as refs + 8 agent TOML)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub, bash -n on all sh)
 Step 3c: PLUGINS    pipeline shared/external -> multi-agent-plugins marketplace (rebuild knowledge/,
                      bump changed plugins' patch version, commit + push the plugins repo)
@@ -90,7 +90,7 @@ Step 0 gate rules and why: `features/doctor.md`.
    - `copilot-instructions.md`: general development instructions + pipeline summary section
    - `multi-agent-pipeline/pipeline/`: generic open-source version (NO personal data)
 3. **Sync the shared sections** (Claude ↔ Copilot):
-   - Pipeline entries table (base / :local / :autopilot / :local-autopilot) + the Full-or-Short depth question
+   - Pipeline entries table (base / :autopilot)
    - Project detection (URL-based + cwd-based)
    - Figma pipeline flow
    - Git conventions (author, branch, commit format)
@@ -494,16 +494,15 @@ same 56 specs as reference files rather than as peer skills, via Step 2b -  see
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**60 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**58 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
 analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off, autopilot-on,
 autopilot-status, build-optimize, channels, complaint-analysis, create-jira,
 design-check, diff-explain, doctor, feedback, forget, garbage-collect, graph, help,
-ios-coding-standard, issue, jira, kill, language, local, local-autopilot, log,
-manual-test, model, prune-logs, prune-prompts, purge, refactor, resume, resume-local,
-review, review-analysis, review-issue, review-jira, route-off, route-on, route-status,
-routines, save, scan, search, setup, stack, status, steer, store-ready, sync, test,
+ios-coding-standard, issue, jira, kill, language, log,
+manual-test, model, prune-logs, prune-prompts, purge, refactor, resume, review, review-analysis, review-issue, review-jira, route-off, route-on, route-status,
+routines, save, scan, search, security-review, setup, stack, status, steer, store-ready, sync, test,
 test-accessibility, test-dark-mode, test-dynamic-type, test-screenshots,
 testflight-validation, uninstall, update
 ```

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

@@ -6,6 +6,8 @@ argument-hint: "[locale]  -  boş = tr; örn. tr | en | de | ar"
 
 # /multi-agent:test-screenshots  -  Locale screenshot set
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 Fixed-scenario alias, **parameterised by locale**. The scenario is pinned; the
 language is not, because one command per language would put a parameter in a name.
 

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

@@ -7,6 +7,8 @@ argument-hint: "[--dry-run] [--all-data] [--claude] [--copilot] [--target=<path>
 
 # multi-agent uninstall  -  Token-Preserving Uninstall
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 Uninstalls the pipeline itself from the system. **This is different from `:purge`:**
 
 | Command | What it removes |

package/pipeline/lib/repo-hygiene.sh

@@ -8,7 +8,7 @@
 # (.multi-agent/). Only the first was ever excluded, and only by a one-line
 # guard duplicated across two phase docs and gc-worktrees.sh. The other two
 # were never excluded anywhere, which is invisible in worktree mode (the
-# worktree is deleted) and permanent in --local mode (nothing deletes it).
+# worktree is deleted) and permanent with a local workspace (nothing deletes it).
 #
 # Functions:
 #   ma_hygiene_ensure_exclusions <repo-root>   Write the managed block into

package/pipeline/multi-agent-refs/analysis/render.md

@@ -64,7 +64,7 @@ Phase 3.2 produced the list. Sort every entry and act:
 | Bucket | Meaning | Action |
 |---|---|---|
 | A. Not searched | The evidence is reachable and this run did not look | Run the search; it closes, and never becomes a question |
-| B. The user knows | Channel scope, which service backs a screen, what is in scope | Ask, `AskUserQuestion`, at most 4 per call |
+| B. The user knows | Channel scope, which service backs a screen, what is in scope | Ask, `AskUserQuestion` per `picker-contract.md`, at most 4 per call |
 | C. External | Final copy, a legal basis, a contract nobody has written | Record as `AS-NN` in Section 20 |
 
 **Bucket A must be empty before Phase 3.5.** A gap reaches C only with a stamp:

package/pipeline/multi-agent-refs/analysis/resolve.md

@@ -6,7 +6,7 @@
 
 ## New Locked decisions (this command)
 
-1. **One question per `AskUserQuestion` call.** Never batch Section 20 rows. Sequential resolution keeps each decision explicit and traceable.
+1. **One question per `AskUserQuestion` call**, shaped by `picker-contract.md`. Never batch Section 20 rows. Sequential resolution keeps each decision explicit and traceable.
 2. **Up to 3 source-labeled candidates plus Defer = 4 options max.** Each candidate's `description` carries its source label: `From evidence - <doc section / citation>`, `From repo - <file:line>`, `AI reasoned - <one-line rationale>`. The auto-provided Other accepts free text and stop tokens.
 3. **Three sources, never blended.**
    - **From evidence**: the answer is already derivable from the doc's own sections and their citations (Sections 5, 6, 9, 13, 21) or from cached `state.analysisSpec.evidence.*` when the session still holds it. Cite the section or evidence bucket.

package/pipeline/multi-agent-refs/analysis/synthesis.md

@@ -34,7 +34,7 @@ synthesizedSections = {
 
 #### Phase 2a - Pass B preview (Locked 25)
 
-Before Pass B renders any file, present the resolved convention table to the user via `AskUserQuestion`. The table is one row per concept, one column per selected platform.
+Before Pass B renders any file, present the resolved convention table to the user via `AskUserQuestion` (`picker-contract.md`). The table is one row per concept, one column per selected platform.
 
 Example (iOS + Android selected):
 

package/pipeline/multi-agent-refs/analysis-template.md

@@ -830,7 +830,7 @@ Framework: iOS XCUITest (`waitForExistence`, identifier-driven); Android Compose
 
 ### 15.7 Manuel test senaryoları / Manual test scenarios
 
-The scenarios a person runs by hand. Same format the pipeline already posts as the Jira test-scenario comment (`/multi-agent:resume-local`), defined once and read by both. Omitted entirely when the feature has none (Locked 2); never rendered as an empty table.
+The scenarios a person runs by hand. Same format the pipeline already posts as the Jira test-scenario comment (`/multi-agent:resume`), defined once and read by both. Omitted entirely when the feature has none (Locked 2); never rendered as an empty table.
 
 Each row is executable by someone who did not write the feature: no "verify it works", no implied setup. Cover the happy path, at least one boundary, and every failure mode that reaches the user - the same four-way split Locked 30 requires of unit tests.
 

package/pipeline/multi-agent-refs/component-dispatch.md

@@ -7,11 +7,10 @@
 - [Subphase contract (dispatch-layer owned)](#subphase-contract-dispatch-layer-owned)
 - [Multi-repo report](#multi-repo-report)
 - [Failure + resume](#failure-resume)
-- [Short-run behaviour](#short-run-behaviour)
 - [Cross-CLI behaviour (intentional divergence)](#cross-cli-behaviour-intentional-divergence)
 <!-- /toc -->
 
-> **TLDR**  -  When `taskType === "component"` (Figma URL in task description or instruction-driven figma workflow), multi-agent Phase 3 **does not run the TDD loop**. It delegates the entire phase to the enabled `ai-<platform>-toolkit` **marketplace plugin's** component skill (`create-component`, falling back to `create-ui-component`) via the Skill tool. Implementation lives in the plugin; multi-agent's job is classification, dispatch, and state report. The pipeline no longer bundles its own `figma-to-component` orchestrator  -  component skills live in one place, the plugin marketplace.
+> **TLDR**  -  When `taskType === "component"` (Figma URL in task description or instruction-driven figma workflow), multi-agent Phase 2 **does not run the TDD loop**. It delegates the entire phase to the enabled `ai-<platform>-toolkit` **marketplace plugin's** component skill (`create-component`, falling back to `create-ui-component`) via the Skill tool. Implementation lives in the plugin; multi-agent's job is classification, dispatch, and state report. The pipeline no longer bundles its own `figma-to-component` orchestrator  -  component skills live in one place, the plugin marketplace.
 
 This doc is referenced from `$HOME/.claude/multi-agent-refs/phases/phase-2-dev.md`. Keeping it separate lets `phase-2-dev.md` remain tight (it's already the largest phase doc) and gives the orchestrator-report contract a stable URL for both Claude-side and Copilot-side implementations.
 
@@ -79,13 +78,12 @@ Emit `→ dispatching create-component <componentName>` via the progress contrac
 
 - `figmaUrl`  -  primary argument (the plugin skill's `<figma-url>`)
 - the component name + the analysis Section 6 (Bileşen Envanteri) row + Section 13.1 conventions as context (the plugin skill does not re-read the pipeline's analysis doc on its own  -  pass what it needs)
-- `mode`  -  `"dev"` vs `"full"`, from `state.onlyDevelop`, so the plugin can elide tests/wiki on a Short run
 
 Plugin skills are user-facing lifecycle skills; they do **not** accept an `agentState` path and do **not** write `agent-state.json`. State tracking therefore moves to the dispatch layer (next section).
 
 ## Subphase contract (dispatch-layer owned)
 
-Because the plugin skill does not write pipeline state, **multi-agent's dispatch layer owns `state.phases["3"].subphases[]`**, not the skill. On dispatch, seed one coarse component-build subphase; on return, finalize it:
+Because the plugin skill does not write pipeline state, **multi-agent's dispatch layer owns `state.phases["2"].subphases[]`**, not the skill. On dispatch, seed one coarse component-build subphase; on return, finalize it:
 
 ```json
 {
@@ -115,17 +113,11 @@ Multi-agent does **not** split the component task into per-repo Phase 2 runs  -
 
 On failure (the plugin skill returns an unrecoverable build/test error, or the dispatch hits retry cap):
 
-1. The dispatch layer persists `{error, buildLog, testLog}` to `state.phases["3"].errors[]`.
-2. Multi-agent increments `state.phases["3"].retryCount`.
+1. The dispatch layer persists `{error, buildLog, testLog}` to `state.phases["2"].errors[]`.
+2. Multi-agent increments `state.phases["2"].retryCount`.
 3. Retry re-invokes the plugin skill (it is idempotent on an existing component; it reconciles rather than duplicating). There is no bundled `phase-<N>` resume anymore.
 4. Hard kill at `retryCount === 3` → surface the errors to the user, halt Phase 2. Do not loop indefinitely.
 
-## Short-run behaviour
-
-When the Phase 0 Step 7.5 depth picker answered Short (`state.onlyDevelop === true`), the dispatch layer passes `mode: "dev"` so the plugin skill can elide unit tests and wiki (structural + snapshot still required; wiki deferred to Phase 5). If the plugin does not honor a `mode` hint, dispatch simply skips the post-build wiki step itself.
-
-Phase 3 runs in a Short run as it does in a Full one, and its reviewer count is **not** Phase 3's concern  -  the Step 1.77 scope gate decides that from diff risk, independently of `mode`. What the dispatch layer owes Phase 4 is the record of which plugin skill it delegated to, appended to `state.telemetry.skillCalls[]`, so the review can check the delivered component against the criteria that skill imposes.
-
 ## Cross-CLI behaviour (intentional divergence)
 
 Component dispatch is **no longer byte-identical across CLIs** and that is by design (see `cross-cli-contract.md` section 1.1):
@@ -133,4 +125,4 @@ Component dispatch is **no longer byte-identical across CLIs** and that is by de
 - **Claude Code**: dispatches to the enabled `ai-<platform>-toolkit` marketplace plugin via the Skill tool (this doc).
 - **Copilot CLI**: has no plugin loader; it continues to use its standalone `~/.copilot/skills/figma-*` skill copies (frozen fallback). Copilot's resolution + progress lines follow those local skills.
 
-What still MUST match across CLIs: the `taskType === "component"` classification, the `state.phases["3"].subphases[]` shape the dispatch layer writes, and the Short-run elision semantics. Figma-skill *inventory* parity is no longer enforced. `smoke-cross-cli-behavior.sh` asserts only the classification + state-shape axis for components.
+What still MUST match across CLIs: the `taskType === "component"` classification, the `state.phases["2"].subphases[]` shape the dispatch layer writes, and the Short-run elision semantics. Figma-skill *inventory* parity is no longer enforced. `smoke-cross-cli-behavior.sh` asserts only the classification + state-shape axis for components.

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

@@ -1,7 +1,7 @@
 # Cross-CLI Contract (Claude Code · Copilot CLI · Codex CLI)
 
 <!-- toc -->
-- [1. Command Inventory (60 commands)](#1-command-inventory-60-commands)
+- [1. Command Inventory (58 commands)](#1-command-inventory-58-commands)
 - [2. Canonical Placeholder Vocabulary](#2-canonical-placeholder-vocabulary)
 - [2.6 Intentional structural divergence  -  thin dispatcher vs inlined orchestrator](#26-intentional-structural-divergence---thin-dispatcher-vs-inlined-orchestrator)
 - [2.7 One command, three different meanings: `/multi-agent:model`](#27-one-command-three-different-meanings-multi-agentmodel)
@@ -20,18 +20,18 @@
 
 ---
 
-## 1. Command Inventory (60 commands)
+## 1. Command Inventory (58 commands)
 
 ```
 analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off,
 autopilot-on, autopilot-status, build-optimize, channels, complaint-analysis,
 create-jira, design-check, diff-explain, doctor, feedback, forget,
 garbage-collect, graph, help, ios-coding-standard, issue, jira, kill,
-language, local, local-autopilot, log, manual-test, model, prune-logs,
-prune-prompts, purge, refactor, resume, resume-local, review,
+language, log, manual-test, model, prune-logs,
+prune-prompts, purge, refactor, resume, review,
 review-analysis, review-issue, review-jira, route-off, route-on,
 route-status, routines, save, scan, search,
-setup, stack, status, steer, store-ready, sync, test, test-accessibility,
+security-review, setup, stack, status, steer, store-ready, sync, test, test-accessibility,
 test-dark-mode, test-dynamic-type, test-screenshots, testflight-validation,
 uninstall, update
 ```
@@ -40,8 +40,8 @@ Categories:
 
 - **Interactive pickers** (single-purpose, not modes): `jira`, `issue`
 - **Issue generator** (one-shot, no worktree, asks type Task/Bug/Story, hard approval gate before create): `create-jira`
-- **Pipeline entries**: `autopilot`, `local`, `local-autopilot` (plus the bare `/multi-agent` in the dispatcher). Depth is not a command: `/multi-agent` and `local` ask Full or Short at Phase 0 Step 7.5; the two autopilot entries never ask and always run Full.
-- **Tail modes** (run the pipeline tail over already-done local work): `resume-local`
+- **Pipeline entries**: `autopilot` (plus the bare `/multi-agent` in the dispatcher). The phase set is a property of the command, and every mode runs its whole set.
+- **Tail path** (the pipeline tail over work already on a branch, no run behind it): `resume`
 - **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `steer`, `purge`, `uninstall`, `resume`, `review`, `review-jira`, `review-issue`, `analysis`, `analysis-resolve`, `complaint-analysis`, `build-optimize`, `channels`, `scan`, `search`, `diff-explain`, `garbage-collect`, `graph`, `prune-logs`, `prune-prompts`
 - **Local audits** (worktree only to build; no commit, push, PR or channels): `design-check`, `testflight-validation`, `ios-coding-standard`. `testflight-validation` additionally never invokes `altool --upload-app`  -  a validation run must not be able to ship a build by accident.
 - **Meta-ops**: `setup`, `sync`, `update`, `help`, `refactor`, `test`, `stack`, `manual-test`, `language`
@@ -86,7 +86,7 @@ Three rules make that work:
 > 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 the Short-run elision semantics. Resolution/routing is Claude-plugin vs Copilot-local-copy by design.
+What still MUST match across CLIs for component tasks: the `taskType === "component"` classification, the `state.phases["2"].subphases[]` shape the dispatch layer writes, and the Short-run elision semantics. Resolution/routing is Claude-plugin vs Copilot-local-copy by design.
 
 ### 1.2 Store-compliance skills
 
@@ -97,7 +97,7 @@ Two parallel shared/core skills under `pipeline/skills/shared/core/` wrap extern
 | `apple-archive-compliance` | `pipeline/skills/shared/core/apple-archive-compliance/` | `ios_app_store_audit` MCP tool (in `@mmerterden/multi-agent-toolkit-mcp` ≥ v3.0.0) | 18 (Apple ITMS + App Store Review Guidelines) |
 | `google-play-compliance` | `pipeline/skills/shared/core/google-play-compliance/` | bundletool + aapt2 + apksigner | 21 (4 categories: Technical / Security / Privacy / Hygiene) |
 
-Both skills are wired to 4 consumers: `/multi-agent:test "store-ready"` (primary), Phase 4 Security Auditor (`pipeline/agents/security-auditor.md`), `/multi-agent:review` + SKILL.md counterpart, `/multi-agent:channels` PR-body auto-augmentation. Contract enforced by `smoke-compliance-skills.sh`.
+Both skills are wired to 4 consumers: `/multi-agent:test "store-ready"` (primary), Phase 3 Security Auditor (`pipeline/agents/security-auditor.md`), `/multi-agent:review` + SKILL.md counterpart, `/multi-agent:channels` PR-body auto-augmentation. Contract enforced by `smoke-compliance-skills.sh`.
 
 ### 1.3 Figma-skill routing from multi-agent (superseded)
 
@@ -222,7 +222,7 @@ Phase 3 runs three reviewers everywhere, but the diversity those three buy is no
 same on every host. Copilot CLI gets cross-VENDOR disagreement for free: GPT-5.4 sits
 beside two Claude models. Claude Code and Codex each run a one-vendor panel - three
 Anthropic models on one, three OpenAI models on the other - so the same three-way
-agreement is weaker evidence there, and Phase 4 says so in the triage note on a
+agreement is weaker evidence there, and Phase 3 says so in the triage note on a
 borderline finding.
 
 Where the budget goes instead, when vendor diversity is unavailable:
@@ -367,11 +367,10 @@ Given the same user input, both CLIs must produce identical parsed state:
 | `#42` or bare `42` | `input.type = "github-issue-number"`, `input.issueNo = 42` |
 | Any other string | `input.type = "free-text"`, `input.summary = <string>` |
 
-Modifier flags are orthogonal and compose:
-- `autopilot`  -  skip confirmations
-- Short depth  -  init → dev → review → test → commit → report (Phase 0 Step 7.5 picker, not a flag)
-- `--local`  -  no worktree
-- Combinations: `--local autopilot`. Short plus autopilot is NOT a combination: autopilot never asks the depth question and always runs Full.
+One modifier exists:
+- `autopilot`  -  skip confirmations, and resolve the workspace to a worktree without asking.
+
+The workspace is not a flag. Where the branch lives is a Phase 0 Step 5b question on attended runs.
 
 ---
 

package/pipeline/multi-agent-refs/features/external-context-injection.md

@@ -7,6 +7,8 @@
 - [Log line shape](#log-line-shape)
 <!-- /toc -->
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 Phase 0 Step 1b catalogued every typed external link from the task description into `state.contextLinks[]`. Phase 1 dispatches each entry to its matching fetcher and prepends the result to the analysis prompt under a **Referenced External Sources** section, so the agent doesn't re-discover what the ticket already pointed at.
 
 ```bash

package/pipeline/multi-agent-refs/features/review-delta.md

@@ -63,7 +63,7 @@ DELTA_JSON=$(node $HOME/.claude/scripts/review-delta.mjs --rounds-dir "$WORKTREE
 jq -c --argjson d "$DELTA_JSON" --argjson i "$((ITERATION-1))" \
   '{reviewIterations: (.reviewIterations | .[$i] += {delta: ($d + {computedAt: (now | todate)})})}' "$STATE_FILE" \
   | node $HOME/.claude/scripts/write-state.mjs "$STATE_FILE"
-$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 review.delta iteration=$ITERATION \
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 review.delta iteration=$ITERATION \
   new=$(jq '.counts.new // 0' <<< "$DELTA_JSON") still_present=$(jq '.counts.stillPresent // 0' <<< "$DELTA_JSON") \
   resolved=$(jq '.counts.resolved // 0' <<< "$DELTA_JSON") plateau=$(jq '.plateau // false' <<< "$DELTA_JSON") tripped=$([ "$DELTA_RC" -eq 3 ] && echo true || echo false)
 ```

package/pipeline/multi-agent-refs/features/review-multi-repo.md

@@ -57,9 +57,9 @@ And log `review.diff_truncated repo=<name> bytes_dropped=<N>`. Triage receives t
 
 **Telemetry**: Per-repo build/test gate timings + a single combined review/triage call set:
 ```bash
-$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 gate.build repo=common status=pass duration_ms=$D
-$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 gate.build repo=uicomponents status=pass duration_ms=$D
-$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 review.combined_diff repos=2 bytes=$BYTES truncated=false
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 gate.build repo=common status=pass duration_ms=$D
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 gate.build repo=uicomponents status=pass duration_ms=$D
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3 review.combined_diff repos=2 bytes=$BYTES truncated=false
 ```
 
 ---

package/pipeline/multi-agent-refs/features/security-audit.md

@@ -0,0 +1,55 @@
+# Security audit (Phase 3 Step 2.7)
+
+The mechanics of the conditional security audit that runs inside the Phase 3 review window and merges at Step 3.0. The phase doc carries the trigger and the merge; the rest is here.
+
+## Trigger (deterministic, no new classifier)
+
+Run the audit when any of these holds:
+
+- Step 1.75 scored `security_path` on a file in the diff (the same signal that already forces `full` review at Step 1.77).
+- The base branch is a release branch.
+- The run is the standalone `/multi-agent:security-review` command, which dispatches straight to this step.
+
+There is no `--audit` flag: the trigger is the diff, not a word the user has to remember. When none of these holds, the audit does not run, `$SECURITY_AUDIT_JSON` stays empty, and the Step 3.0 merge is a no-op.
+
+## Threat model first
+
+The auditor reads `.pipeline/threat-model.md` if Phase 1 or a prior step wrote it, and produces it (four sections) if absent. Contract: `$HOME/.claude/multi-agent-refs/threat-model.md`. It is keyed to repo+branch and mirrored to `state.threatModel` so a resume reuses it rather than re-deriving it.
+
+## Dispatch
+
+One `Agent(subagent_type: "security-auditor")` on the same capped diff the reviewers saw, plus the threat model and the resolved `${CRITERIA}` block:
+
+```
+Agent(subagent_type: "security-auditor", prompt: "<threat-model + capped diff + ${CRITERIA}>")
+```
+
+Persona contract: `~/.claude/agents/security-auditor.md`.
+
+## Output is reviewer-shaped, and that is the point
+
+The auditor returns one object conforming to `$HOME/.claude/schemas/reviewer-output.schema.json`, whose `findings[]` each carry the `security` envelope of `security-finding.schema.json`: OWASP category, CWE, CVSS vector + band, evidence, counterevidence, confidence, remediation, and the before/after fix. Severity is the reviewer enum, derived from the CVSS band:
+
+| CVSS band | severity |
+| --------- | -------- |
+| critical / high | blocking |
+| medium | important |
+| low / none | suggestion |
+
+Compute `security.cvss.baseScore` + `band` with the toolkit `security_cvss_score` tool, not by hand, so the score cannot drift from the vector.
+
+## Validate, persist, merge
+
+Validate with the same gate protocol as a reviewer  -  the exit code decides, not the LLM turn:
+
+```bash
+printf '%s' "$SECURITY_AUDIT_JSON" | node "$HOME/.claude/scripts/validate-reviewer.mjs" -
+```
+
+On validator failure: one self-correction rework, then HALT the phase (identical to the reviewer output-contract gate). Persist the object to `state.reviewIterations[<iteration>].securityAudit` and hold it in `$SECURITY_AUDIT_JSON`.
+
+Because the output is reviewer-shaped, the Step 3.0 merge appends its `findings[]` alongside the test-integrity findings. A `blocking` security finding then reaches triage, and a triage-accepted blocker blocks Phase 4  -  the "critical security items block the commit" contract is wired here, not merely stated.
+
+## Store-compliance cross-reference
+
+On store-relevant diffs the auditor also cites the Apple ITMS / Google Play catalog rule on the finding via `ruleId` + `criteriaSource` (`apple-archive-compliance` / `google-play-compliance`). This is annotation on the same finding, not a second pass; the device-level `store-ready` Gate under `/multi-agent:test` stays separate.

package/pipeline/multi-agent-refs/features/skill-conformance.md

@@ -22,7 +22,7 @@ Phase 4 used to select its review criteria from `detectedStack`, a string Phase
 - The dev side and the review side could disagree about the standard without either noticing. A component built by a plugin skill was reviewed against `clean-code`.
 - "Did it do this correctly?" had no fixed denominator, so the only available answer was "it looks fine", and a reviewer that opened nothing produced the same output as a reviewer that checked everything.
 
-A Short run makes this sharper: it has no Phase 1 at all, so the sole input to the old selection logic was absent.
+The sharper case is a document whose evidence supported few sections: the sole input to the old selection logic was then nearly empty.
 
 ## The four rules that make it work
 

package/pipeline/multi-agent-refs/features/visual-evidence.md

@@ -123,7 +123,8 @@ section still renders, saying so.
 ## 3. After  -  Phase 2, not the Phase 3 user test
 
 The user test is the natural home: the simulator is already up. It is also **dropped by
-every `autopilot` and `--local` entry** (`phase-3-review.md` TLDR), so a capture
+every `autopilot` entry and by any run whose
+workspace is local** (`phase-3-review.md` TLDR), so a capture
 that lives only there produces nothing for unattended runs - which are exactly
 the runs where nobody watched the screen.
 

package/pipeline/multi-agent-refs/features/worktree-finalize.md

@@ -20,7 +20,7 @@ Removing it at PR-open is only safe because of the salvage, so the two are one s
 
 | Condition | Why it blocks |
 |---|---|
-| `worktreePath == projectRoot` (`--local` mode) | there is no worktree; removing it would delete the user's checkout |
+| `worktreePath == projectRoot` (local workspace) | there is no worktree; removing it would delete the user's checkout |
 | cwd is inside the worktree | a shell left on a deleted inode is worse than a leftover directory, and Phase 4 legitimately `cd`s into the worktree earlier |
 | not a registered worktree of the project root | a mistyped path must not delete an unrelated directory |
 | real uncommitted changes | never discarded; see the artefact carve-out below |

package/pipeline/multi-agent-refs/generate-issue.md

@@ -9,6 +9,8 @@
 
 > **TLDR**  -  Shared 12-step flow for `/multi-agent:create-jira`. Asks the issue type (Task / Bug / Story), mines the target project's existing same-type issues to learn team conventions, detects the active sprint, drafts a standards-compliant issue from a fixed standard template with auto-sizing sections, asks the user about every genuinely unknown field, renders a full preview, and creates the Jira issue only after explicit approval. Creates exactly one Jira issue per run  -  no branches, no commits, no worktrees.
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 Consumed by `create-jira/SKILL.md`. This ref is never invoked directly.
 
 ## Hard rules (must not regress)

package/pipeline/multi-agent-refs/issue-jira-triad.md

@@ -9,6 +9,8 @@
 - [Cross-CLI parity](#cross-cli-parity)
 <!-- /toc -->
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 > **TLDR**  -  When a GitHub issue triggers the pipeline and has no Jira ID, the `autoJiraFromGithubIssue` policy decides whether to auto-create a Jira task (and patch the GitHub issue body with the new Jira link). Phase 5 then posts a humanizer'd wiki-content summary back as a Jira comment, closing the loop. Autopilot treats `ask` as `always`.
 
 This doc is referenced from `$HOME/.claude/multi-agent-refs/phases/phase-0-init.md` Step 1 (GitHub issue input) and `$HOME/.claude/multi-agent-refs/phases/phase-5-report.md` Step 2 (component wiki). Keeps the phase docs tight and gives the triad contract a stable home.

package/pipeline/multi-agent-refs/keychain.md

@@ -1,5 +1,7 @@
 ## Keychain Token Registry
 
+> **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+
 Tokens live in the platform-native credential store (macOS Keychain / Linux libsecret / Windows Credential Manager). Key names are resolved via **preferences mapping**  -  never hardcoded.
 
 ### Rule 1  -  Never prompt for a token *value* mid-run

package/pipeline/multi-agent-refs/knowledge.md

@@ -49,13 +49,6 @@ Each task teaches the project a bit more. Token cost decreases over time.
 
 They all complement each other  -  no conflicts.
 
-### Knowledge in a Short run
-
-A Short run skips Phase 1, but knowledge **is still read**:
-
-- Knowledge files are added to the prompt before the Opus agent starts in Phase 3
-- Knowledge capture is still performed in Phase 5 (simplified report)
-
 ### Knowledge Maintenance
 
 Knowledge files grow over time. Maintenance rules:

package/pipeline/multi-agent-refs/outside-the-pipeline.md

@@ -47,7 +47,7 @@ and a review between fetch and action; an ordinary session has neither.
 | Read an issue, page, log, crash, scan result | Resolve the credential and fetch |
 | Comment on Jira, edit an issue, move a board column | `/multi-agent:channels` |
 | Create an issue | `/multi-agent:create-jira` |
-| Open or update a PR | a pipeline run, or `/multi-agent:resume-local` |
+| Open or update a PR | a pipeline run, or `/multi-agent:resume` |
 
 The split is not bureaucracy. Outward writes carry rules that live in those commands:
 issues are never auto-closed (four approvals), PR bodies use `Ref:` and never

package/pipeline/multi-agent-refs/payload-contracts.md

@@ -64,4 +64,4 @@ Non-empty `UNTRACKED` → both the agent-log report and the closing chat summary
 
 ## Fast modes are not exempt
 
-A Short run skips Analysis and Planning, and the autopilot and local entries skip the interactive test gate. They run Phase 4 and Phase 5 **unchanged**. A short pipeline is not a licence for an improvised payload shape, a missing Test Scenarios section, or a report without numbers.
+The autopilot and local entries skip the interactive test gate. They run Phase 4 and Phase 5 **unchanged**. A short pipeline is not a licence for an improvised payload shape, a missing Test Scenarios section, or a report without numbers.