@mmerterden/multi-agent-pipeline 16.31.1 → 17.1.0

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

@@ -10,35 +10,89 @@ Every Jira comment posted by this adapter follows the same section order. Sectio
 
 | # | Section key | Heading (`tr`) | Heading (`en`) | Required? |
 |---|---|---|---|---|
-| 1 | `summary` | `## Yapılan Çalışma Özeti` | `## Work Summary` | always |
+| 1 | `summary` | `## Geliştirme Özeti` | `## Development 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 |
+| 3 | `impact` | `## Etki Analizi` | `## Impact Analysis` | always |
+| 4 | `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.
 
+**Jira is not the PR, and this is the contract that keeps getting that wrong.**
+The PR is read by a reviewer holding the diff. The Jira comment is read by the
+person who filed the ticket and by the tester who has to verify it, and neither
+of them has the diff open. So a Jira body carries no identifiers, no file paths,
+no stack frames, no diff hunks and no framework names. Counts in prose are fine
+and are often the most useful sentence in the comment ("two files, eight lines
+removed, no additions"); a class name is not. A sentence that needs a symbol to
+make its point is describing the change at the wrong level for this reader -
+restate the behaviour, not the mechanism. The technical account has a home, and
+it is the PR body (`channels/pr.md`).
+
 ### 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).
 
-**Visual evidence inside these two sections.** When `state.visualEvidence` carries artefacts, they render INSIDE `summary` and `test_scenarios` - never as a fourth section, which the fixed section order forbids. Upload first (`jira-attach.sh <issue> <file>...`), then reference by the returned filename:
+**Visual evidence inside these sections.** When `state.visualEvidence` carries artefacts, they render INSIDE `summary` and `test_scenarios` - never as a section of their own, which the fixed section order forbids. Phase 6 Step 2.9 has already uploaded them and written the returned name to `visualEvidence.*[].jiraFilename`: reference that name, and call `jira-attach.sh <issue> <file>...` only for an artefact whose `jiraFilename` is absent. Uploading unconditionally here attaches every file a second time whenever the comment is re-rendered - which is exactly what a post-hoc `/multi-agent:channels` run does.
 
 - `summary`, after its sentences: one line naming the pair in `outputLanguage` (`Düzeltme öncesi / Düzeltme sonrası`), then the thumbnails on the next line - `!<file>-before.png|thumbnail! !<file>-after.png|thumbnail!`.
 - `test_scenarios`, under the scenario the recording demonstrates: `!<file>-flow.mp4!` plus one line stating the tier used.
 
 A `gaps[]` entry prints its reason on the line where the artefact would have been (`Düzeltme öncesi: ticket'ta görsel yok`). Never an empty thumbnail, never a silent omission. Contract: `$HOME/.claude/multi-agent-refs/features/visual-evidence.md`.
 
-**`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:
+**`test_scenarios`**  -  one titled scenario per acceptance criterion, each a
+numbered list of steps ending in the expected result. Given/When/Then was the
+shape here for several releases and it reads as translated English to the person
+who actually runs these; a tester wants a list they can follow with the app open.
+The heading and the text render in `outputLanguage`; 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** ...
+**1. <what this scenario exercises>**
+1. <step the tester performs, in the app's own words>
+2. <step>
+3. **Expected:** <what they should see>
+
+**2. <regression scenario>**
+1. <step>
+2. **Expected:** <what should still behave as before>
 ```
 
-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>`.
+Order is load-bearing. The scenarios that reproduce the reported behaviour come
+first, then the regression scenarios for whatever the change could have disturbed -
+anything sharing the component that was touched. A comment that lists only the fix
+leaves the tester to guess the blast radius, and that guess is the one thing they
+cannot make from the ticket.
+
+Screens, fields and menu items are named the way the app shows them, in
+`outputLanguage`. Function names and file paths do not appear at all, per the rule
+above. When there are no executable scenarios (pure doc change, dependency bump),
+write a single line: `- No manual test required  -  <short reason>`.
+
+**`impact`**  -  four fixed numbered parts, each answered, never left as a
+placeholder. This is what a test lead reads before deciding how wide to test and
+what a release manager reads before deciding whether it ships this week, so it is
+written in the same plain register as the rest of the comment:
+
+```markdown
+## Impact Analysis
+
+**1 - The problem**
+<what was wrong and since when, in the reader's words>
+
+**2 - What was changed**
+<what the change does, and why the behaviour around it is unchanged>
+
+**3 - Affected areas**
+<the screens and flows that must be tested, including anything sharing the changed component>
+
+**4 - Effect on other systems**
+<none, or which service, contract or channel is affected>
+```
+
+Part 4 is answered "none" far more often than it is answered at all, and "none" is
+a real answer worth writing: it is what lets the reader stop looking.
 
 **`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):
 
@@ -58,7 +112,7 @@ The links are pulled from `agent-state.json.contextLinks[]` (see Phase 0 link ex
 
 ```
 1. Read agent-state.json (taskId, contextLinks, prUrls, language).
-2. Build section bodies in markdown  -  summary first, test_scenarios next, context_refs last.
+2. Build section bodies in markdown, in table order: summary, test_scenarios, impact, context_refs.
 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.
@@ -116,7 +170,7 @@ Do not hand-apply this table. It was hand-applied for several releases and a smi
 
 Lines outside these patterns pass through verbatim. Multi-paragraph blocks are joined with one blank line.
 
-Every row above is load-bearing, including the ones that look cosmetic. The table must cover each construct the section templates in this file actually emit  -  `##` for the three required headings, `**Given**` / `**When**` / `**Then**` in the test-scenario skeleton, and `1.`-numbered scenarios. A missing row does not degrade gracefully: the "pass through verbatim" fallback POSTs `## Test Senaryoları` and `**Given**` as literal text, so the comment renders with visible `##` and stray asterisks. Single `*bold*` in Markdown means *italic* in Jira wiki  -  never map `**bold**` to `*bold*` by dropping one asterisk mechanically without checking the source was bold, not italic.
+Every row above is load-bearing, including the ones that look cosmetic. The table must cover each construct the section templates in this file actually emit  -  `##` for the four required headings, `**1. title**` on a scenario and `**Expected:**` inside it, the `**1 - ...**` part labels in the impact section, and `1.`-numbered steps. A missing row does not degrade gracefully: the "pass through verbatim" fallback POSTs `## Test Senaryoları` and `**Expected:**` as literal text, so the comment renders with visible `##` and stray asterisks. Single `*bold*` in Markdown means *italic* in Jira wiki  -  never map `**bold**` to `*bold*` by dropping one asterisk mechanically without checking the source was bold, not italic.
 
 There is no markdown→Jira-wiki converter program in the pipeline (`lib/` ships `md2confluence-v3.py` for Confluence only, and `scripts/jira-wiki-escape.mjs` covers the emoticon step alone). This conversion table is applied by the model, by hand, which is exactly why it has to be complete.
 
@@ -149,19 +203,25 @@ Authorization: Bearer $JIRA_TOKEN
 Content-Type: application/json
 ```
 
-Body assembled with `jq --rawfile` + `curl --data-binary @file`, from the escaped file that *Emoticon escaping* produced:
+**Post through `jira-publish.sh`. Never hand-roll the `curl`.**
 
 ```bash
-node "$HOME/.claude/scripts/jira-wiki-escape.mjs" --check /tmp/channels-$TASK_ID-jira-escaped.txt \
-  || { echo "unescaped Jira emoticon in the body - do not POST" >&2; exit 1; }
-jq -n --rawfile body /tmp/channels-$TASK_ID-jira-escaped.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"
+bash "$HOME/.claude/lib/jira-publish.sh" --issue "$JIRA_ID" \
+  --body-file /tmp/channels-$TASK_ID-jira.txt --target comment
 ```
 
+That script escapes every body unconditionally (`lib/jira-publish.sh:109`) and
+passes the token through a `-K` config rather than argv, so neither the escape
+nor the token handling depends on an agent remembering a step.
+
+This block used to be a hand-written `jq` + `curl` pair with the escape as a
+separate `--check` line above it, and a shipped comment rendered the Swift
+selector `hash(into:)` as `hash(into` plus a smiley - twice. The escaper was
+present, correct, and simply not run on that path: `:)` reached Jira intact and
+Jira's wiki renderer turned it into an emoticon, which is what section
+*Emoticon escaping* below is about. A defence that has to be invoked by hand is
+a defence that is eventually not invoked.
+
 The dispatch summary line includes the comment URL with `?focusedCommentId=...` so the user can paste it into Slack/Teams.
 
 ### Writing the issue description (not a comment)

package/pipeline/multi-agent-refs/channels/pr.md

@@ -10,20 +10,31 @@ The PR description targets code reviewers  -  it stays technical. Every adapter
 
 | # | Section key | Heading (`tr`) | Heading (`en`) | Required? |
 |---|---|---|---|---|
-| 1 | `summary` | `## Özet` | `## Summary` | always |
-| 2 | `changes` | `## Değişiklikler` | `## Changes` | always |
+| 1 | `summary` | `## Geliştirme Özeti` | `## Development Summary` | always |
+| 2 | `technical` | `## Teknik Açıklama` | `## Technical Explanation` | always |
 | 3 | `architecture` | `## Mimari Kararlar` | `## Architecture Decisions` | when a non-trivial design choice was made |
-| 4 | `verification` | `## Doğrulama` | `## Verification` | always |
-| 5 | `visuals` | `## Görsel Kanıt` | `## Visual Evidence` | when `state.visualEvidence.required` |
-| 6 | `risk` | `## Risk ve Güvenlik` | `## Risk and Security` | when `state.diffRisk.signals` carries a high-stakes signal (`security_path`, `migration`, `public_api`, `no_test_change`, `test_lines_removed`) |
-| 7 | `dependencies` | `## Bağımlılıklar` | `## Dependencies` | when deps added/removed/bumped |
-| 8 | `related` | `## İlgili` | `## Related` | always (Jira/issue ref; never `Closes/Fixes`) |
+| 4 | `impact` | `## Etki Analizi` | `## Impact Analysis` | always |
+| 5 | `test_scenarios` | `## Test Senaryoları` | `## Test Scenarios` | always |
+| 6 | `visuals` | `## Görsel Kanıt` | `## Visual Evidence` | when `state.visualEvidence.required` |
+| 7 | `risk` | `## Risk ve Güvenlik` | `## Risk and Security` | when `state.diffRisk.signals` carries a high-stakes signal (`security_path`, `migration`, `public_api`, `no_test_change`, `test_lines_removed`) |
+| 8 | `dependencies` | `## Bağımlılıklar` | `## Dependencies` | when deps added/removed/bumped |
+| 9 | `build` | `## Build` | `## Build` | always |
+| 10 | `related` | `## İlgili` | `## Related` | always (Jira/issue ref; never `Closes/Fixes`) |
+
+`summary`, `impact` and `test_scenarios` carry the same three section keys the
+Jira adapter uses, and that pairing is deliberate: the same three questions get
+answered on both surfaces, at the register each reader needs. The PR versions name
+symbols, files, line counts and build shas. The Jira versions name screens and
+behaviour and nothing else (`channels/jira.md`). `technical` has no Jira twin at
+all - it is the section whose absence over there is the point.
 
 ### Section content rules
 
-**`summary`**  -  1-3 sentences in `outputLanguage`. The "why" of the change. Past tense, no marketing voice. Code identifiers stay verbatim.
+**`summary`**  -  2-4 sentences in `outputLanguage`. What broke or what was added, where the user meets it, and the size of the effect when it is measurable (a crash count, a share of a known total, a version range). Past tense, no marketing voice. Code identifiers stay verbatim. This is the one section a reviewer reads before deciding whether to read the rest, so it names the user-visible behaviour before the mechanism.
 
-**`changes`**  -  bullet list, one item per logically distinct change. Each bullet starts with the touched component and ends with a one-line "what". The source is `$WORKTREE/.pipeline/scope-check.json` `files[].reason` (Phase 3 Step 3.7): a file the dev could not justify there is a file this list cannot describe either, so the bullet quotes the gate output instead of inventing a reason. Use the stack's native file extensions / module paths  -  the example below shows the **shape**, not a stack lock-in:
+**`technical`**  -  the account for someone holding the diff: a short paragraph on the mechanism (what the code was actually doing wrong, or what the new code does), then the per-file bullets, then one line of diff stat (`2 files, 8 deletions, 0 insertions`). Where a change is safe for a reason that is not obvious from the diff - an equality relation preserved, an invariant kept, a call site left alone deliberately - that reason belongs here in a sentence, because it is the question the reviewer would otherwise ask in a comment. Tables are welcome when several symbols share a property worth listing side by side.
+
+The bullet list is one item per logically distinct change. Each bullet starts with the touched component and ends with a one-line "what". The source is `$WORKTREE/.pipeline/scope-check.json` `files[].reason` (Phase 3 Step 3.7): a file the dev could not justify there is a file this list cannot describe either, so the bullet quotes the gate output instead of inventing a reason. Use the stack's native file extensions / module paths  -  the example below shows the **shape**, not a stack lock-in:
 
 ```markdown
 ## Changes
@@ -37,20 +48,55 @@ Across stacks the same shape produces, for example: `LoginView.swift  -  ...` (i
 
 **`architecture`**  -  only when the change involves a non-trivial decision (new abstraction, pattern change, data flow shift, dependency direction). Format: short paragraph stating the decision and the alternative considered. Skip the section entirely for mechanical refactors / dependency bumps / formatting passes.
 
-**`verification`**  -  what the reviewer should run to confirm the change works. Commands first, manual steps next. Pick the commands for the project's stack  -  the pipeline supports iOS (Swift/Xcode), Android (Gradle), web (npm/pnpm/yarn), and backend (varies: pytest/jest/go test/etc). Do not hardcode one stack in the body; emit only the commands relevant to the repos touched by this PR.
+**`impact`**  -  four fixed numbered parts, each answered, never a placeholder. Same four questions as the Jira `impact` section, answered here with the identifiers and numbers that section is not allowed to carry:
+
+```markdown
+## Impact Analysis
+
+**1 - The problem**
+<what was wrong, since which version, with the crash/report identifiers and counts>
+
+**2 - What was changed**
+<the change, and why behaviour around it is unchanged>
+
+**3 - Affected functions**
+<the screens, flows and symbols that must be tested, including shared components the change reaches>
+
+**4 - Effect on other systems**
+<none, or which service, contract or channel>
+```
+
+When the change deliberately fixes part of a wider problem, a closing **Risk and remaining scope** paragraph names what is still open and why it was left - a reviewer who can see the rest of the pattern in the repo will ask otherwise, and the honest answer is cheaper written down than defended in a thread.
 
-Skeleton (the adapter fills the body with the actual stack-appropriate lines at write-time; the template lists the shape only):
+**`test_scenarios`**  -  the same titled-scenario shape the Jira adapter uses, so the tester reads one list on both surfaces, with symbols allowed here:
 
 ```markdown
-## Verification
+## Test Scenarios
 
-- Build: <stack-appropriate build command>
-- Tests: <stack-appropriate test command, scoped to the touched targets/packages>
-- Lint / type-check: <if the project has one>
-- Manual: <one or more user-facing steps the reviewer can follow without setup>
+**1. <what this scenario exercises>**
+1. <step>
+2. **Expected:** <observable outcome>
+
+**2. <regression scenario>**
+1. <step>
+2. **Expected:** <what should still behave as before>
+```
+
+Reproduction scenarios first, then regressions for whatever the change could have disturbed. When a UI test target covers a scenario, say so on the scenario line and let `## Build` carry the run result - a scenario a machine already ran is not the same request as one a human has to perform, and conflating them wastes the reviewer's time.
+
+**`build`**  -  what was built, on what, and what came out. Not a promise that it builds; the recorded result of the run that happened:
+
+```markdown
+## Build
+
+- <build command or scheme> on <base branch>@<sha>: BUILD SUCCEEDED, 0 errors
+- Tests: <test command>: <N> passed, <M> failed
+- UI tests: <target>: <status> | not run  -  <reason from state.uiTest.notRunReason>
 ```
 
-Multi-repo PRs (one PR per repo) emit verification commands for that repo's stack only  -  never mix iOS + Android commands into a single PR body.
+The base sha matters because "it builds" is a claim about a merge base, and the reviewer's local tree is usually not that one. `state.uiTest` supplies the third line verbatim, including its `notRunReason` - "no UI test target in this repo" is a result, not a gap, and writing it stops the same question being asked on every PR.
+
+Pick commands for the project's stack  -  the pipeline supports iOS (Swift/Xcode), Android (Gradle), web (npm/pnpm/yarn) and backend (pytest/jest/go test/etc). Multi-repo PRs (one PR per repo) emit the commands for that repo's stack only  -  never mix iOS + Android commands into a single PR body.
 
 **`risk`**  -  only when `state.diffRisk.signals` (Phase 4 Step 1.75) contains a high-stakes signal. Four fixed lines, each answered, never left as a placeholder; the source is Phase 1 `touchedAreas` plus the signals themselves, and when a signal is present the absence of this section is a Phase 6 Step 3 blocker:
 
@@ -136,7 +182,7 @@ Never use `Closes #N`, `Fixes #N`, `Resolves PROJ-X`. Issues require 4-approval
 
 ```
 1. Read agent-state.json (taskId, contextLinks, identity, language).
-2. Build section bodies in markdown  -  summary first, then in the table order, skipping conditional sections that don't apply. Section order is fixed: `summary` → `changes` → `architecture` (cond.) → `verification` → `risk` (cond.) → `dependencies` (cond.) → `related`.
+2. Build section bodies in markdown  -  summary first, then in the table order, skipping conditional sections that don't apply. Section order is fixed: `summary` → `technical` → `architecture` (cond.) → `impact` → `test_scenarios` → `visuals` (cond.) → `risk` (cond.) → `dependencies` (cond.) → `build` → `related`.
 3. Run the assembled body through the `humanizer` skill.
 4. Apply Multi-repo cross-links (## Related PRs prepend when projects.length > 1).
 5. Dispatch per the Behaviour-by-remote table.
@@ -220,7 +266,7 @@ The Bitbucket REST API returns `409 Conflict` if `version` is stale. Adapter beh
 ## Hard rules (must not regress)
 
 - Real newlines, no HTML entities  -  heredoc + `jq --rawfile` + `curl --data-binary @file`. Never embed `\n` literally; Bitbucket stores the literal `\n` characters.
-- Section order is fixed: `summary` → `changes` → `architecture` (cond.) → `verification` → `dependencies` (cond.) → `related`. Conditional sections may be omitted but never reordered or inserted between fixed ones.
+- Section order is fixed: `summary` → `technical` → `architecture` (cond.) → `impact` → `test_scenarios` → `visuals` (cond.) → `risk` (cond.) → `dependencies` (cond.) → `build` → `related`. Conditional sections may be omitted but never reordered or inserted between fixed ones.
 - Humanizer pass runs **after** body assembly and **before** dispatch  -  every body line carries technical, non-AI tone. References at least one symbol/file/line drawn from the diff or pipeline log.
 - Body content language follows `prefs.global.outputLanguage`. Code identifiers, file paths, branch names, PR titles, commands, type names, and `Closes/Fixes`-style keywords stay verbatim English. The template file (this doc) is English because `promptLanguage="en"` is locked; the body is rendered in the user's language at write-time.
 - No body markers (`<!-- channels:start -->`)  -  channels does a full replace each run.

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

@@ -6,13 +6,14 @@
 
 ---
 
-## 1. Command Inventory (53 commands)
+## 1. Command Inventory (56 commands)
 
 ```
-analysis, analysis-jira, analysis-resolve, autopilot, build-optimize, channels,
-complaint-analysis, create-jira, design-check, doctor, diff-explain, feedback,
-forget, garbage-collect, graph, help, ios-coding-standard, issue, jira,
-kill, language, local, local-autopilot, log, manual-test, prune-logs,
+analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off,
+autopilot-on, autopilot-status, build-optimize, channels, complaint-analysis,
+create-jira, design-check, diff-explain, doctor, feedback, forget,
+garbage-collect, graph, help, ios-coding-standard, issue, jira, kill,
+language, local, local-autopilot, log, manual-test, prune-logs,
 prune-prompts, purge, refactor, resume, resume-local, review,
 review-analysis, review-issue, review-jira, routines, save, scan, search,
 setup, stack, status, steer, store-ready, sync, test, test-accessibility,
@@ -297,20 +298,39 @@ Modifier flags are orthogonal and compose:
 
 ---
 
-## 7. Platform Guards (macOS / Linux / WSL)
+## 7. Platform Guards (macOS)
 
-All three CLIs run on macOS, Linux and Windows, so any command may execute on any of them. (This line used to say Claude Code was macOS-only; it has not been true for some time, and the assumption it invited - that a Windows user necessarily arrives through Copilot or Codex - produces wrong conclusions about which paths need to be portable.) Shell code in `pipeline/skills/shared/core/` command files and in `pipeline/lib` / `pipeline/scripts` must be portable.
+All three CLIs are installed from this package, and `package.json` declares
+`os: ["darwin"]` (ADR-0012), so every command executes on macOS. That is not a
+licence to stop being careful about shell: the runtime is **BSD userland and
+bash 3.2**, which is a narrower target than "portable", and three constructs
+below exist because the BSD form silently differs rather than failing.
 
-For Keychain I/O the canonical path is **`~/.claude/lib/credential-store.sh`** (or `~/.copilot/lib/credential-store.sh` / `~/.codex/lib/credential-store.sh` on those installs). The shell driver detects platform internally and auto-delegates to `keychain.py` (Python helper, macOS / Linux) or PowerShell `CredentialManager` (Windows). Call sites stay platform-agnostic  -  no per-OS branching needed.
+For Keychain I/O the canonical path is **`~/.claude/lib/credential-store.sh`**
+(or `~/.copilot/lib/credential-store.sh` / `~/.codex/lib/credential-store.sh` on
+those installs). Call sites never invoke `security` themselves - the wrapper is
+what keeps a secret off argv and what writes the audit entry.
 
-| Purpose | Canonical (cross-platform) | Underlying backend (for reference / debugging) |
+| Purpose | Canonical | Underlying backend (for debugging only) |
 |---|---|---|
-| Keychain read | `~/.claude/lib/credential-store.sh get <key>` | macOS: `security find-generic-password -a "$USER" -s <key> -w` · Linux: `secret-tool lookup account "$USER" service <key>` · Windows: PowerShell `Get-StoredCredential` |
-| Keychain write | `~/.claude/lib/credential-store.sh set <key> <value>` (or `keychain.py set <key> -` to stream the secret over stdin) | macOS: `security add-generic-password -a "$USER" -s <key> -w "$VAL"` · Linux: `secret-tool store --label=<key> account "$USER" service <key>` · Windows: `New-StoredCredential` |
-| Clipboard read |  -  (still needs a per-platform branch  -  there is no helper) | `pbpaste` (macOS) · `wl-paste` (Wayland) · `xclip -selection clipboard -o` (X11) |
-| Clipboard clear |  -  | `pbcopy < /dev/null` (macOS) · `printf '' \| wl-copy` (Wayland) · `printf '' \| xclip -selection clipboard` (X11) |
-
-For clipboard ops, callers still gate with `if command -v pbpaste >/dev/null; then ...; elif command -v wl-paste ...; elif command -v xclip ...; fi`. A future `pipeline/lib/clipboard.sh` could absorb that pattern; until it exists, keep the inline guard in skill bash blocks.
+| Keychain read | `~/.claude/lib/credential-store.sh get <key>` | `security find-generic-password -a "$USER" -s <key> -w` |
+| Keychain write | `~/.claude/lib/credential-store.sh set <key> <value>` (or `keychain.py set <key> -` to stream the secret over stdin, keeping it off argv) | `security add-generic-password -a "$USER" -s <key> -w` |
+| Clipboard read | `pbpaste` | -  |
+| Clipboard clear | `pbcopy < /dev/null` | -  |
+
+**The three that bite on BSD**, and why each is a rule rather than a preference:
+
+- PCRE mode is absent from BSD grep, and is banned here. It exits 2, which under
+  `2>/dev/null` reads as "found nothing" - two gates shipped green for exactly
+  that reason. Use `-E`.
+- `stat -c %Y` FIRST, then `stat -f %m`. GNU-first ordering is required because
+  `stat -f` is a valid GNU flag (`--file-system`) that succeeds and prints
+  something that is not a timestamp.
+- `sed -E`, never `-r`; `sed -i ''` when editing in place.
+
+Clipboard callers may use `pbpaste` / `pbcopy` directly; the three-way
+`command -v` guard they used to carry was for hosts this package no longer
+installs on.
 
 ---
 

package/pipeline/multi-agent-refs/features/doctor.md

@@ -25,9 +25,9 @@ resolver as a clean bill.
 
 **A state in which a run will fail or leak. Not a state in which it will merely
 be worse.** Without a closed definition "blocked" grows until nobody respects
-exit 2, so only five checks can produce it: `install-present`, `script-surface`,
-`state-writable`, `prefs-valid` and `embedded-credentials`. Every other check
-tops out at WARN however bad it looks.
+exit 2, so only six checks can produce it: `host-platform`, `install-present`,
+`script-surface`, `state-writable`, `prefs-valid` and `embedded-credentials`.
+Every other check tops out at WARN however bad it looks.
 
 ## Who calls it, and what they do with the code
 
@@ -91,6 +91,18 @@ its host; everything after that is behind `--explain`.
 
 ## Checks
 
+### host-platform
+
+The host is macOS. BLOCK otherwise: every credential read shells `security`,
+every iOS build shells `xcodebuild`, every piece of visual evidence shells
+`simctl`, so a run on another platform does not degrade, it fails partway
+through with a worktree and a branch already created (ADR-0012).
+
+It runs **first**, before `install-present`, so an unsupported host reads one
+line naming the cause instead of a cascade of consequences. The step names the
+`MULTI_AGENT_ALLOW_NON_DARWIN=1` escape, which the entry points honour and
+nothing tests.
+
 ### install-present
 
 The installed tree exists and carries the subtrees a run reads: `commands/`,

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

@@ -33,6 +33,66 @@ model's reading of the task. A file counts as UI by stack:
 Nothing about this section is optional-by-omission: when it is required and an
 artefact is absent, the absence is written down with its reason (section 5).
 
+### 1a. Who writes the verdict, and when
+
+**Phase 0 Step 7.7 writes `required`, `requiredBy` and `platform`**, before it
+probes. Naming the writer is not a formality: five phases read these three fields
+and nothing set them, so `required` was never true, Step 7.7 never ran, Phase 3
+never captured, and Phase 6's blocker never blocked. A contract with readers and
+no writer reads exactly like a contract that is satisfied.
+
+Phase 0 has no diff, so it decides on what it actually knows - `taskType` and
+whether the intake carried a Figma reference - and that is enough for the whole
+design-work row. The `bugfix` row needs a changed-file list, so Phase 0 records
+it as provisional (`requiredBy: "bugfix (pending diff)"`) and **Phase 3 re-decides
+from the real diff** before capturing. A provisional `false` never suppresses the
+Phase 3 decision.
+
+### 1b. The platform, and when there is not one
+
+`platform` comes from the stack, not from the diff: it selects which device
+tooling is probed, and that is a property of the repo.
+
+```bash
+eval "$(bash $HOME/.claude/lib/stack-detect.sh "$PROJECT_ROOT")"   # MA_STACKS
+EVIDENCE_PLATFORM=""
+case " $MA_STACKS " in
+  *" ios "*)     EVIDENCE_PLATFORM=ios ;;
+  *" android "*) EVIDENCE_PLATFORM=android ;;
+  *" web "*)     EVIDENCE_PLATFORM=web ;;
+esac
+```
+
+iOS wins a tie, and the tie is recorded in `stackWhy`: `simctl` discovery is the
+cheaper of the two, and a repo that is honestly both gets the same answer on
+every run rather than one that depends on ordering. Web is last for the same
+reason and not because it is lesser: a repo that is both iOS and web is a mobile
+app with a marketing site, and the screen the ticket is about is the mobile one.
+
+**Web is a device platform here.** It was not until v17.1.0, and the omission was
+not a decision anyone made: `run-ui-tests.sh` rejected everything but
+`ios|android`, so a repo with a full Playwright suite reported "no UI test
+target". The PR body then said UI tests had not run, which was true of the runner
+and false of the repo - the exact shape of claim this file exists to prevent. The
+browser is the device, the runner is the recorder (both Playwright and Cypress
+write their own video), and `npx --no-install` is what keeps a probe from
+installing one behind the user's back.
+
+**An empty value is still a real outcome, not an error.** A backend-only repo has
+nothing to probe, and `probe-evidence-capability.sh` rejects anything but
+`ios|android|web` with exit 2. So when `EVIDENCE_PLATFORM` is empty the probe
+**does not run**, `platform` is written as `other` from `MA_STACKS`, and the
+reason goes to `state.evidenceCapability.skippedReason` in the probe's own
+`*_REASON` idiom - "no device platform in stacks [backend]". Passing an empty
+string instead is what the probe's exit 2 exists to refuse, and swallowing that
+exit would turn a missing value into a silent skip.
+
+Every `--platform` argument in this pipeline is `$EVIDENCE_PLATFORM`, read from
+`state.visualEvidence.platform` in later phases. `$PLATFORM` is not a pipeline
+variable: nothing ever assigned it, in any phase document, which is why
+`smoke-evidence-probe.sh` now fails a `--platform` argument whose variable is not
+assigned earlier in the same file.
+
 ## 2. Before  -  the reporter's screenshot, or nothing
 
 **The pipeline does not build the old state to photograph it.** Reproducing a
@@ -61,7 +121,7 @@ never the only source.
 
 ```bash
 bash $HOME/.claude/scripts/capture-evidence.sh after \
-  --task "$TASK_ID" --platform "$PLATFORM" --label "<screen-slug>"
+  --task "$TASK_ID" --platform "$EVIDENCE_PLATFORM" --label "<screen-slug>"
 ```
 
 What the capture is worth checking against - the per-component catalog, the

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

@@ -591,21 +591,30 @@ Log: `Phase 0 Step 7.6: test baseline = {green|red|unknown} ({N} pre-existing fa
 
 #### Step 7.7  -  Evidence capability, then test depth
 
-Probe, then ask, then run. Skipped unless `state.visualEvidence.required` and `visualEvidence.enabled` is not `false`. Reasoning: `features/visual-evidence.md` section 4.
+Decide, then probe, then ask, then run. Skipped only when `visualEvidence.enabled` is `false`. Contract: `features/visual-evidence.md` sections 1a, 1b, 4.
+
+**This step is the only writer of `visualEvidence.required`, `requiredBy` and `platform`** (section 1a). No diff exists yet, so the `bugfix` row is provisional and Phase 3 re-decides.
 
 ```bash
-eval "$(bash $HOME/.claude/scripts/probe-evidence-capability.sh \
-  --platform "$PLATFORM" --repo "$WORKTREE" --changed "$CHANGED_CSV" \
-  --json-out "$WORKTREE/.pipeline/evidence-capability.json")"
+eval "$(bash $HOME/.claude/lib/stack-detect.sh "$PROJECT_ROOT")"
+EVIDENCE_PLATFORM=""
+case " $MA_STACKS " in *" ios "*) EVIDENCE_PLATFORM=ios ;; *" android "*) EVIDENCE_PLATFORM=android ;; *" web "*) EVIDENCE_PLATFORM=web ;; esac
+if [ -n "$EVIDENCE_PLATFORM" ]; then
+  eval "$(bash $HOME/.claude/scripts/probe-evidence-capability.sh \
+    --platform "$EVIDENCE_PLATFORM" --repo "$WORKTREE" \
+    --json-out "$WORKTREE/.pipeline/evidence-capability.json")"
+fi
 ```
 
+Empty is an outcome, not a failure: no simulator on web or backend, so the probe does not run and `evidenceCapability.skippedReason` says so. No `--changed` yet, by the same token.
+
 One run, both forms: stdout is `EVIDENCE_*` (shell-quoted, so the eval is safe), and the same measurement lands as JSON.
 
 Persist that file as `state.evidenceCapability`, then build the menu from it, never from a reading of the repo: `1. Sadece unit test` / `2. Unit + UI test, ekran kaydiyla` (tier 1) / `3. Unit + MCP ile akis kaydi` (tier 2).
 
 A closed option keeps its row and prints the probe's reason verbatim. No `uiTestTargets` closes 2; `mcp` false closes 3; a missing `device` or `recorder` closes both. Targets present with no `matchingTests` leaves 2 open, warning that the whole UI suite will run. **When only option 1 is open, do not ask**: `testDepth = unit`, `testDepthSource = forced`, and the tier 3 gap is written.
 
-Pass the default as the **1-based index**, never the label (`rules.md`: labels render in `outputLanguage`, so a label default matches nothing on a `tr` run and `ask-choice.sh` takes option 1 on a non-TTY):
+Default as a 1-based index, never a label - same rule and same reason as Step 7.5:
 
 ```bash
 DEPTH_DEFAULT_INDEX=1

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

@@ -119,19 +119,33 @@ Phase 0 Step 1b catalogued every typed external link from the task description i
 
 #### Step 2  -  Stack Detection
 
-Detect the project's tech stack to load appropriate skills and tooling throughout the pipeline. Auto-detect by scanning `$PROJECT_ROOT` (maxdepth 2) for project markers:
+Two questions shared one answer here, and the shared answer was wrong on both.
 
-| Stack          | Marker Files                                    | Skills                                                       |
-| -------------- | ----------------------------------------------- | ------------------------------------------------------------ |
-| iOS/Swift      | `.xcodeproj`, `Package.swift`                   | `ai-ios-toolkit:*` skills, `ai-ios-toolkit:swift-testing`    |
-| Android/Kotlin | `build.gradle`, `build.gradle.kts`              | `ai-android-toolkit:android-jetpack-compose-expert`, `ai-android-toolkit:kotlin-coroutines-expert` |
-| Python         | `requirements.txt`, `pyproject.toml`, `Pipfile` | `ai-backend-toolkit:fastapi-pro`, `ai-backend-toolkit:api-patterns` |
-| Node.js        | `package.json`                                  | `ai-backend-toolkit:nodejs-backend-patterns`, `ai-backend-toolkit:api-patterns` |
-| Go             | `go.mod`                                        | `ai-backend-toolkit:api-patterns`, `ai-backend-toolkit:clean-code` |
-| Docker         | `Dockerfile`, `docker-compose.yml`              | `ai-backend-toolkit:docker-expert`                           |
-| Monorepo       | Multiple of above                               | `ai-backend-toolkit:monorepo-architect`                      |
+**What the repo is BUILT WITH** - one owner, no marker list in this file:
 
-Store in `agent-state.json` → `"detectedStack": ["ios", "python", "docker"]`
+```bash
+eval "$(bash $HOME/.claude/lib/stack-detect.sh "$PROJECT_ROOT")"
+```
+
+Persist `MA_STACKS` as `state.stacks[]` (a subset of `ios android web backend`,
+always in that order) and `MA_STACK_WHY` as `state.stackWhy`. Empty is a real
+answer meaning no marker matched; `stackWhy` separates that from a directory that
+could not be read, and a caller that cannot tell those apart treats an unreadable
+repo as a language-free one. `state.stacks[]` routes toolkits, through
+`pluginsForStacks()` in `$HOME/.claude/scripts/_stack-routing.mjs`. Do not derive
+plugin names here.
+
+The table that used to live here scanned at depth 2, and `AndroidManifest.xml`
+sits at `<module>/src/main/` - depth 4 in every multi-module app - so **Android
+was never detected**. The owner goes to depth 5 for that one file, prunes
+submodules (a vendored checkout ships its own `Package.swift`, which reported a
+Compose app as iOS) and checks the root first so traversal order cannot decide.
+
+**What the code is WRITTEN IN** - a different axis with its own field.
+`state.detectedStack[]` stays the language answer (`ios`, `python`, `node`, `go`,
+`docker`, `monorepo`): `graph-build.mjs --stack` takes `ios|android|node|python|go`
+and has no notion of `web` or `backend`. Folding the two together is what made a
+Gradle-built JVM service read as an Android app.
 
 This informs:
 
@@ -211,7 +225,7 @@ Progress line: `    → checking validator validate-analysis`
 
 Non-zero exit fails CLOSED: emit the validator stderr + `errors[]` verbatim, attempt ONE self-correction rework (re-invoke the explorer with the errors quoted, overwrite `$ANALYSIS_FILE`), re-run the validator. If it fails again -> HALT the phase with recovery hint: `ERR: analysis output failed validate-analysis.mjs twice. Inspect $ANALYSIS_FILE against $HOME/.claude/schemas/analysis-output.schema.json, then resume with /multi-agent:resume #N.` Record `agent-state.phases["1"].validator` (`pass` | `pass-after-rework` | `halted`).
 
-Log: "Phase 1: Analysis  -  stack:{detectedStack} | {N} files identified, {summary}"
+Log: "Phase 1: Analysis  -  stack:{stacks} lang:{detectedStack} | {N} files identified, {summary}"
 
 #### Telemetry  -  token forwarding
 

package/pipeline/multi-agent-refs/phases/phase-2-planning.md

@@ -7,7 +7,7 @@ Progress emission per `$HOME/.claude/multi-agent-refs/progress-contract.md`  -
 
 ## Phase 2 Pre-flight (BLOCKING, v9.0.0)
 
-Phase 2 Planning consumes the analysis document. MCP forbidden.
+Phase 2 Planning consumes the analysis document. **Figma** MCP / REST forbidden; the toolkit MCP is not.
 
 1. **Analysis document presence**: read `state.analysis.docStatus`, which Phase 1 Step 4 set.
    - `produced` | `reused` -> the file is at `state.analysis.docPath[]`; continue with steps 2-4.
@@ -137,27 +137,29 @@ Non-zero exit fails CLOSED: emit the validator stderr + `errors[]` verbatim, att
 
 Log: "Phase 2: Plan  -  {N} tasks created, {M} with architecture review, validator:pass"
 
+#### Step 4.45  -  Put the plan on the widget (required)
+
+```bash
+printf '%s' "$PLAN_JSON" | bash "$HOME/.claude/scripts/phase-tracker.sh" plan 3
+```
+
+Then do what its output asks - it prints a tile rebuild, because the widget
+orders by creation. `dependsOn` becomes `addBlockedBy`, so the widget answers
+"why has t3 not started". Required, unlike Step 4.5: the plan was always computed
+and stored, only invisible.
+
 #### Step 4.5  -  Emit Plan Todo List (opt-in)
 
 **Gated by `prefs.global.planTodos.enabled`** (default: `false`). When enabled, after the planning-output JSON validates and BEFORE the approval gate, transform `tasks[]` into a structured Todo list conforming to `$HOME/.claude/schemas/plan-todos.schema.json` and persist into `agent-state.plan`. The plan is rendered as a live, always-visible Todo list.
 
 ```bash
-TODO_BLOB=$(jq '
-  {
-    title: .summary,
-    todos: [ .tasks[] | {
-      id:               .id,
-      task:             .subject,
-      status:           "pending",
-      deps:             (.dependsOn // .blockedBy // []),
-      estimatedMinutes: (.estimatedMinutes // null)
-    } | with_entries(select(.value != null)) ]
-  }
-' <<<"$PLAN_JSON")
-
-bash "$HOME/.claude/lib/plan-todos.sh" set "$TASK_ID" "$TODO_BLOB"
+printf '%s' "$PLAN_JSON" | bash "$HOME/.claude/lib/plan-todos.sh" set "$TASK_ID" -
 ```
 
+`set` accepts a planning-output document and converts it itself. The conversion
+used to be written out here, which made the `tasks[]`-to-`todos[]` mapping a
+thing two files defined, and this was the copy nothing tested.
+
 Phase 3 (Dev) then iterates with `plan-todos.sh next "$TASK_ID"` until empty, calling `start` before each step and `complete` (with notes) or `fail`/`skip` after. Phase 4 (Review) reads the Todo list to verify all `completed` items map to diff hunks. Phase 7 (Report) renders `list` into the agent-log + PR body.
 
 **Why opt-in:** the existing `planning-output.schema.json` already drives Phase 3 dependency order  -  `plan.todos[]` is a richer surface (notes, durations, status transitions) but adds state writes per step. Off by default to keep the bare-bones flow unchanged; flip on for visibility into long features.