@mmerterden/multi-agent-pipeline 15.16.0 → 16.0.0

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

@@ -62,7 +62,24 @@ template_version: v3
 
 `ui_tests` and `a11y_depth` record the Phase 0 Step 5a opt-ins (defaults `false` / `basic`) so the coverage choice is auditable and the pre-dispatch validator can enforce it: `ui_tests: true` requires Section 15.6, `a11y_depth: full` requires the Section 16.2 walkthrough.
 
-The dev pipeline (`/multi-agent:dev`) reads `platform` to verify file match, `evidence_digest` to detect stale specs, and `mode` to know which section set to expect.
+The dev pipeline (`/multi-agent`, either depth) reads `platform` to verify file match, `evidence_digest` to detect stale specs, and `mode` to know which section set to expect.
+
+## Layer headings (A / B / C)
+
+The 23 sections render under three named layers. This is an **additive heading level**, not a renumbering: section numbers are referenced in 172 places across the repo including two deterministic validators, so they do not move. Layer headings are `#` (h1); sections stay `##`. `validate-analysis-doc.mjs` collects `^#{1,3}` and `md2confluence-v3.py` maps `#{1,6}` to `<h{level}>`, so the extra level is safe in both and gives the Confluence page a two-level table of contents.
+
+| Layer | Sections | What is lost if it is missing |
+|---|---|---|
+| `# Bölüm A - Analiz` / `# Part A - Analysis` | 1, 2, 3, 4, 18, 19, 20 | **what** to build: user, rule, flow, error scenario |
+| `# Bölüm B - Teknik Analiz` / `# Part B - Technical Analysis` | 5, 6, 7, 8, 9, 10, 11, 12, 16, 17 | **what is true**: endpoint, status code, token, variant axis, key |
+| `# Bölüm C - Geliştirme Analizi` / `# Part C - Development Analysis` | 13, 14, 15 | **how** to build it: class name, file path, reuse, test row |
+| (footer, no heading) | 21, 22, 23 | |
+
+**Boundary rule.** Which layer a row belongs to is settled by one question: remove it, what becomes unclear? A row that is unclear in two layers at once is two rows. `A carries no technology name; C carries no business rationale.`
+
+A layer whose sections all drop for lack of evidence drops its heading too (Locked 2). Numbering still flows 1..N over the rendered set.
+
+**Error scenarios appear in all three, at different altitudes**: what the user sees (4.2), every status code with its body and UI outcome (9.3, exhaustive per Locked 17), and the error-path tests (15.1 error/empty-nil rows, 15.7 negative scenarios). One `BR-<slug>-NN` id ties the three together, so an error described in A cannot reach C untested.
 
 ## Omission rules
 
@@ -239,12 +256,24 @@ Then <expected outcome>
 
 ### 4.4 İş Kuralları / Business Rules
 
-Locked 31 - the traceability spine. Every business rule is deterministic and testable (same input always yields the same outcome) and carries a stable id `BR-<slug>-NN`. Each rule maps to at least one acceptance criterion written Given / When / Then. In Full mode each acceptance criterion is then realized as unit-test scenarios in Section 15.1; in Lite mode Section 15 is not rendered, so the acceptance criterion stands alone here (it is itself the testable statement) and the 15.1 mapping is deferred to a later Full analysis or to `/multi-agent:dev`. Rules come from the spec / Confluence / Jira / annotations, never invented; a rule with no source cites `[label TBD - see Open Questions]` and adds a Section 20 row.
+Locked 31 - the traceability spine. Every business rule is deterministic and testable (same input always yields the same outcome) and carries a stable id `BR-<slug>-NN`.
+
+**The rule statement itself is written in EARS**, not free prose. EARS (Easy Approach to Requirements Syntax, IEEE RE'09) constrains the sentence to a fixed clause order and a small keyword set, which is what removes the ambiguity a prose rule carries. Five patterns, use the one that fits:
+
+| Pattern | Shape | Use when |
+|---|---|---|
+| Ubiquitous | `THE SYSTEM SHALL <behaviour>` | always active, no trigger |
+| Event-driven | `WHEN <trigger> THE SYSTEM SHALL <behaviour>` | fires on a discrete event |
+| State-driven | `WHILE <state> THE SYSTEM SHALL <behaviour>` | holds for as long as a state holds |
+| Unwanted | `IF <unwanted condition> THEN THE SYSTEM SHALL <behaviour>` | error and edge handling |
+| Optional | `WHERE <feature is included> THE SYSTEM SHALL <behaviour>` | applies only to some configurations |
+
+EARS states the rule; Gherkin states how you check it. Each rule still maps to at least one acceptance criterion written Given / When / Then. In Full mode each acceptance criterion is then realized as unit-test scenarios in Section 15.1; in Lite mode Section 15 is not rendered, so the acceptance criterion stands alone here (it is itself the testable statement) and the 15.1 mapping is deferred to a later Full analysis or to the dev run itself. Rules come from the spec / Confluence / Jira / annotations, never invented; a rule with no source cites `[label TBD - see Open Questions]` and adds a Section 20 row.
 
 | BR ID | Kural / Rule (deterministic, testable) | Kaynak / Source | Kabul kriteri / Acceptance criterion (Given/When/Then) |
 |---|---|---|---|
-| BR-<slug>-01 | <rule statement> | [Confluence:<pageId>:<heading>] / [Figma annotation <nodeId>] / file:line | Given <state>, When <action>, Then <binary outcome> |
-| BR-<slug>-02 | <rule statement> | <source> | Given ..., When ..., Then ... (+ >=1 failure-mode criterion) |
+| BR-<slug>-01 | WHEN <trigger> THE SYSTEM SHALL <behaviour> | [Confluence:<pageId>:<heading>] / [Figma annotation <nodeId>] / file:line | Given <state>, When <action>, Then <binary outcome> |
+| BR-<slug>-02 | IF <unwanted condition> THEN THE SYSTEM SHALL <behaviour> | <source> | Given ..., When ..., Then ... (+ >=1 failure-mode criterion) |
 ```
 
 Each scenario in 4.1-4.3 cites the matching `BR-<slug>-NN` id (and, when a server code applies, the Section 9.4 code). Plain-prose user stories without Given/When/Then are rejected by the renderer.
@@ -326,13 +355,17 @@ Locked 11 - existence is resolved against `evidence.codeConnect[]` (the Code Con
 
 ### 6.X Varyant / prop kapsamı - Variant / property coverage
 
-Completeness audit: every property of a consumed Figma component gets exactly one disposition, so the spec proves it examined the whole component surface. An unmapped remainder is a Section 20 Risk.
+Completeness audit over the **whole component surface**, not just the part this screen happens to touch. Phase 1b.2 resolves each Code Connect-bound instance to its main component (component set) and reads the full variant axis, so the "all values" column is the component's real axis rather than what the instance revealed. Every value gets exactly one disposition; an unmapped remainder is a Section 20 Risk.
 
-| Bileşen / Component | Özellik / Property | Karar / Disposition | Not / Note |
-|---|---|---|---|
-| <Name> | <figmaProperty> | implement | <mapped concept / param> |
-| <Name> | <figmaProperty> | skip | <reason not used on this screen> |
-| <Name> | <figmaProperty> | defer | <open question ref> |
+Without the traversal this table could only ever list properties the instance already used, which made "used subset" unverifiable against anything (Locked 29). Phase 2+ cannot re-fetch (Locked 30), so a value missed here is missed for the whole run.
+
+| Bileşen / Component | Eksen / Axis | Tüm değerler / All values | Bu ekranda / Used here | Karar / Disposition | Not / Note |
+|---|---|---|---|---|---|
+| <Name> | <variant property> | <v1, v2, v3, v4> | <v1, v3> | implement | <mapped concept / param> |
+| <Name> | <variant property> | <a, b> | <a> | skip | <why b is not used on this screen> |
+| <Name> | <boolean prop> | true, false | true | defer | <open question ref> |
+
+Each used value needs a matching row in Section 13.6 (Preview) and Section 15.2 (Snapshot); expanding the used subset later means updating this table first.
 
 ## 7. Tasarım Token'ları / Design Tokens
 
@@ -745,7 +778,7 @@ Section 4 Gherkin scenarios + their `BR-` ids mapped to test names.
 
 ### 15.6 UI test senaryoları / UI test scenarios (OPTIONAL)
 
-Rendered ONLY when `state.analysisSpec.options.uiTests == true` (Phase 0 Step 5a opt-in); otherwise omitted. UI tests are the most expensive tier - reserve for high-risk / revenue-connected cross-screen flows, not per-element coverage. Selectors are stable ids (iOS `accessibilityIdentifier`, Android `Modifier.testTag` / `contentDescription`), never localized text, so the flow survives copy/locale changes and an agent can generate it mechanically.
+Rendered when `state.analysisSpec.options.uiTests == true`. That option now **defaults to true** for `taskType == component` or any task carrying a Figma reference - UI work without UI test scenarios is the gap this section exists to close - and stays opt-in for everything else. UI tests are the most expensive tier - reserve for high-risk / revenue-connected cross-screen flows, not per-element coverage. Selectors are stable ids (iOS `accessibilityIdentifier`, Android `Modifier.testTag` / `contentDescription`), never localized text, so the flow survives copy/locale changes and an agent can generate it mechanically.
 
 | Flow ID | Öncelik / Priority (why it earns a UI test) | Adımlar / Steps | Seçiciler / Selectors | Doğrulamalar / Assertions | Ön koşullar / Preconditions | BR ID |
 |---|---|---|---|---|---|---|
@@ -754,6 +787,20 @@ Rendered ONLY when `state.analysisSpec.options.uiTests == true` (Phase 0 Step 5a
 Framework: iOS XCUITest (`waitForExistence`, identifier-driven); Android Compose UI test (`createComposeRule`, `onNodeWithTag`) or Espresso for View-based screens.
 ```
 
+### 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.
+
+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 31 requires of unit tests.
+
+| Senaryo / Scenario | Ön koşul / Precondition | Adımlar / Steps | Beklenen / Expected | BR ID |
+|---|---|---|---|---|
+| MT-<slug>-01 | <account state, seeded data, network condition> | 1. ... 2. ... 3. ... | <observable outcome, incl. exact copy where it matters> | BR-<slug>-NN |
+| MT-<slug>-02 (hata / error) | <condition that triggers the failure> | 1. ... 2. ... | <error surface, message, recovery path> | BR-<slug>-NN |
+```
+
+Full mode: a manual scenario with no `BR-` id, or a business rule whose failure modes reach the user with no matching MT row, fails the dispatch gate.
+
 ## 16. Erişilebilirlik / Accessibility
 
 Per-platform projection. WCAG 2.2 AA + Apple HIG + Material A11y.

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

@@ -65,7 +65,7 @@ One `### C-NN` subsection per complaint:
 - **Elenen katmanlar / Ruled out**: one line listing the repos/layers that were grepped for this complaint's signals and returned nothing (e.g. `mobile-bff, web-bff: sinyal yok`). This is what justifies a single-layer verdict.
 - **Verdict + gerekçe / rationale**: the verdict token, confidence, and 1-3 sentences citing the evidence above (SKILL Locked 10: client/bff needs 1 Graylog + 1 repo citation; core needs the Graylog line naming the upstream).
 - **Geliştirme planı / Fix plan** (client/bff only, SKILL Locked 13; validator-required for every client/bff verdict): 2-5 numbered steps grounded in the existing architecture - each step references a cited `file:line` or component, reuse-first, tests included. Never rendered for core / insufficient-evidence.
-- **Dev prompt** (client/bff only): one fenced English block ready to paste into `/multi-agent:dev` or a Jira description - complaint summary, root cause, cited files, fix plan steps, acceptance check, and the `[C-NN]` id.
+- **Dev prompt** (client/bff only): one fenced English block ready to paste into `/multi-agent` or a Jira description - complaint summary, root cause, cited files, fix plan steps, acceptance check, and the `[C-NN]` id.
 
 ## 4. Core Yönlendirme Önerileri / Core Routing Recommendations
 

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

@@ -68,7 +68,7 @@ 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"` communicated so the plugin can elide tests/wiki on `--dev`
+- `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).
 
@@ -109,11 +109,11 @@ On failure (the plugin skill returns an unrecoverable build/test error, or the d
 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 3. Do not loop indefinitely.
 
-## `--dev` mode behaviour
+## Short-run behaviour
 
-When multi-agent is invoked with `--dev` (fast path: Init → Dev → Review → Commit → Report), the dispatch layer passes `mode: "dev"` so the plugin skill can elide unit tests and wiki (structural + snapshot still required; wiki deferred to Phase 7). If the plugin does not honor a `mode` hint, dispatch simply skips the post-build wiki step itself.
+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 7). If the plugin does not honor a `mode` hint, dispatch simply skips the post-build wiki step itself.
 
-Phase 4 runs in `--dev` as it does in the full pipeline, 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.
+Phase 4 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)
 
@@ -122,4 +122,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 `--dev` 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["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.

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

@@ -6,7 +6,7 @@
 
 ---
 
-## 1. Command Inventory (51 commands)
+## 1. Command Inventory (51 files, 47 live commands)
 
 ```
 analysis, analysis-resolve, autopilot, build-optimize, channels, complaint-analysis, create-jira, design-check, dev,
@@ -21,14 +21,16 @@ 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`
-- **Full 8-phase modes**: `autopilot`, `local`, `local-autopilot`
-- **Fast modes** (Init -> Dev(Opus) -> Review -> Commit -> Report): `dev`, `dev-autopilot`, `dev-local`, `dev-local-autopilot`
+- **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.
+- **Retired stubs** (v16.0.0, deleted next minor  -  they print a redirect and run no phase): `dev`, `dev-local` redirect to the picker entries with Short; `dev-autopilot`, `dev-local-autopilot` have no equivalent, because fast-plus-unattended no longer exists
 - **Tail modes** (run the pipeline tail over already-done local work): `resume-local`
 - **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `purge`, `uninstall`, `resume`, `review`, `review-jira`, `review-issue`, `analysis`, `analysis-resolve`, `complaint-analysis`, `build-optimize`, `channels`, `scan`, `search`, `diff-explain`, `garbage-collect`, `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`
 - **Routines** (user-defined routine registry; the routines they create are local-only and never synced): `save`, `routines`, `forget`
 
+The count is 51 files and 47 live commands until the four stubs are deleted, at which point both numbers become 47. A stub is still installed and still invocable, so counting it as absent would be wrong; counting it as a command would be worse.
+
 > **Inventory drift is a contract violation.** Adding a slash command under `pipeline/commands/multi-agent/` without updating this list + its counterpart Copilot dir (`pipeline/skills/shared/core/multi-agent-<cmd>/`) is a merge blocker. `smoke-commands-skills-parity.sh` enforces command ↔ skill directory parity; `smoke-cross-cli-behavior.sh` enforces behavior parity. This doc is the authoritative command list  -  bump the count + table together.
 
 ### 1.1 Figma / component work (plugin-based on Claude Code; NOT parity-enforced)
@@ -68,7 +70,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 `--dev` 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["3"].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
 
@@ -273,9 +275,9 @@ Given the same user input, both CLIs must produce identical parsed state:
 
 Modifier flags are orthogonal and compose:
 - `autopilot`  -  skip confirmations
-- `--dev`  -  init → dev → commit → report only
+- Short depth  -  init → dev → review → test → commit → report (Phase 0 Step 7.5 picker, not a flag)
 - `--local`  -  no worktree
-- Combinations: `--dev autopilot`, `--dev --local`, etc.
+- Combinations: `--local autopilot`. Short plus autopilot is NOT a combination: autopilot never asks the depth question and always runs Full.
 
 ---
 
@@ -293,7 +295,7 @@ Modifier flags are orthogonal and compose:
 
 ## 7. Platform Guards (macOS / Linux / WSL)
 
-Commands invoked via Copilot CLI or Codex CLI may run on Linux or WSL. Claude Code currently macOS-only. Shell code in `pipeline/skills/shared/core/` command files and in `pipeline/lib` / `pipeline/scripts` must be portable.
+All three CLIs run on macOS, Linux and Windows, so any command may execute on any of them. (This line used to say Claude Code was macOS-only; it has not been true for some time, and the assumption it invited - that a Windows user necessarily arrives through Copilot or Codex - produces wrong conclusions about which paths need to be portable.) Shell code in `pipeline/skills/shared/core/` command files and in `pipeline/lib` / `pipeline/scripts` must be portable.
 
 For Keychain I/O the canonical path is **`~/.claude/lib/credential-store.sh`** (or `~/.copilot/lib/credential-store.sh` / `~/.codex/lib/credential-store.sh` on those installs). The shell driver detects platform internally and auto-delegates to `keychain.py` (Python helper, macOS / Linux) or PowerShell `CredentialManager` (Windows). Call sites stay platform-agnostic  -  no per-OS branching needed.
 

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

@@ -9,7 +9,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.
 
-The `--dev` family made this sharper: those modes have no Phase 1 at all, so the sole input to the old selection logic was absent.
+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 four rules that make it work
 

package/pipeline/multi-agent-refs/features/url-enrichment.md

@@ -32,6 +32,7 @@ Output schema (one array entry per URL  -  full contract in `~/.claude/lib/conte
   { "type": "confluence",  "url": "<url>", "metadata": { "host": "<host>", "pageId": "<id|null>", "spaceKey": "<key|null>" } },
   { "type": "crashlytics", "url": "<url>", "metadata": { "projectId": "...", "platform": "ios|android", "bundle": "...", "issueId": "...", "sessionId": "<id|null>" } },
   { "type": "fortify",     "url": "<url|null>", "metadata": { "host": "<host|null>", "versionId": "<id|null>", "instanceId": "<id|null>", "source": "url|label" } },
+  { "type": "document",    "url": "<url|null>", "metadata": { "path": "...", "format": "docx|pdf|md|txt", "source": "path|url" } },
   { "type": "graylog",     "url": null,    "metadata": { "idType": "trx|conversation", "id": "...", "label": "..." } },
   { "type": "figma",       "url": "<url>", "metadata": { "kind": "design|make|board|slides", "fileKey": "...", "nodeId": "<id|null>" } },
   { "type": "generic-doc", "url": "<url>", "metadata": { "host": "<host>", "kind": "notion|google-docs|gist|github-doc" } }
@@ -82,6 +83,15 @@ The extractor emits `graylog` entries from free-text trx / conversation ids (lab
 - Phase 1 Analysis prepends `state.graylogContext` to the agent prompt under the **Referenced External Sources** section as **diagnostic context, advisory only** (never contradicts code; no task is generated from it, no Phase 4 gate).
 - Soft-fail (non-blocking, mirrors Crashlytics): unreachable host / VPN down / network timeout → the fetcher emits a normalized empty object and exits `0`; mark `state.graylogContext = { skipped: "vpn-unreachable" }` and continue. Only a genuine auth rejection (4xx on a reachable host, fetcher exit `3`) is logged as `skipped` with the auth reason. A log fetch never blocks the run.
 
+##### Step 1b.3b  -  Document fetch (runs when `type == "document"` present)
+
+A feature spec arrives as a Word file at least as often as a Confluence page, and until v15.20.0 nothing in the pipeline could read one. `~/.claude/lib/fetch-document.sh <path-or-url>` extracts the text and returns the fetcher-standard JSON.
+
+- `.docx` needs no external tool: the file is a zip and `word/document.xml` is parsed with the python3 standard library, so the same code path runs on macOS, Linux and Windows.
+- `.md` / `.txt` are read directly. A URL is downloaded first, then treated by extension.
+- `.pdf` has no stdlib path: `pdftotext` is used when present, and its absence is exit `6` with `degraded: true`, `converter-not-available`. That is a soft skip, not an error - on Windows it is the normal case - and the document is cited in Section 21 as "referenced but not fetched".
+- Store as `state.documentContext[]`; Phase 1 injects the text under **Referenced External Sources** and Section 21 cites it as `Doküman:<file>:<title>` (Locked 3).
+
 ##### Step 1b.4  -  Other link types (catalogued only at Phase 0; fetched at Phase 1)
 
 For `swagger`, `confluence`, `figma`, `generic-doc` entries in `state.contextLinks[]`, no Phase 0 fetch runs. The entries pass through to Phase 1, which dispatches the matching fetcher (Block B work: `fetch-swagger.sh`, `fetch-confluence.sh`, etc.). Until those fetchers land, the entries are surfaced in Phase 1 context as "referenced but not fetched  -  agent should treat the URL as an authoritative external source and read it directly when relevant."
@@ -91,8 +101,8 @@ For `swagger`, `confluence`, `figma`, `generic-doc` entries in `state.contextLin
 **Log line shape** (progress contract):
 
 ```
-→ context links: total=<N>, by-type={swagger:<n>, confluence:<n>, crashlytics:<n>, fortify:<n>, graylog:<n>, figma:<n>, generic-doc:<n>}
-→ URL deep fetch: crashlytics=<hit|miss|skipped>, fortify=<hit|miss|skipped>, graylog=<hit|miss|skipped>
+→ context links: total=<N>, by-type={swagger:<n>, confluence:<n>, crashlytics:<n>, fortify:<n>, graylog:<n>, figma:<n>, document:<n>, generic-doc:<n>}
+→ URL deep fetch: crashlytics=<hit|miss|skipped>, fortify=<hit|miss|skipped>, graylog=<hit|miss|skipped>, document=<hit|miss|skipped|degraded>
 ```
 
-Two lines emit at the end of Step 1b. The first reports the catalogue from 1b.0 (always runs). The second reports the deep-fetch outcomes from 1b.1 / 1b.2 / 1b.3  -  `miss` = type not present in catalogue (normal), `skipped` = present but auth/VPN/mismatch skipped the fetch (for graylog this includes the non-blocking VPN-unreachable degrade), `hit` = context stored in state.
+Two lines emit at the end of Step 1b. The first reports the catalogue from 1b.0 (always runs). The second reports the deep-fetch outcomes from 1b.1 / 1b.2 / 1b.3 / 1b.3b  -  `miss` = type not present in catalogue (normal), `skipped` = present but auth/VPN/mismatch skipped the fetch (for graylog this includes the non-blocking VPN-unreachable degrade), `hit` = context stored in state. `degraded` belongs to the document fetch alone: the file was found and named but its text could not be extracted (a PDF with no `pdftotext` on the machine), so Section 21 cites it as referenced-but-not-fetched instead of dropping it.

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

@@ -41,9 +41,9 @@ Each task teaches the project a bit more. Token cost decreases over time.
 
 They all complement each other  -  no conflicts.
 
-### Knowledge in --dev Mode
+### Knowledge in a Short run
 
-In `--dev` mode Phase 1 is skipped but knowledge **is still read**:
+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 7 (simplified report)

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
 
-`--dev`, `--dev --local`, and the autopilot variants skip Analysis, Planning, and the interactive test gate. They run Phase 6 and Phase 7 **unchanged**. A short pipeline is not a licence for an improvised payload shape, a missing Test Scenarios section, or a report without numbers.
+A Short run skips Analysis and Planning, and the autopilot and local entries skip the interactive test gate. They run Phase 6 and Phase 7 **unchanged**. A short pipeline is not a licence for an improvised payload shape, a missing Test Scenarios section, or a report without numbers.

package/pipeline/multi-agent-refs/phases/modes.md

@@ -1,10 +1,10 @@
-> **TLDR**  -  Three orthogonal modifier flags that can combine freely:
+> **TLDR**  -  four entry commands, two axes, and depth is no longer one of them:
 >
-> - `autopilot` → skips confirmations (Plan, Test, Commit, PR prompts), still fails safe on review blockers and build retries.
-> - `--dev` → strips to Init → Dev(Opus self-contained) → Review → Test → Commit → Report. No Phase 1/2. Phase 4 Review runs in every `--dev` combination; Phase 5 Test is an interactive prompt (suppressed only by `autopilot`).
-> - `--local` → no worktree, works directly in `$PROJECT_ROOT` on a local branch.
+> - **Depth** is a picker, not a flag. Phase 0 Step 7.5 asks Full or Short and sets `state.onlyDevelop`. Short strips to Init → Dev(Opus self-contained) → Review → Test → Commit → Report. Review is never stripped.
+> - **`autopilot`** skips confirmations (Plan, Test, Commit, PR prompts) and therefore skips the depth question too, always running Full. Still fails safe on review blockers and build retries.
+> - **`--local`** means no worktree: work happens in `$PROJECT_ROOT` on a local branch.
 >
-> Combined: `--dev --local autopilot` = fastest, least-friction path.
+> Fastest path is `/multi-agent:local` then Short. There is no fast-and-unattended combination any more, and that is deliberate  -  see "Pipeline depth".
 
 ## Autopilot Mode
 
@@ -25,7 +25,7 @@ Autopilot mode skips interactive confirmations and runs the pipeline end-to-end
 | Phase               | Normal (full)                                           | autopilot (full)                            | local (full)                                | local autopilot (full)                      |
 | ------------------- | ------------------------------------------------------- | ------------------------------------------- | ------------------------------------------- | ------------------------------------------- |
 | Phase 2 (Plan Approval Gate) | Clarification (max 2 rounds) + approval loop  -  user: approve/abort/free-text edit | **Gate skip**  -  log the plan, proceed directly to Phase 3 (autopilot contract: zero interaction) | Same as Normal | Same as autopilot |
-| Phase 5 (User Test) | Interactive prompt ("Want to test?" -> wait)            | Skip (autopilot suppresses interactive prompts) -> proceed directly to Phase 6 | Interactive prompt (same as Normal  -  no worktree to remove, code already in `$PROJECT_ROOT`) | Skip (same as autopilot) |
+| Phase 5 (User Test) | Interactive prompt ("Want to test?" -> wait)            | Skip (autopilot suppresses interactive prompts) -> proceed directly to Phase 6 | **Not in the phase set** (the gate checks the change out of a worktree; local has none) | Not in the phase set |
 | Phase 6 (Commit)    | "Want to commit?" -> wait                               | Auto commit + push                          | "Want to commit?" -> wait                   | Auto commit + push                          |
 | Phase 6 (PR)        | "Want to open a PR?" -> wait                            | Auto create PR                              | "Want to open a PR?" -> wait                | Auto create PR                              |
 | **Phase 7 (Channels)**  | Multi-select channel + content menu                 | **STILL PAUSES**  -  see "Phase 7 autopilot exception" below | Multi-select (same as Normal) | **STILL PAUSES** (same as autopilot) |
@@ -44,7 +44,7 @@ Autopilot mode skips interactive confirmations and runs the pipeline end-to-end
 
 The generic "zero-interaction" contract covers Phases 0-6 only. Phase 7 channels dispatch is the **single exception**:
 
-- ALL modes (`autopilot`, `--dev autopilot`, `--local autopilot`) pause at the channels multi-select menu.
+- ALL modes (`autopilot`, `--local autopilot`, and a Short run reaching Phase 7) pause at the channels multi-select menu.
 - Menu pre-ticks from `prefs.global.reportChannels` + `prefs.global.reportContent`  -  user can accept with one keypress if prefs are stable.
 - **30-minute timeout**  -  if user does not respond, session ends cleanly:
   - External delivery aborted (no silent apply  -  prevents accidental Jira comments / Confluence pages).
@@ -57,41 +57,44 @@ Full contract: `$HOME/.claude/multi-agent-refs/phases/phase-7-report.md` (Autopi
 
 ---
 
-## Dev-Only Mode (`--dev`)
+## Pipeline depth (Full / Short)
 
-Dev-only mode strips the pipeline to what a scoped task needs: no deep analysis, no planning phase. The **Opus** dev agent directly analyzes the task scope and implements, and Phase 4 then reviews what it produced. Review is deliberately NOT part of the strip: analysis and planning shape work that has not happened yet, so a task the user has already scoped can skip them, while review judges work that now exists and has no substitute.
+Short strips the pipeline to what an already-scoped task needs: no deep analysis, no planning phase. The **Opus** dev agent reads the task scope and implements, and Phase 4 then reviews what it produced. Review is deliberately NOT part of the strip: analysis and planning shape work that has not happened yet, so a task the user has already scoped can skip them, while review judges work that now exists and has no substitute.
 
-**Activation**: Append `--dev` to any pipeline command:
+**How it is chosen.** Phase 0 Step 7.5, after `taskType` is known:
 
 ```
-/multi-agent "PROJ-12345" --dev
-/multi-agent "https://{JIRA_HOST}/browse/PROJ-12345" --dev
-/multi-agent "https://github.com/.../issues/316" --dev
-/multi-agent "#316" --dev
-/multi-agent "LoginView dark mode fix" --dev
-/multi-agent "PROJ-12345" --dev autopilot
+Bu is icin hangi pipeline? / Which pipeline for this task?
+  1. Tam / Full    Analysis -> Plan -> Dev -> Review -> Test -> Commit -> Report
+  2. Kisa / Short  Dev (self-contained, Opus) -> Review -> Test -> Commit -> Report
 ```
 
-**Pipeline in dev-only mode:**
+`bugfix` and `chore` recommend Short; `feature`, `refactor` and `component` recommend Full. The recommendation is presented first and passed as `ASK_CHOICE_DEFAULT` on hosts without a native picker, because `ask-choice.sh` picks the first option on a non-TTY and option order is not a contract.
+
+**Who is asked.** `/multi-agent` and `/multi-agent:local`. Both autopilot entries always run Full without asking.
+
+**Why there is no fast-and-unattended combination.** It existed until v16.0.0 as `--dev autopilot`, and removing it is a real behaviour change, not a rename. Autopilot may not ask, so something has to choose, and unattended is the worst place to drop analysis and planning: nobody is watching to notice what the shortcut lost. A cron job or script that called `dev-autopilot` now has to pick - stay unattended and pay for the full pipeline, or stay fast and have a person present.
+
+**Pipeline in a Short run:**
 
 ```
 Phase 0: Init -> Phase 3: Dev (self-contained) -> Phase 4: Review -> Phase 5: Test -> Phase 6: Commit -> Phase 7: Report
 ```
 
-**What changes in dev-only (Tablo 2  -  Dev-Only modes):**
+**What changes (Tablo 2  -  Short runs):**
 
-| Phase               | Normal (full)                                   | `--dev`                                                                            | `--dev autopilot`                            | `--dev local`                                 | `--dev local autopilot`                       |
-| ------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------- | --------------------------------------------- | --------------------------------------------- |
-| Phase 0 (Init)      | Full setup                                      | Same  -  worktree, branch, state                                                     | Same                                         | Same  -  no worktree, branch on `$PROJECT_ROOT` | Same as `--dev local`                         |
-| Phase 1 (Analysis)  | Parallel Explore agents                         | **SKIP**                                                                           | **SKIP**                                     | **SKIP**                                      | **SKIP**                                      |
-| Phase 2 (Planning)  | TaskCreate + architecture review + **Plan Approval Gate** (clarification max 2 rounds + approval loop) | **SKIP** (plan gate not applicable  -  fast path) | **SKIP** | **SKIP** | **SKIP** |
-| Phase 3 (Dev)       | Follows Phase 2 plan, TDD cycle (Sonnet)        | **Self-contained** (Opus): agent scans relevant files, implements with TDD, builds | Same as `--dev`                              | Same as `--dev`                               | Same as `--dev`                               |
-| Phase 4 (Review)    | Parallel review + Fable triage (Claude: 2-model / Copilot: 3-model) | **Same**  -  gates, parallel review, triage; blocking findings return to Phase 3 (cap 3) | **Same**, blocking findings auto-fixed; circuit breaker halts at 3 cycles | **Same as `--dev`**, on the local branch diff | **Same as `--dev autopilot`** |
-| Phase 5 (User Test) | Interactive prompt (ask user to test)           | **Interactive prompt** (ask user to test)                                          | **Skip** (autopilot suppresses interactive prompts) | **Interactive prompt** (same as `--dev`)      | **Skip** (same as `--dev autopilot`)          |
-| Phase 6 (Commit)    | Commit + PR                                     | Same  -  still asks (unless autopilot)                                               | Auto commit + push + PR                      | Same as `--dev`                               | Auto commit + push + PR                       |
-| Phase 7 (Report)    | Full report + channels multi-select             | Simplified  -  no analysis section, review section IS present, BUT **channels menu still pauses** | Channels menu **STILL PAUSES** | Same as `--dev` | Channels menu **STILL PAUSES** |
+| Phase               | Full                                            | Short                                                                              | Short + `--local`                             |
+| ------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------- |
+| Phase 0 (Init)      | Full setup                                      | Same  -  worktree, branch, state, and the depth question itself                      | Same  -  no worktree, branch on `$PROJECT_ROOT` |
+| Phase 1 (Analysis)  | Parallel Explore agents + analysis document     | **SKIP**  -  tile flips to `skipped` at Step 7.5                                     | **SKIP**                                      |
+| Phase 2 (Planning)  | TaskCreate + architecture review + **Plan Approval Gate** | **SKIP** (no plan means no plan gate)                                    | **SKIP**                                      |
+| Phase 3 (Dev)       | Follows the Phase 2 plan, TDD cycle (Sonnet)    | **Self-contained** (Opus): agent scans relevant files, implements with TDD, builds | Same, on the local branch                     |
+| Phase 4 (Review)    | Parallel review + Fable triage (Claude: 2-model / Copilot: 3-model) | **Same**  -  gates, parallel review, triage; blocking findings return to Phase 3 (cap 3) | **Same**, on the local branch diff |
+| Phase 5 (User Test) | Interactive prompt                              | **Interactive prompt**                                                             | Not in the set  -  no worktree to check out    |
+| Phase 6 (Commit)    | Commit + PR                                     | Same  -  still asks                                                                  | Same                                          |
+| Phase 7 (Report)    | Full report + channels multi-select             | Simplified  -  no analysis section, review section IS present, channels menu still pauses | Same                              |
 
-**Phase 3 in dev-only mode (self-contained):**
+**Phase 3 in a Short run (self-contained):**
 
 The **Opus** agent receives the task description (from Jira, GitHub issue, or free-text) and:
 
@@ -101,29 +104,49 @@ The **Opus** agent receives the task description (from Jira, GitHub issue, or fr
 
 No separate task breakdown  -  the agent handles scope autonomously.
 
-**State tracking**: `agent-state.json` gets `"onlyDevelop": true`. Phases 1 and 2 are marked `"skipped"` instead of `"pending"`. Phase 4 stays `"pending"` and runs. Phase 5 stays `"pending"` and runs interactively unless `autopilot` is also set, in which case it is marked `"skipped"`.
+**State tracking**: `agent-state.json` gets `"onlyDevelop": true`. Because the tracker boots at Step -1 and the answer arrives at Step 7.5, Phases 1 and 2 are registered `pending` with everything else and flipped to `skipped` when the answer lands; pre-marking is forbidden and would scramble the tile order. Full contract: `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "Late skip".
 
-**Combinable with autopilot**: `--dev autopilot` = fastest path. Init -> Dev -> Review (auto-fix) -> auto-commit -> auto-PR -> Report (Phase 5 skipped). Zero user interaction (except build failures after 3 retries, and review findings that survive 3 rework cycles).
+### Intake warnings for a Short run
 
-### Intake warnings shared by the whole `--dev` family
+**An analysis document was supplied.** Because Phase 1 and Phase 2 are skipped, no phase turns that document into a task breakdown. The doc becomes raw context for one Dev pass, and work comes out ordered by whatever the model read first: the bottom of the dependency chain lands, the screen wiring does not.
 
-These apply to `--dev`, `--dev autopilot`, `--dev local`, and `--dev local autopilot` alike. A mode entry doc may not carry its own copy  -  it points here.
+The depth picker is where this is caught. When the intake carried an analysis document or a Figma reference, say so in the question itself rather than after the choice:
 
-**An analysis document was supplied.** Because Phase 1 and Phase 2 are skipped, no phase turns that document into a task breakdown. The doc becomes raw context for one Dev pass, and work comes out ordered by whatever the model read first: the bottom of the dependency chain lands, the screen wiring does not.
+```
+This task carries an analysis document. Short skips Analysis and Planning, so
+the document will not be turned into a task breakdown.
+  1. Tam / Full    (recommended here)
+  2. Kisa / Short  (doc as context only)
+```
 
-Say so before starting, once, and offer the choice:
+Autopilot never sees this: it runs Full.
+
+**The branch already carries the work.** When the change was developed outside the pipeline, or by hand, Short is still the wrong entry point: it will try to develop again. `/multi-agent:resume-local` puts the existing diff through the same review, adds a build+test success gate, opens the PR, and posts the Jira technical-analysis + test-scenario comment  -  without re-developing. Offer it when the working tree or branch is already ahead of the base with the task's changes.
+
+---
+
+## Analysis Mode (`/multi-agent:analysis`)
+
+Not a depth permutation - a different **output kind**. It produces the analysis document and stops; no code, no branch, no PR. The 8-phase contract holds, with four phases reinterpreted the same way a Short run reinterprets Phase 3.
 
 ```
-This mode skips Analysis and Planning, so the analysis document will not be turned
-into a task breakdown. For analysis-driven screen work, /multi-agent or
-/multi-agent:local run both phases.
-  1. Continue with --dev (doc as context only)
-  2. Switch to the full pipeline
+Phase 0: Init -> Phase 1: Analysis -> Phase 2: Planning -> Phase 4: Review -> Phase 6: Publish -> Phase 7: Report
 ```
 
-Autopilot picks 1 and logs the warning rather than asking.
+| Phase | Analysis mode |
+|---|---|
+| 0 Init | Same intake, but **no worktree**: nothing is isolated because nothing is built, so `state.run.repoPath` is the repo itself |
+| 1 Analysis | The engine (`multi-agent-refs/analysis/*`): evidence, synthesis, render, humanizer, `validate-analysis-doc.mjs` |
+| 2 Planning | Synthesis and render finish here; **no task decomposition** - there is no code to plan |
+| 3 Dev | **SKIP** |
+| 4 Review | Document review plus the open questions still marked `Acik / Open` |
+| 5 Test | **SKIP** |
+| 6 Commit | **Publish** instead: Local file / Confluence / Jira. Locked 6 still forbids `git add` and `git commit` |
+| 7 Report | Channels, same as every mode |
+
+**No `local` or `autopilot` variant.** Worktree isolation buys nothing when no code is written, and the intake, the Pass B convention preview and the open-question resolution are interactive by nature; a zero-interaction analysis would be a document nobody agreed to.
 
-**The branch already carries the work.** When the change was developed outside the pipeline, or by hand, the `--dev` family is the wrong entry point: it will try to develop again. `/multi-agent:resume-local` puts the existing diff through the same review, adds a build+test success gate, opens the PR, and posts the Jira technical-analysis + test-scenario comment  -  without re-developing. Offer it when the working tree or branch is already ahead of the base with the task's changes.
+**Where the document lands.** Drafts go to `/tmp/analysis-<slug>-<ts>/` first, then the Phase 6 picker decides: Local writes `<repo>/analysis/<feature>-<platform>.md` uncommitted, Confluence posts the page, Jira updates the description. In the full pipeline the same engine writes into the worktree instead and `prefs.global.analysisPhase.commitDoc` decides whether it rides along with the commit.
 
 ---
 
@@ -131,13 +154,14 @@ Autopilot picks 1 and logs the warning rather than asking.
 
 Local mode skips worktree creation  -  works directly on a local branch in the project root. Useful for single-task workflows or when worktrees cause issues.
 
-**Activation**: Append `--local` to any pipeline command:
+**Activation**: the `:local` entries, or `--local` on the base command:
 
 ```
+/multi-agent:local "PROJ-12345"
+/multi-agent:local "#316"
+/multi-agent:local "LoginView dark mode fix"
+/multi-agent:local-autopilot "PROJ-12345"
 /multi-agent "PROJ-12345" --local
-/multi-agent "#316" --local
-/multi-agent "LoginView dark mode fix" --local --dev
-/multi-agent "PROJ-12345" --local autopilot
 ```
 
 **What changes in local mode:**
@@ -146,7 +170,7 @@ Local mode skips worktree creation  -  works directly on a local branch in the p
 | -------------- | ------------------------------------------------ | -------------------------------------------------------------- |
 | Phase 0 Step 8 | Creates worktree at `.worktrees/{id}/`           | `git checkout -b {branch}` directly in `$PROJECT_ROOT`         |
 | Phase 3        | Works in worktree path                           | Works in `$PROJECT_ROOT`                                       |
-| Phase 5        | WIP commit -> remove worktree -> checkout branch | No worktree removal  -  code already in place, just build & test |
+| Phase 5        | WIP commit -> remove worktree -> checkout branch | **Not in the phase set**  -  nothing to check out, nothing to remove |
 | Phase 6        | Commit in worktree, push                         | Commit in project root, push                                   |
 | All paths      | `{worktreePath}` references                      | All paths use `$PROJECT_ROOT` directly                         |
 
@@ -160,11 +184,7 @@ git -C $PROJECT_ROOT config user.name "{identity.name}"
 git -C $PROJECT_ROOT config user.email "{identity.email}"
 ```
 
-**Phase 5 in local mode:**
-
-- No worktree to remove  -  user tests directly in project
-- No WIP commit needed (code is already on the branch in PROJECT_ROOT)
-- "fix" goes back to Phase 3 in same directory
+**Phase 5 in local mode:** it is not in the phase set. The gate exists to hand the user a change checked out of a worktree, and in local mode the code is already on the branch in `$PROJECT_ROOT` with nothing to check out or remove. `gen-mode-dispatch.mjs --mode=local` is the enforced statement of this; the row above mirrors it.
 
 **State tracking**: `agent-state.json` gets `"localMode": true`, `"worktreePath": null`. All path references resolve to `$PROJECT_ROOT`.
 
@@ -174,4 +194,4 @@ git -C $PROJECT_ROOT config user.email "{identity.email}"
 - Uncommitted changes in PROJECT_ROOT may conflict  -  pipeline warns if dirty
 - Build queue lock still applies for xcodebuild
 
-**Combinable**: `--local --dev autopilot` = simplest path with no worktree overhead.
+**Combinable**: `/multi-agent:local-autopilot` is the no-worktree unattended path; `/multi-agent:local` then Short is the no-worktree fast path.

package/pipeline/multi-agent-refs/phases/phase-0-init.md

@@ -290,8 +290,8 @@ nothing surfaced it. `phase0-exit-gate.mjs` now refuses to close Phase 0 unless
 `agent-state.json` carries `baseBranch` and `baseFetchStatus`, so a skipped picker is a
 gate failure rather than a silent default.
 
-This holds in every mode. `--dev` skips the *LLM* phases (Analysis, Planning); it does
-not skip Phase 0's pickers. Autopilot resolves them to their defaults without prompting,
+This holds in every mode. A Short run skips the *LLM* phases (Analysis, Planning); it
+does not skip Phase 0's pickers. Autopilot resolves them to their defaults without prompting,
 which still writes the fields - it does not leave them unset.
 
 **TTL filter for recent branches**:
@@ -542,6 +542,25 @@ Persist: `"taskType": "component" | "bugfix" | "feature" | "refactor" | "chore"`
 
 Log: `Phase 0 Step 7: taskType = {component|bugfix|feature|refactor|chore}`
 
+#### Step 7.5  -  Pipeline depth (Full / Short)
+
+Ask the depth question from `$HOME/.claude/multi-agent-refs/phases/modes.md` "Pipeline depth" - it carries the wording, the per-`taskType` recommendation and the mode tables. Here because the recommendation needs `taskType` (Step 7), which needs the fetched issue (Step 1) and the branch (Step 3).
+
+**Who is asked.** `/multi-agent` and `/multi-agent:local` only. Both autopilot entries and analysis mode skip it; autopilot always runs Full.
+
+When the intake carried an analysis document or a Figma reference, say so **inside** the question: Short skips the only two phases that would turn that document into a task breakdown, and the user should learn that before choosing, not after.
+
+**Pass the default explicitly.** `ask-choice.sh` picks the FIRST option on a non-TTY, so relying on option order breaks the first time someone reorders them for readability, on the host where nobody is watching:
+
+```bash
+ASK_CHOICE_DEFAULT="$DEPTH_RECOMMENDATION" \
+  $HOME/.claude/lib/ask-choice.sh "Which pipeline for this task?" "Full" "Short"
+```
+
+**Persist.** Short sets `state.onlyDevelop = true`; Full leaves it `false`. The key is unchanged - only who sets it changed - so every downstream reader keeps working. Short also flips the Phase 1 and Phase 2 tiles to `skipped` (tracker-contract.md, "Late skip"); pre-marking is forbidden.
+
+Log: `Phase 0 Step 7.5: depth = {full|short} (recommended {full|short}, source {user|autopilot|default})`
+
 #### Step 8  -  Clarification (opt-in, runs AFTER maturity, BEFORE Phase 1)
 
 **Gated by `prefs.global.clarifyAmbiguous.enabled`** (default: `false`). When enabled and `state.maturity.status != "blocker"`:

package/pipeline/multi-agent-refs/phases/phase-1-analysis.md

@@ -161,8 +161,34 @@ The light tier keeps a one-line bug fix from triggering a full-repo scan; pairin
 
 **Dispatch resilience (required).** Explore agents run in parallel and the analyst synthesis waits on them, so a single stalled agent hangs the phase. Bound each Explore dispatch by a wall-clock budget (`EXPLORE_TIMEOUT_SECONDS`, default 180). If an agent has not returned by the budget: log `explore.timeout agent=<id>`, drop that agent's slice, and synthesize from the agents that did return. Proceed as long as at least one Explore agent returned; if zero returned, retry the cheapest single Explore once, then HALT with `ERR: no Explore agent returned within ${EXPLORE_TIMEOUT_SECONDS}s; resume with /multi-agent:resume #N.`. Never block indefinitely on a slow or dead dispatch.
 
+#### Step 4  -  Analysis document (the design contract Phase 2 and Phase 3 demand)
+
+Phase 2 and Phase 3 pre-flights BLOCK on `analysis/<feature-slug>-<platform>.md`. **This step produces it.**
+
+**When it runs.** From signals Phase 0 already computed:
+
+| `taskType` | Figma reference in `state.contextLinks[]` | Document |
+|---|---|---|
+| `feature` · `refactor` · `component` | any | **produced** |
+| `bugfix` · `chore` | present | **produced** |
+| `bugfix` · `chore` | absent | **skipped** - record `state.analysis.docStatus = "not-applicable"` |
+
+`analysisPhase.forceFull` (default `false`) overrides the skip row, for a small change that must still leave a spec behind. `analysisPhase.mode` sets depth: `auto` is Lite on the skip-row shape and Full otherwise; `full` / `lite` pin it.
+
+A fresh document is also skipped when one already exists for this feature and platform AND its front-matter `evidence_digest` still matches (Locked 27 cache); record `docStatus = "reused"`.
+
+**How it runs.** Load `$HOME/.claude/multi-agent-refs/analysis/` on demand, in order: `locked.md` (the 31 binding decisions) then `evidence.md`, `synthesis.md`, `render.md`. Intake is NOT re-asked; platform, repos and account come from Phase 0 state. Autopilot auto-approves the Phase 2a convention preview and writes the local file, because it may not ask.
+
+**Where it lands.** `<worktree>/analysis/<feature-slug>-<platform>.md`, one file per platform in `state.analysisSpec.platforms[]`. Persist the paths to `state.analysis.docPath[]` and set `docStatus` to `produced` | `reused` | `not-applicable`. Whether the file is committed with the work is `prefs.global.analysisPhase.commitDoc` (default `true`), read at Phase 6.
+
+**The gate is not optional.** `node $HOME/.claude/scripts/validate-analysis-doc.mjs <file>` must exit 0 for every produced file; non-zero fails CLOSED like the JSON validator below (rework once, then halt).
+
+Progress line: `→ analysis doc: <produced|reused|not-applicable> (<N> platform, validator <pass|pass-after-rework>)`
+
 #### Output contract
 
+Two artefacts, both read downstream: `state.analysis` (the object below, for Phase 2 decomposition) and the Step 4 document (Phase 2 pre-flight + Phase 3's sole design source, Locked 30).
+
 Phase 1 produces an object conforming to `$HOME/.claude/schemas/analysis-output.schema.json` and persists it to `state.analysis`. Required fields (exact names per the schema): `stack` (detected stack identifier + primary language), `touchedAreas[]` (path + why), `risks[]` (existing-code hazards/observations the planner must respect  -  each `{risk, severity, mitigation}`; use an empty array when none), `summary` (one-paragraph human-readable). Phase 2 reads this object as its sole input  -  see `phase-2-planning.md`'s Input contract.
 
 **Required: validator gate (deterministic)  -  run on the persisted file immediately after the analysis object is produced; the validator's exit code decides, not the LLM turn:**