@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/commands/figma-to-swiftui.md

@@ -31,7 +31,7 @@ When invoked from `/multi-agent` with `instructionDriven == true` (figma instruc
 
 ## Phase 0: Init
 
-1. Parse Figma URL — extract fileKey and nodeId
+1. Parse Figma URL  -  extract fileKey and nodeId
 2. Detect component name from Figma metadata or user input
 3. Create branch: `feature/{JIRA_KEY}-{component-name}`
 4. Create task list for all phases
@@ -73,9 +73,9 @@ Map Figma design values to project design tokens:
 | Corner 8 | `.CornerRadius.radius8` |
 
 **Rules**:
-- No magic numbers — all values reference design tokens
-- No raw hex colors — use semantic color tokens
-- No raw `.font()` — use typography tokens
+- No magic numbers  -  all values reference design tokens
+- No raw hex colors  -  use semantic color tokens
+- No raw `.font()`  -  use typography tokens
 - Token hierarchy: Spacing > Size > Radius > BorderWidth > Color > Typography
 
 ## Phase 4: Implementation (sequential sub-phases)
@@ -150,7 +150,7 @@ Generate and push wiki documentation pages to the wiki submodule.
 **Prerequisites check** (deterministic, no prompt):
 
 ```bash
-# 1. Wiki submodule — auto-detect from .gitmodules
+# 1. Wiki submodule  -  auto-detect from .gitmodules
 WIKI_REL=$(git -C "$PROJECT_ROOT" config -f .gitmodules --get-regexp 'submodule\..*\.path' 2>/dev/null \
   | awk '{print $2}' | grep -i 'wiki' | head -1)
 
@@ -161,7 +161,7 @@ WIKI_PATH_PREF=$(jq -r ".projects[\"$PROJECT\"].wikiPath // empty" "$PREFS_FILE"
 
 # User preference: disabled?
 WIKI_PREF=$(jq -r ".projects[\"$PROJECT\"].wikiPhase // empty" "$PREFS_FILE")
-[ "$WIKI_PREF" = "disabled" ] && { log "4F-Wiki disabled for $PROJECT — skipping"; exit 0; }
+[ "$WIKI_PREF" = "disabled" ] && { log "4F-Wiki disabled for $PROJECT  -  skipping"; exit 0; }
 
 # No wiki found
 [ -z "$WIKI_REL_ABS" ] && {
@@ -198,10 +198,10 @@ WIKI_BRANCH=$(git -C "$WIKI_REL_ABS" symbolic-ref refs/remotes/origin/HEAD 2>/de
    ```
    If `DESIGN_TOKEN` missing: leave a `TODO: add screenshot` placeholder, continue.
 
-3. **Generate main wiki page** (`{ComponentName}.md`) — sections:
+3. **Generate main wiki page** (`{ComponentName}.md`)  -  sections:
    Title · screenshot embed · Figma link · Screen/Section/Size metadata · Overview · Testing Identifiers · Localization Keys · Accessibility · Analytics Events · Sub-Components · Platform Implementations (iOS/Android/Web status) · Changelog.
 
-4. **Generate platform-specific page** (`{ComponentName}-iOS.md`) — sections:
+4. **Generate platform-specific page** (`{ComponentName}-iOS.md`)  -  sections:
    Initializer · Parameters · Modifiers · Usage · Design Tokens · Testing Identifiers iOS · Code Connect · Snapshot Tests (image embeds) · Test Coverage · Changelog.
 
 5. **Commit and push**:
@@ -250,8 +250,8 @@ If a GitHub Issue tracks this component, update its body after commit + PR:
 - Fill the `### Pull Requests` section with PR URL(s), one row per submodule touched
 - Flip Implementation / Testing / Code Connect flags from Pending to Done using whatever marker the template uses (match in place, don't introduce new markers)
 - Flip the Wiki flag to Done (SubPhase 4F already pushed the wiki pages)
-- Apply with `gh issue edit {issueNo} --body "{updated body}"` — preserve every other section unchanged
-- NEVER use `Closes:` / `Fixes:` / `Resolves:` keywords — use `Ref:` or `Related:` instead
+- Apply with `gh issue edit {issueNo} --body "{updated body}"`  -  preserve every other section unchanged
+- NEVER use `Closes:` / `Fixes:` / `Resolves:` keywords  -  use `Ref:` or `Related:` instead
 
 Skip this phase if the task has no GitHub Issue (Jira-only or free-text runs).
 

package/pipeline/commands/multi-agent/_account-picker.md

@@ -1,20 +1,20 @@
 ---
-description: "Internal — interactive account picker for multi-agent."
+description: "Internal  -  interactive account picker for multi-agent."
 ---
 
-# _account-picker — Account Selection
+# _account-picker  -  Account Selection
 
 First step of every `multi-agent` flow **that touches a remote provider**.
 
 > **Skip rule (local-only flow)**: When the input is `freetext` AND the user's
 > repo selection will end up being entirely local (no github/bitbucket account
-> needed for any selected primary), this step is **skipped entirely** — no
+> needed for any selected primary), this step is **skipped entirely**  -  no
 > question, no token lookup. Detection: `freetext` flow first fetches local
 > repos (`repo-cache.sh local "$HOME"`); if the picker resolves to local-only
 > repos, account-picker is bypassed and the state file's `accountId` is left
 > `null` with `tokens={}`. Phases 6/7 read these as "local-only" signals.
 
-> **Language**: User-facing prompt strings always render in English (`promptLanguage` is locked to `"en"`). Commit/PR/Jira payloads always English.
+> **Language**: Per `refs/rules.md` Language Application matrix  -  `AskUserQuestion.label` and `header` stay English (UI button + chip contract); `question` and `description` follow `outputLanguage`. Commit/PR/Jira payloads: subject + branch names + code identifiers stay English; body text follows `outputLanguage`.
 
 ## Steps
 
@@ -27,13 +27,17 @@ First step of every `multi-agent` flow **that touches a remote provider**.
    - GitHub-based flow → `--providers github`
    - Bitbucket-based flow → `--providers bitbucket`
 
-3. **Picker UI** — show via AskUserQuestion:
+3. **Picker UI**  -  show via AskUserQuestion (single-select):
+   - Breadcrumb (per `refs/picker-contract.md` Step narration): before the question, print the narrator line `<localized: "Step 1/N: account selection">` (`N` = total Phase 0 steps for the active flow).
+   - `header`: "Account" (English chip)
+   - `question`: `<localized: "Which account should this run use?">`
+   - one option per account: `label` = account label (English), `description` = providers in `outputLanguage`
    ```
-   [1/N] Select account:
+   [1/N] {question}
      > {label}   ({providers})
        ...
    ```
-   - Single account → auto-select, show info only
+   - Single account → auto-select, show info only (still print the breadcrumb line)
    - Multiple → multiSelect=false picker
 
 4. **Persist selection to state**:
@@ -61,7 +65,7 @@ After confirmation (interactive) or auto-selection (autopilot), update
 2. Otherwise prepend `{id, prefix, lastUsed, count: 1}` and trim to 10 entries.
 3. Atomic write via `prefs.json.tmp` + rename.
 
-This is what makes priority rule #2 work — the picker remembers which account
+This is what makes priority rule #2 work  -  the picker remembers which account
 was used last and surfaces it first on the next autopilot invocation.
 
 ## Error Cases
@@ -75,7 +79,7 @@ was used last and surfaces it first on the next autopilot invocation.
 
 ```json
 {
-  "accountId": "m-erden3",
+  "accountId": "my-account",
   "accountPrefix": "${USER}",
   "tokens": {
     "github": "${USER}_Github_Access_Token",

package/pipeline/commands/multi-agent/_dev-context.md

@@ -1,16 +1,16 @@
 ---
-description: "Internal — dev context (extra repos) picker for multi-agent."
+description: "Internal  -  dev context (extra repos) picker for multi-agent."
 ---
 
-# _dev-context — Extra Dev Repo Selection
+# _dev-context  -  Extra Dev Repo Selection
 
-Selects extra repos the pipeline may touch beyond the primary repo(s) — typically submodules (e.g. SDKs vendored inside an app repo) or sibling libraries. Each candidate is enriched with a `canPush` flag so the picker can pre-select repos that the active account is allowed to edit, and surface read-only ones as advisory context the pipeline will not modify.
+Selects extra repos the pipeline may touch beyond the primary repo(s)  -  typically submodules (e.g. SDKs vendored inside an app repo) or sibling libraries. Each candidate is enriched with a `canPush` flag so the picker can pre-select repos that the active account is allowed to edit, and surface read-only ones as advisory context the pipeline will not modify.
 
-> **Language**: Per `refs/rules.md` Language Application matrix — `AskUserQuestion.label` and `header` stay English (UI button + chip contract); `question` and `description` follow `outputLanguage`. Commit/PR/Jira/Wiki payloads: subject + branch names + code identifiers stay English; body text follows `outputLanguage`.
+> **Language**: Per `refs/rules.md` Language Application matrix  -  `AskUserQuestion.label` and `header` stay English (UI button + chip contract); `question` and `description` follow `outputLanguage`. Commit/PR/Jira/Wiki payloads: subject + branch names + code identifiers stay English; body text follows `outputLanguage`.
 
 ## Steps
 
-1. **Submodule detection (with push-access enrichment)** — when the primary repo is checked out locally:
+1. **Submodule detection (with push-access enrichment)**  -  when the primary repo is checked out locally:
    ```bash
    ACCOUNT_GH_OWNER="$ACCOUNT_GH_OWNER" \
    ACCOUNT_BB_PROJECT_KEY="$ACCOUNT_BB_PROJECT_KEY" \
@@ -25,16 +25,16 @@ Selects extra repos the pipeline may touch beyond the primary repo(s) — typica
    ```
 
    `canPush` resolution order (first hit wins):
-   1. **prefs override** — `prefs.projects[<key>].editableRelatedRepos[]` matches `<owner>/<repo>` or bare `<name>`
-   2. **repo-cache hit** — submodule URL matches a cached repo with `viewerPermission ∈ {ADMIN, MAINTAIN, WRITE}`
-   3. **owner-match** — submodule owner equals `ACCOUNT_GH_OWNER`
+   1. **prefs override**  -  `prefs.projects[<key>].editableRelatedRepos[]` matches `<owner>/<repo>` or bare `<name>`
+   2. **repo-cache hit**  -  submodule URL matches a cached repo with `viewerPermission ∈ {ADMIN, MAINTAIN, WRITE}`
+   3. **owner-match**  -  submodule owner equals `ACCOUNT_GH_OWNER`
    4. else `canPush=false` (read-only)
 
 2. **Partition results**:
-   - `editable` — `canPush=true` → picker options, pre-selected
-   - `readonly` — `canPush=false` → printed as an advisory note; not selectable
+   - `editable`  -  `canPush=true` → picker options, pre-selected
+   - `readonly`  -  `canPush=false` → printed as an advisory note; not selectable
 
-3. **AskUserQuestion (multiSelect=true)**:
+3. **AskUserQuestion (multiSelect=true)**. Print the breadcrumb narrator line first (per `refs/picker-contract.md` Step narration): `<localized: "Step N/N: extra dev repos">`.
    ```
    [N/N] Extra editable dev repos (multi):
      [x] <submodule-a>  (suggestion: from .gitmodules)
@@ -43,12 +43,12 @@ Selects extra repos the pipeline may touch beyond the primary repo(s) — typica
      [ ] (none)
 
    Read-only siblings (pipeline will NOT modify):
-     - <vendored-sdk>   (no push access — pipeline works around)
+     - <vendored-sdk>   (no push access  -  pipeline works around)
    ```
 
-4. **Empty submit** — user picks nothing → `extras=[]`, primary repo(s) only.
+4. **Empty submit**  -  user picks nothing → `extras=[]`, primary repo(s) only.
 
-## Pref override — `editableRelatedRepos`
+## Pref override  -  `editableRelatedRepos`
 
 For repos that aren't on a remote provider (local-only checkout) or to explicitly grant edit rights regardless of provider state, add to `~/.claude/multi-agent-preferences.json`:
 
@@ -106,6 +106,6 @@ When `MULTI_AGENT_AUTOPILOT=1`:
 ## Pipeline contract for read-only siblings
 
 When a read-only sibling is present (e.g. a vendored SDK checkout), Phase 3 (Dev) MUST:
-- Treat it as **read-only context** — code may be read for understanding, never edited or committed.
+- Treat it as **read-only context**  -  code may be read for understanding, never edited or committed.
 - Prefer solving the task in the primary repo(s) (e.g. by wrapping/extending in consumer code) rather than patching the sibling.
 - Surface this constraint in the Phase 3 plan output so reviewers know why a workaround was chosen.

package/pipeline/commands/multi-agent/_input-parser.md

@@ -1,12 +1,12 @@
 ---
-description: "Internal — input type detection for multi-agent dispatcher."
+description: "Internal  -  input type detection for multi-agent dispatcher."
 ---
 
-# _input-parser — Multi-Agent Input Type Classification
+# _input-parser  -  Multi-Agent Input Type Classification
 
 The top-level `multi-agent` command classifies user arguments per the rules below.
 
-> **Language**: Schema reference only — no user-facing text. Picker UI strings always English (`promptLanguage` is locked to `"en"`). Commit/PR/Jira payloads stay English.
+> **Language**: Schema reference only  -  no user-facing text. Picker UI strings always English (`promptLanguage` is locked to `"en"`). Commit/PR/Jira payloads stay English.
 
 ## Type Table
 
@@ -34,7 +34,7 @@ The top-level `multi-agent` command classifies user arguments per the rules belo
 | `freetext` | conditional¹ | ✅ (single-select, sources merged²) | ❌ | ✅ |
 
 ¹ Account picker is **skipped** when the resolved primary repo is local-only
-  (`provider="local"`). No token lookup, no provider auth — the pipeline
+  (`provider="local"`). No token lookup, no provider auth  -  the pipeline
   proceeds with `accountId=null` and Phases 6/7 honor the local-only mode.
 
 ² Free-text flow merges `github`+`bitbucket`+`local` repo caches into a

package/pipeline/commands/multi-agent/_repo-picker.md

@@ -1,27 +1,27 @@
 ---
-description: "Internal — multi-select repo picker for multi-agent."
+description: "Internal  -  multi-select repo picker for multi-agent."
 ---
 
-# _repo-picker — Repo Selection (Multi-Select)
+# _repo-picker  -  Repo Selection (Multi-Select)
 
 Used by `picker-issue`, `picker-jira`, `gh-num`, and `freetext` flows.
 
-> **Language**: Per `refs/rules.md` Language Application matrix — `AskUserQuestion.label` and `header` stay English (UI button + chip contract); `question` and `description` follow `outputLanguage`. Commit/PR/Jira/Wiki payloads: subject + branch names + code identifiers stay English; body text follows `outputLanguage`.
+> **Language**: Per `refs/rules.md` Language Application matrix  -  `AskUserQuestion.label` and `header` stay English (UI button + chip contract); `question` and `description` follow `outputLanguage`. Commit/PR/Jira/Wiki payloads: subject + branch names + code identifiers stay English; body text follows `outputLanguage`.
 
 ## Steps
 
 1. **Fetch repo list** per provider/account, then optionally merge local checkouts:
    ```bash
-   # GitHub (only when an account was selected — see _account-picker)
+   # GitHub (only when an account was selected  -  see _account-picker)
    ~/.claude/lib/repo-cache.sh github "$ACCOUNT_GH_OWNER"
 
-   # Bitbucket (work — only when an account was selected)
+   # Bitbucket (work  -  only when an account was selected)
    BB_TOKEN_KEY="$ACCOUNT_BB_TOKEN_KEY" \
    BB_USER_KEY="$ACCOUNT_BB_USER_KEY" \
    BB_HOST="$ACCOUNT_BB_HOST" \
      ~/.claude/lib/repo-cache.sh bitbucket "$BB_PROJECT_KEY"
 
-   # Local — for freetext/no-tracker flows, scan $HOME for .git checkouts so a
+   # Local  -  for freetext/no-tracker flows, scan $HOME for .git checkouts so a
    # user with no provider account can still pick a repo and run the pipeline.
    ~/.claude/lib/repo-cache.sh local "$HOME"
    ```
@@ -30,7 +30,7 @@ Used by `picker-issue`, `picker-jira`, `gh-num`, and `freetext` flows.
    Local rows expose `localPath` (filesystem path) and a redacted `remoteUrl`
    (credentials stripped at cache time).
 
-2. **Show list** via AskUserQuestion (multiSelect=true):
+2. **Show list** via AskUserQuestion (multiSelect=true). Print the breadcrumb narrator line first (per `refs/picker-contract.md` Step narration): `<localized: "Step 2/N: repo selection">`.
    ```
    [2/N] Select repos (multi):
      [ ] <repo-a>      (github)
@@ -42,9 +42,9 @@ Used by `picker-issue`, `picker-jira`, `gh-num`, and `freetext` flows.
    - forks fall to the bottom
    - local-only rows show `(local)` and the trimmed `$HOME`-relative path
 
-3. **Single-repo mode** — used for `gh-num`/`freetext` (multiSelect=false)
+3. **Single-repo mode**  -  used for `gh-num`/`freetext` (multiSelect=false)
 
-4. **All-local selection** — when every selected repo has `provider="local"`,
+4. **All-local selection**  -  when every selected repo has `provider="local"`,
    downstream phases switch to local-only behavior: no remote push, no PR, no
    Jira/Wiki/Confluence channels. Mixed selections (some local, some provider)
    apply per-repo: the local repos stay offline, the provider repos use their

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

@@ -0,0 +1,129 @@
+---
+description: "Resolve the Section 20 Risks and Open Questions of an analysis v3 document one row at a time. Proposes up to 3 source-labeled answer candidates per row (from evidence / from repo / AI reasoned), merges the chosen answer into the target body section, and updates the doc in place with a Section 23 changelog bump. Companion to /multi-agent:analysis - same Locked decisions apply (citation discipline, humanizer punctuation, no MCP, no auto-commit). Optional sibling propagation for per-platform file sets."
+argument-hint: "[path/to/analysis/<feature>-<platform>.md] [--autonomous]"
+---
+
+# multi-agent analysis-resolve - Open Question Resolver for Analysis Docs
+
+Companion command to `/multi-agent:analysis`. Takes an `analysis/<feature>-<platform>.md` (template v3) and walks the user through the open rows of Section 20 (Riskler ve Acik Sorular / Risks and Open Questions) one row at a time, proposing source-labeled answer candidates and merging the chosen answer into the proper body section. The pattern is ported from the ai-mobile-toolkit resolver skills (`mobile-screen-spec-resolver`, `mobile-flow-spec-resolver`) and adapted to the analysis doc contract.
+
+**Core invariant - read this twice:** the analysis doc is authoritative and forward-looking. The resolver never invents an answer; if no source produces a credible candidate, the only options offered are Defer and Other. Each Section 20 row is its own decision; never blend candidates across rows.
+
+> **Language**: Per `refs/rules.md` Language Application matrix - instruction prose stays English. `AskUserQuestion.label` and `header` stay English; `question` and `description` follow `prefs.global.outputLanguage`. Fragments written INTO the doc follow the doc's own front-matter `language` field (not `outputLanguage`), so a `tr` doc stays uniformly Turkish even when the session language differs.
+
+## Inherited Locked decisions (from /multi-agent:analysis - binding here)
+
+- **Locked 3 (citation discipline).** A resolution that introduces a quoted UI string, endpoint path, error code, or analytics event name must carry a citation (`[Figma <nodeId>]`, `file:line`, `Confluence:<pageId>:<heading-slug>`). If the user's free-text Other answer quotes a string with no citation, ask one follow-up: `Where does this string come from?` with options `Repo file:line` / `Existing doc citation` / `Don't quote it`.
+- **Locked 4 (forward-looking spec).** Repo-sourced answers that describe current/legacy behavior merge as `> Legacy reference: <text> (file:line)` blockquotes under the target entry, never as the lead sentence or a primary table row.
+- **Locked 6 (no auto-commit).** The command rewrites the doc file(s) but never runs `git add` or `git commit`.
+- **Locked 7 (humanizer punctuation).** Every fragment this command writes into the doc uses ASCII punctuation only: no em-dash (U+2014), en-dash (U+2013), ellipsis (U+2026), curly quotes, or section sign. Diacritics are preserved verbatim (Turkish letters stay as-is; never ASCII-fold prose). Run the verification grep from `analysis.md` Phase 3 step 3 after the final save.
+- **Locked 24 (Pass B footnote).** When a resolution overrides a convention cell in Section 13 (or any per-platform projection), the cell's footnote is rewritten to `^[user-override: resolved via analysis-resolve <date>]`.
+- **Locked 30 (no MCP outside analysis phase).** This command makes NO Figma MCP calls, no `api.figma.com` requests, no `figma.com/design/...` fetches. A row that genuinely needs new design information gets only `Defer` plus a printed recommendation to re-run `/multi-agent:analysis` for that input. Repo reads and `~/.claude/lib/extract-conventions.sh` re-runs are allowed (they are local evidence, not design fetches).
+
+## 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.
+
+## Input
+
+- `$ARGUMENTS` - optional doc path. If empty, auto-glob at Phase 0.
+- `--autonomous` - auto-pick the strongest candidate where exactly one source is credible; Defer otherwise. No per-row prompts; final report still printed.
+
+## Steps
+
+### Phase 0 - Intake
+
+**Step 1 - Doc picker.** If `$ARGUMENTS` has a path, validate it. Otherwise glob `analysis/*-{ios,android,backend,frontend}.md` under cwd (and each repo root from `state.analysisSpec.repos[]` when the session still holds analysis state):
+- 1 match: use it; echo the path, no question.
+- 0 or 2+ matches: AskUserQuestion, `header: "Doc"`, question `<localized: "Which analysis document should we resolve?">`, options = matches (max 3) + Other for a free-typed path.
+
+**Validate**: file exists; front-matter parses with `template_version: v3` (a `v2` doc gets `WARN: v2 doc has no resolvable Section 20 contract; re-run /multi-agent:analysis` and the run halts); a `## <n>. Riskler ve Acik Sorular` / `## <n>. Risks and Open Questions` heading exists (numbering may have re-flowed per the omission rule - match by title, not by the literal number 20).
+
+**Step 2 - Repo root for "from repo" candidates.** Default order: front-matter platform's repo from `state.analysisSpec.repos[]` if the session holds it, else the repo containing the doc, else cwd. Confirm via AskUserQuestion only when no default resolves (`header: "Repo"`, options `Use current working directory` + Other).
+
+**Step 3 - Mode.** Skipped when `--autonomous` was passed. AskUserQuestion, `header: "Mode"`, question `<localized: "Walk each question interactively, or run autonomously?">`, options:
+- `Interactive (Recommended)` - one question at a time
+- `Autonomous` - auto-pick where exactly one credible candidate exists, Defer otherwise
+
+**Echo** one line: `Resolve: <doc> | repo: <path> | mode: <interactive|autonomous>. Parsing Section 20.`
+
+### 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).
+
+## Reusable refs
+
+| Path | Reason |
+|------|--------|
+| `refs/analysis-template.md` | Section 20 / Section 23 table contracts, front-matter shape, omission re-flow |
+| `refs/conventions-defaults.md` | `convention-fallback` default values per platform |
+| `~/.claude/lib/extract-conventions.sh` | fresh single-field extraction for convention-fallback candidates |
+| `pipeline/skills/shared/external/humanizer/SKILL.md` | tone reference for longer merged fragments (short fragments only need the punctuation gate) |
+
+## Notes
+
+- This command is downstream-safe: it edits only the analysis doc, so the Locked 30 contract (analysis doc as the sole design source for Phase 2+) is strengthened, not weakened - dev phases consume a doc with fewer open holes.
+- The resolver is idempotent over `Karar verildi / Decided` rows: re-running skips them.
+- When the session no longer holds `state.analysisSpec`, everything still works: evidence candidates fall back to what the doc itself cites, and repo candidates come from the Phase 1 subagent.