@mmerterden/multi-agent-pipeline 20.25.0 → 20.26.0

package/pipeline/scripts/jira-wiki-escape.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
-import { pathToFileURL } from "node:url";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
 
 const SEQUENCES = [
   ":)",
@@ -118,8 +119,7 @@ async function readStdin() {
   return Buffer.concat(chunks).toString("utf8");
 }
 
-const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isMain) {
+if (invokedDirectly(import.meta.url)) {
   const args = process.argv.slice(2);
   const check = args.includes("--check");
   const file = args.find((a) => !a.startsWith("--"));

package/pipeline/skills/.skill-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-10-14T08:53:17Z",
-  "skillCount": 230,
+  "generatedAt": "2026-10-14T16:29:25Z",
+  "skillCount": 229,
   "entries": [
     {
       "path": "shared/core/apple-archive-compliance/SKILL.md",
@@ -49,7 +49,7 @@
     },
     {
       "path": "shared/core/multi-agent-channels/SKILL.md",
-      "sha256": "03f7c648e1938f3d6d7c48d4c1c01f2bd734cdce873ec5203120b5be3ae761db"
+      "sha256": "cb5e1f9e82f3fd3e7d9ad20bff7a066cafff75323044a08726e3af368738b123"
     },
     {
       "path": "shared/core/multi-agent-complaint-analysis/SKILL.md",
@@ -59,10 +59,6 @@
       "path": "shared/core/multi-agent-create-jira/SKILL.md",
       "sha256": "5aad0d841e9e5b7140bb441e07819209ca64c5b6fc209d6ad586b5fbb353e377"
     },
-    {
-      "path": "shared/core/multi-agent-deps/SKILL.md",
-      "sha256": "1c583a47a1c1d66f37a581f0436861e511d1272b5014e1bd15397a4b4d6a8553"
-    },
     {
       "path": "shared/core/multi-agent-design-check/SKILL.md",
       "sha256": "8888744fa52e935f53db9a1068e1b18c636b6c9d55b084dabfc19b9ae68bf6f8"
@@ -241,7 +237,7 @@
     },
     {
       "path": "shared/core/multi-agent-sync/SKILL.md",
-      "sha256": "76e713bb107d0fa14db67ca3fc67f420a8e831f3c2db85b21fd59acb327f0017"
+      "sha256": "1e418fe472a93cc7b4b5bc19ff9e9b8b9d89b545e45d343a643f17a492cb0624"
     },
     {
       "path": "shared/core/multi-agent-test-accessibility/SKILL.md",
@@ -277,7 +273,7 @@
     },
     {
       "path": "shared/core/multi-agent/SKILL.md",
-      "sha256": "b2435de3df518efb8ddf9ac89b3089449e46bf55f29220e07a3aa95dfc8cd083"
+      "sha256": "079b49a1981c63d90798089a343b7f324571c4f7cc6ad3fb757e82719c35eb0a"
     },
     {
       "path": "shared/external/accessibility-compliance-accessibility-audit/SKILL.md",

package/pipeline/skills/.skills-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "skillCount": 230,
+  "skillCount": 229,
   "entries": [
     {
       "name": "accessibility-compliance-accessibility-audit",
@@ -1146,17 +1146,6 @@
       "triggerPaths": [],
       "relativePath": "shared/core/multi-agent-create-jira/SKILL.md"
     },
-    {
-      "name": "multi-agent-deps",
-      "description": "Bump one dependency, fix only what the bump broke, review, open a PR; rolls back past the fix round cap. SwiftPM, Gradle, npm, pip. Use when a library needs updating.",
-      "platform": null,
-      "group": "core",
-      "plugin": null,
-      "invokeAs": "multi-agent-deps",
-      "triggerKeywords": [],
-      "triggerPaths": [],
-      "relativePath": "shared/core/multi-agent-deps/SKILL.md"
-    },
     {
       "name": "multi-agent-design-check",
       "description": "Mock-mode vs Figma design audit (iOS / Android, local-only). Pick repo + module, gate on mock support, enumerate every state driver into a countable target set, build Debug in a worktree, launch in mock mode, fetch Figma variants, compare each pixel + px-spacing + typography + color, and export a si",

package/pipeline/skills/shared/README.md

@@ -2,11 +2,11 @@
 
 Single source of truth for skills delivered to both Claude Code (`~/.claude/skills/`) and Copilot CLI (`~/.copilot/skills/`) by the installer.
 
-**Total:** 230 skills (69 core + 161 external). Auto-generated by `scripts/gen-skills-index.mjs`  -  do not edit by hand.
+**Total:** 229 skills (68 core + 161 external). Auto-generated by `scripts/gen-skills-index.mjs`  -  do not edit by hand.
 
 ## Directory layout
 
-- **`core/`**  -  69 `multi-agent*` orchestration skills that are pipeline-critical. Edits here are core-code changes.
+- **`core/`**  -  68 `multi-agent*` orchestration skills that are pipeline-critical. Edits here are core-code changes.
 - **`external/`**  -  161 iOS / Android / generic skills that ship into the stack plugins. Each names its origin in `metadata.source`: `multi-agent-pipeline` when written here, or the upstream and license a `NOTICE-*.md` in this directory covers.
 - Install destinations (ADR-0009): Claude Code gets NO local copy of `external/` - it loads those skills from the `multi-agent-plugins` marketplace, namespaced (`ai-<stack>-toolkit:<name>`); only the two compliance catalogs from `core/` land in `~/.claude/skills/`. Copilot CLI and Codex CLI receive a flat copy filtered to the enabled stacks. `external/` remains the single authoring source that `build-stack-plugins.mjs` publishes from.
 
@@ -14,7 +14,7 @@ Source layout is logical grouping only  -  skill discovery at runtime is unchang
 
 ## Categories
 
-- [Pipeline Orchestration](#pipeline-orchestration)  -  69
+- [Pipeline Orchestration](#pipeline-orchestration)  -  68
 - [iOS / Apple Ecosystem](#ios-apple-ecosystem)  -  94
 - [Android / Kotlin](#android-kotlin)  -  16
 - [Web](#web)  -  10
@@ -40,7 +40,6 @@ Source layout is logical grouping only  -  skill discovery at runtime is unchang
 | [`multi-agent-channels`](./core/multi-agent-channels/) | `core` | Multi-channel reporter  -  Jira/Confluence/Wiki/PR description. Multi-select channels + content, humanizer pass, reviewer-preserving Bitbuck |
 | [`multi-agent-complaint-analysis`](./core/multi-agent-complaint-analysis/) | `core` | Customer-complaint triage. Ingests complaints (paste, csv/xlsx/txt/json file, Jira issue, Confluence URL), fetches Graylog evidence per trx/ |
 | [`multi-agent-create-jira`](./core/multi-agent-create-jira/) | `core` | Create a standards-compliant Jira issue (Task / Bug / Story): asks the type, mines project conventions, drafts from a standard template with |
-| [`multi-agent-deps`](./core/multi-agent-deps/) | `core` | Bump one dependency, fix only what the bump broke, review, open a PR; rolls back past the fix round cap. SwiftPM, Gradle, npm, pip. Use when |
 | [`multi-agent-design-check`](./core/multi-agent-design-check/) | `core` | Mock-mode vs Figma design audit (iOS / Android, local-only). Pick repo + module, gate on mock support, enumerate every state driver into a c |
 | [`multi-agent-diff-explain`](./core/multi-agent-diff-explain/) | `core` | Map Phase 3 triage findings to branch diff lines. Read-only post-hoc command, used after review to answer 'which finding lines up with which |
 | [`multi-agent-doctor`](./core/multi-agent-doctor/) | `core` | Health check for the installed pipeline: layout, preferences, credentials, hooks and host capabilities, each with one actionable step. Exit  |

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

@@ -203,6 +203,11 @@ Per-project input parsing (my-ios-app / my-figma-app / generic), worktree creati
 
 **IMPORTANT**: Update `agent-state.json` at EVERY phase transition. This file is the resume source of truth.
 
+**Issue family** (Jira input, once `agent-state.json` exists): run
+`bash "$HOME/.copilot/lib/jira-family-write.sh" resolve --state "$STATE_FILE"`. It records the
+story, dev and test sub-tasks and the story format check in `state.jiraFamily`, and asks and writes nothing;
+the channels Jira step writes to them.
+
 ### Phase 1: Plan
 Two halves, one phase, one approval gate.
 

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

@@ -169,6 +169,13 @@ argv. Jira turns `:)` `(x)` `(!)` `(/)` into emoticon images, including inside
 `{{monospace}}`; an escape that has to be remembered is one that is eventually
 forgotten, and that is how the selector above shipped.
 
+**Issue family** (`state.jiraFamily` set by Phase 0): the same body goes to the development sub-task, the test scenarios to the test sub-task (or, with none, the story) and a reformat of a story outside the story format to the story. `plan` prints one grouped confirmation ("3 yazma: story açıklaması, dev yorumu, test yorumu") and any question; show every write's body from `jira-family/plan.json` as one multi-select, re-run `plan` with `--skip <deselected ids>` (or `--dev-task` / `--test-task` for a question), then `apply`. Autopilot runs both back to back and records its choices in `state.decisions[]`:
+
+```bash
+bash "$HOME/.copilot/lib/jira-family-write.sh" plan --state "$STATE_FILE" --dev-body "$F"
+bash "$HOME/.copilot/lib/jira-family-write.sh" apply --state "$STATE_FILE"
+```
+
 ### Confluence page
 
 1. Token from `keychainMapping.confluence` via `~/.copilot/lib/credential-store.sh get`  -  missing→Token Save Flow from setup skill.

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

@@ -33,7 +33,7 @@ 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 + 66 sub-command skills)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 65 sub-command skills)
 Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + sub-command specs as refs + 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
@@ -229,12 +229,12 @@ When invoked with the `release` argument:
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**66 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**65 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
 analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off,
 autopilot-on, autopilot-status, bug-bash, build-optimize, channels, complaint-analysis,
-create-jira, deps, design-check, diff-explain, doctor, estimate, feedback, forget,
+create-jira, design-check, diff-explain, doctor, estimate, feedback, forget,
 garbage-collect, graph, help, ios-coding-standard, issue, jira, kill,
 language, log, manual-test, model, postmortem, prune-logs,
 prune-prompts, purge, refactor, research, resume, review,

package/pipeline/skills/skills-index.md

@@ -3,7 +3,7 @@
 > Auto-generated by `pipeline/scripts/build-skills-index.mjs`  -  do not hand-edit.
 > Regenerate with `node pipeline/scripts/build-skills-index.mjs`.
 
-**230 skills** across 2 groups.
+**229 skills** across 2 groups.
 
 | Group | Name | Platform | Description |
 |-------|------|----------|-------------|
@@ -111,7 +111,6 @@
 | core | `multi-agent-channels` |  -  | Multi-channel reporter  -  Jira/Confluence/Wiki/PR description. Multi-select channels + content, humanizer pass, reviewer-preserving Bitbuck |
 | core | `multi-agent-complaint-analysis` |  -  | Customer-complaint triage. Ingests complaints (paste, csv/xlsx/txt/json file, Jira issue, Confluence URL), fetches Graylog evidence per trx/ |
 | core | `multi-agent-create-jira` |  -  | Create a standards-compliant Jira issue (Task / Bug / Story): asks the type, mines project conventions, drafts from a standard template with |
-| core | `multi-agent-deps` |  -  | Bump one dependency, fix only what the bump broke, review, open a PR; rolls back past the fix round cap. SwiftPM, Gradle, npm, pip. Use when |
 | core | `multi-agent-design-check` |  -  | Mock-mode vs Figma design audit (iOS / Android, local-only). Pick repo + module, gate on mock support, enumerate every state driver into a c |
 | core | `multi-agent-diff-explain` |  -  | Map Phase 3 triage findings to branch diff lines. Read-only post-hoc command, used after review to answer 'which finding lines up with which |
 | core | `multi-agent-doctor` |  -  | Health check for the installed pipeline: layout, preferences, credentials, hooks and host capabilities, each with one actionable step. Exit  |

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

@@ -1,61 +0,0 @@
----
-description: "Bump one dependency, fix only what the bump broke, review, open a PR; rolls back past the fix round cap. SwiftPM, Gradle, npm, pip. Use when a library needs updating."
-description-tr: "Tek bağımlılığı yükseltir, yalnızca yükseltmenin kırdığını düzeltir, review edip PR açar; düzeltme turu sınırında geri alır. SwiftPM, Gradle, npm, pip. Bir kütüphaneyi güncellemek için kullanılır."
-argument-hint: "[package[@version]] [--major]  -  no package opens a picker over the outdated candidates; --major allows a breaking bump"
-parameters: [{"name":"package","kind":"text"},{"name":"--major","kind":"flag"}]
-gui: form
-destructive: false
-confirm: none
----
-
-# multi-agent deps  -  bump one dependency and fix what it broke
-
-> **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.
-
-**Input**: $ARGUMENTS
-
-> **Language (read FIRST)**: read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` renders `question`, option `label`s and `description`s in `outputLanguage`; only `header` stays English (<=12-char chip). Commit messages and branch names stay English. Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
-
-The normal pipeline with a fixed task. Read `$HOME/.claude/multi-agent-refs/features/dep-bump.md` first: it is the contract for every step below (run shape, scope rule, rollback). `dep-bump.mjs` does every deterministic step; never edit a version string or a lockfile by hand.
-
-## Steps
-
-1. **Repo and settings.** Resolve the repo as `/multi-agent` does for a free-text task (`_account-picker.md`, `_repo-picker.md`). Then:
-   ```bash
-   node "$HOME/.claude/scripts/dep-bump.mjs" config            # depBump.maxFixRounds, depBump.queryRegistry
-   node "$HOME/.claude/scripts/dep-bump.mjs" detect --dir "$REPO"
-   ```
-   No ecosystem detected: say so and stop.
-
-2. **Candidates.**
-   ```bash
-   node "$HOME/.claude/scripts/dep-bump.mjs" list --dir "$REPO" [--registry]   # --registry when queryRegistry is true
-   ```
-   Show `registry.note` and every per-package `note`: an offline listing is reported as offline, never as "nothing outdated".
-   - `package@version` given: use it. `package` alone: its `latestInMajor`, else `latest`. Not in the list: stop with the manifests that were read.
-   - No package: a single-select picker over the candidates with a newer version, non-breaking first, each option `name current -> target (risk)`. Two or more options per the picker contract; one candidate is confirmed with a yes/no, none means report "nothing newer found" with the registry note.
-
-3. **Major gate.** Risk `major` or `unknown`, or a prerelease target (`prerelease: true`), needs `--major` in the input or an explicit confirmation naming the versions (`Bump anyway` / `Take {latestInMajor} instead` when one exists / `Cancel`). An autopilot run without `--major` takes `latestInMajor` or stops.
-
-4. **Run the pipeline** with `state.mode = "deps"`, `state.taskType = "chore"`, the free-text task `chore(deps): bump {name} from {current} to {target}` and the branch `chore/deps-{name}-{target}` (kebab rules from Phase 0 Step 4). Phase 0 intake, worktree and tracker run as in `/multi-agent`. Then:
-   - **Phase 1**: the fixed plan from the feature doc, with the changelog excerpt as evidence:
-     ```bash
-     node "$HOME/.claude/scripts/dep-bump.mjs" notes --dir "$WORKTREE" --ecosystem E --name N --from A --to B
-     ```
-   - **Phase 2**: apply first, then the exit gate as written:
-     ```bash
-     node "$HOME/.claude/scripts/dep-bump.mjs" apply --dir "$WORKTREE" --ecosystem E --name N --to B [--allow-major]
-     ```
-     Exit 1: report `error` and `lock.output` (or `dirty`: the worktree had uncommitted changes), stop with nothing to commit. Persist the output to `state.depBump`. Green: no dev agent, on to Phase 3. Red: fix rounds, at most `depBump.maxFixRounds`, each dispatched with the failing log tail, `surface` output, the changelog excerpt and the scope rule (feature doc section 4); after each round:
-     ```bash
-     node "$HOME/.claude/scripts/dep-bump.mjs" scope --dir "$WORKTREE" --log "$GATE_LOG"   # the round's build/test log
-     ```
-     Only the surface recorded by `apply` is in scope. A file listed in `newImporters` with `cited: null` started importing the dependency without an error line behind it: revert it before the next round.
-   - **Cap reached and still red** (or still out of scope): `dep-bump.mjs rollback --dir "$WORKTREE"` (restores the manifest, lockfile and fix files; anything under `kept` is reported, not discarded), set `state.depBump.rolledBack = true`, and end with the report from feature doc section 5. No commit, no push, no PR.
-   - **Phase 3**: standard review. Each `outOfScope` file without a cited error line, and each `newImporters` entry with `cited: null`, is a blocking finding.
-   - **Phase 4**: commit with `commitMessage` from `apply` (plus ` [{jiraId}]` when present). PR body per the feature doc; `Ref:` or `Related:`, never `Closes`, `Fixes` or `Resolves`, and never close an issue.
-   - **Phase 5**: channels as in every mode.
-
-## Report
-
-In `outputLanguage`, at most 10 lines: the dependency, from and to, risk, lockfile command and result, rounds taken against the cap, files changed (in scope / justified), review verdict, and the PR URL or the rollback reason.

package/pipeline/multi-agent-refs/features/dep-bump.md

@@ -1,176 +0,0 @@
-# Feature: Dependency Bump and Fix
-
-<!-- toc -->
-- [1. Shape of a run](#1-shape-of-a-run)
-- [2. The script](#2-the-script)
-- [3. What each phase does](#3-what-each-phase-does)
-- [4. Scope of a fix round](#4-scope-of-a-fix-round)
-- [5. Rollback](#5-rollback)
-- [6. Settings](#6-settings)
-- [7. Never](#7-never)
-<!-- /toc -->
-
-**Pattern**: bump one dependency, build and test, and when the bump breaks
-something, fix only that breakage. A bump PR that also refactors, reformats or
-"while I was here" fixes unrelated code cannot be reviewed as a bump, and a fix
-loop with no cap turns a version bump into an open-ended rewrite.
-
-Entry: `/multi-agent:deps [package[@version]] [--major]`. It is the normal
-pipeline with a fixed task, not a second flow: same Phase 0 intake, worktree,
-branch rules, Phase 2 dev agent and exit gate, Phase 3 review gates, Phase 4
-commit and PR rules, Phase 5 channels.
-
-## 1. Shape of a run
-
-| Field | Value |
-|---|---|
-| `state.mode` | `"deps"` |
-| `state.taskType` | `chore` |
-| Branch | `chore/deps-{kebab(name)}-{kebab(to)}`, kebab and collision rules from Phase 0 Step 4 |
-| Commit | `chore(deps): bump {name} from {from} to {to}`, taken verbatim from `dep-bump.mjs apply` (`commitMessage`), plus ` [{jiraId}]` when the run carries one |
-| PR body | the bump, its risk, the lockfile command, `alsoMoves`, the changelog excerpt, each fix and the error line it answers; `Ref:` / `Related:`, never `Closes` / `Fixes` / `Resolves` |
-| `state.depBump` | the apply output plus `rounds`, `scope` and, on rollback, `rolledBack` and `stillFailing` |
-
-## 2. The script
-
-`$HOME/.claude/scripts/dep-bump.mjs` owns every deterministic step; the model
-never edits a version string by hand. JSON on stdout.
-
-| Command | Does |
-|---|---|
-| `detect --dir D` | Ecosystems and manifests: SwiftPM `Package.swift`, Gradle `gradle/*.versions.toml`, npm `package.json`, pip `requirements*.txt` / `pyproject.toml`, each with its lockfile |
-| `list --dir D [--registry]` | Candidates: `current` (lockfile, else declared), `latest`, `latestInMajor` (highest non-breaking), `risk`, `riskInMajor`, `source` |
-| `apply --dir D --ecosystem E --name N --to V [--allow-major]` | One bump: manifest edit plus the lockfile through the ecosystem tool; writes `.pipeline/dep-bump.json` |
-| `surface --dir D --ecosystem E --name N` | Files that import or reference the dependency |
-| `scope --dir D [--log L]` | Files changed since the recorded base, split into `inScope` (manifest, lockfile and the surface recorded at apply), `newImporters` and `outOfScope`; exit 1 when anything is out of scope or a new importer has no cited error line |
-| `notes --dir D --ecosystem E --name N --from A --to B` | The local changelog sections between the two versions, else the repository URL to read release notes from |
-| `rollback --dir D` | Restores what the bump owns (manifest, lockfile, the files `scope` saw the fix touch in scope) from the recorded base and removes those the base lacks; every other change is left in place and listed under `kept` |
-| `config` | The resolved `depBump.*` settings |
-
-SwiftPM identities compare case-insensitively (`--name Alamofire` and
-`alamofire` are one package). The surface covers every module name the package
-is imported under: the identity, the repository name in the url, the products
-named by `.product(name:package:)` and by-name target dependencies in the
-package manifests. Packages an Xcode project adds through File > Packages keep
-their pins in `*.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved`
-or `*.xcworkspace/xcshareddata/swiftpm/Package.resolved` and their requirement
-in `project.pbxproj`. `detect` and `list` report them with `readOnly: true` and
-a note; `apply` refuses them (exit 1), because dep-bump does not edit
-`project.pbxproj`. Such a bump is made in Xcode.
-
-For Gradle the surface is the build scripts that name the catalog alias and
-the Kotlin and Java files whose imports start at the Maven group
-(`com.google.code.gson`), the artifact id or the alias stem, each with an
-optional major suffix (`okhttp3` for `com.squareup.okhttp3:okhttp`, `retrofit2`
-for `retrofit`). A library whose package root is none of these (Gson's
-`com.google.gson`) is not found by `surface`, so a fix in such a file is out of
-scope and needs the error line that names it, cited per file (section 4).
-
-Offline listing reads what is already on disk: the lockfile for the current
-version, SwiftPM `.build/checkouts/<id>` tags and the Gradle module cache for
-newer ones. `--registry` asks the ecosystem's own tool (`npm view`,
-`git ls-remote --tags`, Maven or PyPI metadata over `curl`); a failed query is
-a `note` on that package, never a failed listing. Registry and lockfile tools
-run in the manifest's directory (a workspace member's lockfile tool in the
-workspace root), so the repo's own `.npmrc` registries and scopes apply. A
-name or url that does not fit its ecosystem's grammar (a url that is not
-http(s), ssh, git, file or `git@host:`, a name starting with `-`) is never
-passed to a tool; the package gets a `registry query skipped` note.
-
-Risk follows semver: a major step is breaking, and so is a minor step under
-`0.x` and any step under `0.0.x`. `+build` metadata is ignored, and for Gradle
-a Maven release qualifier (`-jre`, `-android`, `.Final`, `-RELEASE`, `.GA`,
-`.SP1`) is part of a stable version, not a prerelease. A version that does not
-parse is `unknown` and is treated as major, and so is a prerelease target.
-`apply` exits 3 on a major, unknown or prerelease bump without `--allow-major`,
-and touches nothing.
-
-A pip requirement with several clauses (`foo>=1.0,<2.0`) is bumped on its
-primary clause, the first `==`, `===`, `~=`, `>=` or `>`; `<`, `<=` and `!=`
-are never primary, and a requirement made only of them is not listed. When
-another clause would exclude the target (`<2.0` against `2.1`), `apply` exits 1
-and changes nothing: rewriting a bound the repo set is a decision, not part of
-the bump.
-
-`apply` refuses a worktree with uncommitted changes to tracked files (exit 1,
-`dirty` lists them), so the base it records holds no work of anyone else's.
-
-`apply` is atomic. When the lockfile tool fails, the manifest and the lockfile
-are restored byte for byte and the tool's output tail is in `lock.output`.
-Lockfile tools: `swift package resolve`, `./gradlew dependencies --write-locks`
-(only with a `gradle.lockfile`), the resolved npm-family manager with scripts
-disabled (`package-manager.mjs`; yarn 2 and later take `--mode=skip-build`, yarn
-1 `--ignore-scripts`), `poetry lock` on Poetry 2 and `poetry lock --no-update`
-before it, `uv lock --upgrade-package`. A workspace member's lockfile is the
-workspace root's (the nearest directory above it with a lockfile and a
-`workspaces` field or `pnpm-workspace.yaml`), and the tool runs there; a
-lockfile above the manifest in a directory that declares no workspaces fails
-the bump rather than letting it go ahead with no lockfile. Membership is not
-matched against the `workspaces` globs. A shared Gradle `version.ref` moves every module bound to
-it; `alsoMoves` names them and they join the surface.
-
-## 3. What each phase does
-
-| Phase | In a deps run |
-|---|---|
-| 0 Init | Candidate pick and the major gate happen in the command before Phase 0. Then the normal intake (account, repo, base branch, workspace) with the free-text task `chore(deps): bump {name} from {from} to {to}`, `taskType` `chore`, branch from section 1 |
-| 1 Plan | No analysis document (`chore`). The plan is fixed: one todo, "apply the bump", plus one per failing area once Phase 2 has a red run. `notes` output and the `list` record are the plan's evidence. The approval gate shows the bump, its risk and `alsoMoves` |
-| 2 Dev | `apply` in the worktree first, before any agent runs. Then the Phase 2 exit gate as written (build, lint, tests, evidence gates). Green: straight to Phase 3 with no dev agent. Red: fix rounds (section 4) |
-| 3 Review | The standard gates and reviewers over the whole diff. `scope` runs first; every `outOfScope` file is a blocking finding unless the round's report ties it to a build or test error line |
-| 4 Commit | `commitMessage` from `apply`, the PR body from section 1. Never auto-close an issue |
-| 5 Report | Channels as in every mode |
-
-## 4. Scope of a fix round
-
-A round is one Phase 2 dev dispatch, given exactly this:
-
-- the failing build or test log tail, from the exit gate;
-- `surface` output: the files that use the dependency;
-- the `notes` excerpt (breaking changes, migration notes). With no local
-  changelog, read the release notes for the versions in between from the
-  repository URL it returns (`gh release view`, the releases page) when
-  reachable, and say when they were not;
-- the rule: change only what the bump broke. A file outside the surface may be
-  touched only when a compile or test error names it, and the report cites that
-  error line per file.
-
-The surface is the one `apply` recorded. A file that starts importing the
-dependency during a fix round does not join it: `scope` reports it under
-`newImporters`, and each one passes only when the build or test log handed to
-`scope --log` has an error line naming that file. The line is returned as
-`cited`; a new importer with `cited: null` fails scope like an out-of-scope
-file.
-
-After each round: `scope --log <exit-gate log>`, then the exit gate again. Out-of-scope files with no
-cited error are reverted before the next round. Green ends the loop. Every round
-is recorded in `state.depBump.rounds[]` with the files it touched and the
-errors it answered.
-
-## 5. Rollback
-
-A run still red after `depBump.maxFixRounds` rounds (default 2), or out of
-scope after its last round, is not committed: `dep-bump.mjs rollback` returns
-the manifest, the lockfile and the files the fix rounds touched to the recorded
-base, removes the ones the base did not have, and leaves every other change in
-place (`kept`); the run ends with a report instead of a PR. The report names the bump, each round, the errors still failing with their
-log lines, the files that would need to change and the changelog section that
-explains it. `state.depBump.rolledBack` is `true`. The branch is left with no
-commit; nothing is pushed.
-
-## 6. Settings
-
-| Key | Default | Effect |
-|---|---|---|
-| `depBump.maxFixRounds` | 2 | Fix rounds before rollback; 0 rolls back any bump that is not green as-is |
-| `depBump.queryRegistry` | true | `list` gets `--registry`; false lists offline only |
-
-Read through `node "$HOME/.claude/scripts/dep-bump.mjs" config`. Asserted by
-`test/dep-bump.test.mjs` and `smoke-dep-bump.sh`.
-
-## 7. Never
-
-- A major, unparseable or prerelease bump without `--major` or an explicit confirmation.
-- A version edit by hand, or a lockfile edited as text.
-- More than one dependency per run (a shared `version.ref` is one bump).
-- A fix outside the bump's surface with no error line behind it.
-- A commit after the round cap is reached red.