@mmerterden/multi-agent-pipeline 13.5.0 → 14.0.0

package/pipeline/schemas/reviewer-output.schema.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/reviewer-output.schema.json",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "title": "Multi-Agent Pipeline  -  Phase 4 reviewer output",
-  "description": "Contract for a single code-reviewer subagent's JSON output in Phase 4 Step 2. Reviewer set is CLI-aware: Claude Code dispatches 2 parallel reviewers (Fable, Sonnet); Copilot CLI dispatches 3 (Opus, GPT-5.4, Sonnet); Codex CLI dispatches 3 (gpt-5.6 at xhigh, gpt-5.4, gpt-5.6 at medium). Every reviewer must return an object matching this shape before Opus triage merges them.",
+  "description": "Contract for a single code-reviewer subagent's JSON output in Phase 4 Step 2. Reviewer set is CLI-aware: Claude Code dispatches 2 parallel reviewers (Fable, Sonnet); Copilot CLI dispatches 3 (Opus, GPT-5.4, Sonnet); Codex CLI dispatches 3 (gpt-5.6 at xhigh, gpt-5.4, gpt-5.6 at medium). Every reviewer must return an object matching this shape before Opus triage merges them. v1.1.0 adds the rule-ID conformance checklist: when the orchestrator supplies a ${CRITERIA} block (Phase 4 Step 1.78), the reviewer must return one conformance row per selected rule ID. Findings alone cannot answer 'was this applied completely' - a reviewer that opened nothing returns the same empty findings array as one that checked everything.",
   "type": "object",
   "additionalProperties": false,
   "required": ["findings", "approved"],
@@ -11,7 +11,9 @@
     "findings": {
       "type": "array",
       "description": "Raw findings. May be empty. Duplicates and out-of-scope items are acceptable  -  Opus triage will deduplicate and filter.",
-      "items": { "$ref": "#/$defs/finding" }
+      "items": {
+        "$ref": "#/$defs/finding"
+      }
     },
     "approved": {
       "type": "boolean",
@@ -20,6 +22,39 @@
     "reviewer": {
       "type": "string",
       "description": "Model label for this output (e.g. 'fable', 'opus', 'sonnet', 'gpt'). Present once the parallel reviewer outputs are merged into the Phase 4 array so triage/consensus can attribute each finding to its source. Optional on a single reviewer's raw pre-merge output."
+    },
+    "conformance": {
+      "type": "array",
+      "description": "One row per rule ID in the supplied ${CRITERIA} block, and none outside it. Required whenever a ${CRITERIA} block was supplied; omitted entirely when it was not. This is the denominator that makes completeness checkable: the set is fixed on disk before the reviewer runs, so it cannot be narrowed after seeing the diff.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["ruleId", "verdict"],
+        "properties": {
+          "ruleId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Must appear in the supplied criteria list."
+          },
+          "verdict": {
+            "type": "string",
+            "enum": ["conformant", "violated", "not-applicable"],
+            "description": "conformant = checked and honoured, requires file+line evidence. violated = checked and breached, requires a matching findings[] entry with the same ruleId. not-applicable = cannot bind here, requires a reason. There is deliberately no 'unchecked' value: an ID neither checked nor waived fails the stage rather than passing quietly."
+          },
+          "file": {
+            "type": "string",
+            "description": "Where the rule was checked. Required for conformant: a verdict with no evidence certifies completeness nobody established."
+          },
+          "line": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "reason": {
+            "type": "string",
+            "description": "Why the rule does not apply. Required for not-applicable."
+          }
+        }
+      }
     }
   },
   "$defs": {
@@ -52,6 +87,16 @@
           "type": "string",
           "minLength": 4,
           "description": "Concrete remediation. Not 'refactor this'  -  actionable guidance."
+        },
+        "ruleId": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Stable ID of the cited rule, e.g. SEC-01. Present when the finding comes from a rule in the ${CRITERIA} block, omitted otherwise. A cited ID carries evidence a reviewer opinion does not: the author can look it up and disagree with the rule rather than with the reviewer. Must be an ID from the supplied block - inventing one is a validator failure."
+        },
+        "criteriaSource": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Which criteria source the rule came from: a registry name, a module-guide path, or 'exception-marker-audit'. Lets Phase 7 attribute findings to the standard that produced them."
         }
       }
     }

package/pipeline/schemas/token-budget.json

@@ -3,15 +3,39 @@
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/token-budget.json",
   "description": "Per-phase token budget for lazy-loaded pipeline docs. Enforced by smoke-token-budget.sh.",
   "phases": {
-    "phase-0-init": { "max_tokens": 12400, "warn_tokens": 10900 },
-    "phase-1-analysis": { "max_tokens": 3750, "warn_tokens": 3300 },
-    "phase-2-planning": { "max_tokens": 6500, "warn_tokens": 5750 },
-    "phase-3-dev": { "max_tokens": 7900, "warn_tokens": 6950 },
-    "phase-4-review": { "max_tokens": 13250, "warn_tokens": 11650 },
-    "phase-5-test": { "max_tokens": 2550, "warn_tokens": 2250 },
-    "phase-6-commit": { "max_tokens": 6150, "warn_tokens": 5400 },
-    "phase-7-report": { "max_tokens": 5600, "warn_tokens": 4950 }
+    "phase-0-init": {
+      "max_tokens": 12400,
+      "warn_tokens": 11900
+    },
+    "phase-1-analysis": {
+      "max_tokens": 4600,
+      "warn_tokens": 4050
+    },
+    "phase-2-planning": {
+      "max_tokens": 6500,
+      "warn_tokens": 5650
+    },
+    "phase-3-dev": {
+      "max_tokens": 8950,
+      "warn_tokens": 7900
+    },
+    "phase-4-review": {
+      "max_tokens": 14750,
+      "warn_tokens": 12950
+    },
+    "phase-5-test": {
+      "max_tokens": 2900,
+      "warn_tokens": 2550
+    },
+    "phase-6-commit": {
+      "max_tokens": 6150,
+      "warn_tokens": 5450
+    },
+    "phase-7-report": {
+      "max_tokens": 6350,
+      "warn_tokens": 5600
+    }
   },
-  "total_max_tokens": 51000,
-  "note": "Token estimate = ceil(chars / 4). Per-phase budget rule: warn = current+10% (rounded to nearest 50), max = current+25%. Gives ~6 edit cycles of headroom before warn trips  -  intentionally quiet under normal maintenance, loud when a phase grows unusually. Only the active phase is loaded (lazy). Recalibrated at v10.0.0 after the validator/consistency/simplifier/lesson gate contracts landed in phases 1-4. Recalibrated again at v10.9.0 after the verify-by-test (Phase 4 Step 3.7), update-check (Phase 0 Step 0.6), immutable-test (Phase 3 GREEN) and redTests re-entry contracts landed  -  Step 3.7 prose was compressed to a pointer into refs/features/verify-by-test.md before the recalibration. Total bumped 50000 -> 51000 at v12.5.0 after the worktree residue/traversal-prune contract (Phase 0 + Phase 5 heal) and the Reflexion causal-diagnosis contract (Phase 4 lesson memory) landed; the prose was compressed first (161 tokens reclaimed) and every per-phase max still passes  -  only the aggregate needed room."
+  "total_max_tokens": 52200,
+  "note": "Token estimate = ceil(chars / 4). Per-phase budget rule: warn = current+10% (rounded to nearest 50), max = current+25%. Gives ~6 edit cycles of headroom before warn trips  -  intentionally quiet under normal maintenance, loud when a phase grows unusually. Only the active phase is loaded (lazy). Recalibrated at v10.0.0 after the validator/consistency/simplifier/lesson gate contracts landed in phases 1-4. Recalibrated again at v10.9.0 after the verify-by-test (Phase 4 Step 3.7), update-check (Phase 0 Step 0.6), immutable-test (Phase 3 GREEN) and redTests re-entry contracts landed  -  Step 3.7 prose was compressed to a pointer into refs/features/verify-by-test.md before the recalibration. Total bumped 50000 -> 51000 at v12.5.0 after the worktree residue/traversal-prune contract (Phase 0 + Phase 5 heal) and the Reflexion causal-diagnosis contract (Phase 4 lesson memory) landed; the prose was compressed first (161 tokens reclaimed) and every per-phase max still passes  -  only the aggregate needed room. Recalibrated again at v13.6.0 after the install-relative path correction: an instruction that names `pipeline/scripts/x` resolves only from a repo checkout, and a run happens in the user's worktree, so 157 references across these docs moved to `$HOME/.claude/...` at +5 bytes each  -  196 tokens of pure correctness cost. Same discipline as before: prose was compressed FIRST (149 tokens reclaimed, by pointing Phase 1's Figma tier table at the Phase 0 probe that already resolved it and Phase 4's Codex constraints at the always-loaded AGENTS.md block), and only then were the budgets moved. Five warn lines had been permanently amber, which makes the amber tier useless as a signal, so every warn was reset to the documented current+10% and the four maxes that the new warn would have collided with were reset to current+25%. Aggregate 51000 -> 51500. Total bumped 51500 -> 52200 at v14.0.0 after Phase 4 Review entered the four --dev mode phase sets and the criteria-resolution contract (Step 1.78) landed. Same discipline as every prior bump: prose was compressed FIRST, 820 tokens reclaimed, before the number moved. Two of those compressions are structural rather than cosmetic - the hardcoded SwiftUI interaction list in Step 1.5 and the SwiftUI convention paragraph in Step 2.8 were transcriptions of rules that now live in a scoped registry, so keeping them here would have re-created the drift this release exists to remove, and the third moved the Step 1.78 full contract into refs/features/skill-conformance.md leaving a pointer. What remains is contract text that cannot be inferred: the manifest's four consumer-visible parts, the conformance checklist the reviewers must return, and the fail-closed semantics. Every per-phase max still passes (phase-4 12405/14750); only the aggregate needed room."
 }

package/pipeline/schemas/triage-output.schema.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/triage-output.schema.json",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "title": "Multi-Agent Pipeline  -  Phase 4 triage output",
-  "description": "Contract for the Opus triage agent's JSON output in Phase 4 Step 3. Triage consumes merged reviewer findings and splits them into accepted/deferred/rejected. Only `accepted` blocking/important items trigger Phase 3 rework. v3.1.0 adds the optional `consensus` block so triage can surface reviewer-agreement risk (false consensus among same-base-model reviewers) instead of silently merging. v3.2.0 adds the optional per-finding `verification` block written by Phase 4 Step 3.7 (verify-by-test): the empirical repro-test outcome for accepted blocking findings.",
+  "description": "Contract for the Opus triage agent's JSON output in Phase 4 Step 3. Triage consumes merged reviewer findings and splits them into accepted/deferred/rejected. Only `accepted` blocking/important items trigger Phase 3 rework. v3.1.0 adds the optional `consensus` block so triage can surface reviewer-agreement risk (false consensus among same-base-model reviewers) instead of silently merging. v3.2.0 adds the optional per-finding `verification` block written by Phase 4 Step 3.7 (verify-by-test): the empirical repro-test outcome for accepted blocking findings. v3.3.0 carries ruleId + criteriaSource through triage so a finding that cites a stable rule ID keeps that citation into Phase 6 and Phase 7, and the lesson loop can key durable learnings by rule.",
   "type": "object",
   "additionalProperties": false,
   "required": ["accepted", "deferred", "rejected", "approved"],
@@ -11,7 +11,9 @@
     "accepted": {
       "type": "array",
       "description": "Findings that are real, in-scope, and must be actioned in this iteration.",
-      "items": { "$ref": "#/$defs/acceptedFinding" }
+      "items": {
+        "$ref": "#/$defs/acceptedFinding"
+      }
     },
     "deferred": {
       "type": "array",
@@ -21,7 +23,9 @@
         "additionalProperties": false,
         "required": ["finding", "reason"],
         "properties": {
-          "finding": { "$ref": "#/$defs/rawFinding" },
+          "finding": {
+            "$ref": "#/$defs/rawFinding"
+          },
           "reason": {
             "type": "string",
             "minLength": 4,
@@ -38,7 +42,9 @@
         "additionalProperties": false,
         "required": ["finding", "reason"],
         "properties": {
-          "finding": { "$ref": "#/$defs/rawFinding" },
+          "finding": {
+            "$ref": "#/$defs/rawFinding"
+          },
           "reason": {
             "type": "string",
             "minLength": 4,
@@ -51,21 +57,31 @@
       "type": "boolean",
       "description": "True if no accepted BLOCKING items remain. The pipeline uses this to gate Phase 5 / Phase 6 entry."
     },
-    "consensus": { "$ref": "#/$defs/consensus" }
+    "consensus": {
+      "$ref": "#/$defs/consensus"
+    }
   },
   "if": {
     "properties": {
       "accepted": {
         "contains": {
           "type": "object",
-          "properties": { "severity": { "const": "blocking" } },
+          "properties": {
+            "severity": {
+              "const": "blocking"
+            }
+          },
           "required": ["severity"]
         }
       }
     }
   },
   "then": {
-    "properties": { "approved": { "const": false } }
+    "properties": {
+      "approved": {
+        "const": false
+      }
+    }
   },
   "$defs": {
     "severity": {
@@ -101,9 +117,18 @@
             "additionalProperties": false,
             "required": ["file", "issue", "note"],
             "properties": {
-              "file": { "type": "string", "minLength": 1 },
-              "line": { "type": "integer", "minimum": 0 },
-              "issue": { "type": "string", "minLength": 4 },
+              "file": {
+                "type": "string",
+                "minLength": 1
+              },
+              "line": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "issue": {
+                "type": "string",
+                "minLength": 4
+              },
               "note": {
                 "type": "string",
                 "minLength": 4,
@@ -134,10 +159,16 @@
           "minLength": 1,
           "description": "Path to the test-run log verified by evidence-gate.mjs, e.g. '.pipeline/verify-1.test.log'."
         },
-        "note": { "type": "string" }
+        "note": {
+          "type": "string"
+        }
       },
       "if": {
-        "properties": { "result": { "enum": ["confirmed", "not-reproduced"] } }
+        "properties": {
+          "result": {
+            "enum": ["confirmed", "not-reproduced"]
+          }
+        }
       },
       "then": {
         "required": ["result", "testRef", "evidencePath"]
@@ -148,34 +179,88 @@
       "additionalProperties": false,
       "required": ["severity", "file", "line", "issue"],
       "properties": {
-        "severity": { "$ref": "#/$defs/severity" },
-        "file": { "type": "string", "minLength": 1 },
-        "line": { "type": "integer", "minimum": 0 },
-        "issue": { "type": "string", "minLength": 4 },
-        "fix": { "type": "string" },
-        "reviewer": { "$ref": "#/$defs/reviewer" },
-        "verification": { "$ref": "#/$defs/verification" }
+        "severity": {
+          "$ref": "#/$defs/severity"
+        },
+        "file": {
+          "type": "string",
+          "minLength": 1
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "issue": {
+          "type": "string",
+          "minLength": 4
+        },
+        "fix": {
+          "type": "string"
+        },
+        "reviewer": {
+          "$ref": "#/$defs/reviewer"
+        },
+        "verification": {
+          "$ref": "#/$defs/verification"
+        },
+        "ruleId": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Stable ID of the cited rule (e.g. SEC-01), preserved from the reviewer output. A finding citing a registry rule carries evidence an opinion does not, so triage must not reject it as a matter of taste  -  it can still be deferred or rejected as out of scope for THIS task."
+        },
+        "criteriaSource": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Which criteria source produced the rule: a registry name, a module-guide path, or a deterministic gate such as 'exception-marker-audit'."
+        }
       }
     },
     "acceptedFinding": {
       "allOf": [
-        { "$ref": "#/$defs/rawFinding" },
+        {
+          "$ref": "#/$defs/rawFinding"
+        },
         {
           "type": "object",
           "additionalProperties": false,
           "required": ["severity", "file", "line", "issue", "reviewer", "fix"],
           "properties": {
-            "severity": { "$ref": "#/$defs/severity" },
-            "file": { "type": "string", "minLength": 1 },
-            "line": { "type": "integer", "minimum": 0 },
-            "issue": { "type": "string", "minLength": 4 },
-            "reviewer": { "$ref": "#/$defs/reviewer" },
+            "severity": {
+              "$ref": "#/$defs/severity"
+            },
+            "file": {
+              "type": "string",
+              "minLength": 1
+            },
+            "line": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "issue": {
+              "type": "string",
+              "minLength": 4
+            },
+            "reviewer": {
+              "$ref": "#/$defs/reviewer"
+            },
             "fix": {
               "type": "string",
               "minLength": 4,
               "description": "Concrete change the dev agent must make. Required for accepted items so Phase 3 re-entry has actionable direction."
             },
-            "verification": { "$ref": "#/$defs/verification" }
+            "verification": {
+              "$ref": "#/$defs/verification"
+            },
+            "ruleId": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Stable ID of the cited rule (e.g. SEC-01), preserved from the reviewer output. A finding citing a registry rule carries evidence an opinion does not, so triage must not reject it as a matter of taste  -  it can still be deferred or rejected as out of scope for THIS task."
+            },
+            "criteriaSource": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Which criteria source produced the rule: a registry name, a module-guide path, or a deterministic gate such as 'exception-marker-audit'."
+            }
           }
         }
       ]

package/pipeline/scripts/cost-table.json

@@ -1,5 +1,5 @@
 {
-  "_readme": "Per-model unit prices in USD per million tokens. Source: Anthropic public pricing (verified 2026-04-21). Update when Anthropic publishes new tiers. Unknown models render USD as ' - ' and emit a footnote  -  never block PR-body generation. cacheReadPerMtok is the discounted rate for prompt-cache hits (~10% of inPerMtok); the renderer prices a phase's tokens_cached at this rate when the tracker records it, so resume/cache reuse is visible in the ledger.",
+  "_readme": "Per-model unit prices in USD per million tokens. Source: Anthropic public pricing (Claude-family rows verified 2026-07-28 against the current model table; the gpt-* rows remain approximate). Update when Anthropic publishes new tiers. Rung names (fable / opus / sonnet / haiku) are the pipeline's stable identifiers and `modelId` is the wire value they currently resolve to - dispatch reads the rung, so a generation move is a `modelId` edit here plus the phase specs, never a rename of the rungs. Unknown models render USD as ' - ' and emit a footnote  -  never block PR-body generation. cacheReadPerMtok is the discounted rate for prompt-cache hits (~10% of inPerMtok); the renderer prices a phase's tokens_cached at this rate when the tracker records it, so resume/cache reuse is visible in the ledger.",
   "schemaVersion": "1.1.0",
   "prices": {
     "fable": {
@@ -13,19 +13,22 @@
       "inPerMtok": 5.0,
       "outPerMtok": 25.0,
       "cacheReadPerMtok": 0.5,
-      "modelId": "claude-opus-4-8"
+      "modelId": "claude-opus-5",
+      "note": "Second tier - dev phase on --dev modes, Reviewer 1 and triage on Copilot CLI, and the opus rung of the fable -> opus -> sonnet fallback ladder. Same rate as the Opus 4.8 it replaces, so the ledger needed no reprice on the generation move. Claude Opus 5 draws on a rate-limit pool SEPARATE from the combined Opus 4.x pool - moving traffic here neither frees headroom on the old bucket nor inherits it."
     },
     "sonnet": {
       "inPerMtok": 3.0,
       "outPerMtok": 15.0,
       "cacheReadPerMtok": 0.3,
-      "modelId": "claude-sonnet-4-6"
+      "modelId": "claude-sonnet-5",
+      "note": "Floor tier for Claude-family dispatch - Reviewer 3 on both hosts, and the terminal rung of the fallback ladder. Priced at the standard 3/15 rather than the 2/10 introductory rate that runs through 2026-08-31: over-reporting during the intro window is the safe direction for a cost ledger, and it needs no dated edit when the intro ends."
     },
     "haiku": {
       "inPerMtok": 1.0,
       "outPerMtok": 5.0,
       "cacheReadPerMtok": 0.1,
-      "modelId": "claude-haiku-4-5-20251001"
+      "modelId": "claude-haiku-4-5",
+      "note": "Speed tier - task-clarifier and other latency-sensitive dispatches, plus the terminal rung of the fallback ladder. Named by its alias like every other rung here rather than by a dated snapshot, so the four rungs stay comparable at a glance."
     },
     "gpt-5.4": {
       "inPerMtok": 10.0,

package/pipeline/scripts/gc-worktrees.sh

@@ -16,7 +16,7 @@
 #      .git/info/exclude so the gitlink class cannot re-occur.
 #
 # Registered, healthy worktrees are NEVER touched - finishing or killing a
-# task is /multi-agent:finish / /multi-agent:kill territory.
+# task is /multi-agent:ship / /multi-agent:kill territory.
 #
 # SAFE BY DEFAULT: dry-run. Deletes nothing until you pass --yes.
 #

package/pipeline/scripts/gen-mode-dispatch.mjs

@@ -10,10 +10,10 @@
  * call, anti-pattern warning, and ref link are identical.
  *
  * Usage:
- *   node pipeline/scripts/gen-mode-dispatch.mjs --mode=dev          # 0/3/5/6/7 (Phase 5 User Test runs only in dev + full; autopilot/local variants drop it)
+ *   node pipeline/scripts/gen-mode-dispatch.mjs --mode=dev          # 0/3/4/5/6/7 (Phase 5 User Test runs only in dev + full; autopilot/local variants drop it)
  *   node pipeline/scripts/gen-mode-dispatch.mjs --mode=full         # 0..7
  *   node pipeline/scripts/gen-mode-dispatch.mjs --mode=full-local   # 0..7
- *   node pipeline/scripts/gen-mode-dispatch.mjs --mode=dev-local    # 0/3/6/7 + local-mode caveat
+ *   node pipeline/scripts/gen-mode-dispatch.mjs --mode=dev-local    # 0/3/4/6/7 + local-mode caveat
  *
  * Companion smoke `smoke-mode-dispatch-drift.sh` regenerates the section for
  * each mode file, diffs against the on-disk content, and fails on drift.
@@ -54,22 +54,22 @@ const PHASE_NAMES_NO_TEST = PHASE_NAMES.filter((p) => p !== "5:Test");
  */
 const MODES = {
   dev: {
-    phases: ["0:Init", "3:Dev", "5:Test", "6:Commit", "7:Report"],
+    phases: ["0:Init", "3:Dev", "4:Review", "5:Test", "6:Commit", "7:Report"],
     local: false,
     autopilot: false,
   },
   "dev-autopilot": {
-    phases: ["0:Init", "3:Dev", "6:Commit", "7:Report"],
+    phases: ["0:Init", "3:Dev", "4:Review", "6:Commit", "7:Report"],
     local: false,
     autopilot: true,
   },
   "dev-local": {
-    phases: ["0:Init", "3:Dev", "6:Commit", "7:Report"],
+    phases: ["0:Init", "3:Dev", "4:Review", "6:Commit", "7:Report"],
     local: true,
     autopilot: false,
   },
   "dev-local-autopilot": {
-    phases: ["0:Init", "3:Dev", "6:Commit", "7:Report"],
+    phases: ["0:Init", "3:Dev", "4:Review", "6:Commit", "7:Report"],
     local: true,
     autopilot: true,
   },

package/pipeline/scripts/match-skills.mjs

@@ -29,12 +29,42 @@
 //
 // Exit 0 on success; 1 on setup error.
 
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const here = dirname(fileURLToPath(import.meta.url));
-const repoRoot = resolve(here, "..", "..");
+
+/**
+ * Candidate index locations, in the order they are tried.
+ *
+ * This script lives in two shapes: `<repo>/pipeline/scripts/` in a checkout, and
+ * `~/.claude/scripts/` (or `~/.copilot`, `~/.codex`) once installed. The default
+ * used to be `resolve(here, "..", "..") + "/pipeline/skills/.skills-index.json"`,
+ * which is right in a checkout and resolves to `$HOME/pipeline/skills/...` from an
+ * installed tree - a path that has never existed. So dynamic skill loading exited 1
+ * on every real install while passing its own smoke, which runs from the repo.
+ *
+ * Installed layout is tried first: that is where a user's run happens.
+ */
+function defaultIndexCandidates() {
+  const installRoot = resolve(here, ".."); // ~/.claude when here is ~/.claude/scripts
+  const repoRoot = resolve(here, "..", ".."); // <repo> when here is <repo>/pipeline/scripts
+  return [
+    join(installRoot, "skills", ".skills-index.json"),
+    join(repoRoot, "pipeline", "skills", ".skills-index.json"),
+  ];
+}
+
+function resolveDefaultIndex() {
+  const candidates = defaultIndexCandidates();
+  for (const c of candidates) {
+    if (existsSync(c)) return c;
+  }
+  // Nothing found: return the first so the error message names a real intent
+  // rather than a path that only makes sense in a checkout.
+  return candidates[0];
+}
 
 const args = process.argv.slice(2);
 if (args.length === 0 || args[0].startsWith("--")) {
@@ -49,7 +79,7 @@ const opts = {
   touchedFiles: [],
   stack: null,
   limit: 12,
-  indexPath: join(repoRoot, "pipeline", "skills", ".skills-index.json"),
+  indexPath: resolveDefaultIndex(),
   json: false,
 };
 for (let i = 1; i < args.length; i++) {
@@ -69,7 +99,10 @@ try {
   index = JSON.parse(readFileSync(opts.indexPath, "utf-8"));
 } catch (e) {
   console.error(`match-skills: cannot read index ${opts.indexPath}: ${e.message}`);
-  console.error("→ run: node pipeline/scripts/build-skills-index.mjs");
+  console.error(`  tried: ${defaultIndexCandidates().join(", ")}`);
+  console.error(
+    "→ from a checkout: node pipeline/scripts/build-skills-index.mjs; from an install: re-run the installer, which ships the index",
+  );
   process.exit(1);
 }
 

package/pipeline/scripts/migrate-prefs.mjs

@@ -18,7 +18,7 @@ const DEFAULT_FILE = path.join(os.homedir(), ".claude", "multi-agent-preferences
 
 // Single source of truth for the migration target version. Referenced by the
 // migrate() bump chain AND every user-facing message, so they cannot drift.
-const TARGET_VERSION = "2.4.0";
+const TARGET_VERSION = "2.5.0";
 
 const USAGE = "Usage: migrate-prefs.mjs [--dry-run] [--file <path>]";
 
@@ -61,6 +61,40 @@ function defaultSettings() {
   };
 }
 
+/**
+ * Versions this migrator accepts as input, read from the schema's own
+ * `schemaVersion` enum so the two lists cannot disagree.
+ *
+ * Resolved against both layouts: `<repo>/pipeline/schemas` in a checkout and
+ * `<install>/schemas` once installed  -  this script is copied into
+ * ~/.claude/scripts, ~/.copilot/scripts and ~/.codex/scripts without any path
+ * rewriting, so a checkout-relative path alone would resolve to nothing there.
+ *
+ * @param {string} target  -  TARGET_VERSION, excluded from the result
+ * @returns {Set<string>}
+ */
+function readMigratableVersions(target) {
+  const here = path.dirname(new URL(import.meta.url).pathname);
+  const candidates = [
+    path.join(here, "..", "schemas", "prefs.schema.json"),
+    path.join(here, "..", "..", "pipeline", "schemas", "prefs.schema.json"),
+  ];
+  for (const c of candidates) {
+    try {
+      const schema = JSON.parse(fs.readFileSync(c, "utf-8"));
+      const versions = schema?.properties?.schemaVersion?.enum;
+      if (Array.isArray(versions) && versions.length > 0) {
+        return new Set(versions.filter((v) => v !== target));
+      }
+    } catch {
+      // try the next candidate
+    }
+  }
+  // Schema unreadable: refusing to migrate would be worse than migrating from a
+  // version this build cannot enumerate, so fall back to the known history.
+  return new Set(["2.0.0", "2.1.0", "2.2.0", "2.3.0", "2.4.0"]);
+}
+
 function defaultKeychainMapping() {
   return {
     jira: null,
@@ -158,29 +192,30 @@ function migrate(prefs) {
   const changes = [];
   const out = JSON.parse(JSON.stringify(prefs)); // deep clone
 
-  // 1. schemaVersion  -  detect whether a v2.0.0 → 2.1.0 → 2.2.0 → 2.3.0 bump chain is needed.
-  // Sub-migrations run regardless (they're idempotent), so early-return is avoided.
-  // v2.3.0 is the v7.4.0 target  -  adds optional `accounts[]` (per-account host
-  // overrides) and `recentAccounts[]` (LRU for autopilot account picker).
-  // Both default to empty arrays; old prefs continue to validate without them.
+  // 1. schemaVersion. Every known older version bumps STRAIGHT to TARGET: the
+  // sub-migrations below are cumulative and idempotent rather than pairwise, so
+  // there is no per-hop work to do.
+  //
+  // This is a SET rather than an if-else chain per version on purpose. The chain
+  // had to be extended by hand every time TARGET_VERSION moved, and forgetting
+  // made the migrator throw `unknown schemaVersion` on the very version it had
+  // just been released to migrate FROM.
+  //
+  // The set is READ FROM the schema's enum (minus the target) so the two cannot
+  // drift: adding a version to prefs.schema.json is what makes it migratable,
+  // and there is no second list to remember. Falls back to a literal set if the
+  // schema cannot be read, because refusing to migrate is worse than migrating
+  // from a version we cannot currently enumerate.
   const TARGET = TARGET_VERSION;
+  const MIGRATABLE_FROM = readMigratableVersions(TARGET);
   if (out.schemaVersion === TARGET) {
     // already on target  -  skip version bump, but still run sub-migrations below
-  } else if (out.schemaVersion === "2.3.0") {
-    out.schemaVersion = TARGET;
-    changes.push(`schemaVersion: 2.3.0 → ${TARGET}`);
-  } else if (out.schemaVersion === "2.2.0") {
-    out.schemaVersion = TARGET;
-    changes.push(`schemaVersion: 2.2.0 → ${TARGET}`);
-  } else if (out.schemaVersion === "2.1.0") {
-    out.schemaVersion = TARGET;
-    changes.push(`schemaVersion: 2.1.0 → ${TARGET}`);
   } else if (!out.schemaVersion) {
     out.schemaVersion = TARGET;
     changes.push(`added schemaVersion: ${TARGET}`);
-  } else if (out.schemaVersion === "2.0.0") {
+  } else if (MIGRATABLE_FROM.has(out.schemaVersion)) {
+    changes.push(`schemaVersion: ${out.schemaVersion} → ${TARGET}`);
     out.schemaVersion = TARGET;
-    changes.push(`schemaVersion: 2.0.0 → ${TARGET}`);
   } else {
     throw new Error(`unknown schemaVersion: ${out.schemaVersion}`);
   }
@@ -253,6 +288,42 @@ function migrate(prefs) {
     out.global.routines = [];
     changes.push("added empty routines (v2.4.0 user-defined /multi-agent:save routines)");
   }
+  // v2.5.0 / v14.0.0: Phase 4 Review entered the --dev phase sets and Step 1.78
+  // (criteria resolution) landed. Default false because only Swift plus the two
+  // store-compliance catalogs ship a scoped registry today, so blocking on a
+  // coverage gap would stop every Kotlin/Python/Node/ObjC run from day one. The
+  // gap is reported either way; this only decides whether it halts.
+  if (!out.global.skillConformance || typeof out.global.skillConformance !== "object") {
+    out.global.skillConformance = {};
+    changes.push("added skillConformance (v2.5.0 Phase 4 criteria resolution)");
+  }
+  if (typeof out.global.skillConformance.blockOnCoverageGap !== "boolean") {
+    out.global.skillConformance.blockOnCoverageGap = false;
+    changes.push("added skillConformance.blockOnCoverageGap=false (report, do not halt)");
+  }
+  // v2.5.0: /multi-agent:finish became /multi-agent:ship, and its autoFix key -
+  // referenced by the command spec since it shipped but never declared in the
+  // schema - is declared here. Carry any value the user had rather than reset it.
+  if (!out.global.ship || typeof out.global.ship !== "object") {
+    out.global.ship = {};
+    changes.push("added ship (v2.5.0  -  /multi-agent:finish renamed to :ship)");
+  }
+  if (typeof out.global.ship.autoFix !== "boolean") {
+    const legacyAutoFix = out.global.finish?.autoFix;
+    out.global.ship.autoFix = typeof legacyAutoFix === "boolean" ? legacyAutoFix : false;
+    changes.push(
+      typeof legacyAutoFix === "boolean"
+        ? "moved finish.autoFix -> ship.autoFix (value preserved)"
+        : "added ship.autoFix=false",
+    );
+  }
+  if (out.global.finish && typeof out.global.finish === "object") {
+    delete out.global.finish.autoFix;
+    if (Object.keys(out.global.finish).length === 0) {
+      delete out.global.finish;
+      changes.push("removed obsolete finish block (renamed to ship)");
+    }
+  }
   if (!out.global.serviceStatus) {
     out.global.serviceStatus = {};
     changes.push("added empty serviceStatus");