@mmerterden/multi-agent-pipeline 15.15.0 → 16.0.0

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

@@ -0,0 +1,53 @@
+# Locked decisions (31)
+
+> The 31 Locked decisions of the analysis flow. Loaded by `/multi-agent:analysis`, by `/multi-agent:analysis-resolve` (which inherits them) and by pipeline Phase 1 when it runs the analysis engine. Numbering is canonical: cite as `Locked <n> (<short label>)`.
+
+### Index by category (v9.1.0+)
+
+Browse-friendly grouping of the 31 Locked decisions. Numbering stays canonical (matches the list below); the index is read-only navigation.
+
+| Category | Decisions | Concern |
+|---|---|---|
+| **A. Governance** | 1, 5, 6, 7, 10, 26, 27 | Run-level process rules: one feature per run, default output, auto-commit ban, punctuation policy, output picker timing, Pass B preview, evidence digest cache |
+| **B. Citation and Evidence** | 3, 4, 8, 11, 24, 30 | Every fact in the doc traces back to a source: citation discipline, forward-looking spec, standards binding, repo-evidence reuse-first, Pass B footnote mandatory, analysis self-contained (pipeline-wide) |
+| **C. Output Format and Structure** | 2, 9, 13, 14, 16, 17, 20, 21, 25 | How the document is laid out: section omission rule, per-platform output split, Gherkin user stories, Goals + Non-Goals paired, Files-to-Add tag, API response variants exhaustive, localization mode (ownership-aware), References at the bottom, Lite mode |
+| **D. Design Source and Pipeline Architecture** | 12, 22, 23 | Where design comes from and how the pipeline renders: Figma 3-tier access (BLOCKING), platform-agnostic template + Pass B render, convention extraction (Phase 1c) |
+| **E. UI, Variant, and Test Coverage** | 15, 18, 19, 28, 29, 31 | UI artefact rules: SVG default for new assets, screenshots embedded, all Figma variants drilled, SwiftUI Preview block (iOS), variant usage explicit, business-rule to acceptance-criterion to test traceability |
+
+When citing a Locked decision in code or docs, prefer `Locked <n> (<short label>)` form so the category is inferable (e.g. `Locked 30 (analysis self-contained, category B)`).
+
+### Full list
+
+1. **One feature per run.** Every Figma URL, Confluence page, Jira ID, and Standards source the user supplies belongs to the **same feature**. The command never asks "which feature is this for?" or "which URL is primary?". Mixed inputs covering multiple features are treated as user error: surface the conflict, stop, and ask the user to split into separate runs.
+2. **Section omission rule.** Sections with zero evidence are dropped entirely; no `TBD` placeholder section. Numbering remains sequential `1..N` over the rendered set.
+3. **Citation discipline.** Every quoted UI string, endpoint path, error code, or analytics event name in Sections 2-4 must carry an inline citation: `[Figma annotation <nodeId>]` for copy taken from a Dev Mode annotation, `[Figma <nodeId>]` (MCP) or `[figma-export: <project-slug>/<screen-slug>:<nodeId>]` (local source) for design strings; `file:line` for repo evidence; `Confluence:<pageId>:<heading-slug>` for spec text. **Annotation-as-copy precedence:** when the project's `figma-config` has `annotations.enabled` and a node carries a Dev Mode annotation, that annotation is the authoritative copy for the node and the visible text layer is treated as a placeholder; cite the annotation, not the layer text. Never invent copy - blank beats a guess; a node whose annotation has the base language but is missing a target language emits a Section 20 (Risks) row rather than a fabricated value. Uncited quotes are downgraded to `[label TBD - see Open Questions]` and a row is added to Section 7 Risks. Subagent prose and Code Connect snippets are not citations.
+4. **The spec is forward-looking.** Section bodies describe the new feature as drawn / specified. Findings that exist only in legacy code or the existing branch appear as `> Legacy reference: <text> (file:line)` blockquotes inside the relevant section, never as the lead sentence or a primary table row. A legacy-only finding with no forward counterpart goes to Section 7 Risks as a decision item: "current code does X; should the new feature keep, change, or drop this?".
+5. **Output default = Local file.** The Phase 3.5 output picker keeps `Local file` pre-selected. Confluence and Jira outputs are never default-selected (see `analysis-output-confluence-on-request` memory).
+6. **No auto-commit.** Even after a successful local write or Confluence post, the command never runs `git add` or `git commit`. The user does that themselves if they want.
+7. **Humanizer punctuation policy is non-negotiable.** No em-dash, en-dash, ellipsis, curly quotes, or section sign in any emitted text. Verification grep is run before the file lands.
+8. **Standards binding.** When `evidence.standards[]` is non-empty, Section 7 architectural decisions must cite their binding source by file plus section. Decisions that contradict a binding source go to Section 7 Risks rather than silently overriding.
+9. **Per-platform output split.** One markdown file is produced per selected platform under `analysis/<feature>-<platform>.md`. There is no merged single file. Section duplication follows the A3 hybrid table in `$HOME/.claude/multi-agent-refs/analysis-template.md` (Sections 1 + 4 duplicated verbatim; Sections 2, 3, 5, 6, 7 projected per platform). Each file carries a YAML front-matter header naming the feature, platform, generated-at timestamp, sibling file list, and binding standards source.
+10. **Output destination is asked after drafts exist.** Phase 3 renders each per-platform markdown to `/tmp/analysis-<feature-slug>-<timestamp>/` first. Only then does Phase 3.5 surface the output-destination picker (Local / Confluence / Jira). Drafts in `/tmp/` are the source of truth on resume; `/multi-agent:resume` re-uses them when `phase == awaiting_output_decision`.
+11. **Repo-evidence reuse-first.** Phase 1b runs a repo-evidence collector against each selected repo, producing 13 buckets (services, dtos, useCases, validationRules, domainEntities, routes, coordinators, diConfigurators, uiComponents, tokens, localizationKeys, testingIdentifiers, analyticsEvents) with each row tagged `direct-match | same-domain | cross-cutting`. Section 7 emits `Reuse existing X (file:line)` rows for `direct-match` items and advisory rows for `cross-cutting` items. New-write tasks for items that have a `direct-match` are downgraded to Risks ("existing X candidate found; reuse or document why a new one is needed").
+12. **MUST: Figma access - 3-tier fallback chain, pipeline-wide.** When any Figma URL or node ID is supplied (Phase 0 Step 5), Phase 1 establishes a Figma ground-truth artefact via the 3-tier chain before any UI synthesis runs: (1) Figma MCP `get_design_context` / `get_screenshot` / `get_metadata` for every referenced frame, with one re-auth retry on auth failure; (2) Figma REST API (`GET /v1/files/{fileKey}/nodes`, `GET /v1/images/{fileKey}`) using the PAT resolved through `~/.claude/lib/credential-store.sh get <logical-key>` where `<logical-key>` = `prefs.global.keychainMapping.figma`; (3) a user-attached screenshot as last resort. The tier in use is persisted as `state.figmaAccess.tier`. On Tier 1 the `CodeConnectSnippet` blocks name the exact target component consumed verbatim in Section 2 and Section 7. On Tier 2 the canonical-component decision falls back to the repo's `*.figma.swift` / `*.figma.kt` mappings keyed by `fileKey` + `nodeId`. On Tier 3 the canonical-component decision becomes "tier-3 best-fit pending design review" and produces a forced Open Question in Section 7 plus a Phase 4 `review_blocking` flag. Sound-alike alternatives, "more flexible" wrappers, and extrapolating from Confluence text-only "Component Kompozisyonu" / "Component Inventory" tables are forbidden in every tier. If all three tiers fail, halt the run and ask the user for access; never proceed with text-derived guesses. Section 7 architecture decisions must cite the node ID (Tier 1 or Tier 2) or the user-screenshot reference (Tier 3) for every UI atom row. Violations cost rebuild rounds (raw-primitive substitution; sound-alike-component swap). Generic rule rationale and checklist: see `$HOME/.claude/rules/figma-pipeline.md` "MUST: Figma access - 3-tier fallback chain (BLOCKING, pipeline-wide)". Memory: `[[figma-no-guesswork]]`.
+13. **Gherkin user stories.** Section 4 scenarios use Given / When / Then. Plain-prose user stories are rejected at render time.
+14. **Goals and Non-Goals are paired.** Section 2 always carries both columns. A row in only the goal column without an explicit non-goal counterpart is rejected. Vague "out of scope" phrasing does not satisfy the non-goal column; each non-goal names what is excluded.
+15. **New assets default to SVG.** Section 8 entries marked `new` are SVG unless a documented exception is captured in the rationale column (Lottie for motion design, optimized PNG for raster-only icons). PDF, JPG, and unoptimized PNG are rejected.
+16. **Files-to-Add tag mandatory.** Every row in Section 14 carries one tag from `Reuse | Add new | Modify`. Untagged rows fail the dispatch gate.
+17. **API response variants exhaustive.** Section 9 lists every HTTP status code returned by the endpoint with at least one example body and the matching UI outcome. Phrases like "other errors" or "various 4xx" are rejected.
+18. **Screenshots embedded, not linked.** Section 5 frame galleries reference local PNG files. Dispatch uploads them as Confluence multipart attachments and injects `<ac:image><ri:attachment ri:filename="..." /></ac:image>` into the page body. URL-only Figma references in Section 5 fail the dispatch gate.
+19. **All Figma variants drilled.** When a Figma section URL is supplied, all child frames are drilled, not just the canonical default. The renderer enumerates child frames via `mcp__claude_ai_Figma__get_metadata` (Tier 1) or `figma-screenshot.sh --section` (Tier 2) and produces one Section 5.1 row per child frame.
+20. **Localization mode (ownership-aware).** Section 10's shape is driven by the project `figma-config` `localization.ownership` (default `in-repo`). The locale set comes from `localization.locales` (default `tr, en, ar, de, es, fr, it, ru`); do not hardcode a locale list in the render.
+    - **`in-repo`** (default, historical behavior): new keys carry filled cells for every configured locale. Placeholder values `[bekleniyor: çeviri ekibi]` / `[pending: translation team]` are a soft state and the dispatch report flags `i18n_pending: <count>` as a blocker. Empty cells are rejected outright.
+    - **`externally-owned`**: per-locale values are owned by the authoring system named in `localization.authoringPipeline` and MUST NOT be hand-filled. Section 10 lists `key | status | copy source | base value | ownership` only; the gate becomes "the `localization.baseLanguage` value is present (sourced from the Figma annotation, Locked 3) AND the ownership reference is cited". A key missing its base-language value is a blocker (it renders the raw key at runtime). Fabricated per-locale values are rejected.
+21. **References at the bottom.** The user-supplied input table is rendered as Section 21 References, not as Section 1. Readers see goals, flow, and design before sources.
+22. **Platform-agnostic template + Pass B render.** The template (`$HOME/.claude/multi-agent-refs/analysis-template.md`) describes concepts (state holder, view, navigator, use case, repository, DTO, state model, DI register, localization key, accessibility identifier, test method) without platform-specific class names. Pass B (Phase 2b) projects each concept onto the selected platform using conventions extracted at Phase 1c.
+23. **Convention extraction mandatory (Phase 1c).** After Phase 1b repo evidence, Phase 1c extracts seven pattern groups (folder structure, class naming, UI state model, test method naming, accessibility identifier, localization key, DI registration) per selected repo via `~/.claude/lib/extract-conventions.sh`. Output lands in `state.analysisSpec.evidence.conventions[<repo>]` with confidence levels (high / medium / low / none) and evidence file citations.
+24. **Pass B cell footnote mandatory.** Every cell Pass B fills in Section 13 (Architecture Plan concept table) and any other per-platform projection carries a footnote of the form `^[<convention-key> <confidence>: <evidence-source>]` pointing back to Phase 1c output. Cells with `confidence: low | none` cite `conventions-defaults.md:C<n>-<platform>` and emit a row in Section 20 Risks ("convention fallback applied"). Footnote-less cells fail the dispatch gate.
+25. **Lite mode for small features.** When Phase 1 signals indicate a small feature, Lite mode auto-activates and renders only Sections 1, 2, 4, 9, 13, 14, 21, plus optional 23 Changelog. The user can force Lite with `--lite` or force Full with `--full`. Full mode is the default for new feature analyses. **Scoring (v9.1.0+):** three independent signals - `confluenceSpecLines < 100`, `figmaFramesCount <= 1`, `repoDirectMatchCount >= 8`. Each true signal scores 1 point; Lite auto-activates at `score >= 2`. Previous AND-threshold (`v8.12.0..v9.0.x`) was too strict and forced small features into Full mode when one signal was just over the line. Explicit user flags (`--lite` / `--full`) always win over auto-scoring.
+26. **Pass B preview before render.** Phase 2a presents the resolved convention table to the user before Phase 2b emits any platform file. The user can approve, override individual cells, or cancel. Empty answers do not imply consent (`feedback_no-inferred-defaults-from-empty-answer`); the picker re-asks on empty submit.
+27. **Evidence digest caches Phase 1b and 1c.** `evidence_digest = sha256(featureName || sorted(platforms) || repoEvidence.summary || conventions.summary)`. When the same feature name is invoked again against the same set of repos and the digest matches, Phase 1b and 1c are skipped and the cached `evidence.repoEvidence` / `evidence.conventions` is reused. Cache TTL is 24 hours; manual invalidation via `--no-cache` flag.
+28. **SwiftUI Preview block mandatory (iOS projection, SwiftUI only).** When the iOS file is produced AND the affected view is a SwiftUI view (detected via `import SwiftUI` + `: View` protocol conformance in `evidence.repoEvidence[<repo>].buckets.uiComponents`), Section 13.6 renders a Preview block table covering at minimum: canonical default (LTR Light), Dark, RTL, Dynamic Type accessibilityLarge, and one error variant. Loading state and edge-case variants are added when distinct from canonical. UIKit-only features (no SwiftUI view artefact) drop Section 13.6 with note `(N/A: UIKit-only feature)`. Preview macro convention (`#Preview` for Swift 5.9+ vs legacy `PreviewProvider`) is read from `evidence.conventions[<repo>].previewMacro`. Each Preview variant listed in Section 13.6 must have a matching row in Section 15.2 Snapshot Tests; a Preview without a snapshot row triggers a Section 20 Risk.
+29. **Variant usage explicit and bounded.** Section 6 inventory rows list which variants this feature consumes per component (concrete enum case + bool value). New Section 6.X (Variant Usage Matrix) catalogues the full variant axis vs. used subset with a rationale per excluded variant. Sections 13.6 (Preview) and 15.2 (Snapshot) cover only the used subset; expanding the variant set requires updating Section 6.X first.
+30. **Analysis as self-contained design bridge - no MCP outside analysis phase (BLOCKING, pipeline-wide).** The analysis document is the sole design source for every downstream phase. After Phase 1 of `/multi-agent:analysis` produces `analysis/<feature>-<platform>.md`, Phase 2 Planning, Phase 3 Dev, Phase 4 Review, Phase 5 Test, Phase 6 Commit, and Phase 7 Report consume only the analysis document plus repo Code Connect mappings (`*.figma.swift` / `*.figma.kt`). Calling `mcp__claude_ai_Figma__*`, hitting `api.figma.com`, or fetching a `figma.com/design/...` URL during Phase 2+ is a violation. Applies to every mode that runs Phase 2+: `/multi-agent`, `/multi-agent:autopilot`, `/multi-agent:local`, `/multi-agent:local-autopilot`, at either depth. Hard requirement (v9.0.0): Phase 2 Pre-item and Phase 3 Pre-item (BLOCKING) abort the run when the analysis document is missing. Memory: `[[mcp-only-in-analysis]]`. Generic rule rationale and access matrix: see `$HOME/.claude/rules/figma-pipeline.md` "MUST: No MCP outside analysis phase".
+31. **Business-rule to acceptance-criterion to test traceability (AI + human spine).** The analysis is a development handoff that both an AI implementer and a human reviewer must act on, so it is bound by one shared-ID vocabulary. Every business rule carries a stable id `BR-<slug>-NN` (Section 4.4). Each rule maps to at least one acceptance criterion written Given / When / Then (binary - two readers must not be able to disagree on pass/fail). Each acceptance criterion maps to unit-test scenarios in Section 15.1, one row per case across happy / boundary / error / empty-nil (enumerate at least the failure modes; agents hallucinate error handling when it is omitted). The same ids thread onward: Section 15.6 UI-test flows reference the `BR-` ids and use stable selectors (accessibilityIdentifier / testTag), Section 16 accessibility items reuse those identifiers, Section 11 analytics events cite their triggering rule or story, and Section 5/7 layout cells carry token + Figma node refs. Never invent copy or values (blank beats a guess; a missing source becomes a Section 20 Open Question). **Mode-aware gate:** in Full mode a business rule with no acceptance criterion, or an acceptance criterion with no Section 15.1 scenario, fails the dispatch gate. In **Lite mode Section 15 is not rendered**, so the rule-to-test half does not apply - Section 4.4 still lists each rule with its Given/When/Then acceptance criterion (the acceptance criterion is itself the testable statement), and the 15.1 mapping is deferred to whenever the feature is later analyzed in Full or implemented by a dev run. The rule-to-acceptance-criterion half always holds, in both modes.

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

@@ -0,0 +1,133 @@
+# Render, publish, report (Phases 3, 3.5, 4, 5)
+
+> Render, humanize, validate, publish and report. Loaded on demand by `/multi-agent:analysis` and by pipeline Phase 1. The humanizer pass and `validate-analysis-doc.mjs` are required here in every mode: a document that skipped either is not shippable.
+
+### Phase 3 - Humanize & buffer drafts (no side effects)
+
+1. **Language resolution**: read `prefs.global.outputLanguage` (`tr` or `en`, default `tr`). Use the `Output language matrix` table in `$HOME/.claude/multi-agent-refs/analysis-template.md` to swap headings and system strings.
+
+2. **Per-platform markdown render**: for each platform in `state.analysisSpec.platforms[]`, concatenate the per-platform spec into one markdown file. Tables in pipe-syntax. Numbering uses plain `## 1.`, `## 2.`, ... - omitted sections do **not** create gaps. Visible numbering is sequential 1..N over the rendered set.
+
+3. **Humanizer pass (MANDATORY: actually invoke the `ai-common-toolkit:humanizer` skill on the rendered markdown - the punctuation grep alone does NOT satisfy this step)** (`technical-explanatory` tone for the scratch buffer; per-channel re-humanize happens in Phase 4 when actually emitting):
+   ```
+   ai-common-toolkit:humanizer skill input:
+     language: <tr|en>
+     tone: technical-explanatory
+     stripFancyPunctuation: true
+     content: <markdown>
+   ```
+
+   **Explicit punctuation policy** (enforced by `stripFancyPunctuation: true`): no em-dash (U+2014), no en-dash (U+2013), no horizontal ellipsis (U+2026), no curly quotes (U+2018, U+2019, U+201C, U+201D), no section sign (U+00A7). The humanizer replaces these with ASCII equivalents (`-`, `:`, `,`, `...`, `'`, `"`, and `bölüm` / `section` for the section sign per `outputLanguage`) before emit. Tables, code blocks, URLs, and front-matter YAML are exempt. Post-emit verification runs through `node $HOME/.claude/scripts/validate-analysis-doc.mjs <file>`, which checks this policy deterministically in Node on all three operating systems. Do NOT verify with `grep -P`: BSD grep (macOS, the pipeline's primary platform) has no `-P`, so that command never runs and "zero matches" is trivially true. **Diacritics are PRESERVED, not stripped: this policy targets ONLY the listed fancy-punctuation codepoints. Turkish letters (ş/Ş, ç/Ç, ğ/Ğ, ı/I, İ, ö/Ö, ü/Ü) and all other `outputLanguage` letters MUST stay verbatim. Never ASCII-fold the prose - emit `Geliştirme Özeti`, `için`, `Kullanıcı Hikayeleri`, NOT `Gelistirme Ozeti`, `icin`, `Kullanici`. ASCII-folded Turkish is a humanizer-skipped smell and fails review.**
+
+4. **Write scratch drafts**: create `/tmp/analysis-<feature-slug>-<UTC-iso8601>/` and write `<feature>-<platform>.md` for each selected platform. Update `state.analysisSpec.outputs.draftDir` with the path.
+
+5. **Surface the draft tree to the user**:
+   ```
+   Drafts ready (3 files, 6.4 KB):
+     /tmp/analysis-UserProfile-20260514T1015/UserProfile-ios.md
+     /tmp/analysis-UserProfile-20260514T1015/UserProfile-android.md
+     /tmp/analysis-UserProfile-20260514T1015/UserProfile-backend.md
+   ```
+   User can inspect drafts before choosing output destinations in Phase 3.5.
+
+### Phase 3.5 - Output destination picker
+
+AskUserQuestion (multiSelect=true), at least one selection required. `Local file` pre-selected per Locked decision 5.
+
+```
+header: "Output"
+question: <localized: "Where should the per-platform analyses be written?">
+options:
+  - label: "Local file"
+    description: "analysis/<feature>-<platform>.md in each selected repo's working tree"
+  - label: "Confluence page"
+  - label: "Jira description"
+```
+
+Conditional follow-ups:
+- If `Confluence` selected: ask `header="Parent page"`, free-text via Other for the parent page key or URL. One Confluence page per platform is created under this parent, each titled `<Feature> - <Platform>`.
+- If `Jira` selected: if Step 5 Q4 produced Jira IDs, AskUserQuestion (single-select) to pick which one; otherwise ask via Other. Per Locked decision 9 + design choice "single description with platform separators", the chosen issue receives one combined description body holding all per-platform sections under `h2. Platform: <X>` separators (wiki markup  -  the description field does not render Markdown; conversion happens at dispatch, see Phase 4).
+
+Result: `state.analysisSpec.outputs.requested[]`.
+
+### Phase 4 - Dispatch & report
+
+**Pre-dispatch gate (BLOCKING).** Before writing to any destination, run the deterministic doc validator on every per-platform draft:
+
+```bash
+for f in /tmp/analysis-<feature-slug>-<ts>/*.md; do
+  node "$HOME/.claude/scripts/validate-analysis-doc.mjs" "$f" || GATE_FAILED=1
+done
+```
+
+`validate-analysis-doc.mjs` enforces the mechanically-checkable Locked decisions on the emitted markdown itself (front-matter completeness, never-omitted sections per Locked 2, humanizer punctuation per Locked 7, and Full-mode business-rule traceability per Locked 31). Any ERROR blocks dispatch: fix the draft and re-validate. Warnings are advisory (run with `--strict` to treat them as blocking). This turns the "fails the dispatch gate" prose into a real, model-independent check.
+
+Iterate `state.analysisSpec.outputs.requested`. For each target:
+
+| Target | Action |
+|--------|--------|
+| Local | For each per-platform draft, `cp /tmp/analysis-<feature-slug>-<ts>/<feature>-<platform>.md` into `analysis/<feature>-<platform>.md` in the matching repo's working tree. When multiple repos exist for the same platform, the file is duplicated into each and the dispatch report lists every destination. **No commit.** |
+| Confluence | Re-humanize each per-platform draft with `formal-stakeholder` tone. One Confluence page per platform under the chosen parent, titled `<Feature> - <Platform>`. Cross-link siblings inside each page via `<ac:link><ri:page ri:content-title="<Feature> - <OtherPlatform>"/></ac:link>`. Markdown -> storage XML via `$HOME/.claude/multi-agent-refs/channels/confluence.md`. Re-emit on existing pages uses PUT with version bump. |
+| Jira | Re-humanize the combined body with `informal-technical` tone. Concatenate per-platform drafts under `h2. Platform: iOS`, `h2. Platform: Android`, `h2. Platform: Backend`, `h2. Platform: Frontend` separators (in the order platforms were selected), then run the whole body through the markdown → Jira wiki conversion table in `$HOME/.claude/multi-agent-refs/channels/jira.md`  -  the `description` field renders wiki markup, so raw `##`/`**`/backticks arrive as literal text. Write with `PUT /rest/api/2/issue/{key}` body `{"fields": {"description": <converted body>}}` (`channels/jira.md` documents only the comment POST; the description update is this PUT). Same rawfile + `--data-binary` transport rules. |
+
+**Output capture**: fill `state.analysisSpec.outputs.localPaths[]` (one entry per per-platform-per-repo write), `outputs.confluencePageUrls[]` (one entry per platform), `outputs.jiraIssueKey` (single string).
+
+### Phase 5 - Report & stop
+
+After dispatch, print a summary to the user (in `outputLanguage`). Example shape:
+
+```
+Feature: <featureName>
+Language: <tr|en>
+Platforms: iOS, Android, Backend
+Repos: my-ios-app (write), my-android-app (write), my-backend-api (write)
+
+Sources used:
+  Figma:     2 frames
+  Swagger:   1 file
+  Confluence: 1 page (1 fetch error: auth_required)
+  Jira:      1 issue
+  Firebase:  3 events from schema, 1 from auto-detect
+  Standards: 2 local files + 1 wiki page
+    - /Users/.../<project>-Standards.md
+    - /tmp/<repo>-wiki/Navigation.md
+    - ~/.claude/rules/<framework>-qa.md (auto-detected)
+
+Repo evidence (reuse vs new):
+  iOS my-ios-app:        4 direct-match, 6 same-domain, 11 cross-cutting
+  Android my-android-app: 2 direct-match, 8 same-domain, 14 cross-cutting
+  Backend my-backend-api: 1 direct-match, 3 same-domain, 7 cross-cutting
+
+Sections (per platform):
+  iOS:      [1 Scope, 2 Design, 3 Localization, 4 API, 5 Deeplink/Push, 6 Business+Tests, 7 Dev Plan]
+  Android:  [1 Scope, 2 Design, 3 Localization, 4 API, 5 Deeplink/Push, 6 Business+Tests, 7 Dev Plan]
+  Backend:  [1 Scope, 4 API, 6 Business+Tests, 7 Dev Plan]    (Sections 2/3/5 omitted - no UI)
+
+Outputs:
+  - analysis/UserProfile-ios.md       (my-ios-app)
+  - analysis/UserProfile-android.md   (my-android-app)
+  - analysis/UserProfile-backend.md   (my-backend-api)
+  - Confluence (3 pages):
+      https://{CONFLUENCE_HOST}/pages/viewpage.action?pageId=...    (iOS)
+      https://{CONFLUENCE_HOST}/pages/viewpage.action?pageId=...    (Android)
+      https://{CONFLUENCE_HOST}/pages/viewpage.action?pageId=...    (Backend)
+  - Jira: {JIRA_KEY}-12345 (description updated with 3 platform sections)
+```
+
+**Stop. Do not chain into a dev run. Do not open a worktree. Do not create a branch.**
+
+**Open-question follow-up**: when any rendered file's Section 20 (Risks and Open Questions) has rows with status `Acik / Open`, append one line to the report: `<localized: "Section 20 has <N> open rows. Run /multi-agent:analysis-resolve to resolve them interactively before dispatching to dev.">`. This is a suggestion line only - never auto-invoke the resolver.
+
+
+## Confluence write (on-request only)
+
+Per the `analysis-output-confluence-on-request` memory, Confluence post is NEVER default-selected at Phase 3.5 (the output destination picker). Only when the user explicitly asks ("post this to Confluence", "create a page under the Coding Documentation parent", etc.) does the command:
+
+1. Resolve the token via `~/.claude/lib/credential-store.sh get <key>`, where `<key>` is read from `prefs.global.keychainMapping.confluence` (per-user mapping; never hardcode the service name in this doc - see channel adapter doc `$HOME/.claude/multi-agent-refs/channels/confluence.md` for the lookup contract).
+2. Use parent page URL from user input. No default parent is hardcoded here; the user picks one at the prompt (LRU recents come from `prefs.projects[<project>].confluenceUrls`).
+3. Convert markdown to storage XML using the table in `$HOME/.claude/multi-agent-refs/channels/confluence.md`.
+4. Upload Figma frame screenshots as page attachments via `POST /rest/api/content/{pageId}/child/attachment` (cache the MCP asset locally first because the upstream URLs expire after 7 days).
+5. Reference attachments inside the page body via `<ac:image><ri:attachment ri:filename="frame-<nodeId>.png"/></ac:image>`.
+6. POST `/rest/api/content` to create the page (or PUT with version bump when updating). Surface the resulting page URL in the Phase 4 report.
+
+Token miss handling: surface a single line `WARN: Confluence token not configured (prefs.global.keychainMapping.confluence). Run /multi-agent:setup or skip Confluence output.` and continue with local-only output.

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

@@ -0,0 +1,76 @@
+# Open-question resolution engine
+
+> Walks the Section 20 rows of an analysis v3 document one at a time, proposing source-labeled answer candidates and merging the chosen answer into the proper body section. Two mount points share this file: `/multi-agent:analysis-resolve` (standalone, for a document produced earlier) and pipeline Phase 4 in analysis mode. In the full pipeline the same walk runs at the end of Phase 2, before the Plan Approval Gate, because Phase 4 comes after development and a question answered then is answered too late.
+>
+> The 31 inherited decisions are in `locked.md`; the ones below are this engine's own. Core invariant: the document is authoritative and forward-looking. The engine never invents an answer - when no source produces a credible candidate the only options are Defer and Other.
+
+## New Locked decisions (this command)
+
+1. **One question per `AskUserQuestion` call.** 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.
+   - **From repo**: the batched Phase 1 repo lookup (one Explore subagent) returned an answer with a `file:line` citation.
+   - **AI reasoned**: contextual reasoning grounded in the loaded doc (feature scope, platform, surrounding sections). Requires a one-line rationale; skip if the basis is no stronger than guessing.
+4. **Never invent.** If no source produces a credible candidate, offer only Defer and Other.
+5. **Stop tokens** (case-insensitive, typed into Other): `stop`, `pause`, `dur`, `kes`. Halt immediately, save current state, jump to the Finalize phase.
+6. **Follow-up questions surface immediately.** If an answer creates a new question ("use a new endpoint" leads to "endpoint name?"), insert a new `Acik / Open` row into Section 20 directly after the current row and process it next, not at queue end.
+7. **Save after every answer.** Each resolution writes the full doc to disk atomically before the next question. Interruption loses nothing.
+8. **Status enum is fixed:** `Acik / Open`, `Girdi bekleniyor / Pending input`, `Karar verildi / Decided` (render the side matching the doc's `language`). Only the Status cell and a trailing `[Cozum: <value> - <source>]` / `[Resolved: <value> - <source>]` fragment on the question cell are edited in Section 20; Owner is never synthesized or changed.
+9. **Sibling propagation is explicit, never silent.** Per-platform sibling files (front-matter `siblings:`) are touched only in the Finalize phase, only for rows whose question text matches verbatim, and only after the user approves one summary question. Platform-specific rows (convention fallbacks, per-platform reuse rows) never propagate.
+10. **`evidence_digest` stays untouched.** Resolving questions does not change the evidence inputs; the front-matter digest and `generated` timestamp are preserved. Only the Section 23 changelog records the revision.
+
+
+### Phase 1 - Parse and batched repo lookup
+
+1. Read the doc end-to-end. Capture:
+   - Front-matter: `feature`, `platform`, `language`, `mode`, `siblings[]`.
+   - The Risks and Open Questions table: ordered rows `{index, question, owner, status}`.
+   - Context for reasoning: Summary, Goals, API Contracts, Architecture Plan (concept table + footnotes), Files to Add, References.
+2. Filter to rows whose status is `Acik / Open` or `Girdi bekleniyor / Pending input`. If zero remain, report `Section 20 has no open rows.` and stop.
+3. **Classify each row** by its auto-population fingerprint:
+
+   | Class | Fingerprint (from analysis.md auto-population rules) | Extra candidate source |
+   |---|---|---|
+   | `convention-fallback` | row text contains `convention fallback applied` or cites `conventions-defaults.md:C<n>-` (Locked 23) | re-run `~/.claude/lib/extract-conventions.sh <repo> <platform>` for that one field; offer the default vs the fresh extraction |
+   | `reuse-vs-new` | row text matches `existing <X> candidate found; reuse or document why a new one is needed` (Locked 11) | repo lookup reads the candidate `file:line` and summarizes its fit |
+   | `citation-tbd` | row originated from a `[label TBD - see Open Questions]` downgrade (Locked 3) | repo localization keys / Figma evidence already cited elsewhere in the doc |
+   | `legacy-decision` | row phrased `current code does X; should the new feature keep, change, or drop this?` (Locked 4) | repo lookup confirms current behavior with `file:line` |
+   | `standards-conflict` | row cites a binding standards source (Locked 8) | quote the binding section verbatim from References |
+   | `design-gap` | row needs new Figma/design information (tier-3 forced questions, missing variants per Locked 12/19) | NONE - Locked 30; offer only Defer + the re-run recommendation |
+   | `generic` | anything else | all three standard sources |
+
+4. **Batched repo lookup** (single Explore subagent, one call regardless of row count; skip if every row classified `design-gap`):
+   > "For the feature `<feature>` on platform `<platform>`, answer the following questions from the repo at `<repo-root>`. Return one entry per question ID with either an answer plus `file:line` citation OR `not-found`. Scope reading to paths the questions name plus their direct dependencies; do not roam, do not propose changes.
+   > Q1: <row 1 text> ..."
+5. Cache per-question answers keyed by row index. These feed the `From repo` candidate in Phase 2.
+
+### Phase 2 - Sequential resolution loop
+
+For each open row in source order:
+
+1. **Generate candidates** per the row's class (max 3). Skip any source with no credible output. For `design-gap` rows, skip candidate generation entirely.
+2. **Ask** (interactive mode) - single AskUserQuestion:
+   - `header`: the target section anchor, max 12 chars (e.g. `S13 Arch`, `S9 API`, `S10 L10n`, `Conventions`)
+   - `question`: the row text verbatim, prefixed `[R-<index>]` (follows the doc, so it may be Turkish; that is correct here - the row IS the doc content)
+   - `options`: up to 3 candidates + `Defer - keep open`. Candidate descriptions carry the source label per New Locked 2.
+   - Autonomous mode: pick the single credible candidate if exactly one source produced one; otherwise Defer. Log each auto-decision as one line.
+3. **Apply**:
+   - **Concrete answer**: locate the target body section from the row's anchor or content (convention rows target the Architecture Plan concept table; reuse rows target Files to Add + Architecture Plan; API rows target API Contracts; etc.).
+     - `From evidence` / `AI reasoned` / user Other: write as primary content in the doc's `language`, ASCII punctuation, citations preserved.
+     - `From repo` describing current behavior: write as `> Legacy reference: <text> (file:line)` under the target entry (Locked 4). A repo answer that the user adopts as the forward decision is primary content WITH its `file:line` citation.
+     - `convention-fallback`: update the convention cell, rewrite its footnote to `^[user-override: resolved via analysis-resolve <YYYY-MM-DD>]` (Locked 24).
+     - Update the Section 20 row: Status to `Karar verildi / Decided`, append ` [Cozum: <one-line> - <source>]` (tr) / ` [Resolved: <one-line> - <source>]` (en) to the question cell. Do not delete the row; the table stays a decision log.
+   - **Defer**: Status to `Girdi bekleniyor / Pending input`. Row otherwise untouched.
+   - **Stop token**: save, jump to Phase 3.
+   - **Follow-up**: insert the new `Acik / Open` row right after the current one (New Locked 6) and process it next.
+4. **Save the full doc to disk** before the next iteration (New Locked 7).
+
+### Phase 3 - Finalize
+
+1. **Sibling propagation** (only if front-matter `siblings[]` is non-empty AND at least one resolved row's question text appears verbatim with an open status in a sibling file on disk): one AskUserQuestion, `header: "Siblings"`, question `<localized: "N resolved rows also appear open in sibling file(s) <list>. Apply the same resolutions there?">`, options `Apply to all listed` / `Skip siblings`. On apply: repeat the Phase 2 apply step per matching row per sibling, then give each touched sibling its own changelog row. Platform-specific classes (`convention-fallback`, `reuse-vs-new`) are excluded from matching (New Locked 9).
+2. **Changelog**: append one row to the Changelog section of every touched file: next version (integer scheme `v1 -> v2`; dotted scheme bumps the minor), today's date, author `analysis-resolve`, change `Resolved <N> of <M> Section 20 rows; <K> deferred`.
+3. **Punctuation gate**: run the Locked 7 verification grep over every touched file; fix any hit before reporting.
+4. **Report** (in `outputLanguage`, max 12 lines): doc path(s) + new version, counts (resolved / deferred / follow-ups created / still open), `design-gap` rows that need a `/multi-agent:analysis` re-run (list inputs to re-supply), and - if open rows remain - a reminder that re-running this command resumes where it left off (state is the doc itself; no separate state file).
+
+**Stop. No commit, no branch, no dispatch.** The user reviews the diff and commits manually (Locked 6).

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

@@ -0,0 +1,98 @@
+# Two-pass synthesis (Phase 2, 2a, 2b)
+
+> Two-pass synthesis: the platform-agnostic concept pass and the per-platform Pass B projection, plus the convention preview that gates it. Loaded on demand by `/multi-agent:analysis` and by pipeline Phase 1.
+
+### Phase 2 - Two-pass synthesis (per-platform)
+
+Synthesis runs in two passes: Pass A computes the shared logical content once, Pass B projects it onto each selected platform.
+
+#### Pass A - Shared synthesis (sequential, fail-soft)
+
+Build one in-memory `synthesizedSections` object from all evidence. Apply the omission rule per section (zero-evidence → `null`). The object holds both shared content (Sections 1, 4) and `byPlatform` projections (Sections 2, 3, 5, 6, 7).
+
+```
+synthesizedSections = {
+  scope: { ... shared block ... },
+  design: { shared: {frameGallery, codeConnect}, byPlatform: {ios, android, frontend} },
+  localization: { keys: [...], byPlatform: {ios: {source: "Localizable.strings", rows}, android: {source: "strings.xml", rows}, frontend: {source: "i18n/*.json", rows}} },
+  apiContracts: { ... shared verbatim ... },
+  deeplinkPush: { byPlatform: {ios, android, frontend, backend: null} },
+  business: { rules: [...], useCases: [...], firebaseEvents: [...], byPlatform: {ios: {testFramework: "Swift Testing", skeletons}, android: {testFramework: "JUnit5 + Turbine"}, frontend: {testFramework: "Vitest + RTL"}, backend: {testFramework: "pytest"}} },
+  devPlan: { byPlatform: {ios: {tasks, standards}, android: {...}, ...} }
+}
+```
+
+| Section | Production logic |
+|---------|------------------|
+| 1. Scope | Always present. Derive in-scope / out-of-scope, audience from Jira summary + Confluence title + feature name. LLM inference allowed. Shared across all per-platform files verbatim. |
+| 2. Design | If `evidence.figma[]` is empty AND no `evidence.repoEvidence[*].buckets.uiComponents` direct-match → `byPlatform[*]` = null. Otherwise produce frame gallery (shared) + per-platform component inventory (rows from `evidence.repoEvidence[<repo>].buckets.uiComponents`). |
+| 3. Localization | If both Figma annotations/text layers and `evidence.repoEvidence[*].buckets.localizationKeys` are empty → `byPlatform[*]` = null. Otherwise produce the key table per the project `localization.ownership` mode (Locked 20): `in-repo` fills the configured locale set (default `ar, de, en, es, fr, it, ru, tr`, RTL for ar); `externally-owned` lists key + status + copy source + base value and defers per-locale values. Base copy is sourced from the Figma annotation when present (Locked 3). |
+| 4. API Contracts | If `evidence.swagger[]` is empty AND no Confluence embedded API table AND no `evidence.repoEvidence[*].buckets.services` direct-match → null. Otherwise produce endpoint summary + per-endpoint tables (shared verbatim across files). |
+| 5. Deeplink / Push | Per-platform: iOS uses Universal Links / `UNUserNotificationCenter`; Android uses `intent-filter` / FCM; Frontend uses web URL routing; Backend file omits this section entirely. |
+| 6. Business + Tests | If sections 2 and 4 are both `null` AND `evidence.firebase[]` is empty → null. Otherwise produce use-case + mock stubs + per-platform test skeletons + shared Firebase events table. Reuse Red-Green-Refactor naming from `$HOME/.claude/rules/tdd.md`. |
+| 7. Development Plan | Always present. Tasks for the current platform only. Architecture standards come from `evidence.standards[]` filtered by platform (see Pass B step 1). **Reuse-first rule (Locked 11)**: when an item has `direct-match` in `evidence.repoEvidence[<repo>].buckets.<X>`, emit `Reuse existing <FQN> (<file>:<line>)` instead of `Add new <FQN>`. New-write task with a `direct-match` competitor becomes a Risk row. |
+
+#### Phase 2a - Pass B preview (Locked 26)
+
+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.
+
+Example (iOS + Android selected):
+
+```
+Convention preview - Pass B will render with:
+
+| Concept | iOS | Android |
+|---|---|---|
+| Module folder | Domains/Profile/.../Screens/ProfileEditor/ ^[C1 high] | feature/profile/.../userprofile/ ^[C1 high] |
+| State holder | UserProfileViewModel ^[C2 high: 8 examples] | UserProfileViewModel ^[C2 high: 5 examples] |
+| State model | sealed enum UserProfileUIState ^[C3 high] | sealed interface UserProfileUiState ^[C3 high] |
+| Test naming | @Test func scenario_expected() ^[C4 medium: 4 examples] | fun scenario_expectedBehavior() ^[C4 high] |
+| Identifier | userProfile.continueButton ^[C5 high] | userProfileContinueButton ^[C5 medium] |
+| Localization key | UserProfile.ContinueButton ^[C6 high] | user_profile_continue_button ^[C6 high] |
+| DI | UserProfileDependencyConfigurator ^[C7 high] | UserProfileModule (Hilt) ^[C7 fallback: defaults] |
+
+Confidence summary:
+  iOS:     7/7 high, 0 medium, 0 low, 0 fallback
+  Android: 5/7 high, 1 medium, 0 low, 1 fallback
+```
+
+AskUserQuestion shape:
+
+```
+header: "Conventions"
+question: <localized: "Pass B will render with the above conventions. Approve, override, or cancel?">
+options:
+  - label: "Approve, render"
+    description: "Proceed to Phase 2b with these conventions"
+  - label: "Override individual cells"
+    description: "Open follow-up questions for cells you want to change"
+  - label: "Cancel"
+```
+
+On `Approve`: proceed to Phase 2b directly.
+On `Override`: for each cell the user wants to change, surface one follow-up AskUserQuestion with the current value and an `Other` for the new value. Persist overrides into `state.analysisSpec.conventionOverrides[<repo>][<field>] = <new pattern>`. Pass B reads overrides before defaults.
+On `Cancel`: halt and write `state.analysisSpec.phase = "cancelled_at_pass_b_preview"`. Drafts in `/tmp/` are kept for inspection.
+
+Empty submit (`feedback_no-inferred-defaults-from-empty-answer`): re-ask the same question. Do not infer consent.
+
+Skip condition: Phase 2a is skipped only when every `evidence.conventions[<repo>].*.confidence` is `high` AND `state.analysisSpec.conventionRisks[]` is empty AND the user did not pass `--preview-conventions` flag. Otherwise it always runs.
+
+#### Phase 2b - Per-platform render (Pass B)
+
+For each `platform` in `state.analysisSpec.platforms[]`:
+
+1. **Resolve standards binding source** (one canonical source per platform):
+   - `ios` → `prefs.projects[<key>].standardsFile` if present → glob `~/<project>-iOS-Standards.md` → `~/.claude/rules/swiftui-qa.md`
+   - `android` → `~/.claude/rules/kotlin-android.md` first → `evidence.standards[]` entries whose path contains `android` or `kotlin`
+   - `backend` → `evidence.standards[]` entries matching language hints (`python`, `go`, `node`, `fastapi`) → fall back to `~/.claude/rules/security.md` + `code-style.md`
+   - `frontend` → `evidence.standards[]` entries matching `react`, `vue`, `next`, `sveltekit` → `~/.claude/rules/code-style.md`
+2. **Apply per-platform omission rules.** Backend-only file drops Sections 5, 6, 7, 8, 16. Frontend with no UI inventory still keeps 5 (UI exists in code). Sections 1, 2, 4, 9, 13, 14, 20, 21 always present per Locked decision 2 + 13.
+3. **Resolve mode.** If user passed `--lite` → Lite. If user passed `--full` → Full. Otherwise use `state.analysisSpec.liteModeAuto`. Lite mode renders only Sections 1, 2, 4, 9, 13, 14, 21 plus optional 23.
+4. **Produce YAML front-matter header** (see `$HOME/.claude/multi-agent-refs/analysis-template.md`). Include `mode: full | lite`, plus `ui_tests: <state.analysisSpec.options.uiTests | false>` and `a11y_depth: <state.analysisSpec.options.a11yDepth | basic>` so the pre-dispatch validator can enforce the opt-in coverage (15.6 present when ui_tests, 16.2 walkthrough present when a11y_depth is full).
+5. **Read conventions for this platform's repo.** For each cell Pass B fills in Section 13 and in any per-platform projection (Sections 5, 6, 7, 8, 10, 11, 13, 14, 15, 16, 17), read `state.analysisSpec.evidence.conventions[<repo>].<field>` and emit the value with a footnote (Locked 24). If `conventionOverrides` has an entry for that field, use the override and footnote with `^[user-override: <reason>]` instead of evidence path.
+6. **Concatenate non-null sections in canonical order.** Numbering stays sequential `1..N` over the rendered set (omitted sections do not create gaps).
+7. **Schema validation** on the per-platform spec object:
+   ```bash
+   python3 -c "import json,jsonschema; jsonschema.validate(json.load(open('state/<feature>-<platform>.json')), json.load(open('$HOME/.claude/schemas/analysis-spec.schema.json')))"
+   ```
+   On failure for any platform, surface the error and stop before Phase 3 (do not draft partial outputs).

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.