@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/commands/multi-agent/refs/channels/confluence.md

@@ -0,0 +1,153 @@
+# Channel adapter — Confluence page
+
+> Detailed contract for the `confluence` channel of `/multi-agent:channels`. Split out of `channels.md` in v8.0.0; the parent doc keeps a one-line summary and a link here.
+
+The Confluence adapter creates or updates a Confluence page under a chosen parent. Like the Jira adapter, it runs **once** per invocation — the page lives at the primary repo's component slug in multi-repo mode.
+
+## Required body structure
+
+Every Confluence page written by this adapter follows the same section order. Section headings render in `prefs.global.outputLanguage`; the template (this doc) is English because `promptLanguage="en"` is locked, but the runtime body is in the user's language.
+
+| # | Section key | Heading (`tr`) | Heading (`en`) | Required? |
+|---|---|---|---|---|
+| 1 | `overview` | `## Genel Bakış` | `## Overview` | always |
+| 2 | `flow` | `## Akış Diyagramı` | `## Flow Diagram` | when work involves a non-trivial sequence (auth, payment, multi-step UI, async pipeline) |
+| 3 | `technical_details` | `## Teknik Detaylar` | `## Technical Details` | always |
+| 4 | `api_contracts` | `## API Kontratları` | `## API Contracts` | when work added or modified HTTP endpoints, GraphQL ops, or RPC methods |
+| 5 | `references` | `## İlgili Bağlantılar` | `## References` | when any context link exists |
+
+> Headings in the source markdown are `##`; the storage-format converter rewrites them to `<h2>…</h2>`. Sub-headings (`###`) become `<h3>` and so on.
+
+### Section content rules
+
+**`overview`** — 3-6 sentences. Audience is stakeholders/PM/designers, not engineers — explain the change in user/business terms first, then a single sentence on the technical approach. No marketing voice, no "we are proud to announce".
+
+**`flow`** — when included, embed a flow diagram. Preferred form is a Mermaid block (Confluence renders Mermaid via the storage-format macro when the space has the plugin enabled); fallback is a numbered step list when Mermaid is unavailable. Template shape:
+
+```markdown
+## Flow Diagram
+
+\`\`\`mermaid
+sequenceDiagram
+  participant <actor>
+  participant <service>
+  <actor>->><service>: <request>
+  <service>-->><actor>: <response>
+\`\`\`
+```
+
+Replace `<actor>` / `<service>` with the real names at write-time; do not invent placeholders that don't exist in the diff.
+
+**`technical_details`** — bullet list or sub-sections covering implementation specifics: data flow, key components touched, edge cases handled, performance notes. Code identifiers stay verbatim across languages.
+
+**`api_contracts`** — for each new/changed endpoint:
+
+```markdown
+### <METHOD> <path>
+
+**Request**
+\`\`\`json
+{ "..." }
+\`\`\`
+
+**Response — 200**
+\`\`\`json
+{ "..." }
+\`\`\`
+
+**Error responses**
+- `400` — <when>
+- `401` — <when>
+- `404` — <when>
+```
+
+When the task referenced a Confluence API-contract source page (see Phase 0 link extraction / Phase 1 context injection), this section may consume that contract directly — verbatim where it matches, with a `(source: <confluence-page-url>)` annotation at the end of the section.
+
+**`references`** — flat bullet list, mirrors the Jira `## References` shape (Swagger, Figma, Crashlytics, Fortify, source Confluence pages, PR URLs). Emit one line per link, never deduplicate across categories.
+
+### Assembly order (per run)
+
+```
+1. Read agent-state.json (taskId, contextLinks, prUrls, language).
+2. Build section bodies in markdown — overview first, then in the table order, skipping conditional sections that don't apply.
+3. Run the assembled body through the `humanizer` skill (tone target: formal, stakeholder-readable).
+4. Convert markdown → Confluence storage XML (see table below).
+5. POST / PUT.
+```
+
+## Token check
+
+1. Read `prefs.global.keychainMapping.confluence` → `~/.claude/lib/credential-store.sh get`.
+2. Missing → trigger the inline Token Save Flow from `setup.md` (clipboard-based). User can save the token now or skip the run.
+3. Expired (`401 Unauthorized`) → same Save Flow with the `expired` trigger.
+4. Skipped → adapter returns `{status: "skipped", reason: "no token"}`, does NOT block other adapters.
+
+## Parent page resolution
+
+Recents from `prefs.projects[<project>].confluenceUrls` (LRU, max 5):
+
+```
+Confluence parent page URL:
+  Recent [1]: https://<host>/display/<SPACE>/ComponentLibrary   (enter to reuse)
+  Recent [2]: https://<host>/display/<SPACE>/Releases
+  [p] Paste new URL
+  [s] Skip this run
+```
+
+`spaceKey` + `parentId` extracted from URL with these patterns:
+
+| URL form | Extraction |
+|---|---|
+| `/display/<SPACE>/<title>` | `spaceKey=<SPACE>`, `parentId` looked up via `GET /rest/api/content?spaceKey=<SPACE>&title=<title>` |
+| `?pageId=12345` | `parentId=12345`, `spaceKey` resolved from page's `space.key` |
+| `/spaces/<SPACE>/pages/12345/<title>` | both fields direct |
+
+## Page title
+
+Auto-suggested as `"{jiraId} — {taskTitle}"` — user can edit at the prompt. The `taskTitle` comes from `state.taskTitle` if set, else from the Jira summary, else from the PR title.
+
+## Body conversion (markdown → storage format)
+
+| Markdown | Confluence storage XML |
+|---|---|
+| `### Heading` | `<h3>Heading</h3>` |
+| Tables | `<table><tr><th>...</th>...</tr><tr><td>...</td>...</tr></table>` |
+| Code fences ` ```lang ` | `<ac:structured-macro ac:name="code"><ac:parameter ac:name="language">lang</ac:parameter><ac:plain-text-body><![CDATA[...]]></ac:plain-text-body></ac:structured-macro>` |
+| Inline `code` | `<code>code</code>` |
+| Links `[t](u)` | `<a href="u">t</a>` |
+| Lists | `<ul><li>...</li></ul>` / `<ol><li>...</li></ol>` |
+
+Body is run through humanizer before XML conversion — Confluence tone is the most formal of the four channels (target audience: stakeholders, PMs, designers).
+
+## POST contract
+
+```
+POST /rest/api/content
+{
+  "type": "page",
+  "title": "<title>",
+  "space": { "key": "<spaceKey>" },
+  "ancestors": [{ "id": "<parentId>" }],
+  "body": {
+    "storage": {
+      "value": "<storage-format-body>",
+      "representation": "storage"
+    }
+  }
+}
+```
+
+If a page with the same title already lives under that parent, the adapter switches to update mode: `GET /rest/api/content/<id>?expand=version` → `PUT /rest/api/content/<id>` with incremented `version.number`.
+
+## Recents persistence
+
+Successful POST → URL prepended to `prefs.projects[<project>].confluenceUrls` (dedup by URL, trim to 5 entries). Surfaces as `Recent [1]` on the next run.
+
+## Hard rules (must not regress)
+
+- Real newlines and no HTML entities in the source body — XML conversion happens at adapter time, never embed `\n` literals.
+- Section order is fixed: `overview` → `flow` (cond.) → `technical_details` → `api_contracts` (cond.) → `references` (cond.). Conditional sections may be omitted but never reordered.
+- Humanizer pass runs **after** body assembly and **before** storage-XML conversion. Tone: formal, stakeholder-readable. No "we are excited", no first-person plural.
+- Body content language follows `prefs.global.outputLanguage`. Code identifiers, API paths, file paths, type names, JSON keys, and the storage-XML markup stay verbatim. The template (this doc) is English because `promptLanguage="en"` is locked.
+- Adapter failures are non-blocking. 401 / network timeout / parent-not-found → `failed` status, loop continues.
+- If `--dry-run`, print the assembled storage XML to stdout and return without POST.

package/pipeline/commands/multi-agent/refs/channels/issue-comment.md

@@ -0,0 +1,141 @@
+# Channel adapter — GitHub Issue comment
+
+> Canonical template for the `issue` channel of `/multi-agent:channels`. Every successful run that touched a tracked GitHub issue MUST post one comment using this template — no exceptions, no "state-only" shortcuts.
+
+## When this fires
+
+The Issue Comment adapter runs once per channels invocation when:
+
+```
+state.tracker.kind === "github-issue"  AND  channels.selected includes "issue"
+```
+
+In multi-repo tasks, the issue lives on the primary repo's issue tracker. Extras don't get separate issue comments — their PRs are linked back through the comment body.
+
+## The hard rule
+
+**Never update the issue body Progress flags without ALSO posting a comment.** The comment is the human-readable narrative; flags are the machine-readable status. Either both or neither. A run that updates flags without commenting is a contract violation and the run is incomplete.
+
+## Required body structure
+
+The template (this doc) is English because `promptLanguage="en"` is locked. At write-time, headings and prose render in `prefs.global.outputLanguage`; code identifiers, repo/branch/commit names, URLs, and the `Ref: #N` footer stay verbatim across languages.
+
+| # | Section key | Heading (`tr`) | Heading (`en`) | Required? |
+|---|---|---|---|---|
+| 1 | `title` | `## Geliştirme Detayı — \`<name>\`` | `## Implementation Detail — \`<name>\`` | always |
+| 2 | `summary` | (paragraphs immediately under the title) | (same) | always |
+| 3 | `prs_branches` | `### Pull Request / Dal` | `### Pull Requests / Branches` | always |
+| 4 | `acceptance_criteria` | `### Kabul Kriterleri` | `### Acceptance Criteria` | always |
+| 5 | `build_and_test` | `### Build & Test` | `### Build & Test` | always (heading stays English — tooling token) |
+| 6 | `figma_extras` | `### Code Connect / Wiki` | `### Code Connect / Wiki` | only on the figma component task type |
+| 7 | `next_steps` | `### Sonraki Adımlar` | `### Next Steps` | always (empty list allowed — signals "fully complete") |
+| 8 | `ref_footer` | `Ref: #<issueNumber>` | `Ref: #<issueNumber>` | always (token text, never translated) |
+
+### Template body (English — runtime renders headings in `outputLanguage`)
+
+```markdown
+## Implementation Detail — `<ComponentOrTaskName>`
+
+<1-3 paragraphs: why this approach was chosen, what changed, any architectural decision worth flagging>
+
+### Pull Requests / Branches
+- **<repoName>:** <prKindLabel> — <prUrl OR "branch `<branchName>` pushed (commit `<shortSha>`), PR not opened">
+<one line per repo touched; never collapse multiple repos into one>
+
+### Acceptance Criteria
+- [<x|·>] <AC text — `x` if delivered, `·` if intentionally deferred (with `(deferred: <reason>)` suffix)>
+<one bullet per AC item from the issue body, or per implicit AC if the issue had none>
+
+### Build & Test
+- Build: <green|red|baseline-pre-existing|skipped> — <one-line evidence: command + result OR "pre-existing failure verified on `<baselineSha>`">
+- Tests: <N tests added | tests skipped (Phase 5 user-test path) | none>
+<for figma component flow, also:>
+- Code Connect: <published | dry-run-only | not-applicable> — <URL of Figma node if published>
+- Wiki: <published | local-only | skipped> — <URL of wiki page if published>
+
+### Next Steps
+- <follow-up bullet — PRs to open, manual deploys, push consents needed>
+<empty list is fine; the section header itself stays>
+
+Ref: #<issueNumber>
+```
+
+### Section content rules
+
+- **`title`** — always wraps the component or task name in backticks. No emoji.
+- **`summary`** — 1-3 paragraphs, **why** before **what**. No bullet lists in the summary block — those belong in `acceptance_criteria`.
+- **`prs_branches`** — every repo the run touched gets exactly ONE line. If the PR was deferred, write the branch + commit SHA explicitly so the reader can `gh pr create` from there. Never collapse multiple repos into one line.
+- **`acceptance_criteria`** — copy from the issue body verbatim when an `### Acceptance Criteria` section exists. If the section is `_No response_`, the agent enumerates the implicit ACs it satisfied during Phase 1/3. `[x]` only when delivered and verified; `[·]` for deferred (with reason in parens).
+- **`build_and_test`** — required. If a build failure was pre-existing, the line includes the baseline SHA where the failure was reproduced (per `feedback_build_baseline_proof.md`).
+- **`figma_extras`** — emitted only when `state.taskType == "component"` and the figma sub-pipeline ran.
+- **`next_steps`** — empty list is fine; the section header itself stays. Empty signals "fully complete, no follow-ups".
+- **`ref_footer`** — always `Ref: #N` (or `Related: #N`). NEVER `Closes/Fixes/Resolves` — the pipeline never auto-closes issues (`feedback_no_issue_close.md`).
+
+### Assembly order (per run)
+
+```
+1. Read agent-state.json (taskId, contextLinks, prUrls, taskType, language).
+2. Build section bodies in markdown — title first, then in the table order, skipping conditional sections that don't apply.
+3. Run the assembled body through the `humanizer` skill.
+4. Apply compaction policy if length > 4000 chars (see below).
+5. POST via `gh issue comment`.
+```
+
+## Hard prohibitions
+
+- No "Co-Authored-By: Claude" trailer. No "🤖 Generated with …" footer. No mention of Claude / Copilot / AI / model names anywhere in the body.
+- No em-dashes (`—`) in prose. Use ` · ` or `→` per `feedback_no_em_dash.md`.
+- No HTML entities. Use raw markdown.
+- No links to internal `/tmp/*` or local-machine paths.
+- No screenshots embedded as base64 — link to wiki / Figma instead.
+
+## Compaction policy
+
+If the comment exceeds 4000 characters, compact in this order:
+
+1. `summary` trimmed to 1 paragraph.
+2. `acceptance_criteria` list moved to a `<details>` collapsible.
+3. `build_and_test` details collapsed to a one-line outcome.
+4. `prs_branches` stays verbatim — never compact.
+5. `next_steps` stays verbatim — never compact.
+
+Below 4000 chars, no compaction; render the full template.
+
+## API contract
+
+```bash
+gh issue comment "$ISSUE_NUMBER" --repo "$ORG/$REPO" --body-file /tmp/channels-$TASK_ID-issue.md
+```
+
+Token resolution: `gh auth status` for the active GitHub account selected in Phase 0. The comment is authored by the configured Git identity, posted via that account's PAT.
+
+## Pairing with the Progress flag updater
+
+Every issue comment post is paired with `pipeline/scripts/update-issue-progress.sh "$TASK_ID"` in the same Phase 7 step. Order: comment FIRST (so the timestamp marks the run), flags SECOND (so the body diff is one logical change).
+
+```bash
+# Phase 7 Step 5 — issue channel
+gh issue comment "$ISSUE_NUMBER" --repo "$ORG/$REPO" --body-file /tmp/channels-$TASK_ID-issue.md
+bash $HOME/.claude/scripts/update-issue-progress.sh "$TASK_ID"
+```
+
+If either call fails, the channel adapter MUST NOT mark the issue channel as completed in `agent-state.json`. The user sees a clear error and can retry.
+
+## Drift detection
+
+`pipeline/scripts/smoke-issue-comment-template.sh` greps the latest 5 issue comments authored by the configured Git identity and asserts each contains:
+
+- `## Geliştirme Detayı` OR `## Implementation Detail` (language axis)
+- `### Pull Requests` OR `### Branches`
+- `### Acceptance Criteria`
+- `### Build & Test`
+- `Ref: #` footer
+
+A failed assertion blocks `pre-push-check.sh`. This catches runs where the agent free-formed the comment instead of using the template.
+
+## Hard rules (must not regress)
+
+- Section order is fixed: `title` → `summary` → `prs_branches` → `acceptance_criteria` → `build_and_test` → `figma_extras` (cond.) → `next_steps` → `ref_footer`. Conditional sections may be omitted but never reordered.
+- Humanizer pass runs **after** body assembly and **before** compaction / POST.
+- Body content language follows `prefs.global.outputLanguage`. Repo names, branch names, commit SHAs, URLs, the `Ref: #N` footer, and the `### Build & Test` heading itself stay verbatim. The template (this doc) is English because `promptLanguage="en"` is locked.
+- Never update issue body Progress flags without also posting this comment — see "The hard rule" above and `pairing` block below.

package/pipeline/commands/multi-agent/refs/channels/jira.md

@@ -0,0 +1,127 @@
+# Channel adapter — Jira comment
+
+> Detailed contract for the `jira` channel of `/multi-agent:channels`. Split out of `channels.md` in v8.0.0; the parent doc keeps a one-line summary and a link here.
+
+The Jira adapter posts a comment on the linked issue. The Jira ticket is shared by all repos in a multi-repo task, so the adapter runs **once** per channels invocation regardless of how many PR targets are dispatched in parallel.
+
+## Required body structure
+
+Every Jira comment posted by this adapter follows the same section order. Section headings render in `prefs.global.outputLanguage` (Turkish when `tr`, English when `en`); section keys and the structure itself are stable across languages so downstream tooling and humans both know where to look.
+
+| # | Section key | Heading (`tr`) | Heading (`en`) | Required? |
+|---|---|---|---|---|
+| 1 | `summary` | `## Yapılan Çalışma Özeti` | `## Work Summary` | always |
+| 2 | `test_scenarios` | `## Test Senaryoları` | `## Test Scenarios` | always (use "—" placeholder line if truly N/A) |
+| 3 | `context_refs` | `## Bağlantılar` | `## References` | when any link exists |
+
+> Heading levels in the source markdown are `##`. The wiki-markup converter (next section) rewrites them to `h2.` for Jira rendering.
+
+### Section content rules
+
+**`summary`** — 2-5 sentences in `outputLanguage`. What changed, why, and the user-visible impact. No "we", no marketing tone. Past tense (the work is done at the time the comment goes up).
+
+**`test_scenarios`** — Given/When/Then numbered list. One scenario per acceptance criterion. The heading and scenario text are rendered in `outputLanguage` at write-time; the template itself (this file) shows the English skeleton:
+
+```markdown
+## Test Scenarios
+
+1. **Given** a signed-in user
+   **When** they navigate to the Profile screen
+   **Then** their saved preferences appear in the configured order
+2. **Given** ...
+```
+
+Code identifiers (function names, file paths) stay verbatim — they are not translated. When there are no executable scenarios (pure doc change, dependency bump), write a single line: `- No manual test required — <short reason>`.
+
+**`context_refs`** — flat bullet list of external links the work depends on or produced. PR URL is **not** repeated here; it lives on the first line (see *Cross-link injection*). Common entries (only when present in the task):
+
+```markdown
+## References
+
+- Confluence: <page-url>
+- Swagger: <openapi-url>
+- Figma: <design-url>
+- Crashlytics: <issue-url>
+- Fortify: <findings-url>
+```
+
+The links are pulled from `agent-state.json.contextLinks[]` (see Phase 0 link extraction). Empty `contextLinks[]` ⇒ section omitted.
+
+### Assembly order (per run)
+
+```
+1. Read agent-state.json (taskId, contextLinks, prUrls, language).
+2. Build section bodies in markdown — summary first, test_scenarios next, context_refs last.
+3. Run the assembled body through the `humanizer` skill (see Hard rules below).
+4. Apply Cross-link injection (PR URL on line 1).
+5. Run Wiki markup conversion.
+6. POST.
+```
+
+## Wiki markup conversion
+
+Body markdown is rewritten to Jira wiki markup before POST:
+
+| Markdown | Jira wiki |
+|---|---|
+| `### Heading` | `*Heading*` |
+| `- [ ] task` / `- [x] task` | `# task` (numbered list — Jira renders TODO checkboxes inconsistently) |
+| `` `code` `` | `{{code}}` |
+| Tables (` | h | h | / | --- | --- |`) | `||h||h||` then `|c|c|` rows |
+| Code fences ` ```lang ` | `{code:lang} ... {code}` |
+
+Lines outside these patterns pass through verbatim. Multi-paragraph blocks are joined with one blank line.
+
+## Cross-link injection
+
+The adapter prepends the linked PR URL on the **first line** so reviewers can jump to the PR with one click:
+
+```
+PR: https://github.com/<org>/<repo>/pull/4321
+
+Phase 4 review accepted 2 findings...
+```
+
+In multi-repo mode, `channels-multi-repo.sh render-jira <state> <body>` prepends a bulleted `* PR:` list — primary first, extras after. Single-repo tasks fall through to the unchanged body.
+
+## Token resolution
+
+Token comes from `prefs.global.keychainMapping.jira` → `~/.claude/lib/credential-store.sh get "$ACCOUNT_JIRA_TOKEN_KEY"`. Resolution path:
+
+1. Read `keychainMapping.jira` from prefs.
+2. Resolve via `credential-store.sh get` — the driver auto-delegates to `keychain.py` on macOS / Linux and PowerShell `CredentialManager` on Windows.
+3. Missing → adapter prompts the inline Token Save Flow from `setup.md` (clipboard-based); user can save now or skip this run.
+4. Expired (401) → same Save Flow with the "expired" trigger; on skip, returns `{status: "skipped", reason: "token expired"}`, does not block other adapters.
+
+## POST contract
+
+```
+POST /rest/api/2/issue/{id}/comment
+Authorization: Bearer $JIRA_TOKEN
+Content-Type: application/json
+```
+
+Body assembled with `jq --rawfile` + `curl --data-binary @file`:
+
+```bash
+jq -n --rawfile body /tmp/channels-$TASK_ID-jira.txt '{body: $body}' \
+  > /tmp/channels-$TASK_ID-jira-payload.json
+curl -s -X POST -H "Authorization: Bearer $JIRA_TOKEN" \
+     -H "Content-Type: application/json" \
+     --data-binary @/tmp/channels-$TASK_ID-jira-payload.json \
+     "$JIRA_BASE/rest/api/2/issue/$JIRA_ID/comment"
+```
+
+The dispatch summary line includes the comment URL with `?focusedCommentId=…` so the user can paste it into Slack/Teams.
+
+## Wiki → Jira auto-link triad
+
+When the **Wiki** adapter writes pages on the same run AND `prefs.global.wikiToJiraComment === true`, the Wiki adapter also posts a humanizer-passed Jira comment summarizing wiki pages (component name + variant count + wiki URL). That secondary comment is independent of this adapter — both can coexist on the same issue. Full contract: `refs/issue-jira-triad.md`.
+
+## Hard rules (must not regress)
+
+- Real newlines, no HTML entities — heredoc + `jq --rawfile` + `curl --data-binary @file`.
+- Section order is fixed: `summary` → `test_scenarios` → `context_refs`. Never insert sections between them; never reorder.
+- Humanizer pass runs **after** body assembly and **before** wiki-markup conversion. Tone target: informal but technical. No marketing voice, no "we are excited", no "I have…".
+- Body content language follows `prefs.global.outputLanguage`. Code identifiers, file paths, type names, branch names, and the wiki-markup syntax stay verbatim. The `promptLanguage="en"` lock means any LLM prompt that produces the body is in English; the body itself is then rendered in the user's language.
+- Adapter failures are non-blocking — a missing token or 401 returns `skipped`/`failed`, the loop keeps going for PR / Confluence / Wiki.

package/pipeline/commands/multi-agent/refs/channels/pr-review-actions.md

@@ -0,0 +1,135 @@
+# Channel adapter — Pull Request review actions
+
+> Canonical contract for the PR-actions branch of `/multi-agent:review`. The PR-side artifacts are **per-finding inline comments + an explicit approve / needs-work decision** — never a single monolithic description comment.
+
+## When this fires
+
+```
+review.input.kind === "pr"   (PR URL, #N, or repo#N input)
+```
+
+Branch-only invocations (`/multi-agent:review feature/foo`) do NOT post anything — chat-only summary is the only artifact.
+
+## The decision rule
+
+After triage, count the `accepted` findings by severity:
+
+| Accepted blocking | Accepted important | Accepted suggestion | Decision | Inline comments |
+|---|---|---|---|---|
+| 0 | 0 | 0 | **APPROVE** | none |
+| 0 | 0 | ≥1 | **APPROVE** | none (suggestions stay in chat summary only) |
+| 0 | ≥1 | any | **NEEDS WORK / REQUEST CHANGES** | one per accepted blocking + important |
+| ≥1 | any | any | **NEEDS WORK / REQUEST CHANGES** | one per accepted blocking + important |
+
+**Hard rule — no monolithic description comment.** "Post one big advisory comment with verdict + tables + finding sections" is forbidden. Every finding that warrants posting MUST be an inline comment anchored to `file:line`. The verdict itself is the review state (APPROVED / NEEDS_WORK), not a comment body.
+
+**Suggestions never block and never get inline comments by default.** They only appear in the chat summary. Inline-posting suggestions floods the PR for taste-level concerns; reserve PR comments for blocking + important.
+
+## Inline comment template (per finding)
+
+Body language follows `prefs.global.outputLanguage`. Both forms below are 1:1 — pick the matching one at render time.
+
+### Turkish (outputLanguage = "tr")
+
+```markdown
+{severityEmoji} **{severityLabelTr}** — {issueTr}
+
+**Öneri:** {fixTr}
+
+{Optional rule reference, e.g.:}
+_apple-archive-compliance / no-force-unwrap — Guideline 2.1.1_
+
+---
+🤖 _Multi-Agent Review · iteration #{iterationNumber}_
+```
+
+Severity labels (TR):
+- `blocking` → `🔴 **Blocker**`
+- `important` → `🟡 **Önemli**`
+
+### English (outputLanguage = "en")
+
+```markdown
+{severityEmoji} **{severityLabelEn}** — {issueEn}
+
+**Suggestion:** {fixEn}
+
+{Optional rule reference}
+
+---
+🤖 _Multi-Agent Review · iteration #{iterationNumber}_
+```
+
+Severity labels (EN):
+- `blocking` → `🔴 **Blocker**`
+- `important` → `🟡 **Important**`
+
+### Anchoring
+
+| Provider | Endpoint | Anchor |
+|---|---|---|
+| GitHub | `POST /repos/{owner}/{repo}/pulls/{n}/comments` | `path` + `line` (right side) + `commit_id` |
+| Bitbucket Server | `POST /rest/api/1.0/projects/{key}/repos/{slug}/pull-requests/{id}/comments` with `anchor: { path, line, lineType: "ADDED", fileType: "TO" }` | `path` + `line` |
+
+If a finding's `line` falls outside the diff (review of unchanged code), the anchor is dropped and the comment becomes a top-level PR comment instead — same body, no inline anchor.
+
+## Decision endpoints
+
+| Provider | Approve | Needs Work / Request Changes |
+|---|---|---|
+| GitHub | `gh pr review <N> --approve` | `gh pr review <N> --request-changes --body "<empty>"` |
+| Bitbucket Server | `PUT /pull-requests/{id}/participants/{userSlug}` body `{"status":"APPROVED"}` | `PUT /pull-requests/{id}/participants/{userSlug}` body `{"status":"NEEDS_WORK"}` |
+
+The Bitbucket needs-work pattern keeps the user as REVIEWER role; status flip is the visible "Request changes" signal in the UI.
+
+## Order of operations
+
+1. Decide: APPROVE vs NEEDS_WORK from the table above.
+2. If NEEDS_WORK: post one inline comment per accepted blocking + important finding, in `outputLanguage`.
+3. Set the review state (APPROVE / NEEDS_WORK) — this is the durable verdict signal.
+4. The chat summary still prints regardless (live conversation). Suggestions go to chat only.
+
+Comments and the decision are paired — the decision is set AFTER comments are posted so reviewers see the inlines before the state flag.
+
+## Hard prohibitions
+
+- No monolith description comment (no "## 🔍 Multi-Agent Review — PR #N" body).
+- No `Closes #` / `Fixes #` / `Resolves #` keywords in any comment.
+- No em-dashes (`—`) in free-form reviewer prose (the `issue` / `fix` body text); use ` · ` or `→`. The em-dash in the fixed inline template (severity label separator, e.g. `**Blocker** — {issue}`) is part of the rendered shape, not prose, and is allowed.
+- No model vendor names in comment prose; the chat-side table column header is the only place they may appear.
+- No suggestion-severity inline comments. Suggestions are chat-only.
+- No mixing languages in one comment body — pick `outputLanguage` and stick to it.
+
+## Idempotency
+
+Each `/multi-agent:review` invocation:
+- Posts new inline comments (does not edit prior runs' comments — preserves audit trail).
+- Sets review state via the appropriate endpoint (PUT/POST) — overwrites prior state for the same user.
+
+If the user re-runs review and findings shrink (e.g., from 3 important → 0), the state flips from NEEDS_WORK → APPROVED automatically.
+
+## Provider auto-detection
+
+```bash
+case "$prHostUrl" in
+  github.com|api.github.com)             provider=github ;;
+  bitbucket.*|*.bitbucket.*)             provider=bitbucket-server ;;
+  gitlab.*|*.gitlab.*)                   provider=gitlab ;;     # not implemented yet
+  *)                                     provider=unknown ;;
+esac
+```
+
+Unknown providers fall back to chat-only with a warning: "Provider not recognized for {host}. Findings printed to chat; manual review action required on the PR UI."
+
+## Pairing with the chat summary
+
+The chat-side summary ALWAYS prints with the verdict table (per-model breakdown for parallel runs). The summary stays in chat; the PR receives inline comments per finding + the state flag — the two channels do not mirror each other.
+
+## Drift detection
+
+`pipeline/scripts/smoke-pr-review-actions.sh` asserts:
+- The review.md flow uses `post-pr-review.sh` (not the legacy renderer).
+- The legacy `pr-review-comment.md` template + `render-pr-review-body.sh` are GONE (no traces).
+- The decision table appears verbatim in this file.
+- Both `tr` and `en` inline comment shapes are present.
+- Provider switch covers `github`, `bitbucket-server`, and a fallback case.