@mmerterden/multi-agent-pipeline 17.6.0 → 19.0.0

package/pipeline/lib/phase-schema.mjs

@@ -0,0 +1,88 @@
+/**
+ * @file phase-schema.mjs  -  read a phase number that may have been written
+ * under either phase vocabulary.
+ *
+ * metrics.jsonl is append-only and v19.0.0 renumbered the phases, so the same
+ * field means two different things depending on when the line was written:
+ * `phase: 3` is Dev in a pre-v19 row and Review in a post-v19 one. Rows from
+ * v19.0.0 on carry `phaseSchema: 2`; rows without the field are generation 1.
+ *
+ * Every aggregator that compares a phase number to a literal, or prints a
+ * phase name, goes through here. Comparing directly is the bug this module
+ * exists to prevent - it does not throw, it silently attributes work to the
+ * wrong phase and the roll-up still looks plausible.
+ *
+ * @module pipeline/lib/phase-schema
+ */
+
+import { readFileSync } from "node:fs";
+
+const CONTRACT = JSON.parse(
+  readFileSync(new URL("../schemas/phases.json", import.meta.url), "utf8"),
+);
+
+export const CURRENT_SCHEMA = CONTRACT.phaseSchema;
+
+/** Generation 1 number -> current number, derived from each phase's `was`. */
+const GEN1_TO_CURRENT = new Map();
+for (const p of CONTRACT.phases) {
+  for (const old of p.was) GEN1_TO_CURRENT.set(Number(old), p.id);
+}
+
+const CURRENT_NAMES = new Map(CONTRACT.phases.map((p) => [p.id, p.name]));
+const GEN1_NAMES = new Map(
+  Object.entries(CONTRACT.legacyPhaseNames)
+    .filter(([k]) => /^\d+$/.test(k))
+    .map(([k, v]) => [Number(k), v]),
+);
+
+/**
+ * Which vocabulary a metrics row was written under.
+ *
+ * @param {object} row  -  a parsed metrics.jsonl line
+ * @returns {number}    -  1 or 2
+ */
+export function schemaOf(row) {
+  const s = Number(row?.phaseSchema);
+  return Number.isInteger(s) && s > 0 ? s : 1;
+}
+
+/**
+ * A row's phase expressed in the CURRENT vocabulary, so rows from both
+ * generations can be counted together.
+ *
+ * @param {string|number} phase
+ * @param {number} schema  -  from schemaOf()
+ * @returns {number|null}  -  null when the value is not a phase number at all
+ */
+export function toCurrentPhase(phase, schema) {
+  const n = Number(phase);
+  if (!Number.isInteger(n)) return null;
+  if (schema >= CURRENT_SCHEMA) return CURRENT_NAMES.has(n) ? n : null;
+  return GEN1_TO_CURRENT.has(n) ? GEN1_TO_CURRENT.get(n) : null;
+}
+
+/**
+ * The name the phase number carried WHEN IT WAS WRITTEN. A historical row is
+ * labelled with its own vocabulary's name; relabelling it with today's name
+ * would make the archive disagree with the log it came from.
+ *
+ * @param {string|number} phase
+ * @param {number} schema
+ * @returns {string}
+ */
+export function phaseNameAsWritten(phase, schema) {
+  const n = Number(phase);
+  const table = schema >= CURRENT_SCHEMA ? CURRENT_NAMES : GEN1_NAMES;
+  return table.get(n) ?? `Phase ${phase}`;
+}
+
+/**
+ * Convenience for the common shape: a row in, its current-vocabulary phase out.
+ *
+ * @param {object} row
+ * @returns {number|null}
+ */
+export function rowPhase(row) {
+  return toCurrentPhase(row?.phase, schemaOf(row));
+}

package/pipeline/lib/plan-todos.sh

@@ -1,14 +1,14 @@
 #!/usr/bin/env bash
 #
-# plan-todos.sh  -  manage the Phase 2 plan as a live Todo list.
+# plan-todos.sh  -  manage the Phase 1 plan as a live Todo list.
 #
-# The Phase 2 plan is broken into a live, reviewable Todo list that updates
+# The Phase 1 plan is broken into a live, reviewable Todo list that updates
 # step-by-step as Phase 3 works through it.
 #
 # State lives in `agent-state.json` under `.plan.todos[]` per
 # pipeline/schemas/plan-todos.schema.json. Phase 2 (Planning) emits the
 # initial plan; Phase 3 (Dev) iterates step-by-step; Phase 4 (Review)
-# inspects completion; Phase 7 (Report) renders the rollup.
+# inspects completion; Phase 5 (Report) renders the rollup.
 #
 # Subcommands:
 #   init      <task-id> [title]            Initialize with empty todos[] (Phase 2 usually pipes the JSON instead)
@@ -19,7 +19,7 @@
 #   skip      <task-id> <todo-id> <reason> Mark skipped (counts as satisfied for dependents)
 #   next      <task-id>                    Print next pending todo (deps-respecting); empty if none
 #   list      <task-id>                    Render Markdown checklist
-#   status    <task-id>                    Print one-line summary: "3/7 done, 1 in progress"
+#   status    <task-id>                    Print one-line summary: "2/5 done, 1 in progress"
 #   show      <task-id>                    Print the full plan JSON
 #
 # Exit codes:
@@ -30,6 +30,31 @@
 
 set -euo pipefail
 
+# jq is not optional on this path. Without the guard below a missing binary
+# renders as EMPTY DATA and the work continues on it; see lib/require-jq.sh.
+for _rq in "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/require-jq.sh" \
+           "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../lib" 2>/dev/null && pwd)/require-jq.sh" \
+           "$HOME/.claude/lib/require-jq.sh" \
+           "$HOME/.copilot/lib/require-jq.sh" \
+           "$HOME/.codex/lib/require-jq.sh"; do
+  [ -f "$_rq" ] || continue
+  # shellcheck source=/dev/null
+  . "$_rq" && break
+done
+unset _rq
+if ! command -v ma_require_jq >/dev/null 2>&1; then
+  # The helper itself is missing, which is an install problem, not a jq one.
+  ma_require_jq() { command -v jq >/dev/null 2>&1 || { echo "jq not found - cannot ${1:-continue}." >&2; return 1; }; }
+fi
+ma_require_jq "read or write the plan" || exit 3
+
+# Run-state path resolution: pipeline/lib/run-paths.sh owns the two layouts
+# (nested <root>/<project>/<id>/ and flat <root>/<id>/) and every id spelling.
+_MA_RP_HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "$_MA_RP_HERE/run-paths.sh" 2>/dev/null || . "$HOME/.claude/lib/run-paths.sh"
+
+
 CMD="${1:-}"
 shift || true
 
@@ -49,12 +74,8 @@ resolve_state() {
   # directory ($HOME/.claude/logs/multi-agent/{project}/{taskId}/) - not the
   # ~/.claude/projects/*/state/ path this used to glob, which no writer in
   # the pipeline ever populates.
-  for candidate in "$HOME"/.claude/logs/multi-agent/*/"$task_id"/agent-state.json; do
-    if [ -f "$candidate" ]; then
-      found="$candidate"
-      break
-    fi
-  done
+  # This globbed ONLY the nested layout; flat-layout runs resolved to nothing.
+  found="$(ma_resolve_run_file "$task_id" agent-state.json 2>/dev/null || true)"
   if [ -z "$found" ]; then
     echo "plan-todos: agent-state.json not found for task=$task_id" >&2
     exit 1
@@ -96,7 +117,7 @@ do_set() {
   fi
   # A planning-output document is accepted directly and converted here.
   #
-  # The conversion used to live as a jq blob inside phase-2-planning.md, which
+  # The conversion used to live as a jq blob inside phase-1-plan.md, which
   # made the mapping from `tasks[]` to `todos[]` a thing two files defined - and
   # the phase doc was the copy nothing tested. Accepting both shapes costs four
   # lines and removes the second definition.

package/pipeline/lib/post-pr-review.sh

@@ -34,6 +34,65 @@
 
 set -euo pipefail
 
+# jq is not optional on this path. Without the guard below a missing binary
+# renders as EMPTY DATA and the work continues on it; see lib/require-jq.sh.
+for _rq in "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/require-jq.sh" \
+           "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../lib" 2>/dev/null && pwd)/require-jq.sh" \
+           "$HOME/.claude/lib/require-jq.sh" \
+           "$HOME/.copilot/lib/require-jq.sh" \
+           "$HOME/.codex/lib/require-jq.sh"; do
+  [ -f "$_rq" ] || continue
+  # shellcheck source=/dev/null
+  . "$_rq" && break
+done
+unset _rq
+if ! command -v ma_require_jq >/dev/null 2>&1; then
+  # The helper itself is missing, which is an install problem, not a jq one.
+  ma_require_jq() { command -v jq >/dev/null 2>&1 || { echo "jq not found - cannot ${1:-continue}." >&2; return 1; }; }
+fi
+ma_require_jq "parse the review findings" || exit 3
+
+# Outbound leak gate. Every byte below is composed at runtime out of command
+# output, error text and file excerpts, any of which can carry a token that was
+# on this machine a second earlier - and once it is in a comment it is in
+# someone else's database. The repo's own leak scanner looks at FILES IN THE
+# REPO and never sees this text. See lib/outbound-gate.mjs.
+ma_outbound_gate() {
+  local body_file="$1" og=""
+  for c in "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/outbound-gate.mjs" \
+           "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../lib" 2>/dev/null && pwd)/outbound-gate.mjs" \
+           "$HOME/.claude/lib/outbound-gate.mjs" \
+           "$HOME/.copilot/lib/outbound-gate.mjs" \
+           "$HOME/.codex/lib/outbound-gate.mjs"; do
+    [ -f "$c" ] && { og="$c"; break; }
+  done
+  # Missing gate is NOT an open door: refusing to publish beats publishing
+  # unchecked, and the only way this file is absent is a broken install.
+  if [ -z "$og" ]; then
+    echo "outbound-gate.mjs not found - refusing to publish unchecked text." >&2
+    return 7
+  fi
+  node "$og" --file "$body_file"
+}
+
+# Same gate, for the bodies this file keeps in a variable rather than a file.
+ma_outbound_gate_text() {
+  local tmp
+  tmp=$(mktemp) || return 7
+  printf '%s' "$1" > "$tmp"
+  ma_outbound_gate "$tmp"
+  local rc=$?
+  rm -f "$tmp"
+  return $rc
+}
+
+# Run-state path resolution: pipeline/lib/run-paths.sh owns the two layouts
+# (nested <root>/<project>/<id>/ and flat <root>/<id>/) and every id spelling.
+_MA_RP_HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "$_MA_RP_HERE/run-paths.sh" 2>/dev/null || . "$HOME/.claude/lib/run-paths.sh"
+
+
 # Basic-auth via a curl config fed through process substitution so the
 # credential never appears in argv (argv is visible to `ps` / process audit).
 bb_auth_cfg() { printf 'user = "%s:%s"\n' "$1" "$2"; }
@@ -49,13 +108,10 @@ fi
 # per-project directory ($HOME/.claude/logs/multi-agent/{project}/{taskId}/)
 # - not the ~/.claude/projects/*/state/ path this used to glob, which no
 # writer in the pipeline ever populates.
-AGENT_STATE=""
-for candidate in "$HOME"/.claude/logs/multi-agent/*/"$TASK_ID"/agent-state.json; do
-  if [ -f "$candidate" ]; then
-    AGENT_STATE="$candidate"
-    break
-  fi
-done
+# This globbed ONLY the nested layout. phase-tracker.sh and most Phase 0 paths
+# write flat, so on a real machine the majority of runs resolved to nothing and
+# this script reported "no agent-state.json" for a run whose state existed.
+AGENT_STATE="$(ma_resolve_run_file "$TASK_ID" agent-state.json 2>/dev/null || true)"
 
 if [ -z "$AGENT_STATE" ]; then
   echo "post-pr-review: agent-state.json not found for task=$TASK_ID" >&2
@@ -271,6 +327,13 @@ post_github() {
           continue
         fi
 
+        # A finding's body quotes the diff and the reviewer's prose, so it is
+        # the most likely of the three to carry something from the machine.
+        if ! ma_outbound_gate_text "$body"; then
+          echo "post-pr-review: outbound gate refused the comment for $path:$line - not posted" >&2
+          continue
+        fi
+
         local inline_ok=0
         if [ -n "$head_sha" ] && [ "$line" -gt 0 ] 2>/dev/null; then
           if gh api -X POST "/repos/$org_repo/pulls/$PR_NUM/comments" \
@@ -290,7 +353,13 @@ post_github() {
 
   case "$DECISION" in
     approve)    gh pr review "$PR_NUM" --repo "$org_repo" --approve ;;
-    needs_work) gh pr review "$PR_NUM" --repo "$org_repo" --request-changes --body "$rc_body" ;;
+    needs_work)
+      if ! ma_outbound_gate_text "$rc_body"; then
+        echo "post-pr-review: outbound gate refused the request-changes body; no verdict posted" >&2
+        return 7
+      fi
+      gh pr review "$PR_NUM" --repo "$org_repo" --request-changes --body "$rc_body"
+      ;;
   esac
 }
 

package/pipeline/lib/repo-hygiene.sh

@@ -141,11 +141,16 @@ ma_hygiene_local_gitignore() {
 # rmdir, never rm -rf: it fails harmlessly when anything is left, which is the
 # behaviour we want. An empty .worktrees/ and .pipeline/evidence/ survive a
 # clean run today and read as leftovers to anyone looking at the checkout.
+#
+# "Harmlessly" is only true while the CALLER does not run under `set -e`, and
+# this file is sourced, so that is the caller's choice and not ours. Every
+# rmdir here is therefore explicitly forgiven: a non-empty directory is the
+# ordinary case, and it must not abort a teardown half-way.
 ma_hygiene_prune_empty() {
   local root d
   root=$(ma_hygiene_safe_root "${1:-}") || return 0
   for d in "$root/.pipeline/evidence" "$root/.pipeline" "$root/.worktrees/.archive" "$root/.worktrees" "$root/.multi-agent/refs"; do
-    [ -d "$d" ] && rmdir "$d" 2>/dev/null
+    [ -d "$d" ] && { rmdir "$d" 2>/dev/null || true; }
   done
 
   # .multi-agent survives the loop above because it still holds the .gitignore
@@ -156,8 +161,8 @@ ma_hygiene_prune_empty() {
     local leftover
     leftover=$(ls -A "$root/.multi-agent" 2>/dev/null)
     if [ "$leftover" = ".gitignore" ]; then
-      rm -f "$root/.multi-agent/.gitignore" 2>/dev/null
-      rmdir "$root/.multi-agent" 2>/dev/null
+      rm -f "$root/.multi-agent/.gitignore" 2>/dev/null || true
+      rmdir "$root/.multi-agent" 2>/dev/null || true
     fi
   fi
   return 0

package/pipeline/lib/require-jq.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# require-jq.sh  -  one place to refuse when `jq` is missing.
+#
+# 78 shell files in this repo call `jq`. 46 of them called it with no check at
+# all, and the README described that as helpers which "skip in silence" - which
+# is the defect stated as if it were the design. A bare `jq` on a machine
+# without it does not skip. It writes "command not found" to stderr, produces
+# an empty string on stdout, and the caller carries on with that empty string
+# as if it were the answer.
+#
+# The nine production paths are where that matters:
+#
+#   autopilot-state.sh   an unreadable queue reads as an EMPTY queue, so the
+#                        runner concludes there is no work and goes quiet
+#   jira-publish.sh      posts a comment built from empty fields
+#   post-pr-review.sh    publishes a review whose findings did not parse
+#   update-issue-progress.sh  same, on an issue
+#   _jira-auth.sh        no credential, and the failure surfaces later as 401
+#   figma-mcp-refresh.sh / figma-screenshot.sh   silent no-op on a design fetch
+#   plan-todos.sh        an empty plan looks like a plan with no work in it
+#   search-logs.sh       "no results" instead of "could not search"
+#
+# Every one of those is the same shape: absence of a tool rendered as absence
+# of data. Refusing is the only honest answer, and the exit code is distinct
+# so a caller can tell "jq missing" from "the work failed".
+#
+# Usage:
+#   . "$(dirname "$0")/require-jq.sh"
+#   ma_require_jq "read the autopilot queue" || exit 3
+#
+# It returns rather than exits: this file is SOURCED, and a sourced file that
+# exits kills the caller's shell in ways the caller did not write down.
+
+# shellcheck disable=SC2329  # sourced by other scripts, not called here
+ma_require_jq() {
+  command -v jq >/dev/null 2>&1 && return 0
+  printf 'jq not found - cannot %s.\n' "${1:-continue}" >&2
+  printf '  install it: brew install jq\n' >&2
+  return 1
+}

package/pipeline/lib/route-state.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+# route-state.sh  -  read and write prefs.global.modelRouting.
+#
+# Backs /multi-agent:route-on, route-off and route-status. Ships disabled and
+# stays that way until someone turns it on; while `enabled` is false nothing in
+# this file changes one dispatch.
+#
+# The `off` contract is borrowed from autopilot-off and for the same reason: it
+# clears the ON STATE, never the rules. Turning routing back on must not re-ask
+# for a configuration the user already gave.
+#
+# Usage:
+#   route-state.sh status                       print the current policy
+#   route-state.sh on  [--strategy=S] [--scope=a,b]
+#   route-state.sh off
+#   route-state.sh set-rules <file.json>        replace rules[] from a JSON array
+#
+# Exit codes:
+#   0  -  done
+#   2  -  bad usage
+#   3  -  preferences missing/unparseable, or a scope value this refuses
+
+set -uo pipefail
+
+PREFS="${MULTI_AGENT_PREFS:-$HOME/.claude/multi-agent-preferences.json}"
+
+# The scope values this accepts, spelled once. `host-session` is NOT here and
+# must never be added: it would mean rewriting the host's base URL, which routes
+# the user's whole session - work that has nothing to do with this pipeline
+# included - through a third layer, breaks the subscription's auth model, and
+# silently changes which model answers. The schema encodes the same list so a
+# hand-edited preferences file is rejected too, rather than only this entry point.
+ALLOWED_SCOPE="subagent bulk-read research"
+
+die() { echo "route-state: $1" >&2; exit "${2:-3}"; }
+
+# A missing `jq` must not look like routing being off. Every read below would
+# come back empty, `route-status` would report disabled, and a user with rules
+# armed would be told there are none.
+command -v jq >/dev/null 2>&1 || die "jq not found  -  cannot read or write preferences (install: brew install jq)"
+[ -f "$PREFS" ] || die "preferences not found at $PREFS  -  run /multi-agent:setup first"
+jq -e . "$PREFS" >/dev/null 2>&1 || die "$PREFS is not valid JSON  -  refusing to write over it"
+
+ACTION="${1:-status}"; shift 2>/dev/null || true
+
+write_prefs() {
+  local filter="$1"; shift
+  local tmp
+  tmp=$(mktemp) || die "mktemp failed"
+  if ! jq "$@" "$filter" "$PREFS" > "$tmp"; then rm -f "$tmp"; die "jq failed  -  preferences left untouched"; fi
+  jq -e . "$tmp" >/dev/null 2>&1 || { rm -f "$tmp"; die "produced invalid JSON  -  preferences left untouched"; }
+  mv "$tmp" "$PREFS"
+}
+
+case "$ACTION" in
+  status)
+    ENABLED=$(jq -r '.global.modelRouting.enabled // false' "$PREFS")
+    STRATEGY=$(jq -r '.global.modelRouting.strategy // "manual"' "$PREFS")
+    SCOPE=$(jq -r '(.global.modelRouting.scope // ["subagent"]) | join(", ")' "$PREFS")
+    NRULES=$(jq -r '(.global.modelRouting.rules // []) | length' "$PREFS")
+    CEIL=$(jq -r '.global.modelRouting.budgetCeilingUsd // "none"' "$PREFS")
+    REC=$(jq -r '.global.modelRouting.recordDecisions // true' "$PREFS")
+
+    echo "routing:   $ENABLED"
+    echo "strategy:  $STRATEGY"
+    echo "scope:     $SCOPE"
+    echo "rules:     $NRULES"
+    echo "ceiling:   $CEIL"
+    echo "decisions: $REC"
+    echo ""
+
+    if [ "$ENABLED" != "true" ]; then
+      echo "Disabled. Rules are stored but read by nothing; dispatch is unchanged."
+      [ "$NRULES" -gt 0 ] && echo "route-on turns these $NRULES rule(s) back on without re-asking."
+      exit 0
+    fi
+
+    if [ "$NRULES" -eq 0 ]; then
+      echo "Armed with no rules. Nothing matches, so nothing is routed  -  this is a"
+      echo "configuration state, not an error."
+    else
+      jq -r '(.global.modelRouting.rules // [])[] |
+        "  when " + ([.when | to_entries[] | "\(.key)=\(.value)"] | join(" ")) +
+        "  ->  " + (.prefer | join(" > "))' "$PREFS"
+    fi
+
+    echo ""
+    # The limit is printed every time rather than documented once, because the
+    # question it answers ("routing is on, why is the reviewer still on Opus")
+    # otherwise arrives days later as a bug report.
+    echo "Honest limit: on Claude Code a subagent cannot be sent to a non-Anthropic"
+    echo "model  -  subagent dispatch belongs to the host. Phase 1/2/3 personas stay"
+    echo "inside the Anthropic ladder whatever the rules say. External providers apply"
+    echo "only where this pipeline makes the call itself (bulk-read, research)."
+    ;;
+
+  on)
+    STRATEGY="manual"; SCOPE_ARG=""
+    for arg in "$@"; do
+      case "$arg" in
+        --strategy=*) STRATEGY="${arg#*=}" ;;
+        --scope=*)    SCOPE_ARG="${arg#*=}" ;;
+        *) die "unknown option: $arg" 2 ;;
+      esac
+    done
+    case "$STRATEGY" in
+      manual|task-fit|cost-ceiling) ;;
+      *) die "strategy must be manual, task-fit or cost-ceiling (got '$STRATEGY')" 2 ;;
+    esac
+
+    if [ -n "$SCOPE_ARG" ]; then
+      SCOPE_JSON="[]"
+      IFS=',' read -r -a parts <<< "$SCOPE_ARG"
+      for one in "${parts[@]}"; do
+        one="${one// /}"
+        # shellcheck disable=SC2076
+        case " $ALLOWED_SCOPE " in
+          *" $one "*) ;;
+          *) die "scope '$one' is not allowed (allowed: $ALLOWED_SCOPE). 'host-session' is refused by design: it would route the whole session, not this pipeline's calls." ;;
+        esac
+        SCOPE_JSON=$(jq -c --arg s "$one" '. + [$s]' <<< "$SCOPE_JSON")
+      done
+      write_prefs '
+          .global.modelRouting //= {}
+        | .global.modelRouting.enabled = true
+        | .global.modelRouting.strategy = $st
+        | .global.modelRouting.scope = ($sc | fromjson)
+      ' --arg st "$STRATEGY" --arg sc "$SCOPE_JSON"
+    else
+      write_prefs '
+          .global.modelRouting //= {}
+        | .global.modelRouting.enabled = true
+        | .global.modelRouting.strategy = $st
+        | .global.modelRouting.scope //= ["subagent"]
+      ' --arg st "$STRATEGY"
+    fi
+    echo "routing enabled (strategy: $STRATEGY)"
+    exec "$0" status
+    ;;
+
+  off)
+    # Rules survive on purpose. Clearing them here would make route-off a
+    # destructive action wearing the name of a toggle.
+    write_prefs '.global.modelRouting //= {} | .global.modelRouting.enabled = false'
+    echo "routing disabled. Rules kept  -  route-on restores this configuration as it is."
+    ;;
+
+  set-rules)
+    FILE="${1:-}"
+    [ -n "$FILE" ] || die "set-rules needs a JSON file containing an array of rules" 2
+    [ -f "$FILE" ] || die "no such file: $FILE" 2
+    jq -e 'type == "array"' "$FILE" >/dev/null 2>&1 || die "$FILE must contain a JSON ARRAY of rules" 2
+    write_prefs '.global.modelRouting //= {} | .global.modelRouting.rules = $r' --slurpfile _ignore /dev/null --argjson r "$(cat "$FILE")"
+    echo "rules replaced: $(jq -r 'length' "$FILE")"
+    ;;
+
+  *)
+    echo "usage: route-state.sh [status|on|off|set-rules <file>]" >&2
+    exit 2
+    ;;
+esac