@mmerterden/multi-agent-pipeline 20.12.0 → 20.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "20.12.0",
+  "version": "20.15.0",
   "description": "6-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

package/pipeline/commands/multi-agent/SKILL.md

@@ -1,6 +1,7 @@
 ---
 description: "Task orchestrator  -  full pipeline via Jira ID + branch or GitHub Issue URL: analysis, plan, TDD development, parallel review + Fable triage (3 reviewers per host: Fable + Opus + Sonnet on Claude Code, GPT-5.4 + Opus + Sonnet on Copilot CLI), commit, log. Use when given a Jira ID, a GitHub issue or a free-text task and the whole pipeline should run."
 description-tr: "Görev orkestratörü - Jira ID + branch veya GitHub Issue URL ile tam pipeline: analiz, plan, TDD geliştirme, paralel review + Fable triyajı (CLI'ya göre: Claude Code'da 3, Copilot CLI'da 3 model), commit, log"
+argument-hint: "[JIRA-KEY | issue URL | repo#N | \"task\"] [autopilot] [--dev]  -  or a sub-command: status, log #N, resume #N, kill #N"
 allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdate, TaskList, TaskGet, AskUserQuestion, WebFetch, WebSearch, NotebookEdit, Skill
 ---
 

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

@@ -1,7 +1,7 @@
 ---
 description: "Standalone feature-spec analysis. Two profiles picked at intake: global (23-section development handoff, evidence-trimmed) or corporate (IG/UC/FG requirements document with traceability matrices). Platform-agnostic concept layer with repo-driven convention extraction (Phase 1c) and per-platform Pass B render; stack selection is optional. Collects Figma / Swagger / Confluence / Jira / Standards (Confluence + Wiki + local file) / Firebase / repo inputs. Stops after emit - does not chain into a dev run. Use when a feature needs a written specification before any code."
 description-tr: "Bağımsız özellik-spesifikasyonu analizi. Girişte iki profil: global (23 bölümlük geliştirme dokümanı, kanıta göre budanır) veya kurumsal (izlenebilirlik matrisleriyle IG/UC/FG gereksinim dokümanı). Repo'dan konvansiyon çıkarımıyla (Faz 1c) platform-bağımsız kavram katmanı ve platform başına Pass B render; stack seçimi opsiyonel. Figma / Swagger / Confluence / Jira / Standartlar (Confluence + Wiki + yerel dosya) / Firebase / repo girdilerini toplar. Çıktıyı üretince durur - dev koşusuna zincirlenmez."
-argument-hint: "[\"<analysis-name>\"] [--no-cache] [--preview-conventions]"
+argument-hint: "[\"<analysis-name>\" | check <doc.md> | refresh <doc.md> | conform <doc.md>] [--no-cache] [--preview-conventions]"
 parameters: [{"name":"name","kind":"text"},{"name":"--no-cache","kind":"flag"},{"name":"--preview-conventions","kind":"flag"}]
 gui: form
 destructive: false
@@ -11,6 +11,8 @@ confirm: none
 # multi-agent analysis - Feature Spec Analysis (v3)
 
 > **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
+>
+> **Background runs** (`MULTI_AGENT_UNATTENDED=1`, no `autopilot`): never ask or default a picker; write `agent-state.json`, park on the question, stop (`$HOME/.claude/multi-agent-refs/picker-contract.md`, Background).
 
 This command is **independent** from the orchestrator's Phase 1 analysis (which is a stack/findings detector inside `/multi-agent`). It produces a stakeholder-ready, platform-agnostic feature-spec document - up to 23 sections, trimmed to whatever the evidence supports - before any implementation starts. Each per-platform file is rendered by projecting concept-layer content onto repo-extracted conventions (Pass B).
 
@@ -20,17 +22,24 @@ This command is **independent** from the orchestrator's Phase 1 analysis (which
 
 > **Language**: Per `$HOME/.claude/multi-agent-refs/rules.md` Language Application matrix - instruction prose stays English (this file is read as a system prompt). `AskUserQuestion.question`, `.options[].label` and `.options[].description` follow `outputLanguage`; only `header` stays English (<=12-char chip). The emitted analysis document body follows `outputLanguage` (`tr` or `en`).
 
+## Gotchas
+
+- Design is fetched only inside this command (Locked 29). A variant missing from the document is added by re-running analysis, never by a later phase.
+- `status: final` fails the validator while any `AS-NN` is still open; publish drafts as `draft`.
+
 ## Locked decisions (do not re-ask)
 
 These decisions are settled. Do not surface them as `AskUserQuestion` items, do not re-derive them from context, do not invite the user to override mid-run. If the user explicitly wants one of them changed, treat that as a separate request and update this list.
 
-The full list of 35, with the category index, lives in `$HOME/.claude/multi-agent-refs/analysis/locked.md`. Read it before the run starts; it is the contract the whole flow is judged against. `/multi-agent:analysis-resolve` inherits the same list.
+The full list of 37, with the category index, lives in `$HOME/.claude/multi-agent-refs/analysis/locked.md`. Read it before the run starts; it is the contract the whole flow is judged against. `/multi-agent:analysis-resolve` inherits the same list.
 
 Cite a decision as `Locked <n> (<short label>)` so the category is inferable.
 
 ## Input
 
 - `$ARGUMENTS` - optional analysis name (e.g. `"UserProfile"`). If empty, asked at Phase 0 Step 1. Stored internally as `state.analysisSpec.featureName` for backward compatibility.
+- `check <doc.md>` / `refresh <doc.md>` - not a name: compare the document with its sources, or redraft from the stale ones. Read `$HOME/.claude/multi-agent-refs/features/analysis-sources.md` and follow it instead of the steps below.
+- `conform <doc.md>` - not a name: map an existing document onto a template without changing what it says. Follow `$HOME/.claude/multi-agent-refs/features/analysis-outline.md` instead of the steps below.
 
 ## Profile
 
@@ -47,7 +56,7 @@ One run emits one profile. A missing input never blocks either profile: the gap
 
 ## Template
 
-v3 template at `$HOME/.claude/multi-agent-refs/analysis-template.md`. The document renders up to 23 main sections + footer, minus any dropped by the omission table. The analysis doc is a development handoff, so low-signal sections are default-drop: **19 Alternatives** (render only for a real 2+-option architectural decision), **22 Glossary** (render only on request or >5 unfamiliar domain terms), and **18 Rollout** (compact checklist only, dropped when the pipeline's own commit/PR/rollout phase covers it). Sections are chosen from evidence; there is no second mode (ADR-0015, `docs/adr/0015-one-pipeline-no-depth-answer.md` in the pipeline repo). Section omission rule (Locked 2): zero-evidence and default-drop sections omit entirely; numbering re-flows to stay sequential `1..N` over the rendered set.
+v3 template at `$HOME/.claude/multi-agent-refs/analysis-template.md`. The document renders up to 23 main sections + footer, minus any dropped by the omission table. The analysis doc is a development handoff, so low-signal sections are default-drop: **19 Alternatives** (render only for a real 2+-option architectural decision), **22 Glossary** (render only on request or >5 unfamiliar domain terms), and **18 Rollout** (compact checklist only, dropped when the pipeline's own commit/PR/rollout phase covers it). Sections are chosen from evidence; there is no second mode (ADR-0015, `docs/adr/0015-one-pipeline-no-depth-answer.md` in the pipeline repo). Section omission rule (Locked 2): zero-evidence and default-drop sections omit entirely; a rendered section keeps its canonical template number, so the rendered set has gaps.
 
 Numbering is plain Arabic numerals: `## 1. Geliştirme Özeti` / `## 1. Summary`, `## 2. Hedefler ve Karşı Hedefler` / `## 2. Goals and Non-Goals`. No special section characters; the section sign codepoint (U+00A7) is banned by `feedback_no-section-sign`.
 
@@ -73,67 +82,14 @@ Full contract: `$HOME/.claude/multi-agent-refs/analysis/render.md`. Renders one
 
 ### Resume contract
 
-`state.analysisSpec.phase` enumeration:
-
-- `intake` (Phase 0 in progress)
-- `fetching` (Phase 1 in progress)
-- `collecting_repo_evidence` (Phase 1b)
-- `extracting_conventions` (Phase 1c)
-- `synthesizing_pass_a` (Phase 2 Pass A)
-- `awaiting_pass_b_approval` (Phase 2a - preview not yet answered)
-- `rendering_pass_b` (Phase 2b)
-- `drafting` (Phase 3)
-- `awaiting_output_decision` (Phase 3.5 - drafts written, picker not yet answered)
-- `dispatching` (Phase 4)
-- `reporting` (Phase 5)
-- `done`
-- `cancelled_at_pass_b_preview` (user cancelled at Phase 2a)
-
-When `/multi-agent:resume` is invoked and `phase == "awaiting_output_decision"`:
-
-1. Check `state.analysisSpec.outputs.draftDir` exists on disk and contains the expected per-platform `.md` files.
-2. If present, jump directly to Phase 3.5 (re-prompt the output picker; do not re-fetch evidence, do not re-synthesize).
-3. If missing, print `WARN: scratch drafts at <draftDir> are gone; re-running Phase 2 synthesis from fetched evidence.` and restart from Phase 2 (cheap: evidence is still in state).
-
-When `phase == "awaiting_pass_b_approval"`:
-
-1. Re-present the convention preview table (Phase 2a) with the same options.
-2. Pass A synthesis results are kept in state; Phase 1b / 1c results are kept too.
-3. Approval continues to Phase 2b without re-running anything.
-
-When `phase == "cancelled_at_pass_b_preview"`:
-
-1. Print `state.analysisSpec.outputs.draftDir` (likely empty unless prior drafts exist from a previous run).
-2. Show the convention preview that was rejected (for context).
-3. Ask whether to restart from Phase 0, retry Phase 1c with fresh evidence, or abort.
+Full procedure: `$HOME/.claude/multi-agent-refs/analysis/resume.md`. Read it when `/multi-agent:resume` is invoked on an analysis run (`state.analysisSpec.phase` enumeration and the re-entry rule per paused phase; evidence and synthesis already in state are never re-fetched).
 
 ## Reusable refs
 
-| Path | Reason |
-|------|--------|
-| `~/.claude/lib/submodule-detector.sh` | Phase 0 Step 4 repo discovery |
-| `~/.claude/lib/context-link-extractor.sh` | Phase 0 Step 5 source classifier for every question's Other input (handles `local-file`, `document`, `wiki`, `standards-confluence`, `generic-doc`, `firebase-events:names`, `firebase-events:schema`, `firebase-events:console` types) |
-| `~/.claude/lib/fetch-swagger.sh`, `fetch-confluence.sh` | Phase 1 fetchers |
-| Phase 1 wiki fetch chain (inline, no standalone script) | `git clone --depth 1 <repo>.wiki.git` first, `gh api repos/.../contents/<file>.md` second, WebFetch third - see the Phase 1 type table `wiki` row |
-| `~/.claude/lib/extract-conventions.sh` | Phase 1c convention extractor (7 pattern groups, JSON output, confidence levels) |
-| `~/.claude/lib/figma-screenshot.sh` | Phase 2b Tier 2 Figma image downloader (REST API, section drill, 2x scale PNG, manifest.json) |
-| `~/.claude/lib/md2confluence-v3.py` | Phase 4 Confluence dispatch (multipart attachments, `<ac:image>` injection, mermaid macro + fallback, tooltip footnote macro, punctuation gate) |
-| `ai-common-toolkit:humanizer` | Phase 3 tone pass |
-| 8-locale set (ar, de, en, es, fr, it, ru, tr) + localization-key naming (inline) | Section 10 localization generation |
-| `$HOME/.claude/multi-agent-refs/channels/confluence.md` | Phase 4 Confluence dispatch |
-| `$HOME/.claude/multi-agent-refs/channels/jira.md` | Phase 4 Jira dispatch |
-| `$HOME/.claude/rules/tdd.md` | Section 15 test naming |
-| `$HOME/.claude/multi-agent-refs/analysis-template.md` | Template master copy + language matrix (v3 - 23 sections) |
-| `$HOME/.claude/multi-agent-refs/conventions-defaults.md` | Pass B fallback defaults (4 platforms x 7 pattern groups) - applied when convention confidence is none AND standards binding is silent |
-| `$HOME/.claude/lib/jira-publish.sh` | Phase 4 Jira write: comment by default, description only on explicit choice - reads the current description first, backs it up, appends below a rule, refuses a non-empty replace without `--confirm-overwrite` |
-| `$HOME/.claude/scripts/validate-analysis-doc.mjs` | Phase 4 pre-dispatch gate: deterministic check of the emitted per-platform doc (front-matter, never-omitted sections, humanizer punctuation, BR traceability) |
-| a project-supplied Confluence-embedded API-table parser (optional) | Parse endpoints from a Confluence page's Request Path / Service Name / Response Body table columns |
-| `~/<project>-Standards.md` | Canonical home-dir standards reference (auto-detected by the Standards question's option 2; exact filename from `prefs.projects[<project>].standardsFile`) |
-| `~/.claude/rules/*.md` | Fallback rules when `evidence.standards[]` is empty |
+Full table: `$HOME/.claude/multi-agent-refs/analysis/reusable-refs.md`. Read it when a phase needs a fetcher, extractor, dispatcher, validator or fallback ref and the phase ref does not name its path.
 
 ## Notes
 
-- Default `prefs.global.outputLanguage` is `tr` for this user.
 - The minimum possible output (per per-platform file) is `1. Scope` + `7. Development Plan` (both always-present).
 - If Confluence or Jira POST returns 401 / 403 during Phase 4, surface the error and offer Local fallback (the local drafts in `/tmp/` are still on disk; copying them into the repo working tree is always available).
 - The `analysis/` directory is not in `.gitignore`; the user can `git add analysis/` manually. No auto-commit.
@@ -173,34 +129,13 @@ bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
 
 ### Visual channel  -  Claude Code (native TaskList widget, required)
 
-In Claude Code the agent MUST also drive the native TaskList widget so the user sees a sticky phase tile stack  -  this is the only progress signal Claude Code surfaces. Skipping these calls is the #1 source of "I don't see any phases" complaints.
-
-**TaskCreate ordering (strict)**: All TaskCreate calls in a registration batch fire in strict phase-number order BEFORE any TaskUpdate in that batch, and a later batch only ever appends phases numbered above everything already registered. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
-
-```text
-# Register one tile per phase, capture the taskId, persist it:
-for each phase in 0:Init, 1:Plan, 3:Review, 4:Commit, 5:Report:
-  TaskCreate({ subject: "Phase <N>: <Name>", activeForm: "<doing-form>" })
-    -> returns taskId
-  bash $HOME/.claude/scripts/phase-tracker.sh meta <N> tasklist_id "<taskId>"
-
-# Phase entry  -  flip the tile to in_progress alongside the state update:
-TaskUpdate({ taskId: <saved>, status: "in_progress" })
-bash $HOME/.claude/scripts/phase-tracker.sh update <N> in_progress
-
-# Active sub-step inside a phase  -  update activeForm so the spinner header reflects what's happening now:
-TaskUpdate({ taskId: <saved>, activeForm: "Editing TopBarView.swift" })
-
-# Phase exit  -  flip to completed/failed/skipped on both channels:
-TaskUpdate({ taskId: <saved>, status: "completed" })
-bash $HOME/.claude/scripts/phase-tracker.sh update <N> completed
-```
+In Claude Code the agent MUST also drive the native TaskList widget so the user sees a sticky phase tile stack  -  this is the only progress signal Claude Code surfaces. Register one tile per phase of the active set (`0:Init 1:Plan 3:Review 4:Commit 5:Report`) with `TaskCreate`, persist each `taskId` via `phase-tracker.sh meta <N> tasklist_id "<taskId>"`, and at every phase entry, sub-step and exit pair a `TaskUpdate` (status or `activeForm`) with the matching `phase-tracker.sh update`. Call pattern: `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "Call pattern". Mirror each with `phase-tracker.sh task` ("Mirroring the host's task list").
 
-`analysis` mode does NOT TaskCreate phases 2  -  those are not part of the `analysis` phase set (`0:Init 1:Plan 3:Review 4:Commit 5:Report`). Only register tiles for the active set.
+`analysis` mode does NOT TaskCreate phase 2: register tiles for the active set only.
 
 #### TaskCreate ordering (strict)
 
-**All TaskCreate calls in a batch fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `analysis` that means: Phase 0 → Phase 1 → Phase 3 → Phase 4 → Phase 5. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+**All TaskCreate calls in a batch fire in strict phase-number order BEFORE any TaskUpdate is applied**, and a later batch only ever appends phases numbered above everything already registered. For `analysis` that means: Phase 0 → Phase 1 → Phase 3 → Phase 4 → Phase 5. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order, then flip status via TaskUpdate when the phase actually short-circuits. Full ordering contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
 ### Visual channel  -  Copilot CLI / plain shell
 

package/pipeline/commands/multi-agent/analysis-jira/SKILL.md

@@ -2,8 +2,8 @@
 description: "Turn a rendered analysis document into a Jira story tree: derive stories from the document's own rule ids, check coverage both ways, preview every byte, then create only what does not already exist. Use when an analysis is final and the work needs tickets."
 description-tr: "Yazılmış bir analiz dokümanını Jira story ağacına çevirir: story'leri dokümanın kendi kural kimliklerinden türetir, kapsamı iki yönlü kontrol eder, yazılacak her baytı önizler, sonra yalnız var olmayanı açar."
 allowed-tools: Bash, Read, AskUserQuestion
-argument-hint: "[analysis.md] [--project KEY]  -  optional; with no argument, pick from the documents this run emitted"
-parameters: [{"name":"document","kind":"path"},{"name":"--project","kind":"text"}]
+argument-hint: "[analysis.md] [--project KEY] [--epic KEY]  -  optional; with no argument, pick from the documents this run emitted"
+parameters: [{"name":"document","kind":"path"},{"name":"--project","kind":"text"},{"name":"--epic","kind":"text"}]
 gui: form
 destructive: false
 confirm: none
@@ -22,13 +22,26 @@ invents a story: every node comes from an id the document defines.
 Contract, severities and reasoning:
 `$HOME/.claude/multi-agent-refs/features/analysis-jira.md`.
 
+## Gotchas
+
+- An issue whose label already exists is skipped, never updated. Editing the document and re-running creates only what is missing; existing tickets keep their old text.
+- A document with no `BR-`/`FG-` ids still plans, from its `4.N` sub-sections, but its coverage verdict is `unverifiable`: there is nothing to check the tree against.
+- An open `EKLENECEK`/`TBD` marker or an open Section 20 row stops planning with exit 4. Resolve them with `/multi-agent:analysis-resolve` first.
+- The epic must already exist: stories are linked to it, never an epic created. On Server/Data Center the Epic Link field is discovered from the site; when none is found the stories are created unlinked and the writer says so.
+- Channel clones (`issueTree.cloneByChannel`) carry their own labels and are searched like stories, so a re-run never doubles them or their links.
+- Story bodies hold only document text. A body warning (no user story, fewer than 2 criteria, no negative criterion) is a gap in the document; fix the document, not the ticket.
+
 ## Phase 1 - Plan, offline
 
 ```bash
-node "$HOME/.claude/scripts/analysis-story-tree.mjs" "<analysis.md>" --json > /tmp/ma-plan.json
-node "$HOME/.claude/scripts/analysis-story-tree.mjs" "<analysis.md>"
+node "$HOME/.claude/scripts/analysis-story-tree.mjs" "<analysis.md>" --json $PAGE > /tmp/ma-plan.json
+node "$HOME/.claude/scripts/analysis-story-tree.mjs" "<analysis.md>" $PAGE
 ```
 
+`$PAGE` is `--page-url <url>` when the document was published (the run's
+`outputs.confluencePages[]`); without it the front-matter `confluence_url` is
+used, and with neither the story bodies carry no analysis link.
+
 Exit 4 means the document still carries an open placeholder. Stop and report it:
 the step is `/multi-agent:analysis-resolve`, and a tree built from an open
 question publishes the gap as work somebody is now assigned.
@@ -52,12 +65,19 @@ what makes a preview meaningful:
 - every field beside the pref key it came from, so a wrong setting shows here
   rather than in Jira afterwards
 - the write count
+- every story's full description, as it will be written, with its body
+  warnings; `--brief` gives the one-line-per-node view
+
+Then ask for the epic, once. `AskUserQuestion`:
+
+- **Link to an existing epic** - the user types its key (`--epic <KEY>`)
+- **No epic** - the stories are created unlinked
 
 Then the dry run, which is what proves the writer agrees with the plan:
 
 ```bash
 bash "$HOME/.claude/lib/analysis-jira-write.sh" \
-  --plan /tmp/ma-plan.json --project "<KEY>" --dry-run
+  --plan /tmp/ma-plan.json --project "<KEY>" [--epic "<EPIC>"] --dry-run
 ```
 
 ## Phase 3 - Approve
@@ -83,11 +103,14 @@ be reachable.
 invented id means the plan cites something the document does not define - treat
 that as a defect in the plan, not a warning to click past.
 
+Body warnings are printed before the question too. They do not block: the
+ticket says only what the document says, and the warning names the gap.
+
 ## Phase 4 - Write
 
 ```bash
 bash "$HOME/.claude/lib/analysis-jira-write.sh" \
-  --plan /tmp/ma-plan.json --project "<KEY>"
+  --plan /tmp/ma-plan.json --project "<KEY>" [--epic "<EPIC>"]
 ```
 
 It searches by label first and skips what exists. Re-running is safe and is the
@@ -97,9 +120,36 @@ findable rather than duplicable.
 **Never pass `--force`-like flags, and never update an existing node.** Jira has
 no backup path for fields other than description.
 
+### Write the tickets back
+
+The document lists what it produced. Local and idempotent: the table sits
+between `<!-- tickets:start -->` and `<!-- tickets:end -->`, a re-run replaces
+it, and only nodes with a key appear.
+
+```bash
+LEDGER="$HOME/.claude/logs/multi-agent/_analysis-jira/$(jq -r '.document.id // "unidentified"' /tmp/ma-plan.json).jsonl"
+node "$HOME/.claude/scripts/analysis-tickets-writeback.mjs" \
+  --doc "<analysis.md>" --ledger "$LEDGER" --plan /tmp/ma-plan.json
+```
+
+When the document has a Confluence page, updating it is a **separate**
+`AskUserQuestion`, never part of the tree approval:
+
+- **Update the Confluence page** - publish the document with its new table
+- **Keep it local** - the page stays as it is
+
+```bash
+python3 "$HOME/.claude/lib/md2confluence-v3.py" update \
+  --page-id "<pageId>" --title "<page title>" \
+  --markdown "<analysis.md>" --attachments-dir "$(dirname "<analysis.md>")"
+```
+
+Read its JSON envelope as the analysis render step does, and surface any
+missing-attachment warning.
+
 ## Phase 5 - Report
 
-Keys created, keys skipped, the coverage verdict, and the ledger path. If the
+Keys created, keys skipped, the epic linked (or none), the coverage verdict, and the ledger path. If the
 verdict was `unverifiable`, say that in the report too - not only at approval
 time, because the report is what gets pasted elsewhere.
 

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

@@ -45,7 +45,7 @@ Inherited decisions: `$HOME/.claude/multi-agent-refs/analysis/locked.md`.
 - 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).
+**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 (match by title, not by the literal number 20: the profiles number the section differently).
 
 **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).
 
@@ -60,7 +60,7 @@ Inherited decisions: `$HOME/.claude/multi-agent-refs/analysis/locked.md`.
 
 | Path | Reason |
 |------|--------|
-| `$HOME/.claude/multi-agent-refs/analysis-template.md` | Section 20 / Section 23 table contracts, front-matter shape, omission re-flow |
+| `$HOME/.claude/multi-agent-refs/analysis-template.md` | Section 20 / Section 23 table contracts, front-matter shape, section omission |
 | `$HOME/.claude/multi-agent-refs/conventions-defaults.md` | `convention-fallback` default values per platform |
 | `~/.claude/lib/extract-conventions.sh` | fresh single-field extraction for convention-fallback candidates |
 | `ai-common-toolkit:humanizer` | tone reference for longer merged fragments (short fragments only need the punctuation gate) |

package/pipeline/commands/multi-agent/autopilot/SKILL.md

@@ -18,6 +18,12 @@ confirm: none
 
 Run the task end-to-end with no confirmations.
 
+## Gotchas
+
+- The guard decides within a 5-second internal deadline and fails closed when unattended. On a heavily loaded machine a correct command can be refused for time, not for policy.
+- An unattended run never pushes or opens a PR itself: it records the request in `pr-request.json` and the runner publishes it.
+- An unattended run cannot run `/multi-agent:stack` or write `.claude/` in the repo; a missing stack toolkit is read from a local marketplace clone instead.
+
 ## What changes
 
 | Phase | Normal | Autopilot |
@@ -87,34 +93,13 @@ bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
 
 ### Visual channel  -  Claude Code (native TaskList widget, required)
 
-In Claude Code the agent MUST also drive the native TaskList widget so the user sees a sticky phase tile stack  -  this is the only progress signal Claude Code surfaces. Skipping these calls is the #1 source of "I don't see any phases" complaints.
-
-**TaskCreate ordering (strict)**: All TaskCreate calls in a registration batch fire in strict phase-number order BEFORE any TaskUpdate in that batch, and a later batch only ever appends phases numbered above everything already registered. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
-
-```text
-# Register one tile per phase, capture the taskId, persist it:
-for each phase in 0:Init, 1:Plan, 2:Dev, 3:Review, 4:Commit, 5:Report:
-  TaskCreate({ subject: "Phase <N>: <Name>", activeForm: "<doing-form>" })
-    -> returns taskId
-  bash $HOME/.claude/scripts/phase-tracker.sh meta <N> tasklist_id "<taskId>"
-
-# Phase entry  -  flip the tile to in_progress alongside the state update:
-TaskUpdate({ taskId: <saved>, status: "in_progress" })
-bash $HOME/.claude/scripts/phase-tracker.sh update <N> in_progress
-
-# Active sub-step inside a phase  -  update activeForm so the spinner header reflects what's happening now:
-TaskUpdate({ taskId: <saved>, activeForm: "Editing TopBarView.swift" })
-
-# Phase exit  -  flip to completed/failed/skipped on both channels:
-TaskUpdate({ taskId: <saved>, status: "completed" })
-bash $HOME/.claude/scripts/phase-tracker.sh update <N> completed
-```
+In Claude Code the agent MUST also drive the native TaskList widget so the user sees a sticky phase tile stack  -  this is the only progress signal Claude Code surfaces. Register one tile per phase of the active set (`0:Init 1:Plan 2:Dev 3:Review 4:Commit 5:Report`) with `TaskCreate`, persist each `taskId` via `phase-tracker.sh meta <N> tasklist_id "<taskId>"`, and at every phase entry, sub-step and exit pair a `TaskUpdate` (status or `activeForm`) with the matching `phase-tracker.sh update`. Call pattern: `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "Call pattern". Mirror each with `phase-tracker.sh task` ("Mirroring the host's task list").
 
 `autopilot` mode TaskCreates all 6 phases (no phase is skipped).
 
 #### TaskCreate ordering (strict)
 
-**All TaskCreate calls in a batch fire in strict phase-number order BEFORE any TaskUpdate is applied.** For `autopilot` that means: Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks. Full ordering contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+**All TaskCreate calls in a batch fire in strict phase-number order BEFORE any TaskUpdate is applied**, and a later batch only ever appends phases numbered above everything already registered. For `autopilot` that means: Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5. The native widget renders by creation order, not by phase number  -  out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN  -  register the tile in order, then flip status via TaskUpdate when the phase actually short-circuits. Full ordering contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
 
 ### Visual channel  -  Copilot CLI / plain shell
 

package/pipeline/commands/multi-agent/autopilot-off/SKILL.md

@@ -1,5 +1,6 @@
 ---
 description: "Turn off continuous mode on this machine: the schedule is removed, work already running finishes, the repo selection is kept. Use when the machine should stop picking work up."
+disable-model-invocation: true
 description-tr: "Bu makinede sürekli modu kapatır: zamanlama kaldırılır, koşan iş biter, repo seçimi saklanır."
 argument-hint: "[--now]  -  --now also stops the item currently running"
 parameters: [{"name":"--now","kind":"flag"}]
@@ -26,61 +27,40 @@ When something is running, name it and how long it has been going. "Stopped"
 means something different when an item is 2 minutes from a PR than when the queue
 is idle, and the user is the one who knows which.
 
-### 2. Remove the schedule
+### 2. Turn it off
 
 ```bash
-L="com.multi-agent.autopilot"
-launchctl bootout "gui/$(id -u)/$L" 2>/dev/null || launchctl unload "$HOME/Library/LaunchAgents/$L.plist" 2>/dev/null
-rm -f "$HOME/Library/LaunchAgents/$L.plist"
+node "$HOME/.claude/scripts/autopilot-control.mjs" off
 ```
 
-The plist is removed rather than left disabled, because its presence is the
-definition of on: a disabled-but-present job is a third state nobody can read
-from the outside.
+One script does every step, the same one `POST /v1/autopilot/off` runs, so the
+command and a client turn the mode off the same way: the schedule's job is
+booted out and its plist removed (its presence is the definition of on, so it is
+removed rather than disabled), the awake agent goes with it (it would keep a Mac
+awake for a mode that is off), an in-flight sleep lock is released only when the
+tick that holds it has ended, and the menu bar indicator stops. It prints
+`{"enabled": false, "stoppedInFlight": false}`.
 
-The awake agent goes with it, the same way:
+### 3. `--now` only: end the in-flight item deliberately
 
-```bash
-. "$HOME/.claude/lib/autopilot-state.sh"
-node "$(ma_ap_asset scripts/autopilot-awake.mjs)" remove
-```
-
-It holds sleep off for as long as it is loaded, and it has no meaning without
-the schedule: left behind, it keeps a Mac awake for a mode that is off.
-
-### 3. Release the in-flight sleep lock and the indicator
+Without `--now` nothing in flight is touched. With it, first name the item, its
+worktree and whether it holds uncommitted work, and ask before stopping
+anything; the command is declared `destructive: true` with `confirm: required`,
+so a client confirms before it even starts. On a yes:
 
 ```bash
-INH="$HOME/.claude/autopilot/inhibitor.json"
-if [ -f "$INH" ]; then
-  RP=$(jq -r '.runnerPid // empty' "$INH"); IP=$(jq -r '.pid // empty' "$INH")
-  if [ -n "$RP" ] && kill -0 "$RP" 2>/dev/null; then
-    echo "the tick in flight holds sleep until it ends"
-  else
-    [ -n "$IP" ] && kill "$IP" 2>/dev/null; rm -f "$INH"
-  fi
-fi
-pkill -f "$HOME/.claude/autopilot/bin/menubar" 2>/dev/null || true
+node "$HOME/.claude/scripts/autopilot-control.mjs" off --now
 ```
 
-The in-flight sleep lock belongs to a tick, not to the mode: the runner releases it
-when the tick ends and it exits with the runner's pid, so the only one left to
-stop is one whose runner is already gone - by the pid it recorded, never by name.
-
-### 4. `--now` only: end the in-flight item deliberately
-
-Without `--now` nothing here runs. With it, first name the item, its worktree and
-whether it holds uncommitted work, and ask before stopping anything; the command
-is declared `destructive: true` with `confirm: required`, so a client confirms
-before it even starts. On a yes, the child session is stopped and the run is
-marked `abandoned`, its worktree is removed **unless it holds uncommitted
-work**, in which case the work goes into a stash entry labelled
-`autopilot/abandoned/<task-id>` (find it with `git stash list`) and the worktree
-is kept. Same contract as `gc-abandoned.sh` and `autopilot-runner.mjs`; losing a
-day of edits is worse than 750 MB. No branch is created - one made after
-`stash push` would point at HEAD and contain none of the work.
+The child session is stopped and the run is marked `abandoned`; its worktree is
+removed **unless it holds uncommitted work**, in which case the work goes into a
+stash entry labelled `autopilot/abandoned/<task-id>` (find it with
+`git stash list`) and the worktree is kept. Same contract as `gc-abandoned.sh`
+and `autopilot-runner.mjs`; losing a day of edits is worse than 750 MB. No
+branch is created - one made after `stash push` would point at HEAD and contain
+none of the work. `stoppedInFlight` says whether a session was stopped.
 
-### 5. Keep the selection
+### 4. Keep the selection
 
 `~/.claude/autopilot/config.json`, `queue.json` and `attempted.jsonl` all stay.
 Turning the mode back on must not re-ask which repos, and the attempt history is
@@ -89,7 +69,7 @@ what stops an item that already failed twice from being retried forever.
 To forget the selection as well: `rm -rf ~/.claude/autopilot`. Say that rather
 than doing it - "off" and "forget everything" are different requests.
 
-### 6. Report
+### 5. Report
 
 State that it is off, what was left running or finishing, and that the repo
 selection is kept. If an item was stashed, name the stash entry

package/pipeline/commands/multi-agent/channels/SKILL.md

@@ -16,6 +16,13 @@ allowed-tools: Read, Write, Edit, Bash, Grep, WebFetch, AskUserQuestion
 **Claude Code invocation:** `/multi-agent:channels <target>`
 **Copilot CLI invocation:** `multi-agent-channels <target>` (top-level command, dash-separated per Copilot no-namespace convention)
 
+## Gotchas
+
+- Nothing is posted before the Step 6 approval gate resolves, in every interactive mode. Under `MULTI_AGENT_UNATTENDED=1` nothing is posted at all.
+- Jira renders `:)` `(x)` `(!)` as emoticons, so a Swift selector like `login(source:input:)` breaks. Post through `jira-publish.sh`, which escapes the body; never assemble the request by hand.
+- A Bitbucket PR update must carry the reviewer list back, or the PUT removes every reviewer.
+- With several repos, the PR description goes to every PR but Jira and Confluence get one post each.
+
 ## Input
 
 ```
@@ -90,42 +97,9 @@ When the preview renders:
 When the preview does NOT render (no state, or pref explicitly off at global level with no override):
 - Skip 3a silently, go straight to the channels picker. The workSummary row in 3b stays at its pref default (`false`).
 
-**Visual flow (TR, pref on + state available):**
-
-```
-Yapılan iş özeti  -  PROJ-12345
-──────────────────────────────────────────────────────────
-{rendered Work Summary block  -  header + scope + diffstat + review + phases}
-──────────────────────────────────────────────────────────
-
-[done] İş özetini gördün. Şimdi nereye rapor gönderelim?
-```
-
-Then 3b renders:
-
-```
-┌─ Kanallar ────────────────────────────────────────────
-│ Nereye rapor gönderilsin?
-│   [x] PR description      (replace / append)
-│   [x] Jira comment        (jiraId: PROJ-12345)
-│   [ ] Confluence page
-│   [ ] Wiki                (taskType=component + wiki.enabled gerekli)
-│   [ ] Board               (figmaConfig.board.enabled + projectV2Id gerekli)
-└───────────────────────────────────────────────────────
-
-┌─ İçerik ──────────────────────────────────────────────
-│ Ne eklensin?
-│   [x] Normal analiz       (Phase 1+2+4'ten  -  high-level impact + risks)
-│   [ ] Teknik analiz       (Changes · Architecture · Dependencies  -  PR body'deki Technical Details özeti)
-│   [x] Test senaryoları    (Phase 1+2+4'ten)
-│   [ ] PR diff'ten auto-gen (PR varsa diff'i summarize eder)
-│   [ ] Manuel not          (--message / --message-file)
-│   [ ] Cost özeti          (per-phase token + est. USD  -  tracker data gerekli)
-│   [x] Yapılan iş özeti     (executive summary  -  yukarıda gösterilen block)
-└───────────────────────────────────────────────────────
-```
+After the preview prints, 3b renders the two pickers: **Channels** (PR description, Jira comment, Confluence page, Wiki, Board; each unavailable one greyed with its reason) and **Content** (normal analysis, technical analysis, test scenarios, PR auto-diff, manual note, cost summary, work summary).
 
-**Why auto-tick:** the user JUST saw the summary and is likely sending it somewhere  -  otherwise they would have stopped before running `/multi-agent:channels`. Auto-tick matches the 80% case; the 20% case (preview was enough, no remote post needed) is a single keystroke to uncheck.
+**Why auto-tick:** the user just saw the summary and is most likely sending it; the explicit pref still wins.
 
 **Autopilot interaction (Step 4):** `state.autopilot === true` still pauses at channels (documented exception to zero-interaction contract), preview in-line. Under `MULTI_AGENT_UNATTENDED=1` it posts nothing: `$HOME/.claude/multi-agent-refs/features/unattended-security.md`.
 
@@ -370,19 +344,7 @@ Secondary artifacts ride along as one-line intents at the bottom of the preview:
 
 For each selected **channel**, call the corresponding adapter. Adapters run **in parallel**  -  one failure does not block others. Dispatch NEVER starts before the Step 6 gate resolves (`Approve & post`), except in the two documented skip cases (autopilot, `--dry-run`).
 
-**Multi-repo dispatch:** When `state.projects[].length > 1`, the dispatcher delegates per-channel rendering to `~/.claude/lib/channels-multi-repo.sh`:
-
-| Channel | Behavior | Adapter call |
-|---------|----------|--------------|
-| **PR description** | Posted to **every** target's PR. Primary's body lists extras as `Related: <url>`; each extra's body lists primary as `Part of: <url>`. | `channels-multi-repo.sh render-pr <state> <body> <repoName>` per target |
-| **Jira comment** | Posted **once** (Jira ticket is shared by all repos). Body prepended with bulleted `* PR:` list  -  primary first, extras after. | `channels-multi-repo.sh render-jira <state> <body>` once |
-| **Confluence page** | Posted **once** to the primary's component slug. `## Related PRs` heading block prepended. | `channels-multi-repo.sh render-conf <state> <body>` once |
-| **Wiki** | Posted **once** to the primary repo's wiki, since wiki scope is `figma-config.wikiRepo` (single repo). | No adapter  -  body unchanged |
-| **Board** | Posted **once**  -  board status is keyed off the GitHub Issue, not per-PR. Primary repo's issue is the target. | No adapter  -  single mutation |
-
-**Target enumeration:** `channels-multi-repo.sh targets <state>` returns a JSON array `[{repoName, prUrl, prNumber, isPrimary, crossLinks}]` for the dispatch loop. Single-repo tasks return one entry with empty `crossLinks`  -  every render-* call falls through to the body unchanged, so the loop is uniform across single-repo and multi-repo paths.
-
-**Logging hint:** `channels-multi-repo.sh summary <state>` produces a one-line autopilot log entry (`1 primary (foo) + 2 extras: <url> <url>` or `single-repo task`).
+**Multi-repo dispatch** (`state.projects[].length > 1`): which channel posts once and which per repo, and the `channels-multi-repo.sh` calls: `$HOME/.claude/multi-agent-refs/channels/multi-repo.md`.
 
 #### Adapter: PR description
 Aggregated Markdown from Step 5 → PR description. GitHub uses `gh pr edit --body-file`; Bitbucket uses a **reviewer-preserving (required)** `PUT /pull-requests/{id}` payload (must re-send `reviewers`, `fromRef`, `toRef`, `draft`, `version`  -  omitting any one resets that field server-side). Default is **replace**; `--append` opt-in. Multi-repo cross-links handled by `channels-multi-repo.sh render-pr`.
@@ -409,21 +371,7 @@ Full contract: [`$HOME/.claude/multi-agent-refs/channels/confluence.md`]($HOME/.
 
 #### Adapter: Board (GitHub Projects v2 status move)
 
-**Precondition gate:** `figmaConfig.board.enabled === true` AND `figmaConfig.board.provider === "github-projects-v2"` AND `figmaConfig.github.projectV2Id` non-empty. If not met, the channel is greyed in the menu (Step 3b rule) and the adapter is skipped silently in flag-mode dispatch.
-
-**Default target column:** `inReview`  -  read from `figmaConfig.github.fieldOptions.status.inReview` (the option ID, e.g. `bdb0d8ef`). Other column targets (e.g. `done`, `bugfix`) overridable via flag `--board-status <key>` where `<key>` matches a key under `fieldOptions.status`.
-
-**Token:** `prefs.global.keychainMapping.github_projects` (preferred  -  must include `project,read:project` scopes). Fallback chain: `keychainMapping.github` → standard key `${USER}_Github_Access_Token`. Resolve via `~/.claude/lib/credential-store.sh get <key>` (reads the macOS Keychain). Token must NOT be passed on the CLI  -  export as `GH_TOKEN` env var only (per memory rule on token leakage).
-
-**Item lookup:** the issue's project item ID is fetched via GraphQL `repository.issue(number).projectItems(first:5)` filtered to `project.id === figmaConfig.github.projectV2Id`. If the issue is not yet in the project, dispatch silently no-ops with reason `"issue not on board"` in the summary.
-
-**Mutation:** GraphQL `updateProjectV2ItemFieldValue(input: { projectId, itemId, fieldId: figmaConfig.github.projectV2Fields.status, value: { singleSelectOptionId: <target> } })`. Verify by re-querying `fieldValueByName(name: "Status")` on the same item; assert `name === target column label` from `figmaConfig.board.columns`.
-
-**Multi-repo:** runs **once** (board status is keyed off the GitHub Issue, not per-PR). When `state.projects[].length > 1`, the primary repo's issue is the target; extras' PRs do not trigger additional moves.
-
-**Idempotency:** if the issue is already on the target column, the mutation is a no-op and the adapter reports `"already in <column>"` in the summary.
-
-**Additional behaviors handled inline by this adapter** (no separate contract file): token scope upgrade flow (`gh auth refresh -s project,read:project`), field-ID auto-discovery for repos missing `projectV2Fields.status` in figma-config, error-recovery (token expired vs scope insufficient).
+Precondition, token, item lookup, mutation and idempotency: `$HOME/.claude/multi-agent-refs/channels/board.md`.
 
 #### Adapter: Wiki
 **Precondition gate:** `state.taskType === "component"` AND `figmaConfig.wiki.enabled === true`. If not met, shows the Case B menu from `$HOME/.claude/multi-agent-refs/wiki-capture.md` (setup / skip / disable / manual-note).