@mmerterden/multi-agent-pipeline 16.28.0 → 16.29.0

package/CHANGELOG.md

@@ -14,6 +14,81 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ---
 
+## [16.29.0] - 2026-09-11
+
+### Added
+
+- **Two release guards that had stopped working, found by running them.** The sync leak backstop matched `ai-ios(-engineering)?-toolkit:`, so it fired on `ai-ios-toolkit`, the GENERIC marketplace plugin, and aborted the sync over a legitimate reference that had been in main for months. It now names the corporate plugins only, and is asserted in both directions - the corporate name still caught, the generic one ignored.
+
+  `scan-agent-config.sh` resolved its root as `$0/../..`, which is the repo from a checkout and the HOME directory from an install: from `~/.claude/scripts` it found zero shipped config files, then died on `"${TARGETS[@]}"` under bash 3.2's `set -u` rather than saying so. Same defect class as the one `skill-siblings.mjs` carried, so it gets the same two-candidate resolution, and zero targets is now a HIGH finding instead of a clean bill. The installed layout deliberately excludes `settings.json`: that file is the user's, not something the pipeline ships, and scanning it turned a personal permission choice into a release blocker.
+
+- **`/multi-agent:doctor` - would a run work on this machine, and if not, what is the one next step.** Every failure it reports has already reached a user, and each arrived the same way: late, mid-run, after the pickers had been answered. A missing script fails at the call. Malformed preferences fail after Phase 0 has asked five questions. A token in a remote URL does not fail at all - it leaks. The pipeline's own answer to "is this set up correctly" was to start a run and find out.
+
+  **The exit code is the product**, not the report: 0 healthy, 1 degraded, 2 blocked, 3 usage, **4 indeterminate**. The fourth is the one usually collapsed into 0 or 2, and collapsing it means a resolver that could not look borrows the code for a clean bill. `/multi-agent:sync` stops on 2 and on 4 - syncing a blocked install copies one fault onto five surfaces, and the copies are what people then debug. `/multi-agent:setup` runs it first and last, so "setup complete" has evidence behind it. `/multi-agent:update` runs it after the install, because that is when the layout changed.
+
+  **BLOCK is a closed definition** - a state where a run will fail or leak, never one where it will merely be worse - and only five checks may produce it. That rule is enforced, not just written: a sixth check returning BLOCK is downgraded and the downgrade is reported, because a rule nothing enforces is a comment.
+
+  **Absence is printed.** `SKIP` is a fourth severity in the same list at the same position, and the summary always carries its count, so "healthy" and "not looked at" are never the same output. Without `--probe` the liveness check prints `SKIP` and says why; a network check is the user's decision to spend.
+
+  **It recommends, it never fixes.** A remote carrying a token may be the only credential that repo has, the remote may be a mirror a script depends on verbatim, and doctor can run inside a checkout the user does not own. For an embedded credential the honest step is not "hide it" - a token that reached `.git/config` is already burned - so the step is to revoke it at its host. The line carries the repo, the key, the host, a shape and a length bucket; never the value, and not the prefix either, since `ghp_` plus a length is already a fingerprint and this prints to a shared terminal.
+
+  Fourteen checks, each with a `### <id>` entry in `features/doctor.md`, and `--list-checks` is asserted equal to that set in **both** directions: a check cannot ship without its entry, and an entry cannot outlive its check.
+
+  Running it against this machine immediately paid for itself twice - it reported a missing git identity on a machine with two (the key is `identities[]`, a list, because work and personal both exist) and told the user to sync seven commands that are local-only and excluded from sync by design. Both were fixed before the gate was written; a health check that is wrong about a healthy machine is worse than none.
+
+- **`/multi-agent:analysis-jira` - an analysis document, read as work.** A finished analysis already contains the breakdown: `BR-<slug>-NN` in the global profile, `FG-NN` in the corporate one, both guaranteed by Locked 31. The tree is derived from those ids, never from a reading of the prose.
+
+  **Coverage runs in both directions, and the second one is the reason.** Forward catches a dropped requirement. Backward catches an INVENTED story - a node with no requirement behind it - and no forward check can see one. `coverageOf()` is exported and tested against itself: the planner cannot emit an invented id, so a test that fabricates one and re-checks it with its own logic proves nothing about the shipped code.
+
+  **An unverifiable run is allowed; looking verified is not.** A lite document with no ids cannot be coverage-checked, so the verdict is `unverifiable` - on its own line in the preview, as a separate fourth approval option rather than a reworded `Approve`, in the writer's output, and beside every key in the ledger. Such a document still plans work from its user-story sub-sections; without that the no-atom case produced no stories at all and the `unverifiable` branch was unreachable, a state the code claimed to handle and never could.
+
+  **Identity is a label, not a title.** Each node carries a hash of the document's `evidence_digest` plus its own source ids, and a second run finds its tree back with one JQL search. Titles were the obvious key and are the wrong one: they get edited, and matching on them breaks exactly when someone improves the wording. The label is server-side, so it survives a new machine, a deleted `~/.claude`, and a second analyst - who is precisely the person positioned to open a duplicate tree.
+
+  **The write is ledgered.** An `intent` line before each POST, the key after the response; a crash between them leaves an intent with no key, and the next run searches by label before sending anything. The failure that matters is not "the run stopped" but "the run stopped and the retry made a second tree". An existing node is skipped, never updated: Jira has no backup path for fields other than description.
+
+  The marker gate runs before any network call - zero `EKLENECEK`, zero `TBD`, no open Section 20 row - because a tree built from an open question publishes the gap as work somebody is now assigned.
+
+  Every site-specific name lives in `prefs.global.issueTree` as a map VALUE, never a schema key: a key is a published literal and this schema ships to everyone. `subtaskRoles` ships empty on purpose, and `subtaskIssueType: null` means discover it from `createmeta` rather than assume a name.
+
+- **`lib/_jira-auth.sh`** - one resolution of host and token, and one `-K` curl idiom, for Jira callers to share. The twelve lines existed twice and a third writer was about to make it three; the part most worth getting right (the token never reaching argv, a log, or `ps`) is the part most easily retyped badly. Only the new writer consumes it so far - `jira-publish.sh` and `issue-fetcher.sh` still carry their own resolution, and `issue-fetcher.sh`'s per-account token keys are not modelled here yet, so retrofitting them is a refactor rather than a rename and is not in this release. The leak property is asserted on all three independently, which is the part that has to hold either way.
+
+- **`outputs.confluencePages[]`** records each emitted page's identity - `pageId`, `title`, `space`, `channel` - not only its URL. A write-back needs the id, and a `/display/SPACE/Title` URL cannot be parsed for one, so a URL-only record works on some sites and silently does not on others.
+
+- **`install/templates/` now reaches the user tree.** It shipped in the tarball and was never copied, so `setup` told people to merge `install/templates/claude-hooks.json` - a path that exists only in a checkout. From an install the instruction named a file the reader did not have, and nothing said so. The doctor's `hook-coverage` check would have been a permanent `SKIP` for the same reason.
+
+
+### Fixed
+
+- **The widget came back empty of everything except the phase name.** The native tile renders exactly one string, its subject, so whatever a reader wants from the card has to travel in that subject. It carried `Phase 1 Analysis` and nothing else, while the tracker already held the model, the elapsed time, the tokens and the cost for that phase and the fallback card printed all four. `phase-tracker.sh subjects [id]` now renders the same values in the one shape the host accepts, `tiles` builds its `TaskCreate` calls from it, and every boundary hint re-reads it so the numbers advance instead of freezing at creation time. A phase with nothing to report is still just its name - no empty separators.
+
+- **The base branch stopped being asked.** Step 3 is marked not skippable and the run skipped it anyway, because the filter left one candidate and "there is only one option" read like a legitimate reason. It is not one: the filter is narrow by design, `Other` is a real choice on every picker, and announcing the pick in prose is the same skip with a sentence in front of it. The rule is now written where pickers are defined rather than only in this step, together with the ordering it depends on - project, then repo, then base branch, because a branch is a property of a repo and an answer given before the repo is settled cannot be told apart from a correct one.
+
+  Autopilot changed in the same pass. It resolved pickers to a sort order; it now reads `recentBranches[{projectKey}]` first and falls back to the order only when the record is empty, stale or gone from the remote, recording which rule fired. A remembered branch is evidence about this user and this repo; an option order is a guess that happens to be sorted.
+
+- **Corporate stories all claimed every requirement.** The planner attributed `FG` ids by section containment, and the corporate template states the mapping in a COLUMN - the functional-requirement table carries a source-UC cell and the traceability matrix repeats the chain - so both of those sections name every use case and every group harvested every atom. Three use cases produced three stories with identical sources, identical titles and, since the label hashes the sources, one identical label: the second run found all three under that label and collapsed the tree onto a single issue, while coverage reported `ok` throughout because a set check cannot see misattribution. Attribution is now read from the row, which is where the template states it, with no column name hardcoded - an atom and a group sharing a table row IS the mapping, in whatever language the site writes its headers. The node's group is also in the identity hash now, because source ids alone are not an identity: two groups may legitimately cite the same atoms.
+
+- **A failed story still wrote its sub-tasks.** `create_issue` omits the parent field when the parent key is empty, so when Jira refused a story the writer logged the error, set the exit code, and went on to POST its sub-tasks - which landed as live, parentless issues from a run that had already reported a failure.
+
+- **Three gates that could not fail.** `smoke-analysis-jira.sh` asserted no token is interpolated into a curl argument using `[^\n]` inside a bracket expression, which BSD grep reads as the two literal characters `\` and `n`: the class excluded every header name containing an "n", `Authorization` among them, so on macOS the assertion could not fire for any header a caller would really write. The same file printed a green "no caller puts a token on a curl command line" unconditionally after the loop that checks it, so the report could contradict its own red line. And `smoke-doctor.sh` asserted the `MAY_BLOCK` downgrade with a regex over `doctor.mjs`'s own source, which a nearby comment satisfied as well as the code did - the enforcement could be deleted outright with the gate still green. The downgrade is now driven rather than read: the engine is importable behind a main guard and the gate calls `report()` with an out-of-set id and measures what comes back.
+
+- **`smoke-command-inventory.sh` aborted instead of reporting.** It parsed the inventory block with a hardcoded `/^analysis, analysis-resolve/` trigger, so a command sorting between those two names left the parse empty - and under `set -e` the empty assignment killed the whole gate before its own "could not parse the inventory block" guard, before the shared-core counterpart check, and before it printed its tally. A publish-blocking gate that exits silently is worse than one that fails. The block is now anchored on the tree's own first and last command, and the parse failure is reported as a finding.
+
+- **`doctor`'s script-surface check could not see one directory down.** Its pattern excluded `/` from the path segment, so a reference to `$HOME/.claude/scripts/nested/bar.mjs` was truncated to the directory; as long as that directory existed, a genuinely missing file inside it reported OK - the exact case the check exists to catch.
+
+- **Maturity warnings named the jargon instead of the gap.** "Bug icin repro adimlari yok" tells a reader what is missing only if they already know what repro steps are. The two warnings that get read most now say what is absent in plain terms: what was done, what was expected, what happened; and, for acceptance criteria, that nothing says what "done" looks like.
+
+- **Stale surface counts.** `docs/architecture.md` and `docs/ecosystem.md` still described Copilot CLI as carrying 51 skills while naming 53 for the other two hosts in the same diagram and the same table row; the installed tree has 53. `skill-siblings.mjs` carried the same stale number in a comment.
+
+- **The phase widget disappeared because the task tools now depend on the model.** Claude Code provides `TaskCreate` / `TaskUpdate` by default only on Claude 3.x, Opus 4 through 4.7, Sonnet 4 through 4.6 and Haiku 4.5; on any newer model it leaves them out unless the user opts in, and that default arrived in v2.1.268. This contract named those calls in the very first release and was right for years, so nothing noticed the default change: a run wrote its tracker state correctly, advanced all eight phases, and drew nothing on screen for the whole run.
+
+  It went unnoticed because the gate asserted the wrong thing. `smoke-tracker-widget.sh` checked that `tiles` PRINTS five `TaskCreate(` lines - a claim about our own output, not about the tool existing - and no run log in the local tree has ever recorded a `TaskCreate` call. That is the same shape as the `tokens` defect described one entry below it in 16.23.0: a gate that lints prose rather than a run.
+
+  Both `tiles` and every phase boundary now name the fallback on the same output: the bordered card IS the widget there, reprinted inside the reply exactly as on Copilot CLI, and `tiles` renders the card itself so the content is already on screen. They also print the one command that brings the native widget back - `CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude` - because a user staring at a missing widget needs the command, not the diagnosis. The branch is taken by the agent, which knows its own tool list; a shell script cannot see it.
+
+  **Naming the fallback was not enough: the card came back in the wrong shape.** With the instruction reading "reprint the card", a run redrew it as two compact lines and dropped exactly what a reader watches for - the per-phase rows, the elapsed time and the running token count. The card was on screen and the information was not, which is the failure the fallback existed to prevent. Both the `tiles` banner and the per-boundary hint now say to run `render` and paste its output VERBATIM inside a code block, and forbid the three ways it was lost: redrawing it, folding phases onto one line, dropping the columns. The gate asserts the wording on both surfaces and asserts `render` itself still emits one line per phase, a token column and a total row.
+
+---
+
 ## [16.28.0] - 2026-09-10
 
 ### Added
@@ -70,8 +145,6 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 - `smoke-install-layout.sh` fixture regenerated: `council-view.mjs` and `features/jira-context.md` moved the installed counts.
 
-- **The phase widget could not render on a Claude Code build without the tile API.** `TaskCreate` and `TaskUpdate` are not in every build, and `phase-tracker.sh` cannot see the model's tool list, so both the bootstrap and every phase boundary named a tool the host does not have and neither named what to do instead. The tracker state was written correctly, every phase advanced, and the screen stayed empty for the whole run. Both outputs now carry the fallback on the same line - the bordered card IS the widget on such a build, reprinted inside the reply at every boundary, which is what Copilot has always done - and `tiles` renders the card itself so the fallback content is already on screen. The branch is taken where the information lives: the model knows which tools it has, the shell does not.
-
 - **The closure gate read the wrong row, and then read it wrongly.** `status: final` decided whether an `AS-NN` was still open by taking the first table row in the document that mentioned the id. The corporate template writes `| **Request** | EKLENECEK (AS-NN) |` in the body, so that row won and a final document shipped with live placeholders. Openness now comes from the Section 20 row only, and from its status CELL located by header - and where there is no status column (the corporate Section 20 has none) an `EKLENECEK` still stamped with the id is itself the signal.
 
   The second half of the same line was a substring search: `açıklama` contains `Açık`, so a correctly closed Turkish row reading `Karar verildi / Decided` whose question text said "hata açıklaması" was reported as open and blocked. The status vocabulary is now matched per token across the bilingual `/`, never as a substring. English had the same trap in "reopened".

package/README.md

@@ -89,7 +89,7 @@ Depth, autopilot and `--local` are the only knobs on the run itself; everything
 
 ## Commands
 
-`/multi-agent` plus 51 sub-commands. `/multi-agent:help` renders the same catalog in your terminal, in your `outputLanguage`.
+`/multi-agent` plus 53 sub-commands. `/multi-agent:help` renders the same catalog in your terminal, in your `outputLanguage`.
 
 ### Pipeline entries
 
@@ -207,13 +207,13 @@ This enables the matching plugin (+ the shared `ai-common` plugin) in the repo's
 
 ## Tool support
 
-The pipeline runs natively on **Claude Code**, **Copilot CLI** and **Codex CLI** - all three install from the same `pipeline/` source and get the same 51 commands.
+The pipeline runs natively on **Claude Code**, **Copilot CLI** and **Codex CLI** - all three install from the same `pipeline/` source and get the same 53 commands.
 
 | Tool | Flag | What it installs |
 |---|---|---|
 | Claude Code | `--claude` (default) | slash commands + skills + agents + three `PreToolUse` hooks (secret scan, agent-guard, read-size gate) |
-| Copilot CLI | `--copilot` | instructions + 51 sub-command skills + scripts |
-| Codex CLI | `--codex` | one router skill + 51 specs as refs + 8 agent TOML + `AGENTS.md` block + `codex mcp add` |
+| Copilot CLI | `--copilot` | instructions + 53 sub-command skills + scripts |
+| Codex CLI | `--codex` | one router skill + 53 specs as refs + 8 agent TOML + `AGENTS.md` block + `codex mcp add` |
 
 Filter skills by stack with `--platform=ios\|android\|all`.
 

package/README.tr.md

@@ -207,13 +207,13 @@ Bu, ilgili plugin'i (+ ortak `ai-common` plugin'ini) repo'nun `.claude/settings.
 
 ## Araç desteği
 
-Pipeline **Claude Code**, **Copilot CLI** ve **Codex CLI** üzerinde native çalışır - üçü de aynı `pipeline/` kaynağından kurulur ve aynı 51 komutu alır.
+Pipeline **Claude Code**, **Copilot CLI** ve **Codex CLI** üzerinde native çalışır - üçü de aynı `pipeline/` kaynağından kurulur ve aynı 53 komutu alır.
 
 | Araç | Bayrak | Ne kurar |
 |---|---|---|
 | Claude Code | `--claude` (varsayılan) | slash komutları + skill'ler + agent'lar + üç `PreToolUse` hook'u (secret scan, agent-guard, okuma-boyutu geçidi) |
-| Copilot CLI | `--copilot` | talimatlar + 51 alt-komut skill'i + script'ler |
-| Codex CLI | `--codex` | bir router skill + ref olarak 51 spec + 8 agent TOML + `AGENTS.md` bloğu + `codex mcp add` |
+| Copilot CLI | `--copilot` | talimatlar + 53 alt-komut skill'i + script'ler |
+| Codex CLI | `--codex` | bir router skill + ref olarak 53 spec + 8 agent TOML + `AGENTS.md` bloğu + `codex mcp add` |
 
 Skill'leri stack'e göre filtrele: `--platform=ios\|android\|all`.
 

package/docs/architecture.md

@@ -117,7 +117,7 @@ graph TB
     end
 
     subgraph "Pipeline Specs"
-        CMD[commands/<br/>51 command files]
+        CMD[commands/<br/>53 command files]
         AGT[agents/<br/>8 agent personas]
         RUL[rules/<br/>12 domain rules]
         PHS[multi-agent-refs/phases/<br/>phase specs + contracts]
@@ -169,8 +169,8 @@ revisions of this diagram - Codex CLI and the two independently-shipped repos
 ```mermaid
 graph TD
     CC["Claude Code<br/>(source of truth)"]
-    COP["Copilot CLI<br/>(instructions + 51 skills)"]
-    COD["Codex CLI<br/>(1 router skill + 51 refs)"]
+    COP["Copilot CLI<br/>(instructions + 53 skills)"]
+    COD["Codex CLI<br/>(1 router skill + 53 refs)"]
     REPO["Pipeline Repo<br/>(npm package)"]
     WEB["Website"]
     PLUGREPO["multi-agent-plugins<br/>(5 stack plugins, own repo)"]

package/docs/ecosystem.md

@@ -5,7 +5,7 @@ separately, wired together at install time and at run time:
 
 | Repo | What it owns | Ships as |
 |---|---|---|
-| **`multi-agent-pipeline`** (this repo) | Orchestration: the 8-phase flow, the 51 slash commands, quality gates, review/triage, cross-CLI parity | npm package (`@mmerterden/multi-agent-pipeline`), installs itself onto Claude Code / Copilot CLI / Codex CLI |
+| **`multi-agent-pipeline`** (this repo) | Orchestration: the 8-phase flow, the 53 slash commands, quality gates, review/triage, cross-CLI parity | npm package (`@mmerterden/multi-agent-pipeline`), installs itself onto Claude Code / Copilot CLI / Codex CLI |
 | **`multi-agent-plugins`** | Stack knowledge: per-platform component/lifecycle skills (iOS, Android, Frontend, Backend) + shared knowledge | Claude Code marketplace, 5 independently-versioned plugins |
 | **`multi-agent-toolkit-mcp`** | The pipeline's hands on devices and browsers: 80 MCP tools across 6 categories (simulator/emulator control, accessibility audit, store compliance, web automation, Figma-vs-mock design audit, an agent-DSL batch runner) | npm package, registered as a standard stdio MCP server on every host |
 
@@ -18,7 +18,7 @@ Either can be swapped or removed without touching the other two's source.
 graph LR
     subgraph PIPE ["multi-agent-pipeline (orchestrator)"]
         direction TB
-        PHASES["8 phases · 51 commands"]
+        PHASES["8 phases · 53 commands"]
         GATES["deterministic gates + review triage"]
     end
 
@@ -64,8 +64,8 @@ only those:
 graph TD
     CC["Claude Code<br/>~/.claude/commands/multi-agent/<br/>(source of truth)"]
 
-    CC -->|"Step 2: copy + reformat<br/>51 sub-command skills"| COP["Copilot CLI<br/>~/.copilot/skills/"]
-    CC -->|"Step 2b: transform<br/>(install.js --codex)"| COD["Codex CLI<br/>1 router skill + 51 refs<br/>+ 8 agent TOML"]
+    CC -->|"Step 2: copy + reformat<br/>53 sub-command skills"| COP["Copilot CLI<br/>~/.copilot/skills/"]
+    CC -->|"Step 2b: transform<br/>(install.js --codex)"| COD["Codex CLI<br/>1 router skill + 53 refs<br/>+ 8 agent TOML"]
     CC -->|"Step 3: genericize<br/>(strip personal data)"| REPO["multi-agent-pipeline repo<br/>pipeline/"]
     CC -->|"Step 4: version + feature sync"| WEB["Website<br/>projects.ts / i18n.tsx"]
 
@@ -153,7 +153,7 @@ measurements behind this table):
 
 | | Claude Code | Copilot CLI | Codex CLI |
 |---|---|---|---|
-| **Pipeline commands** | 51 slash-command skills, native | 51 skills, `multi-agent-{cmd}` naming, copied in | 1 router skill (`multi-agent`) + 51 command specs as reference files - Codex silently truncates its skills block past a few dozen entries, so sub-commands are not peer skills here |
+| **Pipeline commands** | 53 slash-command skills, native | 53 skills, `multi-agent-{cmd}` naming, copied in | 1 router skill (`multi-agent`) + 53 command specs as reference files - Codex silently truncates its skills block past a few dozen entries, so sub-commands are not peer skills here |
 | **Stack plugins** | Marketplace plugin, loaded natively, resolved by `.claude/settings.json` enabled-list | Enabled plugin's authored skills copied flat into `~/.copilot/skills/`; `knowledge/` **not** re-copied (already delivered via `shared/external`) | Copied as reference files under `~/.codex/multi-agent-refs/skills/`, plugin-prefixed on name clash (e.g. `architecture` → `ai-ios-toolkit-architecture`) |
 | **Component dispatch (Phase 3)** | Marketplace plugin's `create-component`/`create-screen` skill via the Skill tool | No plugin loader - the enabled stack plugin's authored skills (incl. `create-component`) are copied flat into `~/.copilot/skills/` at install time (the old frozen `figma-*` copies are pruned, they were never a fallback) | Not part of the enforced parity axis; classification + state-shape must match, skill *inventory* does not |
 | **multi-agent-toolkit-mcp** | `claude mcp add multi-agent-toolkit -- npx -y @mmerterden/multi-agent-toolkit-mcp` | `copilot mcp add multi-agent-toolkit -- npx -y @mmerterden/multi-agent-toolkit-mcp` | `codex mcp add multi-agent-toolkit -- npx -y @mmerterden/multi-agent-toolkit-mcp` (skipped with a warning if `codex` isn't on `PATH`) |

package/install/claude.mjs

@@ -80,6 +80,7 @@ export function installClaude(ctx) {
   const CLAUDE_SCHEMAS = join(home, ".claude", "schemas");
   const CLAUDE_LIB = join(home, ".claude", "lib");
   const CLAUDE_MA_REFS = join(home, ".claude", "multi-agent-refs");
+  const CLAUDE_TEMPLATES = join(home, ".claude", "templates");
 
   // Before laying anything down: drop trees an older install created that no
   // current installer manages. Wipe-before-copy only protects trees still being
@@ -96,6 +97,7 @@ export function installClaude(ctx) {
   installRules(pipelineSrc, CLAUDE_RULES, useSymlinks);
   installSchemas(pipelineSrc, CLAUDE_SCHEMAS, useSymlinks);
   installLib(pipelineSrc, CLAUDE_LIB, useSymlinks);
+  installTemplates(pipelineSrc, CLAUDE_TEMPLATES, useSymlinks);
   runPreDeployScans(pipelineSrc);
   installSkills({
     pipelineSrc,
@@ -324,6 +326,21 @@ function installLib(pipelineSrc, dest, useSymlinks) {
   console.log(`    -> ${countFiles(libSrc)} files copied to ${dest}`);
 }
 
+function installTemplates(pipelineSrc, dest, useSymlinks) {
+  // The templates shipped in the tarball but never reached the user tree, so
+  // `setup` told people to merge `install/templates/claude-hooks.json` - a path
+  // that exists only in a checkout. From an install the instruction named a file
+  // the reader did not have, and nothing said so.
+  console.log("  [Claude Code] Installing templates...");
+  const templatesSrc = join(dirname(pipelineSrc), "install", "templates");
+  if (!existsSync(templatesSrc)) return;
+  // Wipe-before-copy - templates/ is a 100% pipeline-managed tree.
+  if (!useSymlinks) ensureRealDir(dest);
+  wipeDir(dest);
+  copyDir(templatesSrc, dest, { useSymlinks });
+  console.log(`    -> ${countFiles(templatesSrc)} files copied to ${dest}`);
+}
+
 function runPreDeployScans(pipelineSrc) {
   // Pre-deploy security scan - warn-only, never halts install on its own.
   const scanScript = join(pipelineSrc, "scripts", "scan-skills.sh");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "16.28.0",
+  "version": "16.29.0",
   "description": "8-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/analysis-jira/SKILL.md

@@ -0,0 +1,93 @@
+---
+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"
+not-for: create-jira, jira
+---
+
+# multi-agent analysis-jira
+
+**Input**: $ARGUMENTS
+
+Reads an analysis document as a work breakdown and creates the tree. It never
+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`.
+
+## 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>"
+```
+
+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.
+
+Exit 2 means nothing could be derived. Say so; do not improvise a tree.
+
+## Phase 2 - Preview, in full
+
+Show the human-readable output verbatim, in `outputLanguage`. It already carries
+what makes a preview meaningful:
+
+- every node, its source ids and its identity label
+- the coverage verdict **on its own line**
+- every field beside the pref key it came from, so a wrong setting shows here
+  rather than in Jira afterwards
+- the write count
+
+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
+```
+
+## Phase 3 - Approve
+
+One `AskUserQuestion`. When the verdict is `ok` or `incomplete`:
+
+- **Create the tree** - proceed
+- **Show a node in full** - print one node's body, ask again
+- **Cancel** - stop, write nothing
+
+When the verdict is `unverifiable`, the approve option is **replaced**, never
+reworded:
+
+- **Create it, unverified** - the tree will be written and recorded as unchecked
+- **Show a node in full**
+- **Cancel**
+
+A run that could not be checked is allowed. One that looks checked when it was
+not is the defect, so the approval has to name it and a plain "Approve" must not
+be reachable.
+
+`incomplete` prints its uncovered and invented ids before the question. An
+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.
+
+## Phase 4 - Write
+
+```bash
+bash "$HOME/.claude/lib/analysis-jira-write.sh" \
+  --plan /tmp/ma-plan.json --project "<KEY>"
+```
+
+It searches by label first and skips what exists. Re-running is safe and is the
+intended recovery from any failure: the ledger makes a half-written tree
+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.
+
+## Phase 5 - Report
+
+Keys created, keys skipped, 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.
+
+**Stop. No worktree, no branch, no dev chain.**

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

@@ -0,0 +1,78 @@
+---
+description: "Health check for the installed pipeline: layout, preferences, credentials, hooks and host capabilities, each with one actionable step. Exit code is the verdict. Use when a run failed for an environmental reason, before a sync, or after an update."
+description-tr: "Kurulu pipeline için sağlık kontrolü: yerleşim, tercihler, kimlik bilgileri, hook'lar ve host yetenekleri; her biri tek uygulanabilir adımla. Çıkış kodu verdiktin kendisi."
+allowed-tools: Bash, Read
+argument-hint: "[--probe] [--explain] [--json] [--list-checks]  -  optional; --probe also makes one network request per configured service"
+not-for: scan, setup
+---
+
+# multi-agent doctor
+
+**Input**: $ARGUMENTS
+
+Answers one question about this machine: **would a run work here, and if not,
+what is the single next step?**
+
+Every failure it reports has already reached a user, and each one arrived the
+same way - late, mid-run, after the pickers had been answered. A missing script
+fails at the call. Malformed preferences fail after Phase 0 has asked five
+questions. A token in a remote URL does not fail at all; it leaks.
+
+## Run it
+
+```bash
+node "$HOME/.claude/scripts/doctor.mjs" $ARGUMENTS
+```
+
+Then report the output in `outputLanguage`. Do not re-word the steps: each line
+already carries one imperative step, and paraphrasing is how a step turns into
+advice.
+
+**Answer the one check a script cannot.** `task-tools` asks whether THIS session
+carries `TaskCreate` / `TaskUpdate`, and only the agent can see its own tool
+list. Pass what you know:
+
+```bash
+node "$HOME/.claude/scripts/doctor.mjs" --task-tools=yes   # they are in your tools
+node "$HOME/.claude/scripts/doctor.mjs" --task-tools=no    # they are not
+```
+
+Without the flag that check prints `SKIP`, which is correct - reporting "absent"
+from a script that never looked is the defect this check is about.
+
+## The exit code is the product
+
+| Code | Meaning |
+|---|---|
+| 0 | healthy |
+| 1 | degraded - at least one WARN |
+| 2 | blocked - a run will fail or leak |
+| 3 | usage error |
+| 4 | indeterminate - the layout did not resolve, so nothing was checked |
+
+4 matters as much as 2. Without it, "I could not look" borrows the code for
+"I looked and it is fine".
+
+## What it does not do
+
+It recommends; it never fixes. It does not rewrite a remote URL, edit
+`settings.json`, or touch a credential. A remote carrying a token may be the only
+credential that repo has, the remote may be a mirror a script depends on
+verbatim, and this can run inside a checkout the user does not own.
+
+For an embedded credential the honest step is **not** "hide it". A token that
+reached `.git/config` is already burned - it is in the shell history and readable
+by anything that can read the working tree. The step is to revoke it at its host.
+
+## Flags
+
+| Flag | Effect |
+|---|---|
+| `--probe` | also make one authenticated request per configured service, and start the MCP server to count its tools. Off by default: a network check is the user's decision to spend. |
+| `--explain` | print the detail behind a finding (which scripts, which repos) |
+| `--json` | the same verdict in machine form, same exit code |
+| `--list-checks` | the check ids, one per line |
+| `--task-tools=yes\|no` | answer the check only the caller can see |
+
+Every check, its severity and its reasoning:
+`$HOME/.claude/multi-agent-refs/features/doctor.md`.

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

@@ -119,6 +119,7 @@ Post-Hoc & Side-Channel:
   /multi-agent:analysis ["analysis-name"]  Feature-spec analysis (Figma + Swagger + Confluence + repos). Asks the standard first: global (23-section dev handoff) or corporate (IG→UC→FG requirements doc). Stack optional; References built from the evidence record
   /multi-agent:analysis-resolve [doc]      Resolve Section 20 open questions of an analysis doc, one at a time with source-labeled candidates
   /multi-agent:review-analysis [doc]  Review a written analysis; findings cite the rule they break
+  /multi-agent:analysis-jira [doc]    A final analysis -> a Jira story tree; coverage two-way, existing nodes skipped
   /multi-agent:complaint-analysis ["run-name"] [--file path]  Customer-complaint triage: Graylog evidence per trx/conv id + read-only repo correlation → client/bff root cause + fix plan + dev prompt, or core routing recommendation
   /multi-agent:build-optimize iOS-only Xcode build perf wrapper → benchmark + analyze + recommend-first .build-benchmark/optimization-plan.md
   /multi-agent:create-jira ["desc"] [figma-url] [swagger-url]  Create a Jira Task/Bug/Story matching team conventions (asks type + mining + active sprint + auto-sizing sections + preview & approval)
@@ -126,6 +127,7 @@ Post-Hoc & Side-Channel:
   /multi-agent:graph         Build and query the repo code graph (symbols, imports, references), LLM-free
   /multi-agent:search         Cross-task log search with smart ranking; --semantic queries triage corpus
   /multi-agent:scan           Skill security scan against tiered pattern catalog
+  /multi-agent:doctor         Would a run work here? Layout, prefs, credentials, hooks; exit code is the verdict
   /multi-agent:refactor       Best practices + bug hunt + upstream drift + toolkit MCP research -> one plan, approval, dev + sync
   /multi-agent:refactor backlog  Decide the friction already recorded about the pipeline itself, nothing re-derived
   /multi-agent:store-ready [repo] [--archive=|--ipa=|--aab=|--apk=] [--skip-sweep]  Pre-submission store readiness, iOS + Android, local-only: three symmetric gates per platform plus the running-app sweep. A skipped gate is never a pass. Validates only, never uploads.

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

@@ -4,6 +4,19 @@ description-tr: "İlk kurulum sihirbazı: keychain token keşfi, Git Identity ka
 allowed-tools: Bash, Read, Write, AskUserQuestion, WebFetch
 ---
 
+## Step 0 - What is actually wrong
+
+```bash
+node "$HOME/.claude/scripts/doctor.mjs"
+```
+
+Run it before the first question and again at the end. The first run turns setup
+from a fixed script into a targeted one: there is no point asking for a token
+that is already mapped and answering. The second run is the only honest way to
+end - "setup complete" is a claim, and the doctor's exit code is the evidence for
+or against it. Report both in `outputLanguage`, and if the second run still shows
+a BLOCK, say so plainly rather than closing on the word "complete".
+
 ## Setup (Credential Store + Git Identity Onboarding)
 
 Cross-platform setup  -  uses `$HOME/.claude/lib/credential-store.sh` to read/write secrets in the platform-native credential store:
@@ -789,7 +802,7 @@ All tokens are optional in the sense that every service can be answered with Ski
 
 ### Step 8  -  Enforcement hooks (optional, Claude Code)
 
-Offer to merge `install/templates/claude-hooks.json`: three `PreToolUse` gates that block on a non-zero exit (secret scan, agent-guard, read-size) plus two capture hooks that block nothing (`SessionEnd`, `SessionStart`). What each does: `$HOME/.claude/multi-agent-refs/picker-contract.md`.
+Offer to merge `$HOME/.claude/templates/claude-hooks.json`: three `PreToolUse` gates that block on a non-zero exit (secret scan, agent-guard, read-size) plus two capture hooks that block nothing (`SessionEnd`, `SessionStart`). What each does: `$HOME/.claude/multi-agent-refs/picker-contract.md`.
 
 - Ask (picker): "Install the pipeline's hooks into `~/.claude/settings.json`?" Default Yes.
 - On Yes, deep-merge EVERY event in the template's `hooks` object, not `PreToolUse` alone - merging one event silently drops the capture hooks, and a run killed before Phase 7 then loses its findings exactly as it did before they existed. Preserve existing hooks; never duplicate a matcher already calling the same script.

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

@@ -57,10 +57,11 @@ The sync skill must run on all three platforms. Commands go through the platform
 Run every step automatically:
 
 ```
+Step 0: DOCTOR      doctor.mjs  -  exit 2 or 4 stops the sync
 Step 1: PLATFORM    Detect macOS / Linux / Windows (Git Bash / WSL); export PLATFORM env
 Step 1.5: DETECT    Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 51 sub-command skills)
-Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + 51 specs as refs + 8 agent TOML)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 53 sub-command skills)
+Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + 53 specs as refs + 8 agent TOML)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub, bash -n on all sh)
 Step 3c: PLUGINS    pipeline shared/external -> multi-agent-plugins marketplace (rebuild knowledge/,
                      bump changed plugins' patch version, commit + push the plugins repo)
@@ -72,6 +73,8 @@ Step 6: Report      Summary: synced targets, platform, changed files, deploy sta
 
 If nothing is stale → report "All targets up to date" and stop.
 
+Step 0 gate rules and why: `features/doctor.md`.
+
 ---
 
 ## Sync rules
@@ -122,8 +125,8 @@ If nothing is stale → report "All targets up to date" and stop.
      # backstop: no local-only wrapper may exist in the synced target
      grep -rl "^local-only: true" ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
        && { echo "ABORT: local-only wrapper leaked into pipeline/commands"; exit 1; } || true
-     # backstop: no corporate marketplace/skill reference in the synced tree
-     grep -rniE "ai-ios(-engineering)?-toolkit:(create-ui-component|evolve-ui-component|fix-bug|branch-and-pr|backlog|code-connect|figma-utility|resource-utility|component-wiki|component-docs|figma-setup)" \
+     # backstop: corporate refs only (generic ai-ios-toolkit is fine)
+     grep -rniE "ai-(ios-engineering|mobile)-toolkit:(create-ui-component|evolve-ui-component|fix-bug|branch-and-pr|backlog|code-connect|figma-utility|resource-utility|component-wiki|component-docs|figma-setup)" \
        ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
        && { echo "ABORT: corporate reference leaked into pipeline/commands"; exit 1; } || true
      ```
@@ -166,7 +169,7 @@ If nothing is stale → report "All targets up to date" and stop.
 Unlike the Copilot step, this one does **not** hand-copy files. The Codex tree is a
 *transform* of the Claude tree, not a mirror of it, and the transform is real work:
 
-- the 51 sub-command specs become reference files, because Codex silently truncates
+- the 53 sub-command specs become reference files, because Codex silently truncates
   its skills block (see `cross-cli-contract.md` 2.6 for the measurement)
 - every `$HOME/.claude/...` reference to a CLI-owned tree is retargeted, with
   `agents/<persona>.md` becoming `.toml` and the dispatcher becoming the router skill
@@ -480,18 +483,18 @@ When invoked with the `release` argument:
 ## Sub-Command Sync (Claude Code <-> Copilot CLI Skills)
 
 This runs on the Claude <-> Copilot axis. Codex is NOT synced here: it receives the
-same 51 specs as reference files rather than as peer skills, via Step 2b -  see
+same 53 specs as reference files rather than as peer skills, via Step 2b -  see
 `cross-cli-contract.md` 2.6 for why the parity axis differs per host.
 
 | Claude Code | Copilot CLI |
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**51 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**53 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
-analysis, analysis-resolve, autopilot, build-optimize, channels,
-complaint-analysis, create-jira, design-check, diff-explain, feedback,
+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,
 prune-prompts, purge, refactor, resume, resume-local, review,

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

@@ -4,6 +4,18 @@ description-tr: "Pipeline'ı npm'deki son yayına günceller: registry kontrolü
 allowed-tools: Bash, Read, Write, AskUserQuestion
 ---
 
+## After the install, check it
+
+```bash
+node "$HOME/.claude/scripts/doctor.mjs"
+```
+
+An update is the moment the layout changes, so it is the moment a layout check is
+worth most: a script that moved, a host tree that did not get the copy, a version
+stamp that disagrees with the package. Report the result in `outputLanguage`.
+Exit 2 means the update left the install in a state a run will fail from - say
+that, do not report "updated" and stop.
+
 # multi-agent update
 
 Update the pipeline in one command. The npm registry is the single update channel: the latest published release is downloaded and installed. Existing preferences are preserved; only skill / script / schema files are refreshed.