@mmerterden/multi-agent-pipeline 15.12.2 → 15.14.0

package/CHANGELOG.md

@@ -16,6 +16,38 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [15.14.0] - 2026-08-22
+
+### Added
+- **A release can now be required, not just available.** `/multi-agent:update` stays exactly what it was, and most releases change nothing: the run-start check keeps reading `dist-tags.latest` and keeps asking politely. What is new is a second tag. `npm dist-tag add <pkg>@<version> required` names the oldest version a user may run, and an install below that floor is not behind, it is wrong - it would produce work against a contract that no longer holds, which then has to be redone. Below the floor, Phase 0 Step 0.6 halts: it runs the update flow and stops, and the user re-issues the command on the new version. It does not continue on the freshly updated install, because this run's phase docs, refs and scripts were already loaded from the old one, and that is the drift the floor exists to prevent. Interactive and autopilot behave identically - there is nothing to decide.
+- **`require-supported-version.sh`** turns the signal into an exit code for shell callers: 0 = proceed, 3 = halt, with `force|<local>|<latest>|<required>` on stdout and a human block on stderr. It shares `update-check.sh`'s cache, so a second command inside the TTL window costs no network call.
+
+### Fixed
+- **The Firebase Crashlytics fetcher called an endpoint that does not exist.** It built the app reference by hand as `<platform>:<bundle>` and asked for `/v1alpha/projects/<p>/apps/<ref>/issues/<issueId>`. The appId is opaque (`1:1234567890:ios:abcdef`) and cannot be derived from a bundle, and v1alpha has no get-issue-by-id route, so every fetch failed - and the failure was reported as `api-not-enabled`, which sent anyone debugging it to look at Google's API allowlist instead of at the URL. It now resolves the real appId through the Firebase Management API (`iosApps` / `androidApps`, matching `bundleId` / `packageName`), then reads `reports/topIssues` for the summary and metrics and `events?filter.issue.id=<id>` for the newest event. The payload gains what that event carries and the old shape could not: the full `stackTrace[]`, the breadcrumb and log timeline with screen names, session and occurrence counts, and the console URI. A multi-app project with no bundle match exits 3 as `app-not-found` rather than picking a neighbouring app.
+- **Fortify findings that arrive without a URL are no longer invisible.** A scanner-to-tracker bridge writes the instance id and the `file:line` into the ticket and never writes the SSC link - it knows the id, and the person reading the ticket never needed the URL. The extractor was URL-only, so those tickets produced an empty `contextLinks[]`, Phase 0 skipped the deep fetch, and Phase 4's Fortify gate reported `n/a` on a ticket that exists *because of* a security finding. It now also matches a labelled `Fortify Instance ID` / `issue instance id` / `fortify id` and emits a URL-less entry, the same shape graylog trx ids already used. `fetch-fortify.sh --instance-id <id>` resolves the project version by asking each id in `prefs.global.fortify.versionIds` in order. To stay off prose, the id must be at least 16 characters and contain a digit, and the bare label `instance id` is deliberately not matched.
+- **`prefs.global.fortify` did not exist.** Phase 4 Gate 5 documented `fortify.alwaysCheck` as its opt-in from the day it shipped, but `global` is closed to additional properties and the schema had no `fortify` object, so setting it failed validation - the gate could only ever run off a referenced URL. The object now exists with `alwaysCheck` and `versionIds`.
+- Fortify URLs of the form `/ssc/html/ssc/version/<id>` and `#/version/<id>` now yield a version id. Only the API shape `/projectVersions/<id>` was matched before, so the UI links people actually paste parsed to `projectId: null`.
+
+### Changed
+- `update-check.sh` reads both tags in one call and now uses the abbreviated packument (60 kB instead of 250 kB for the same answer). Its own contract is unchanged and deliberately so: it still always exits 0, still says nothing when the registry is unreachable, and still emits `<local>|<latest>` for a plain update. The floor appends a third field, `force`, which a `cut -f1`/`-f2` reader ignores. The cache file grows a third field too; a two-field cache written by an older install still reads, and its missing floor means "unknown", never "none".
+- **Fail-open, on purpose.** Offline, a blocked registry, an undeterminable local version, a `required` tag published above `latest`, or no tag at all: every one of these exits 0. A version gate that bricks the pipeline on a flaky network is worse than the drift it guards against.
+- **Not opt-out.** `updateCheck.enabled: false` silences the advisory "update available" prompt, which is what it always meant; it does not lift a floor. The single override is the env var `MULTI_AGENT_ALLOW_OUTDATED=1`, which exits 0 with a warning and is logged in the run record, so a broken release cannot strand someone mid-incident. Exempt commands - `update`, `setup`, `uninstall`, `help`, `status`, `log`, `search`, `routines`, `forget`, `language` - are the remedy or cannot depend on a contract.
+- Phase-doc token budget: total 54050 -> 54400. Compression came first and took the new Step 0.6 prose from 469 tokens to 337, by moving the rationale, the exemption list and the `npm dist-tag add` recipe into `multi-agent-refs/rules.md` "Supported Version Gate" (loaded by 25 commands, outside this budget) and into the script header, leaving the phase doc with the call, the decision table and the halt.
+- `smoke-update-check.sh` grew from 12 to 27 assertions, covering the floor, the clamp, the legacy cache, the wrapper's three exit paths and the doc wiring on both sides.
+- **`smoke-context-links.sh`: the extractor has a behaviour test now.** A 250-line deterministic classifier that every Phase 0 deep fetch dispatches on had no test of its own, so a regression in any pattern would only ever surface as "the ticket had a link and nothing was enriched", with nothing red to point at. 32 assertions over every emitted type, both Fortify entry shapes, dedup, and the two things that must NOT match: prose containing the words, and a bare non-doc URL.
+- `sync/SKILL.md` lost a "Special inputs" table that repeated the argument table from the top of the same file, minus one row.
+
+## [15.13.0] - 2026-08-22
+
+### Fixed
+- **Three settings that were declared and did nothing are now wired up.** `learningsLedger.maxBriefEntries` had a default of 20 while both phase docs hardcoded `--max 20`, so raising it changed nothing. `testGap.scanTree` and `testGap.promoteSeverity` were declared in the schema AND implemented as `--scan-tree` / `--severity-promote` in the scanner, with nothing in between reading the pref and passing the flag: the plumbing existed at both ends and the middle was missing. A user who set any of the three got the default back with no error and no warning, and the schema told them they had done it right.
+
+### Added
+- **`smoke-prefs-consumed.sh`: every setting the schema declares must be read by something.** This class has now shipped five times - the two `contextOffload` fields fixed in 15.11.0 and the three above - which is enough to gate rather than to keep catching by hand. The check walks the nested schema and asserts each leaf key is mentioned as a whole word somewhere outside `schemas/`. Deliberately loose: it asks "did anyone wire this up", not "is the wiring correct", because a stricter rule would have to understand shell, JS and markdown, and a gate that is wrong is worse than one that is broad. `keychainMapping.*` is exempt with a reason - those are resolved dynamically, so the literal name never appears in code by design. Verified by planting a setting nothing reads and watching the gate go red.
+
+### Changed
+- Phase-doc token budget: total 53950 -> 54050. The 94 tokens are the wiring itself, not prose - two `--max` substitutions and a three-line flag block. Compression came first and twice: the rationale moved into the new gate's header, where it is enforced rather than described, and a `--severity-promote` table row was dropped because the invocation above it now shows the flag and names the pref that triggers it.
+
 ## [15.12.2] - 2026-08-22
 
 ### Fixed

package/docs/features.md

@@ -162,7 +162,11 @@ Existing tests are immutable during a task: deleting, renaming, or weakening an
 
 ### Update Check at Run Start
 
-Phase 0 Step 0.6, opt-out via `prefs.global.updateCheck`. Once per `ttlHours` window (cached, 3s-bounded curl to the npm registry), the installed version is compared against `dist-tags.latest`. Newer version: interactive modes ask "Update now?" (yes runs the `/multi-agent:update` flow, then the run continues); autopilot logs one line and never asks. `autoUpdate: true` updates silently before the worktree exists. Offline and failed checks are silent - never blocks.
+Phase 0 Step 0.6. Once per `ttlHours` window (cached, 3s-bounded curl to the npm registry), the installed version is compared against two dist-tags.
+
+**`latest` - advisory**, opt-out via `prefs.global.updateCheck.enabled`. Newer version: interactive modes ask "Update now?" (yes runs the `/multi-agent:update` flow, then the run continues); autopilot logs one line and never asks. `autoUpdate: true` updates silently before the worktree exists. Offline and failed checks are silent - never blocks.
+
+**`required` - blocking** (v15.14.0+). Most releases do not publish this tag and nothing changes for them. A release that changed a contract a run depends on is promoted with `npm dist-tag add <pkg>@<version> required`, and an install below that floor is not behind, it is wrong: `require-supported-version.sh` exits 3, the run halts, `/multi-agent:update` runs, and the user re-issues the command on the new version rather than continuing on docs already loaded from the old one. Interactive and autopilot behave identically. The gate fails open on every undeterminable answer (offline, blocked registry, no tag), `updateCheck.enabled: false` does not disable it, and the single override is the env var `MULTI_AGENT_ALLOW_OUTDATED=1`, which is logged in the run record. Exemptions: `update`, `setup`, `uninstall`, `help`, `status`, `log`, `search`, `routines`, `forget`, `language`.
 
 ### Structured Handoff Blocks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "15.12.2",
+  "version": "15.14.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

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

@@ -72,15 +72,6 @@ Step 6: Report      Summary: synced targets, platform, changed files, deploy sta
 
 If nothing is stale → report "All targets up to date" and stop.
 
-## Special inputs
-
-| Input | Behaviour |
-|-------|----------|
-| (no args) | Full ecosystem sync (default) |
-| `release` | Full sync + version bump + tag + npm publish + website deploy |
-| `multi-agent-toolkit` | Run Step 3d only: gate, commit and publish the companion MCP server |
-| `"change description"` | Apply the description to EVERY target at once |
-
 ---
 
 ## Sync rules
@@ -427,6 +418,8 @@ npm publish --userconfig "$NPMRC"
 
 Verify the publish landed: on GitHub Packages `npm view <package> version --userconfig "$NPMRC"`; on npmjs read the registry directly (`curl -s https://registry.npmjs.org/<package>/latest`) rather than `npm view`, which can answer from a stale cache.
 
+**Required release** (optional; ask first even in `release` mode, it halts every older install): `npm dist-tag add "$(node -p "require('./package.json').name")@$VER" required --userconfig "$NPMRC"`. Out of band, so promote or demote any time. Contract: `multi-agent-refs/rules.md` "Supported Version Gate".
+
 **Approval**: outside autopilot and outside `release`, ask before shipping.
 
 > "multi-agent-toolkit moved (N changed files, M unpushed commits, v$VER). What should I do?"

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

@@ -25,9 +25,17 @@ A git clone of the pipeline repo is a maintainer workspace, kept in sync by `/mu
      echo "Registry unreachable ($REG) - check your network and retry."
      exit 1
    fi
-   echo "Current: v$CUR   Latest: v$LATEST"
+   # dist-tags.required is the supported-version floor (absent on most releases).
+   REQUIRED=$(curl -fsS -H 'Accept: application/vnd.npm.install-v1+json' \
+     "$REG/$(printf '%s' "$PKG" | sed 's|/|%2F|')" \
+     | node -pe 'JSON.parse(require("fs").readFileSync(0,"utf8"))["dist-tags"].required || ""' 2>/dev/null)
+   echo "Current: v$CUR   Latest: v$LATEST${REQUIRED:+   Required floor: v$REQUIRED}"
    ```
 
+   This command is never blocked by the floor  -  it is the remedy for it. The
+   line above is where the floor is reported, so the user sees why a run halted;
+   `$REQUIRED` does not survive into the later shell blocks.
+
 2. **Stop early when already current** (still refresh the marketplace, step 4b):
    ```bash
    [ "$CUR" = "$LATEST" ] && echo "✓ Already up to date: v$LATEST"

package/pipeline/lib/context-link-extractor.sh

@@ -10,7 +10,8 @@
 #   - swagger     : OpenAPI / Swagger JSON or YAML spec URLs
 #   - confluence  : Confluence pages (host pattern + display/spaces/pageId)
 #   - crashlytics : Firebase Crashlytics issue/session URLs
-#   - fortify     : Fortify SSC findings URLs
+#   - fortify     : Fortify SSC finding URLs, and (URL-less, like graylog)
+#                   labelled issue instance ids  -  "Fortify Instance ID: <id>"
 #   - graylog     : Graylog trx-id / conversation-id references. Unlike the
 #                   others this is matched from free text (labels like "trx",
 #                   "trxid", "transaction id", "conversationId", "convId",
@@ -31,7 +32,7 @@
 #     { "type": "confluence", "url": "...", "metadata": { "host": "...", "pageId": "...|null", "spaceKey": "...|null" } },
 #     { "type": "swagger",    "url": "...", "metadata": { "format": "json|yaml|unknown" } },
 #     { "type": "crashlytics","url": "...", "metadata": { "projectId": "...", "platform": "ios|android", "issueId": "...", "sessionId": "...|null" } },
-#     { "type": "fortify",    "url": "...", "metadata": { "host": "...", "projectId": "...|null" } },
+#     { "type": "fortify",    "url": "...|null", "metadata": { "host": "...|null", "versionId": "...|null", "instanceId": "...|null", "source": "url|label" } },
 #     { "type": "graylog",    "url": null,  "metadata": { "idType": "trx|conversation", "id": "...", "label": "..." } },
 #     { "type": "figma",      "url": "...", "metadata": { "kind": "design|make|board|slides", "fileKey": "...", "nodeId": "...|null" } },
 #     ...
@@ -155,11 +156,18 @@ def classify(url: str):
     #   https://<ssc-host>/ssc/html/ssc/...
     #   https://<ssc-host>/ssc/api/v1/projectVersions/<id>/...
     if "fortify" in host or "/ssc/" in path or "/api/v1/projectVersions/" in path:
-        project_id = None
-        m = re.search(r"/projectVersions/(?P<id>\d+)", path)
-        if m:
-            project_id = m.group("id")
-        return ("fortify", {"host": host, "projectId": project_id})
+        # The SSC UI keeps the version id in the fragment on some deployments
+        # and in the path on others; search both.
+        where = path + ("#" + parsed.fragment if parsed.fragment else "")
+        m = re.search(r"/(?:projectVersions|version)/(?P<id>\d+)", where)
+        version_id = m.group("id") if m else None
+        m2 = re.search(r"/fix/(?P<inst>[A-Za-z0-9_-]{8,})", where)
+        return ("fortify", {
+            "host": host,
+            "versionId": version_id,
+            "instanceId": m2.group("inst") if m2 else None,
+            "source": "url",
+        })
 
     # --- Generic doc fallbacks ---------------------------------------------
     # Notion, Google Docs, GitHub markdown blob/wiki, gists. Useful as
@@ -228,5 +236,45 @@ for m in GRAYLOG_RE.finditer(text):
         "metadata": {"idType": id_type, "id": gid, "label": label},
     })
 
+# --- Fortify issue instance ids (label-based, not URL) ---------------------
+# A finding often arrives as a ticket written by a scanner-to-tracker bridge,
+# which quotes the instance id and the file:line but no SSC deep link  -  the
+# bridge knows the id, the reader does not need the URL, and the pipeline then
+# saw nothing to enrich. Same shape as the graylog entries: "url": null, the id
+# in metadata. Resolution to a project version happens in fetch-fortify.sh,
+# which is where the prefs live.
+FORTIFY_ID_RE = re.compile(
+    r"(?P<label>"
+    r"fortify[\s_-]*instance[\s_-]*id"
+    r"|issue[\s_-]*instance[\s_-]*id"
+    r"|fortify[\s_-]*id"
+    r")"
+    r"[\s*_~`]*[:=#]?[\s*_~`]*"
+    r"[\"']?(?P<id>(?=[A-Za-z0-9._-]*[0-9])[A-Za-z0-9][A-Za-z0-9._-]{15,})",
+    re.IGNORECASE,
+)
+already_linked = {
+    e["metadata"].get("instanceId")
+    for e in out
+    if e["type"] == "fortify" and e["metadata"].get("instanceId")
+}
+for m in FORTIFY_ID_RE.finditer(text):
+    fid = m.group("id").rstrip(".,;:!?)")
+    key = ("fortify", fid)
+    if not fid or key in seen or fid in already_linked:
+        continue
+    seen.add(key)
+    out.append({
+        "type": "fortify",
+        "url": None,
+        "metadata": {
+            "host": None,
+            "versionId": None,
+            "instanceId": fid,
+            "source": "label",
+            "label": m.group("label"),
+        },
+    })
+
 print(json.dumps(out))
 PY

package/pipeline/lib/fetch-crashlytics.sh

@@ -19,16 +19,21 @@
 # Output (stdout, single JSON object):
 #   {
 #     "fetchedAt": "<ISO8601>",
-#     "source": { "url": "<url|null>", "projectId": "...", "platform": "ios|android",
-#                 "bundle": "...", "issueId": "...", "sessionId": "<id|null>" },
-#     "issue": { "title": "...", "subtitle": "...", "type": "fatal|nonFatal|ANR",
-#                "occurrences": <n>, "impactedUsers": <n>,
-#                "firstSeen": "<ISO8601>", "lastSeen": "<ISO8601>",
-#                "topStackFrame": { "file": "...", "line": <n>, "symbol": "..." },
+#     "source": { "url": "<url|null>", "projectId": "...", "appId": "<resolved|null>",
+#                 "platform": "ios|android", "bundle": "...", "issueId": "...",
+#                 "sessionId": "<id|null>" },
+#     "issue": { "title": "...", "subtitle": "...", "type": "FATAL|NON_FATAL|ANR",
+#                "state": "...", "consoleUri": "<url|null>",
+#                "occurrences": <n>, "impactedUsers": <n>, "sessions": <n>,
+#                "firstSeenVersion": "<v|null>", "lastSeenVersion": "<v|null>",
+#                "topStackFrame": { "file": "<library>", "line": 0, "symbol": "..." },
+#                "stackTrace": [ { "library": "...", "symbol": "..." }, ... ],
 #                "topDevices": [ "<name>", ... ],
 #                "topOS": [ "<version>", ... ],
 #                "affectedAppVersions": [ "<version>", ... ] },
-#     "session": null | { "id": "...", "events": [ { "type": "...", "time": "...", "summary": "..." } ] }
+#     "session": null | { "id": "<eventId>", "time": "<ISO8601>",
+#                         "events": [ { "type": "breadcrumb|log", "time": "...",
+#                                       "summary": "...", "screen": "<name|null>" } ] }
 #   }
 #
 # Exit codes:
@@ -39,11 +44,13 @@
 #   5  project mismatch  -  SA JSON project_id != URL project (configuration bug)
 #
 # Notes:
-#   The Firebase Crashlytics REST surface (`firebasecrashlytics.googleapis.com`)
-#   is currently invitation-only in some regions. When the API returns 404 for
-#   a valid project the script exits 3 with reason "api-not-enabled"; the
-#   orchestrator surfaces this as "fetcher unavailable, advisory only" to
-#   keep the pipeline moving.
+#   Two v1alpha calls back this, because there is no get-issue-by-id endpoint:
+#   `reports/topIssues` for the summary and metrics, and `events?filter.issue.id`
+#   for the stack trace, device, OS and breadcrumbs. The opaque appId is resolved
+#   first through the Firebase Management API (`iosApps` / `androidApps`), since a
+#   console URL only ever carries the bundle id. Any failure exits 3 with a reason
+#   ("app-not-found", "crashlytics-unreachable"); the orchestrator surfaces that as
+#   "fetcher unavailable, advisory only" and keeps the pipeline moving.
 
 set -euo pipefail
 
@@ -279,80 +286,183 @@ fi
 # never appears in argv (argv is visible to ps).
 crashlytics_auth_cfg() { printf 'header = "Authorization: Bearer %s"\n' "$ACCESS_TOKEN"; }
 
-# Construct the appId in the form Firebase expects:
-#   ios:   ios:<bundleId>   →  api: /projects/<n>/apps/<bundleId> (looked up via list)
-#   android: android:<package>
-# In practice the appId is opaque (1:1234567890:ios:abcdef). We try the
-# Crashlytics v1alpha endpoint with the bundle as a fallback "app"  -  the API
-# accepts the package/bundle when scoped to the project.
-APP_REF="$PLATFORM:$BUNDLE"
-ISSUE_URL_API="https://firebasecrashlytics.googleapis.com/v1alpha/projects/$PROJECT_ID/apps/$APP_REF/issues/$ISSUE_ID"
-
-ISSUE_JSON=$(curl -sS --fail --max-time "$TIMEOUT" --connect-timeout 5 \
-  -K <(crashlytics_auth_cfg) -H "Accept: application/json" \
-  "$ISSUE_URL_API" 2>/dev/null || true)
-
-if [ -z "$ISSUE_JSON" ]; then
-  printf '{"status":"failed","reason":"api-not-enabled-or-app-mismatch","appRef":"%s","issueId":"%s"}\n' "$APP_REF" "$ISSUE_ID" >&2
+fb_get() {
+  curl -sS --fail --max-time "$TIMEOUT" --connect-timeout 5 \
+    -K <(crashlytics_auth_cfg) -H "Accept: application/json" "$1" 2>/dev/null || true
+}
+
+# The appId is opaque (1:1234567890:ios:abcdef) and cannot be derived from the
+# bundle id. Ask the Firebase Management API which app owns this bundle; the
+# console URL only ever carries the bundle.
+FB_MGMT="https://firebase.googleapis.com/v1beta1/projects/$PROJECT_ID"
+if [ "$PLATFORM" = "ios" ]; then
+  APPS_JSON=$(fb_get "$FB_MGMT/iosApps?pageSize=200")
+  MATCH_FIELD="bundleId"
+else
+  APPS_JSON=$(fb_get "$FB_MGMT/androidApps?pageSize=200")
+  MATCH_FIELD="packageName"
+fi
+
+APP_ID=$(APPS_IN="$APPS_JSON" WANT="$BUNDLE" FIELD="$MATCH_FIELD" python3 -c "
+import json, os
+try:
+    apps = (json.loads(os.environ['APPS_IN'] or '{}').get('apps') or [])
+except Exception:
+    apps = []
+want = (os.environ['WANT'] or '').lower()
+field = os.environ['FIELD']
+for a in apps:
+    if str(a.get(field) or '').lower() == want:
+        print(a.get('appId') or '')
+        break
+else:
+    # A single-app project needs no disambiguation; anything else stays unresolved
+    # rather than guessing at the wrong app.
+    print(apps[0].get('appId') or '' if len(apps) == 1 else '')
+" 2>/dev/null || true)
+
+if [ -z "$APP_ID" ]; then
+  printf '{"status":"failed","reason":"app-not-found","platform":"%s","bundle":"%s","projectId":"%s"}\n' \
+    "$PLATFORM" "$BUNDLE" "$PROJECT_ID" >&2
   exit 3
 fi
 
-SESSION_JSON=""
-if [ -n "$SESSION_ID" ]; then
-  SESSION_URL_API="$ISSUE_URL_API/sessions/$SESSION_ID"
-  SESSION_JSON=$(curl -sS --fail --max-time "$TIMEOUT" --connect-timeout 5 \
-    -K <(crashlytics_auth_cfg) -H "Accept: application/json" \
-    "$SESSION_URL_API" 2>/dev/null || true)
+CRASHLYTICS_APP="https://firebasecrashlytics.googleapis.com/v1alpha/projects/$PROJECT_ID/apps/$APP_ID"
+
+# There is no get-issue-by-id endpoint on v1alpha. The issue summary comes from
+# the topIssues report (filtered to the id we want) and the stack trace, device,
+# OS and breadcrumbs come from the issue's most recent event. An earlier version
+# of this script called /issues/<id> with a guessed "<platform>:<bundle>" app
+# reference; neither the path nor the reference exists, so every fetch failed and
+# reported it as "api-not-enabled".
+#
+# Two partial answers are treated as answers, not failures. A long-tail issue
+# outside the top 200 leaves the summary empty and the event still carries the
+# stack trace, and an event fetch that comes back empty still leaves the summary.
+# Only both being empty is a failure. A URL naming a specific session gets that
+# issue's most recent event instead: v1alpha exposes no per-session read, and
+# `source.sessionId` is passed through so the caller can see what was asked for.
+ISSUE_ID_ENC=$(ISSUE_IN="$ISSUE_ID" python3 -c "
+import os, urllib.parse
+print(urllib.parse.quote(os.environ['ISSUE_IN'], safe=''))
+" 2>/dev/null || printf '%s' "$ISSUE_ID")
+TOP_ISSUES_JSON=$(fb_get "$CRASHLYTICS_APP/reports/topIssues?pageSize=200")
+EVENT_JSON=$(fb_get "$CRASHLYTICS_APP/events?filter.issue.id=$ISSUE_ID_ENC&pageSize=1")
+
+if [ -z "$TOP_ISSUES_JSON" ] && [ -z "$EVENT_JSON" ]; then
+  printf '{"status":"failed","reason":"crashlytics-unreachable","appId":"%s","issueId":"%s"}\n' "$APP_ID" "$ISSUE_ID" >&2
+  exit 3
 fi
 
+ISSUE_JSON="$TOP_ISSUES_JSON"
+SESSION_JSON="$EVENT_JSON"
+
 SRC_URL="$URL" SRC_PROJECT="$PROJECT_ID" SRC_PLATFORM="$PLATFORM" SRC_BUNDLE="$BUNDLE" \
-SRC_ISSUE="$ISSUE_ID" SRC_SESSION="$SESSION_ID" \
+SRC_ISSUE="$ISSUE_ID" SRC_SESSION="$SESSION_ID" SRC_APPID="$APP_ID" \
 ISSUE_JSON_IN="$ISSUE_JSON" SESSION_JSON_IN="$SESSION_JSON" \
 python3 - <<'PY'
 import json, os, datetime
 
-issue = json.loads(os.environ["ISSUE_JSON_IN"] or "{}")
-session_raw = os.environ.get("SESSION_JSON_IN") or ""
-session = json.loads(session_raw) if session_raw else None
+def load(name):
+    raw = os.environ.get(name) or ""
+    try:
+        return json.loads(raw) if raw else {}
+    except Exception:
+        return {}
+
+issue_id = os.environ["SRC_ISSUE"]
+
+# topIssues returns groups: {"issue": {...}, "metrics": [{...}]}. Find ours.
+groups = load("ISSUE_JSON_IN").get("topIssues") or load("ISSUE_JSON_IN").get("issues") or []
+group = {}
+for g in groups:
+    if str(((g or {}).get("issue") or {}).get("id") or "") == issue_id:
+        group = g
+        break
+issue = (group.get("issue") or {}) if isinstance(group, dict) else {}
+metrics_list = (group.get("metrics") or []) if isinstance(group, dict) else []
+metrics = metrics_list[0] if metrics_list else {}
+
+def count(value):
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return 0
+
+events_body = load("SESSION_JSON_IN")
+events = events_body.get("events") or events_body.get("errorEvents") or []
+event = events[0] if events else {}
+
+exceptions = event.get("exceptions") or []
+top_exception = exceptions[0] if exceptions else {}
+frames = top_exception.get("frames") or []
+top_frame = frames[0] if frames else {}
+
+# v1alpha frames carry library + symbol, not file + line. Keeping the documented
+# key names with the library in "file" beats inventing a second shape for the
+# one consumer (Phase 1 prompt injection) that reads them.
+stack = [
+    {"library": f.get("library") or "", "symbol": f.get("symbol") or f.get("rawSymbol") or ""}
+    for f in frames[:40]
+]
+
+versions = []
+for v in (issue.get("firstSeenVersion"), issue.get("lastSeenVersion"),
+          ((event.get("version") or {}).get("displayName"))):
+    if v and v not in versions:
+        versions.append(v)
 
-def first(d, *keys, default=None):
-    for k in keys:
-        if isinstance(d, dict) and k in d:
-            return d[k]
-    return default
+timeline = []
+for crumb in (event.get("breadcrumbs") or [])[:25]:
+    screen = ((crumb.get("params") or {}).get("firebase_screen_class")) or None
+    timeline.append({
+        "type": "breadcrumb",
+        "time": crumb.get("eventTime") or "",
+        "summary": crumb.get("title") or "",
+        "screen": screen,
+    })
+for log in (event.get("logs") or [])[:25]:
+    message = log.get("message") or ""
+    if message:
+        timeline.append({"type": "log", "time": "", "summary": message, "screen": None})
 
-top_frame_raw = first(issue, "topFrame", "frame", default={}) or {}
 result = {
-    "fetchedAt": datetime.datetime.utcnow().isoformat() + "Z",
+    "fetchedAt": datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z"),
     "source": {
         "url": os.environ.get("SRC_URL") or None,
         "projectId": os.environ["SRC_PROJECT"],
+        "appId": os.environ.get("SRC_APPID") or None,
         "platform": os.environ["SRC_PLATFORM"],
         "bundle": os.environ["SRC_BUNDLE"],
-        "issueId": os.environ["SRC_ISSUE"],
+        "issueId": issue_id,
         "sessionId": os.environ.get("SRC_SESSION") or None,
     },
     "issue": {
-        "title": first(issue, "title", "errorTitle", "subtitle", default=""),
-        "subtitle": first(issue, "subtitle", "errorMessage", default=""),
-        "type": first(issue, "type", "errorType", default="unknown"),
-        "occurrences": first(issue, "occurrences", "eventCount", default=0),
-        "impactedUsers": first(issue, "impactedUsers", "userCount", default=0),
-        "firstSeen": first(issue, "firstSeen", "createTime", default=None),
-        "lastSeen": first(issue, "lastSeen", "updateTime", default=None),
+        "title": issue.get("title") or top_exception.get("title") or "",
+        "subtitle": issue.get("subtitle") or "",
+        "type": issue.get("errorType") or "unknown",
+        "state": issue.get("state") or "",
+        "consoleUri": issue.get("uri") or None,
+        "occurrences": count(metrics.get("eventsCount")),
+        "impactedUsers": count(metrics.get("impactedUsersCount")),
+        "sessions": count(metrics.get("sessionsCount")),
+        "firstSeenVersion": issue.get("firstSeenVersion") or None,
+        "lastSeenVersion": issue.get("lastSeenVersion") or None,
         "topStackFrame": {
-            "file": first(top_frame_raw, "fileName", "file", default=""),
-            "line": first(top_frame_raw, "lineNumber", "line", default=0),
-            "symbol": first(top_frame_raw, "symbol", "function", default=""),
+            "file": top_frame.get("library") or "",
+            "line": 0,
+            "symbol": top_frame.get("symbol") or top_frame.get("rawSymbol") or "",
         },
-        "topDevices": (issue.get("topDevices") or [])[:5],
-        "topOS": (issue.get("topOperatingSystems") or issue.get("topOS") or [])[:5],
-        "affectedAppVersions": (issue.get("affectedVersions") or issue.get("appVersions") or [])[:5],
+        "stackTrace": stack,
+        "topDevices": [d for d in [((event.get("device") or {}).get("displayName"))] if d],
+        "topOS": [o for o in [((event.get("operatingSystem") or {}).get("displayName"))] if o],
+        "affectedAppVersions": versions,
     },
     "session": ({
-        "id": os.environ.get("SRC_SESSION") or "",
-        "events": (session.get("events") if isinstance(session, dict) else None) or [],
-    } if session else None),
+        "id": event.get("eventId") or os.environ.get("SRC_SESSION") or "",
+        "time": event.get("eventTime") or "",
+        "events": timeline,
+    } if event else None),
 }
 print(json.dumps(result, ensure_ascii=False))
 PY

package/pipeline/lib/fetch-fortify.sh

@@ -5,13 +5,20 @@
 # emit a normalized JSON view that Phase 4 (Review) consumes as a
 # deterministic security gate.
 #
-# Two input forms:
+# Three input forms:
 #   ./fetch-fortify.sh <ssc-url>                         # parses versionId / issue from URL
 #   ./fetch-fortify.sh --version-id <id> [--issue <id>]  # explicit components
+#   ./fetch-fortify.sh --instance-id <id>                # instance id alone; the
+#       project version is resolved by searching prefs.global.fortify.versionIds
+#       in order. A finding often reaches a ticket as "Fortify Instance ID: <id>"
+#       with no SSC link at all - a scanner-to-tracker bridge knows the id, and
+#       the person reading the ticket never needed the URL.
 #
 # Required configuration:
 #   prefs.global.hosts.fortify            -  SSC host (e.g. ssc.example.com)
 #   prefs.global.keychainMapping.fortify  -  keychain key holding the API token
+#   prefs.global.fortify.versionIds[]     -  project versions searched, in order,
+#                                            when only an instance id is known
 #
 # Optional env:
 #   FORTIFY_TIMEOUT_SECONDS    default 25
@@ -39,7 +46,8 @@
 #   2  missing/expired credential (orchestrator handles the Save Flow)
 #   3  network/auth failure
 #   4  bad usage
-#   6  host not configured (prefs.global.hosts.fortify is empty)
+#   6  not configured (prefs.global.hosts.fortify empty, or an instance-id-only
+#      lookup with no prefs.global.fortify.versionIds to search)
 #
 # Phase 4 review gate contract:
 #   Critical > 0   → blocking=true, reason="critical-findings"
@@ -58,8 +66,9 @@ while [ $# -gt 0 ]; do
   case "$1" in
     --version-id) VERSION_ID="$2"; shift 2 ;;
     --issue)      ISSUE_ID="$2";   shift 2 ;;
+    --instance-id) ISSUE_ID="$2";  shift 2 ;;
     -h|--help)
-      echo "usage: $0 <ssc-url> | $0 --version-id <id> [--issue <id>]" >&2
+      echo "usage: $0 <ssc-url> | $0 --version-id <id> [--issue <id>] | $0 --instance-id <id>" >&2
       exit 4 ;;
     *)
       if [ -z "$URL" ]; then URL="$1"; shift; else
@@ -109,11 +118,30 @@ PY
   [ -z "$ISSUE_ID" ] && ISSUE_ID=$(printf '%s' "$PARSED" | cut -f2)
 fi
 
-if [ -z "$VERSION_ID" ]; then
-  echo "ERR: no Fortify version id (pass --version-id or use a URL containing /version/<id>)" >&2
+# An instance id with no version is resolvable: search the configured versions
+# below, once the token is in hand. Anything else is a usage error.
+if [ -z "$VERSION_ID" ] && [ -z "$ISSUE_ID" ]; then
+  echo "ERR: no Fortify version id (pass --version-id, --instance-id, or a URL containing /version/<id>)" >&2
   exit 4
 fi
 
+VERSION_CANDIDATES=""
+if [ -z "$VERSION_ID" ] && [ -f "$PREFS" ]; then
+  VERSION_CANDIDATES=$(python3 -c "
+import json
+try:
+    p = json.load(open('$PREFS'))
+    ids = p.get('global', {}).get('fortify', {}).get('versionIds') or []
+    print(' '.join(str(i) for i in ids if str(i).strip()))
+except Exception:
+    print('')
+")
+fi
+if [ -z "$VERSION_ID" ] && [ -z "$VERSION_CANDIDATES" ]; then
+  printf '%s\n' '{"status":"blocked","reason":"version-not-configured","service":"fortify","expected_pref":"global.fortify.versionIds"}' >&2
+  exit 6
+fi
+
 # Token via keychain mapping.
 TOKEN_KEY=""
 if [ -f "$PREFS" ]; then
@@ -202,6 +230,31 @@ fortify_get() {
   return 1
 }
 
+# Instance-id-only lookup: ask each configured version whether it owns the id.
+# First hit wins; instance ids are globally unique in practice, and searching a
+# handful of versions costs one bounded call each.
+if [ -z "$VERSION_ID" ]; then
+  for _cand in $VERSION_CANDIDATES; do
+    _probe=$(fortify_get "projectVersions/$_cand/issues?q=issueInstanceId:\"$ISSUE_ID\"&limit=1" 2>/dev/null || true)
+    _hit=$(printf '%s' "$_probe" | python3 -c "
+import sys, json
+try:
+    print('yes' if (json.load(sys.stdin).get('data') or []) else 'no')
+except Exception:
+    print('no')
+" 2>/dev/null || echo no)
+    if [ "$_hit" = "yes" ]; then
+      VERSION_ID="$_cand"
+      break
+    fi
+  done
+  if [ -z "$VERSION_ID" ]; then
+    echo "ERR: Fortify instance $ISSUE_ID not found in configured versions ($VERSION_CANDIDATES)" >&2
+    exit 3
+  fi
+fi
+unset _cand _probe _hit 2>/dev/null || true
+
 # Check fortify_get's actual exit status, not a string pattern over its
 # output - the old `case ... HTTP_AUTH_FAILED|*HTTP_4*)` only recognized
 # auth failures and 4xx. A dropped connection, timeout, or 5xx made

package/pipeline/multi-agent-refs/features/url-enrichment.md

@@ -31,7 +31,7 @@ Output schema (one array entry per URL  -  full contract in `~/.claude/lib/conte
   { "type": "swagger",     "url": "<url>", "metadata": { "format": "json|yaml|unknown" } },
   { "type": "confluence",  "url": "<url>", "metadata": { "host": "<host>", "pageId": "<id|null>", "spaceKey": "<key|null>" } },
   { "type": "crashlytics", "url": "<url>", "metadata": { "projectId": "...", "platform": "ios|android", "bundle": "...", "issueId": "...", "sessionId": "<id|null>" } },
-  { "type": "fortify",     "url": "<url>", "metadata": { "host": "<host>", "projectId": "<id|null>" } },
+  { "type": "fortify",     "url": "<url|null>", "metadata": { "host": "<host|null>", "versionId": "<id|null>", "instanceId": "<id|null>", "source": "url|label" } },
   { "type": "graylog",     "url": null,    "metadata": { "idType": "trx|conversation", "id": "...", "label": "..." } },
   { "type": "figma",       "url": "<url>", "metadata": { "kind": "design|make|board|slides", "fileKey": "...", "nodeId": "<id|null>" } },
   { "type": "generic-doc", "url": "<url>", "metadata": { "host": "<host>", "kind": "notion|google-docs|gist|github-doc" } }
@@ -47,16 +47,20 @@ URL pattern (caught by the extractor): `console.firebase.google.com/(u/[0-9]+/)?
 - Host is fixed (`console.firebase.google.com`); no `hosts.firebase` pref needed.
 - Token resolution: `prefs.global.keychainMapping.firebase` → `~/.claude/lib/credential-store.sh get "<key>" | base64 -d` → Service Account JSON. `project_id` read from decoded JSON  -  verify it matches the `<projectId>` from the URL; mismatch → warn, skip enrichment.
 - Exchange the SA JSON for a short-lived GCP access token (scope `https://www.googleapis.com/auth/firebase https://www.googleapis.com/auth/cloud-platform`) using `google-auth` (Python) or an inline JWT exchange (OpenSSL sign → `https://oauth2.googleapis.com/token`). Cache in-memory for the pipeline run only  -  never persist.
-- Fetch crash detail: `GET https://firebasecrashlytics.googleapis.com/v1alpha/projects/<projectId>/apps/<appId>/issues/<issueId>` (issue summary + top device + OS + impacted users + top stack frame). If `sessionId` present, also fetch `/sessions/<sessionId>` for the full session timeline.
-- Store as `state.crashContext = { projectId, appId, issueId, title, subtitle, impactedUsers, topDevices[], topOS[], topStackFrame, sessionTimeline?, fetchedAt }`.
+- Resolve the opaque `appId` first: `GET https://firebase.googleapis.com/v1beta1/projects/<projectId>/(iosApps|androidApps)?pageSize=200` and match `bundleId` (iOS) / `packageName` (Android) against the bundle from the URL. The console URL only carries the bundle, and the Crashlytics API only accepts the appId (`1:1234567890:ios:abcdef`). No match in a multi-app project → exit `3`, reason `app-not-found`; never guess at another app.
+- Fetch crash detail with two calls  -  v1alpha has no get-issue-by-id endpoint: `GET .../v1alpha/projects/<projectId>/apps/<appId>/reports/topIssues?pageSize=200` for the summary and metrics (filter to the issue id), and `GET .../apps/<appId>/events?filter.issue.id=<issueId>&pageSize=1` for the newest event, which carries the stack frames, device, OS and breadcrumbs.
+- Store as `state.crashContext = { projectId, appId, issueId, title, subtitle, type, state, occurrences, impactedUsers, sessions, firstSeenVersion, lastSeenVersion, topStackFrame, stackTrace[], topDevices[], topOS[], affectedAppVersions[], sessionTimeline?, fetchedAt }`.
 - Phase 1 Analysis prepends `state.crashContext` to the agent prompt under a **Known Crash Context** section (do not rediscover, use as ground truth).
 - Soft-fail: any network/auth error → log warning, continue pipeline without enrichment (ticket still gets manually analysed).
 
 ##### Step 1b.2  -  Fortify SSC deep fetch (runs when `type == "fortify"` present in `state.contextLinks[]`)
 
-URL pattern (caught by the extractor): `https://<prefs.global.hosts.fortify>/ssc/html/(ssc/)?version/<versionId>(/.*)?(#/version/<versionId>)?(/audit|/issues|/artifacts)?(\?issue=<issueId>)?` (plus the short-link variant `/ssc/html/ssc/version/<versionId>/fix/<issueInstanceId>`).
+Two entry shapes reach this step, and `metadata.source` says which:
 
-- Host comes from `prefs.global.hosts.fortify` (collected during Token Save Flow Step 3.5). URL host must match, else warn and skip (protects against pasting another company's Fortify URL by accident).
+- `source: "url"`  -  `https://<prefs.global.hosts.fortify>/ssc/html/(ssc/)?version/<versionId>(/.*)?(#/version/<versionId>)?(/audit|/issues|/artifacts)?(\?issue=<issueId>)?`, plus the short-link variant `/ssc/html/ssc/version/<versionId>/fix/<issueInstanceId>`. The version id is read from the path or the fragment, whichever the deployment uses.
+- `source: "label"`  -  a bare `Fortify Instance ID: <id>` (also `issue instance id`, `fortify id`; the id must be at least 16 characters and carry a digit, so a word following the label is never mistaken for a finding) with no URL anywhere in the text, so the entry carries `"url": null`, exactly like a graylog entry. This is the common shape when a scanner-to-tracker bridge opens the ticket: it knows the instance id and the file:line, and never writes the SSC link. Call `~/.claude/lib/fetch-fortify.sh --instance-id <id>`; it resolves the project version by asking each id in `prefs.global.fortify.versionIds` in order and taking the first hit. No `versionIds` configured → the fetcher exits `6` with reason `version-not-configured`; log the setup hint and skip. Configured but no version owns the id → exit `3`, reason `instance-not-found`, also a skip.
+
+- Host comes from `prefs.global.hosts.fortify` (collected during Token Save Flow Step 3.5). On the URL form the URL host must match, else warn and skip (protects against pasting another company's Fortify URL by accident); the label form has no host to disagree with.
 - Token resolution: `prefs.global.keychainMapping.fortify` → `~/.claude/lib/credential-store.sh get "<key>"` → API token. Auth header: `Authorization: FortifyToken <base64(token)>` (legacy tokens) or `Bearer <token>` (scoped tokens)  -  try Bearer first, fall back to FortifyToken on 401.
 - Fetch finding detail (VPN required; respect `vpnServices.fortify`):
   - Version: `GET /ssc/api/v1/projectVersions/<versionId>` → name, project name, current issue count.

package/pipeline/multi-agent-refs/phases/phase-0-init.md

@@ -100,14 +100,28 @@ Log the resolved tier in the agent log:
 
 Full chain definition, REST endpoints, URL parsing, canonical-component contract: `$HOME/.claude/rules/figma-pipeline.md` "MUST: Figma access - 3-tier fallback chain (BLOCKING, pipeline-wide)". Do not duplicate it here.
 
-#### Step 0.6 - Update check (advisory, opt-out via `prefs.global.updateCheck.enabled`)
+#### Step 0.6 - Update check (advisory by default, blocking on a required release)
 
-Run `bash $HOME/.claude/scripts/update-check.sh` (cached per `updateCheck.ttlHours`, default 24h; 3s-bounded; every failure path silent). Empty output → continue. Output `<local>|<latest>` means a newer version exists:
+Run `bash $HOME/.claude/scripts/update-check.sh` (cached per `updateCheck.ttlHours`, default 24h; 3s-bounded; every failure path silent; exit code always 0). Read stdout:
+
+| stdout | Meaning | Branch |
+|---|---|---|
+| empty | current, ahead of the registry, or the check could not run | continue |
+| `<local>\|<latest>` | a newer release exists | advisory |
+| `<local>\|<latest>\|force` | installed version is below `dist-tags.required` | **required  -  the run halts** |
+
+**Required branch (blocking).** Confirm with `bash $HOME/.claude/scripts/require-supported-version.sh` (exit 3 = halt; stdout `force|<local>|<latest>|<required>`, stderr the human block), then:
+
+- Log `→ update required: v<local> < required v<required> (halting)`.
+- Interactive and autopilot are identical  -  there is nothing to decide. Run the `/multi-agent:update` flow, then **stop the run** and ask the user, in `outputLanguage`, to re-issue the command. Do NOT continue into Phase 1: this run loaded its docs and scripts from the old version, which is the drift the floor exists to prevent. An update flow that itself fails halts too, never falls through.
+- `MULTI_AGENT_ALLOW_OUTDATED=1` is the only override (`updateCheck.enabled: false` silences the advisory nag, not this); when set, log `→ supported-version gate overridden` and continue. Exemptions, fail-open rules and how a floor is published: `$HOME/.claude/multi-agent-refs/rules.md` "Supported Version Gate".
+
+**Advisory branch (never blocks).**
 
 - **Interactive**: log `→ update available: v<local> -> v<latest>`, ask ONE AskUserQuestion  -  **Update now** (recommended) / **Continue without updating**. On *Update now* (or `updateCheck.autoUpdate: true`, which skips the question): run the `/multi-agent:update` flow, log `→ updated to v<latest>`, continue the run (note in the log: already-loaded phase docs finish this run on the old version; full effect next session). On *Continue*: no re-ask until the TTL expires.
 - **Autopilot**: never ask (zero-interaction contract). Log `→ update available: ... (log-only; run /multi-agent:update)` and continue  -  unless `autoUpdate: true`, then update silently first.
 
-Advisory  -  NEVER blocks. Must run BEFORE Step 6 (worktree creation) so an accepted update cannot mutate `~/.claude` under a mid-phase run.
+Both branches must run BEFORE Step 6 (worktree creation) so an accepted or forced update cannot mutate `~/.claude` under a mid-phase run.
 
 #### Step 0.7 - Token expiry pre-flight (runs before Step 1 fetch)
 

package/pipeline/multi-agent-refs/phases/phase-1-analysis.md

@@ -40,7 +40,7 @@ Exit 0 with empty output = pref off or no memory on disk  -  skip. Otherwise the
 # HEAD of the prompt: task-independent, byte-stable, so it caches.
 node $HOME/.claude/scripts/learnings-ledger.mjs profile 2>/dev/null
 # END of the prompt, after the task text: ranked against this task.
-node $HOME/.claude/scripts/learnings-ledger.mjs brief --max 20 \
+node $HOME/.claude/scripts/learnings-ledger.mjs brief --max "${prefs_learningsLedger_maxBriefEntries:-20}" \
   --task "$TASK_TITLE $TASK_DESCRIPTION" 2>/dev/null
 ```
 

package/pipeline/multi-agent-refs/phases/phase-4-review.md

@@ -36,7 +36,7 @@ This prevents a false "it built" claim with no log behind it. On exit 1, treat t
 
 ##### Gate 5  -  Fortify SSC findings (runs when `state.contextLinks[]` contains a `fortify` entry, or when `prefs.global.fortify.alwaysCheck === true`)
 
-If the task description referenced a Fortify version, `~/.claude/lib/fetch-fortify.sh` already populated `state.fortifyFinding` in Phase 0. Phase 4 reuses that payload and applies the deterministic gate:
+If the task description referenced a Fortify version, or named a bare issue instance id, `~/.claude/lib/fetch-fortify.sh` already populated `state.fortifyFinding` in Phase 0 (`alwaysCheck` needs `prefs.global.fortify.versionIds` to know what to scan). Phase 4 reuses that payload and applies the deterministic gate:
 
 ```bash
 gate=$(jq -r '.fortifyFinding.gateOutcome // empty' "$STATE_FILE")
@@ -423,7 +423,7 @@ Hits are relevance-ranked (`prefs.global.memoryRecall`); a finding matching noth
 **Rejected-preference brief (on by default via `prefs.global.learningsLedger.injectIntoTriage`).** Inject the durable rejected-preference list so triage does not re-accept a suggestion the team already rejected on this repo:
 
 ```bash
-node $HOME/.claude/scripts/learnings-ledger.mjs brief --max 20 \
+node $HOME/.claude/scripts/learnings-ledger.mjs brief --max "${prefs_learningsLedger_maxBriefEntries:-20}" \
   --task "$(jq -r '[.findings[].issue] | join(" ")' <<< "$MERGED_FINDINGS")" 2>/dev/null
 ```
 

package/pipeline/multi-agent-refs/phases/phase-5-test.md

@@ -19,8 +19,11 @@ case "$STACK" in
   *)                     SCAN_STACK="" ;;
 esac
 if [ -n "$SCAN_STACK" ] && [ "${prefs_testGap_enabled:-true}" = "true" ]; then
+  GAP_FLAGS=""
+  [ "${prefs_testGap_scanTree:-false}" = "true" ] && GAP_FLAGS="$GAP_FLAGS --scan-tree"
+  [ "${prefs_testGap_promoteSeverity:-false}" = "true" ] && GAP_FLAGS="$GAP_FLAGS --severity-promote"
   GAP_JSON=$(node $HOME/.claude/scripts/test-gap-scan.mjs \
-    --base "$BASE_BRANCH" --head HEAD --stack "$SCAN_STACK" 2>/dev/null)
+    --base "$BASE_BRANCH" --head HEAD --stack "$SCAN_STACK" $GAP_FLAGS 2>/dev/null)
   echo "$GAP_JSON" | node $HOME/.claude/scripts/validate-test-gap.mjs - >/dev/null 2>&1 || GAP_JSON=""
 fi
 ```
@@ -42,7 +45,6 @@ fi
 |---|---|
 | `composable_fun`, `view_struct`, `config_struct`, `interface`, `objc_export`, `public_proto` | important |
 | Other public API additions (`public_func`, `open_fun`, `named_export`, `default_export`, ...) | suggestion |
-| `--severity-promote` | forces every gap to `important` (used when audit-mode is on) |
 
 **Gating** (opt-in): if `prefs.testGap.blockingThreshold` is set and `gapBySeverity.important + gapBySeverity.blocking` exceeds it, Phase 5 surfaces the report as a Phase 4 rework finding and loops back. **Default off**  -  gaps render as advisory under "Test Gap Report" only.
 

package/pipeline/multi-agent-refs/rules.md

@@ -228,6 +228,17 @@ Violation: smoke gate `smoke-no-mcp-in-dev-phases.sh` fails the run.
 
 Memory: [[mcp-only-in-analysis]]
 
+## Supported Version Gate (pipeline-wide)
+
+The npm dist-tag `required` names the oldest version a user may run. Most releases do not set it, and nothing changes for them. A release that changes a contract a run depends on sets it, and then an older install is not "behind"  -  it is wrong, and its output would have to be redone.
+
+- **Where it runs**: Phase 0 Step 0.6 for every pipeline mode, and as the first step of any standalone command that reaches an external system or writes to a repo. The check is cached (`updateCheck.ttlHours`, default 24h) and shared, so a second command in the same window costs nothing.
+- **Exempt commands**  -  they are the remedy or cannot depend on a contract: `update`, `setup`, `uninstall`, `help`, `status`, `log`, `search`, `routines`, `forget`, `language`.
+- **How to check**: `bash $HOME/.claude/scripts/require-supported-version.sh`. Exit 0 = proceed. Exit 3 = halt: run the `/multi-agent:update` flow, then stop and ask the user to re-issue the command  -  never continue into the work on the freshly updated install, because this run's docs and scripts were already loaded from the old version.
+- **Fail-open**: offline, blocked registry, unknown local version or no `required` tag all exit 0. A version gate that bricks the pipeline on a flaky network is worse than the drift it guards.
+- **Not opt-out**: `updateCheck.enabled: false` silences the advisory "update available" nag, not this gate. The only override is `MULTI_AGENT_ALLOW_OUTDATED=1`, which exits 0 with a warning and must be logged in the run record when used.
+- **Setting the floor** (maintainers): `npm dist-tag add @<scope>/multi-agent-pipeline@<version> required`. It is set out of band, so a release can be promoted to required after the fact, and demoted the same way.
+
 ## Naming & Hygiene
 
 - **No task-sequence shortcuts in code.** "F1", "F2", "F3", "Feature1", "Step2" etc. are task-numbering UX labels in pickers / Confluence; they do not belong in identifiers, comments, log categories, commit messages, branch names, or file names. Use the full feature name (`FlightStatus`, `CheckoutFlow`, `PasswordReset`). Existing legacy references stay until a touch-up touches the same line; do not mass-rename without scope.

package/pipeline/schemas/prefs.schema.json

@@ -582,6 +582,24 @@
             }
           }
         },
+        "fortify": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "v15.14+ - Fortify SSC behaviour. The host and the API token live in global.hosts.fortify and global.keychainMapping.fortify; this object holds the two things that are neither. Phase 4 Gate 5 read `fortify.alwaysCheck` from the moment it shipped, but global was closed to additional properties and this object did not exist, so setting it failed validation and the gate could only ever run off a referenced URL.",
+          "properties": {
+            "alwaysCheck": {
+              "type": "boolean",
+              "default": false,
+              "description": "Run the Phase 4 Fortify gate on every run, not only when the task referenced a finding. Needs versionIds to know what to scan."
+            },
+            "versionIds": {
+              "type": "array",
+              "items": { "type": "string" },
+              "default": [],
+              "description": "SSC project version ids, searched in order. Used when a ticket names an issue instance id but no SSC URL (fetch-fortify.sh --instance-id), and by alwaysCheck. Ids are strings because SSC returns them as strings in some deployments."
+            }
+          }
+        },
         "reportChannels": {
           "type": "object",
           "additionalProperties": false,
@@ -749,12 +767,12 @@
         "updateCheck": {
           "type": "object",
           "additionalProperties": false,
-          "description": "v10.9+ - Phase 0 Step 0.6 advisory version check. Once per ttlHours window, a bounded (3s) registry read compares the installed version against dist-tags.latest. Newer version found: interactive modes ask 'Update now / Continue' (yes runs the /multi-agent:update flow, then the run continues); autopilot logs one line and never asks. Offline/failed checks are silent; the step never blocks the pipeline.",
+          "description": "v10.9+ - Phase 0 Step 0.6 version check. Once per ttlHours window, a bounded (3s) registry read compares the installed version against dist-tags.latest and dist-tags.required. Newer version found: interactive modes ask 'Update now / Continue' (yes runs the /multi-agent:update flow, then the run continues); autopilot logs one line and never asks; offline/failed checks are silent and never block. v15.14+ adds the required floor: when the installed version is BELOW dist-tags.required the run halts until /multi-agent:update ran - that branch is governed by no key here (enabled:false silences the advisory nag only), its single override is the env var MULTI_AGENT_ALLOW_OUTDATED=1, and it fails open on every undeterminable answer.",
           "properties": {
             "enabled": {
               "type": "boolean",
               "default": true,
-              "description": "Master switch. On by default - the cost is at most one 3s-bounded curl per ttlHours."
+              "description": "Master switch for the ADVISORY 'update available' prompt. On by default - the cost is at most one 3s-bounded curl per ttlHours. Does not disable the required-version floor; see the object description."
             },
             "ttlHours": {
               "type": "integer",

package/pipeline/schemas/token-budget.json

@@ -36,6 +36,6 @@
       "warn_tokens": 5600
     }
   },
-  "total_max_tokens": 53950,
-  "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. Total bumped 52200 -> 52700 at v14.1.0 after two more contracts landed: stack skill routing (Phase 3 pre-flight step 9) and worktree finalize (Phase 6 step 9). Compression came first, as always, and twice: 224 tokens out of Phase 3 by pointing its criteria-ledger and routing steps at their feature files instead of restating them, and 190 out of Phase 6 by moving the finalize contract into refs/features/worktree-finalize.md and leaving the invocation plus the exit-3 semantics. Both new contracts follow the pattern the earlier ones set: the phase doc carries the call and the decision, the feature file carries the reasoning, and the feature files are outside this budget because it loops only the eight phase-N-* keys. Every per-phase max still passes (phase-3 7677/8950, phase-6 5223/6150 and both under warn); only the aggregate needed room. Total bumped 52700 -> 52750 for the Phase 0 Step 3 branch-persistence correction: the step wrote the legacy `projects[].branches` while the TTL filter two sections below read `global.recentBranches`, and both spots named a `{name, lastUsed}` shape the schema rejects (`branch` required, `additionalProperties: false`), so the recent-branch picker option could never populate and a literal implementation would have failed prefs validation. Naming the right target, the right key and the legacy field to avoid costs 41 tokens over the one line it replaces. Compression came first and was applied three times to the replacement text itself, from 120 tokens down to 66, by moving the rationale out of the phase doc entirely: the reasoning now lives where it is enforced, in the migrate-prefs carry-forward comment and the smoke-pref-migration f7 block, leaving the phase doc with only the instruction. 50 was the smallest step that clears it; phase-0-init sits at 10893/12400, far under its own max, so this is purely an aggregate ceiling. v15.0.0: total 52750 -> 53100, the stack-skill tables in phase-1/2/4 now carry plugin-namespaced names (ai-<stack>-toolkit:<skill>) - functional prefixes, ~170 tokens. v15.10.0: total 53350 -> 53950 for the memory-recall + context-offload contracts (Phase 1 two-block durable-knowledge injection and its telemetry, Phase 3 build-log offload pipe, Phase 4 ranked prior art, offload pipe and recall telemetry). Compression came first and twice, taking the new prose from 1168 tokens to 580: the reasoning behind the two blocks lives in multi-agent-refs/prompt-assembly.md and the reasoning behind the offload filter lives in the offload-ref.sh header, both outside this budget, so the phase docs carry only the call, the pref that gates it and the one fact an agent cannot infer - that the evidence gate still reads the whole build log, so offloading changes what is read, never what counts as a verified pass. Every per-phase max still passes (phase-3 7985/8950, phase-4 12997/14750); phase-3 and phase-4 crossed their warn lines and are left amber on purpose, because that is the signal that those two docs are the next ones needing structural compression rather than another bump."
+  "total_max_tokens": 54400,
+  "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. Total bumped 52200 -> 52700 at v14.1.0 after two more contracts landed: stack skill routing (Phase 3 pre-flight step 9) and worktree finalize (Phase 6 step 9). Compression came first, as always, and twice: 224 tokens out of Phase 3 by pointing its criteria-ledger and routing steps at their feature files instead of restating them, and 190 out of Phase 6 by moving the finalize contract into refs/features/worktree-finalize.md and leaving the invocation plus the exit-3 semantics. Both new contracts follow the pattern the earlier ones set: the phase doc carries the call and the decision, the feature file carries the reasoning, and the feature files are outside this budget because it loops only the eight phase-N-* keys. Every per-phase max still passes (phase-3 7677/8950, phase-6 5223/6150 and both under warn); only the aggregate needed room. Total bumped 52700 -> 52750 for the Phase 0 Step 3 branch-persistence correction: the step wrote the legacy `projects[].branches` while the TTL filter two sections below read `global.recentBranches`, and both spots named a `{name, lastUsed}` shape the schema rejects (`branch` required, `additionalProperties: false`), so the recent-branch picker option could never populate and a literal implementation would have failed prefs validation. Naming the right target, the right key and the legacy field to avoid costs 41 tokens over the one line it replaces. Compression came first and was applied three times to the replacement text itself, from 120 tokens down to 66, by moving the rationale out of the phase doc entirely: the reasoning now lives where it is enforced, in the migrate-prefs carry-forward comment and the smoke-pref-migration f7 block, leaving the phase doc with only the instruction. 50 was the smallest step that clears it; phase-0-init sits at 10893/12400, far under its own max, so this is purely an aggregate ceiling. v15.0.0: total 52750 -> 53100, the stack-skill tables in phase-1/2/4 now carry plugin-namespaced names (ai-<stack>-toolkit:<skill>) - functional prefixes, ~170 tokens. v15.10.0: total 53350 -> 53950 for the memory-recall + context-offload contracts (Phase 1 two-block durable-knowledge injection and its telemetry, Phase 3 build-log offload pipe, Phase 4 ranked prior art, offload pipe and recall telemetry). Compression came first and twice, taking the new prose from 1168 tokens to 580: the reasoning behind the two blocks lives in multi-agent-refs/prompt-assembly.md and the reasoning behind the offload filter lives in the offload-ref.sh header, both outside this budget, so the phase docs carry only the call, the pref that gates it and the one fact an agent cannot infer - that the evidence gate still reads the whole build log, so offloading changes what is read, never what counts as a verified pass. Every per-phase max still passes (phase-3 7985/8950, phase-4 12997/14750); phase-3 and phase-4 crossed their warn lines and are left amber on purpose, because that is the signal that those two docs are the next ones needing structural compression rather than another bump. v15.13.0: total 53950 -> 54050 for the prefs-to-flag bridges. Five settings had shipped declared-but-inert: contextOffload.minLines and .tailLines (fixed in 15.11.0), learningsLedger.maxBriefEntries, and testGap.scanTree and .promoteSeverity - the last two declared in the schema AND implemented as flags in the scanner, with nothing in between reading the pref and passing the flag. Wiring three of them costs the phase docs 94 tokens, which is the wiring itself and not prose: two `--max` substitutions and a three-line GAP_FLAGS block. Compression came first and twice, as always: the rationale that would have sat in phase-5 now lives in the header of smoke-prefs-consumed.sh, the gate that makes this class fail a build instead of shipping, and a `--severity-promote` table row was dropped because the invocation above it now shows the flag and names the pref that triggers it, which the row did not. 100 was the smallest step that clears it. Every per-phase max still passes; phase-3 and phase-4 remain amber on purpose. v15.14.0: total 54050 -> 54400 for the supported-version gate. Phase 0 Step 0.6 stopped being purely advisory: a release can now publish an npm dist-tag `required` that names the oldest runnable version, and below it the run halts instead of nagging. What the phase doc has to carry is the part an agent cannot infer - the third stdout field, that the halt is identical in autopilot, and that the run must NOT continue on the freshly updated install because its docs were already loaded from the old version. Compression came first, as always, and took the new prose from 469 tokens to 337: the rationale for the floor, the exemption list, the fail-open rules and the `npm dist-tag add` recipe all moved to multi-agent-refs/rules.md \"Supported Version Gate\" (loaded by 25 commands, outside this budget) and to the header of require-supported-version.sh, leaving the phase doc with the call, the decision table and the halt. 350 was the smallest step that clears it. Every per-phase max still passes (phase-0-init 11230/12400); phase-3 and phase-4 remain amber on purpose."
 }

package/pipeline/scripts/README.md

@@ -24,7 +24,8 @@ Validate contracts. Each emits `══ <name> smoke: N passed, M failed ══`
 - `smoke-phase4-triage.sh`  -  Phase 4 reviewer → triage flow
 - `smoke-verify-by-test.sh`  -  Phase 4 Step 3.7 verify-by-test contract (v10.8.0)
 - `smoke-handoff-contract.sh`  -  phase-boundary structured handoff + handoff-first resume (v10.8.0)
-- `smoke-update-check.sh`  -  Phase 0 Step 0.6 advisory update-check contract (v10.9.0)
+- `smoke-update-check.sh`  -  Phase 0 Step 0.6 update-check + required-floor contract (v10.9.0, floor v15.14.0)
+- `smoke-context-links.sh`  -  context-link-extractor classification contract, all types (v15.14.0)
 
 ### Schema + state
 - `smoke-schema-validation.sh`  -  all JSON schemas validate
@@ -80,6 +81,8 @@ Shell scripts invoked during pipeline execution.
 - `scan-skills.sh`  -  backs `/multi-agent:scan`
 - `benchmark-phase-0.sh`  -  Phase 0 perf harness
 - `github-ssh-setup.sh`  -  first-run SSH key setup helper
+- `update-check.sh`  -  cached registry read (`dist-tags.latest` + `dist-tags.required`); always exit 0
+- `require-supported-version.sh`  -  turns the `force` signal into exit 3; fails open offline
 - `sync-parity-check.sh`  -  manual parity verification helper
 
 ## Node.js helpers (54 `.mjs` files)

package/pipeline/scripts/require-supported-version.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# require-supported-version.sh  -  turn the update-check "force" signal into an
+# exit code (Phase 0 Step 0.6, pipeline-wide supported-version gate).
+#
+# update-check.sh stays advisory by contract: it always exits 0 and the caller
+# decides. This wrapper is that decision for shell callers. It runs the same
+# cached check (one shared cache file, so it costs nothing extra) and:
+#
+#   exit 0  -  the run may proceed (current, merely-behind, offline, or the
+#              registry has no `required` floor)
+#   exit 3  -  the installed version is BELOW dist-tags.required; the caller
+#              must halt and tell the user to run /multi-agent:update
+#
+# Fail-open is deliberate and load-bearing. A floor is only ever enforced from a
+# registry answer we actually received: offline, a blocked registry, a missing
+# `required` tag or an undeterminable local version all exit 0. A version gate
+# that bricks the pipeline on a flaky network is worse than the drift it guards.
+#
+# Emergency override: MULTI_AGENT_ALLOW_OUTDATED=1 exits 0 with a loud stderr
+# warning. It exists so a broken release cannot strand someone mid-incident; it
+# is not a supported way to stay behind, and the caller logs that it was used.
+#
+# `prefs.global.updateCheck.enabled: false` does NOT disable this gate  -  that
+# switch silences the advisory nag. A floor is only published for a release that
+# changes a contract, and opting out of it would only fail later and less
+# legibly.
+#
+# stdout on exit 3 (one machine-readable line, then a human block on stderr):
+#   force|<local>|<latest>|<required>
+#
+# Usage:
+#   bash pipeline/scripts/require-supported-version.sh || halt
+#   bash pipeline/scripts/require-supported-version.sh --local 15.0.0
+
+set -uo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+CHECK="$HERE/update-check.sh"
+[ -f "$CHECK" ] || CHECK="$HOME/.claude/scripts/update-check.sh"
+[ -f "$CHECK" ] || exit 0  # no checker installed -> nothing to enforce
+
+out=$(bash "$CHECK" "$@" 2>/dev/null) || exit 0
+case "$out" in
+  *"|force") ;;
+  *) exit 0 ;;
+esac
+
+local_v="${out%%|*}"
+rest="${out#*|}"
+latest_v="${rest%%|*}"
+# Second call is served from the same fresh cache the first one just used.
+required_v=$(bash "$CHECK" --print-required "$@" 2>/dev/null | tr -d '[:space:]')
+[ -n "$required_v" ] || required_v="$latest_v"
+
+if [ "${MULTI_AGENT_ALLOW_OUTDATED:-}" = "1" ]; then
+  printf 'WARNING: MULTI_AGENT_ALLOW_OUTDATED=1 - running v%s below the required floor. Update as soon as this run ends.\n' \
+    "$local_v" >&2
+  exit 0
+fi
+
+printf 'force|%s|%s|%s\n' "$local_v" "$latest_v" "$required_v"
+cat >&2 <<MSG
+
+  This release line is required, not optional.
+  Installed: v${local_v}   Required: v${required_v} or newer   Latest: v${latest_v}
+
+  Run /multi-agent:update, then start this command again.
+
+MSG
+exit 3

package/pipeline/scripts/update-check.sh

@@ -1,21 +1,38 @@
 #!/usr/bin/env bash
-# update-check.sh  -  cached advisory version check (Phase 0 Step 0.6)
+# update-check.sh  -  cached version check (Phase 0 Step 0.6)
 #
 # Compares the locally installed pipeline version against the npm registry's
-# dist-tags.latest. Cached with a TTL so at most one network call per TTL
-# window; the call is bounded by a short timeout and every failure path is
-# silent  -  this script NEVER blocks or fails the pipeline.
+# dist-tags. Cached with a TTL so at most one network call per TTL window; the
+# call is bounded by a short timeout and every failure path is silent  -  this
+# script NEVER blocks and NEVER fails the pipeline (exit code is always 0).
 #
-# stdout: "<local>|<latest>" when a newer version exists, nothing otherwise.
-# Exit code: always 0 (advisory contract).
+# Two tags are read:
+#   dist-tags.latest    newest published release  -> advisory "update available"
+#   dist-tags.required  minimum version a user may run -> forced-update signal
+#
+# `required` is opt-in per release and set out of band, without republishing:
+#   npm dist-tag add @<scope>/multi-agent-pipeline@<version> required
+# Absent tag = no floor = advisory-only behaviour, exactly as before.
+#
+# stdout:
+#   ""                        already current (or local ahead of the registry)
+#   "<local>|<latest>"        a newer version exists  -  advisory
+#   "<local>|<latest>|force"  local is BELOW dist-tags.required  -  the caller
+#                             must halt the run until /multi-agent:update ran
+# Exit code: always 0. Enforcement is the caller's job  -  see
+# pipeline/scripts/require-supported-version.sh, which turns "force" into a
+# non-zero exit for shell callers.
 #
 # Usage:
 #   bash pipeline/scripts/update-check.sh                 # auto-detect local version
 #   bash pipeline/scripts/update-check.sh --local 10.8.0  # explicit local version
 #   bash pipeline/scripts/update-check.sh --ttl-hours 24  # cache window (default 24)
 #   bash pipeline/scripts/update-check.sh --force         # ignore cache
+#   bash pipeline/scripts/update-check.sh --print-required  # emit the floor only
 #
-# Cache file: ~/.claude/logs/multi-agent/.update-check ("epoch|latest").
+# Cache file: ~/.claude/logs/multi-agent/.update-check ("epoch|latest|required").
+# A legacy two-field cache ("epoch|latest") still reads  -  the missing third
+# field means "no floor known", never "no floor exists".
 # Registry read is a plain curl  -  never `npm view` (a user-level .npmrc scope
 # mapping can silently reroute npm to a different registry; curl cannot lie).
 
@@ -27,12 +44,14 @@ CACHE_FILE="${UPDATE_CHECK_CACHE:-$HOME/.claude/logs/multi-agent/.update-check}"
 TTL_HOURS=24
 LOCAL_VERSION=""
 FORCE=0
+PRINT_REQUIRED=0
 
 while [ $# -gt 0 ]; do
   case "$1" in
     --local) LOCAL_VERSION="${2:-}"; shift 2 ;;
     --ttl-hours) TTL_HOURS="${2:-24}"; shift 2 ;;
     --force) FORCE=1; shift ;;
+    --print-required) PRINT_REQUIRED=1; shift ;;
     *) shift ;;
   esac
 done
@@ -58,35 +77,67 @@ if [ -z "$LOCAL_VERSION" ]; then
 fi
 [ -z "$LOCAL_VERSION" ] && exit 0  # cannot determine local version -> silent no-op
 
+# Highest of two dotted versions; ties resolve to the second argument.
+highest_of() {
+  printf '%s\n%s\n' "$1" "$2" | sort -t. -k1,1n -k2,2n -k3,3n | tail -1
+}
+
 now=$(date +%s)
 latest=""
+required=""
 
 # Fresh cache?
 if [ "$FORCE" -eq 0 ] && [ -f "$CACHE_FILE" ]; then
   cached_epoch=$(cut -d'|' -f1 "$CACHE_FILE" 2>/dev/null || echo 0)
   cached_latest=$(cut -d'|' -f2 "$CACHE_FILE" 2>/dev/null || echo "")
+  cached_required=$(cut -d'|' -f3 "$CACHE_FILE" 2>/dev/null || echo "")
   case "$cached_epoch" in (*[!0-9]*|"") cached_epoch=0 ;; esac
   if [ $((now - cached_epoch)) -lt $((TTL_HOURS * 3600)) ] && [ -n "$cached_latest" ]; then
     latest="$cached_latest"
+    required="$cached_required"
   fi
 fi
 
 # Stale or missing cache -> one bounded registry call (silent on any failure).
+# The abbreviated packument carries dist-tags at a quarter of the full document.
 if [ -z "$latest" ]; then
-  latest=$(curl -sm 3 "$REGISTRY_URL" 2>/dev/null \
-    | { command -v jq >/dev/null 2>&1 && jq -r '."dist-tags".latest // empty' \
-        || sed -n 's/.*"latest":"\([^"]*\)".*/\1/p'; } | head -1) || true
+  tags=$(curl -sm 3 -H 'Accept: application/vnd.npm.install-v1+json' "$REGISTRY_URL" 2>/dev/null \
+    | { if command -v jq >/dev/null 2>&1; then
+          jq -r '[."dist-tags".latest // "", ."dist-tags".required // ""] | join("|")'
+        else
+          node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{const t=JSON.parse(s)["dist-tags"]||{};process.stdout.write(`${t.latest||""}|${t.required||""}`)}catch{}})'
+        fi; } ) || true
+  latest="${tags%%|*}"
+  required="${tags#*|}"
+  [ "$required" = "$tags" ] && required=""
   [ -z "$latest" ] && exit 0
   mkdir -p "$(dirname "$CACHE_FILE")" 2>/dev/null || exit 0
-  printf '%s|%s\n' "$now" "$latest" > "$CACHE_FILE" 2>/dev/null || true
+  printf '%s|%s|%s\n' "$now" "$latest" "$required" > "$CACHE_FILE" 2>/dev/null || true
+fi
+
+# A floor above latest is a publisher mistake (the `required` tag was moved to a
+# version that `latest` no longer covers). Clamp rather than brick every user.
+if [ -n "$required" ] && [ "$(highest_of "$required" "$latest")" != "$latest" ]; then
+  required="$latest"
+fi
+
+if [ "$PRINT_REQUIRED" -eq 1 ]; then
+  printf '%s\n' "$required"
+  exit 0
+fi
+
+# Forced update: local sorts strictly BELOW the required floor.
+if [ -n "$required" ] && [ "$LOCAL_VERSION" != "$required" ] \
+   && [ "$(highest_of "$LOCAL_VERSION" "$required")" = "$required" ]; then
+  printf '%s|%s|force\n' "$LOCAL_VERSION" "$latest"
+  exit 0
 fi
 
 [ "$latest" = "$LOCAL_VERSION" ] && exit 0
 
 # Update available only when latest sorts strictly ABOVE local (a dev machine
 # running ahead of the registry must not see an "update" prompt).
-highest=$(printf '%s\n%s\n' "$LOCAL_VERSION" "$latest" | sort -t. -k1,1n -k2,2n -k3,3n | tail -1)
-if [ "$highest" = "$latest" ]; then
+if [ "$(highest_of "$LOCAL_VERSION" "$latest")" = "$latest" ]; then
   printf '%s|%s\n' "$LOCAL_VERSION" "$latest"
 fi
 exit 0