@mmerterden/multi-agent-pipeline 16.28.0 → 16.29.0

package/pipeline/scripts/phase-tracker.sh

@@ -570,10 +570,11 @@ tracker_next_hint() {
   [ "${TRACKER_QUIET:-0}" = "1" ] && return 0
   name=$(load_state | jq -r --arg id "$pid" '(.phases[] | select(.id == $id) | .name) // ""')
   case "$(host_kind)" in
-    # Not every Claude Code build ships the tile API, and the shell cannot see
-    # the model's tool list. Naming the fallback on the same line is what keeps a
-    # build without TaskUpdate from advancing eight phases in silence.
-    claude) mirror="TaskUpdate(\"Phase $pid $name\", status=\"$status\") - or, if TaskUpdate is not one of your tools, reprint the card above inside your reply text" ;;
+    claude) mirror="TaskUpdate(\"$(subjects "$pid")\", status=\"$status\")  -  the subject is re-read from \`phase-tracker.sh subjects $pid\` so the widget carries the model, the elapsed time and the tokens; if TaskUpdate is not one of your tools, paste the card above into your reply VERBATIM in a code block (every phase on its own line, keep the elapsed and token columns; do not redraw or compact it)" ;;
+    # Not every session carries the task tools: Claude Code provides them by
+    # default only up to Opus 4.7 / Sonnet 4.6, a default that landed in
+    # v2.1.268. Naming the fallback on the same line is what keeps a newer model
+    # from advancing eight phases in silence.
     codex) mirror="update_plan: set step \"Phase $pid $name\" to $status (send the FULL step list, it is not a delta)" ;;
     *) mirror="no task widget on this host - reprint the card above inside your reply text" ;;
   esac
@@ -664,6 +665,61 @@ EOF
   printf '\n'
 }
 
+# The native widget renders one row per task and gives us exactly one string to
+# fill it: the subject. So the numbers a reader wants - which model is spending,
+# how long the phase has run, what it cost - have to travel IN the subject or not
+# at all. `render` already computes all of it for the fallback card; this prints
+# the same values in the one shape the host will accept.
+#
+# Every segment is omitted while it is empty, so a pending phase is just its name
+# and a finished one carries its whole bill. Separator is ` - `, not a middle dot:
+# a subject is a task title and travels through surfaces that are not a terminal.
+subjects() {
+  need_jq
+  local state want="${1:-}"
+  state=$(load_state)
+  local prices_json='{"prices":{}}'
+  if [ -f "$COST_TABLE" ]; then
+    prices_json=$(cat "$COST_TABLE" 2>/dev/null) || prices_json='{"prices":{}}'
+    echo "$prices_json" | jq empty 2>/dev/null || prices_json='{"prices":{}}'
+  fi
+  local now_s; now_s=$(now_epoch)
+  local rows
+  rows=$(echo "$state" | jq -r --argjson prices "$prices_json" "$COST_JQ_DEFS"'
+    def usd_of(p): cost_usd_of($prices.prices[p.model // ""] // null; (p.tokens_in // 0); (p.tokens_out // 0); (p.tokens_cached // 0));
+    .phases // []
+    | sort_by(.id | (tonumber? // 9999))
+    | .[] | [
+      (.id // ""), (.name // ""), (.status // ""),
+      (.started_at // ""), (.completed_at // ""), (.model // ""),
+      (((.tokens_in // 0) + (.tokens_out // 0)) | tostring),
+      (usd_of(.) | if . == null then "" else (((. * 100) | floor) / 100 | tostring) end)
+    ] | join("\u001f")')
+  local pid pname pstatus p_start p_end pmodel ptok pusd
+  while IFS=$'\x1f' read -r pid pname pstatus p_start p_end pmodel ptok pusd; do
+    [ -n "$pid" ] || continue
+    [ -z "$want" ] || [ "$want" = "$pid" ] || continue
+    local line="Phase $pid $pname"
+    [ -n "$pmodel" ] && line="$line - $pmodel"
+    local s_ep e_ep el=""
+    s_ep=$(iso_to_epoch "$p_start")
+    e_ep=$(iso_to_epoch "$p_end")
+    if [ -n "$s_ep" ]; then
+      case "$pstatus" in
+        completed|failed|skipped) [ -n "$e_ep" ] && el=$((e_ep - s_ep)) ;;
+        in_progress) el=$((now_s - s_ep)) ;;
+      esac
+    fi
+    if [ -n "$el" ] && [ "$el" -lt 0 ] 2>/dev/null; then el=0; fi
+    [ -n "$el" ] && line="$line - $(format_elapsed "$el")"
+    if [ "${ptok:-0}" -gt 0 ] 2>/dev/null; then
+      line="$line - $(format_tokens "$ptok") tok"
+      [ -n "$pusd" ] && line="$line - $(printf '~$%.2f' "$pusd" 2>/dev/null || echo '')"
+    fi
+    printf '%s\n' "$line"
+  done <<< "$rows"
+}
+
 render() {
   need_jq
   local state
@@ -1159,6 +1215,10 @@ GATE
     fi
     ;;
 
+  subjects)
+    subjects "${1:-}"
+    ;;
+
   tiles)
     need_jq
     tiles_state=$(load_state)
@@ -1169,22 +1229,42 @@ GATE
     }
     case "$(host_kind)" in
       claude)
-        # The native tile API is not in every Claude Code build. This script
-        # cannot probe the model's tool list, and a run that fires nothing and
-        # says nothing is the failure that reached a user: the tracker state was
-        # written correctly, every phase advanced, and the screen stayed empty
-        # for the whole run. So the fallback is named here rather than assumed,
-        # and the branch is taken where the information actually lives - the
-        # model knows which tools it has, the shell does not.
+        # The task tools are not in every session, and the reason is the model,
+        # not the CLI version. 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 landed in v2.1.268. This contract was written
+        # when the tools were universal and stayed true for years, so nothing
+        # noticed: the tracker state was written correctly, every phase advanced,
+        # and the screen stayed empty for a whole run.
+        #
+        # A shell script cannot probe the model's tool list, so the branch is
+        # taken where the information actually lives - the model knows which
+        # tools it has. And the fallback is not enough on its own: a user looking
+        # at a missing widget needs the one command that brings it back, which is
+        # why the opt-in is printed next to it.
         echo "REQUIRED  -  create one native tile per phase, in this exact order,"
         echo "BEFORE any TaskUpdate. The widget renders by creation order, not by"
         echo "phase number, so an out-of-order call scrambles the stack."
-        echo "$tiles_state" | jq -r '.phases[] | "  TaskCreate(subject: \"Phase \(.id) \(.name)\")"'
+        subjects | sed 's/^/  TaskCreate(subject: "/; s/$/")/'
+        echo
+        echo "At every phase boundary re-run \`phase-tracker.sh subjects <id>\` and"
+        echo "pass that line as the subject of the TaskUpdate. The subject is the only"
+        echo "string the native widget renders, so the model, the elapsed time and the"
+        echo "token count reach the user through it or not at all."
         echo
-        echo "IF TaskCreate IS NOT ONE OF YOUR TOOLS this build has no native tile"
-        echo "API. Do not skip the signal: the card below IS the widget then, and"
-        echo "it must be reprinted inside your reply at every phase boundary  - "
-        echo "tool output is collapsed, so a card left in stdout never arrives."
+        echo "IF TaskCreate IS NOT ONE OF YOUR TOOLS this session's model does not"
+        echo "carry them (default since v2.1.268 on models newer than Opus 4.7 /"
+        echo "Sonnet 4.6). Then the card below IS the widget, and at every phase"
+        echo "boundary you run \`phase-tracker.sh render\` and paste its output"
+        echo "into your reply VERBATIM, inside a code block  -  every phase on"
+        echo "its own line, with the elapsed time, the token count and the total"
+        echo "row exactly as printed. Do NOT redraw it, do not compact phases"
+        echo "onto one line, do not drop the columns: those numbers are the"
+        echo "whole reason the card is worth showing. Tool output is collapsed,"
+        echo "so a card left in stdout never reaches the user."
+        echo "Say once, in outputLanguage, that the native widget returns with:"
+        echo "  CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude"
         echo
         render
         ;;
@@ -1212,7 +1292,7 @@ GATE
     ;;
 
   *)
-    echo "phase-tracker: unknown action '$ACTION' (use init|add|update|sub|tokens|model|meta|now|cost|render)" >&2
+    echo "phase-tracker: unknown action '$ACTION' (use init|add|update|sub|tokens|model|meta|now|cost|render|subjects)" >&2
     exit 64
     ;;
 esac

package/pipeline/scripts/scan-agent-config.sh

@@ -18,7 +18,24 @@ set -uo pipefail
 
 # ROOT defaults to the repo root; SCAN_ROOT overrides it (used by the smoke test
 # to point at a fixture tree of planted-bad configs).
-ROOT="${SCAN_ROOT:-$(cd "$(dirname "$0")/../.." && pwd)}"
+#
+# Two layouts, and this script ships into the second one. From the checkout, $0
+# is <repo>/pipeline/scripts/... and `../..` is the repo. From an install it is
+# ~/.claude/scripts/... and `../..` is the HOME directory, where none of the
+# shipped config paths exist - the scan then found zero files and called itself
+# clean. Same defect class as the one skill-siblings.mjs carried, so it gets the
+# same two-candidate resolution: try the repo layout, fall back to the install.
+if [ -n "${SCAN_ROOT:-}" ]; then
+  ROOT="$SCAN_ROOT"
+else
+  _here="$(cd "$(dirname "$0")" && pwd)"
+  _repo="$(cd "$_here/../.." && pwd)"
+  if [ -d "$_repo/pipeline/agents" ]; then
+    ROOT="$_repo"
+  else
+    ROOT="$HOME/.claude"
+  fi
+fi
 
 HIGH=0; MED=0
 high() { HIGH=$((HIGH+1)); echo "  [HIGH]   $1"; }
@@ -27,18 +44,39 @@ med()  { MED=$((MED+1));  echo "  [MEDIUM] $1"; }
 # Shipped config surface (globs expanded safely; missing paths are skipped).
 TARGETS=()
 add() { [ -e "$1" ] && TARGETS+=("$1"); }
-add "$ROOT/install/templates/claude-hooks.json"
-add "$ROOT/install/templates/copilot-instructions.md"
-add "$ROOT/pipeline/preferences-template.json"
-for f in "$ROOT"/pipeline/agents/*.md; do add "$f"; done
-# (figma component skills + their scripts now live in the ai-*-toolkit
-#  marketplace plugin, not in this repo, so there is nothing figma to scan here.)
-add "$ROOT/pipeline/scripts/agent-guard.sh"
-add "$ROOT/pipeline/scripts/pre-commit-check.sh"
+# The same surface under either layout: `pipeline/`-prefixed in the checkout,
+# flat under ~/.claude once installed.
+if [ -d "$ROOT/pipeline/agents" ]; then
+  add "$ROOT/install/templates/claude-hooks.json"
+  add "$ROOT/install/templates/copilot-instructions.md"
+  add "$ROOT/pipeline/preferences-template.json"
+  for f in "$ROOT"/pipeline/agents/*.md; do add "$f"; done
+  # (figma component skills + their scripts now live in the ai-*-toolkit
+  #  marketplace plugin, not in this repo, so there is nothing figma to scan here.)
+  add "$ROOT/pipeline/scripts/agent-guard.sh"
+  add "$ROOT/pipeline/scripts/pre-commit-check.sh"
+else
+  # settings.json is deliberately NOT in this list. It is the USER's file, not
+  # something the pipeline ships, and their own permission choices are theirs to
+  # make - scanning it turned a personal setting into a release blocker.
+  for f in "$ROOT"/templates/*; do add "$f"; done
+  for f in "$ROOT"/agents/*.md; do add "$f"; done
+  add "$ROOT/scripts/agent-guard.sh"
+  add "$ROOT/scripts/pre-commit-check.sh"
+fi
 
 rel() { echo "${1#$ROOT/}"; }
 
-echo "→ scanning ${#TARGETS[@]} shipped config files"
+echo "→ scanning ${#TARGETS[@]} shipped config files (root: $ROOT)"
+
+# Zero targets is a resolution failure, not a clean bill: `"${TARGETS[@]}"` on an
+# empty array is also an unbound-variable error under bash 3.2 with `set -u`, so
+# the script died here instead of saying what went wrong.
+if [ "${#TARGETS[@]}" -eq 0 ]; then
+  echo "  [HIGH]   no shipped config file found under $ROOT - nothing was scanned"
+  echo "→ config hygiene: 1 HIGH, 0 MEDIUM"
+  exit 1
+fi
 
 for f in "${TARGETS[@]}"; do
   [ -f "$f" ] || continue

package/pipeline/scripts/skill-siblings.mjs

@@ -60,7 +60,7 @@ const CMD_DIR = IN_REPO ? REPO_CMD_DIR : join(HOME, ".claude", "commands", "mult
 const CORE_DIR = join(REPO_ROOT, "pipeline", "skills", "shared", "core");
 const COPILOT_DIR = join(HOME, ".copilot", "skills");
 const CODEX_DIR = join(HOME, ".codex", "multi-agent-refs", "commands");
-// The dispatcher is the one skill Codex installs as a SKILL: the 51 sub-commands
+// The dispatcher is the one skill Codex installs as a SKILL: the sub-commands
 // become refs there, because Codex truncates a large skills block. Resolving it
 // under the refs tree like the others reported a false "absent" - and a sibling
 // check that invents a missing copy is worse than none, since it sends the next

package/pipeline/skills/shared/core/multi-agent-analysis-jira/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: multi-agent-analysis-jira
+language: en
+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."
+user-invocable: true
+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/skills/shared/core/multi-agent-doctor/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: multi-agent-doctor
+language: en
+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."
+user-invocable: true
+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/skills/shared/core/multi-agent-setup/SKILL.md

@@ -5,6 +5,19 @@ description: "First-run setup wizard: keychain token discovery, Git Identity onb
 user-invocable: true
 ---
 
+## 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 (Keychain Token + Git Identity Onboarding)
 
 Self-contained setup  -  works with inline `security` commands, no external script **required**. If `$HOME/.claude/scripts/keychain-save.sh` exists, it can be used as an interactive alternative but is not mandatory. The `setup` command starts interactive onboarding.

package/pipeline/skills/shared/core/multi-agent-sync/SKILL.md

@@ -30,9 +30,10 @@ When invoked, it synchronizes all targets in order. It detects what changed, upd
 Run all steps automatically:
 
 ```
+Step 0: DOCTOR      node $HOME/.claude/scripts/doctor.mjs  -  exit 2 or 4 STOPS the sync
 Step 1: 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)
 Step 3d: DEV-TOOLKIT Companion MCP server -> detect movement, ship gates, commit + publish
 Step 4: WEBSITE     Version + phase/model counts -> {website-host} (i18n + projects.ts)
@@ -40,6 +41,8 @@ Step 5: Commit      Commit + push all changed repos
 Step 6: Report      Summary: synced targets, changed files, deploy status, multi-agent-toolkit version
 ```
 
+**Step 0 is a gate, not a report.** Syncing a blocked install copies one fault onto five surfaces, and the copies are what people then debug. Exit 4 stops too: the layout did not resolve, so nothing was checked, and syncing from an unknown state is worse than not syncing.
+
 If nothing is stale -> report "All targets up to date" and stop.
 
 ## Special inputs
@@ -98,7 +101,7 @@ If nothing is stale -> report "All targets up to date" and stop.
 ## Codex Sync (Step 2b)
 
 This step does **not** hand-copy files. The Codex tree is a *transform* of the Claude
-tree, not a mirror: the 51 sub-command specs become reference files (Codex silently
+tree, not a mirror: the 53 sub-command specs become reference files (Codex silently
 truncates its skills block  -  see `cross-cli-contract.md` 2.6), every reference to a
 CLI-owned tree is retargeted (`agents/<persona>.md` becomes `.toml`, the dispatcher
 becomes the router skill), the 8 personas are regenerated as TOML with a model +
@@ -224,11 +227,11 @@ When invoked with the `release` argument:
 |-------------|-------------|
 | `~/.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/skills/shared/core/multi-agent-update/SKILL.md

@@ -6,6 +6,24 @@ user-invocable: true
 argument-hint: ""
 ---
 
+## 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.
+
+A git clone of the pipeline repo is a maintainer workspace, kept in sync by `/multi-agent:sync` - it is never consulted here. A fix that only exists on `main` reaches users when a release is published, not before.
+
 # multi-agent-update  -  Pipeline Update
 
 Update the pipeline with a single command. Preferences are preserved; only skill/script/schema files are refreshed.