@ainova-systems/intelligence 0.11.0-rc.1

package/engine/scripts/lib/migrations.sh

@@ -0,0 +1,708 @@
+#!/bin/bash
+# shellcheck disable=SC2034  # IS_RC_*/IS_MIGRATED/IS_VERSION_KEY are the public bash↔skill contract, consumed by the scripts that source this lib
+# intelligence-sync: versioned migrations — breaking-change update architecture
+# Source this file — never execute directly. Requires layout.sh already
+# sourced (uses no globals from it directly; callers pass paths explicitly).
+#
+# THE MODEL (how breaking changes are shipped & absorbed):
+#   * The project carries a version stamp (.intelligence-sync-version); the
+#     engine carries scripts/VERSION. The gap stamped → engine IS the set of
+#     breaking changes to apply.
+#   * Each breaking structural change ships as ONE registered migrate_to_<ver>
+#     in MIGRATIONS (ordered, ascending). The dispatcher applies only the
+#     pending ones (target version > stamped), in order, so a project several
+#     versions behind is walked forward step by step, stamping after each.
+#   * Every migrate_to_<ver> obeys the contract: precondition → stage → verify
+#     postcondition (sentinel) → commit → cleanup; idempotent; fail-closed
+#     (never destroy prior state before the replacement is verified).
+#   * A stale engine refuses a project stamped newer than it knows
+#     (ahead-of-engine). sync.sh refuses to sync across an un-applied gap
+#     (needs-update). The intelligence-update SKILL is the brain: it reads the
+#     CHANGELOG across the gap, surfaces breaking items, runs this chain, and
+#     verifies after.
+#
+# Naming carries the target version (bash forbids dots → underscores):
+#   migrate_to_0_3_1   flat <umbrella>/scripts → modular <umbrella>/sync/
+# Future breaking changes: append a new suffix to MIGRATIONS and add the
+# matching migrate_to_<ver> — nothing here is rewritten or reordered.
+
+# Ordered (ascending) list of migration target versions. Append only.
+MIGRATIONS=( "0_3_1" "0_7_0" "0_10_0" )
+
+# The applied-schema version is a managed key in config.yaml — NOT a dotfile,
+# NOT scripts/VERSION. config.yaml is what most future breaking changes will
+# reshape, so the schema version lives with what it versions.
+#
+# INVARIANT: this key is a PERMANENT, format-stable, top-level scalar contract.
+# Migrations may restructure anything else in config.yaml, but never the name,
+# location, or shape of this key — so any engine (however old/new) can always
+# read "what schema is this?" before parsing the rest. The bootstrap/INIT flow
+# must emit it for fresh projects and preserve it on re-bootstrap.
+IS_VERSION_KEY="sync_version"
+
+# "0_3_1" → "0.3.1"
+_mig_ver_dotted() { printf '%s' "$1" | tr '_' '.'; }
+
+# read_engine_stamp <config_file> → applied version, or "" if absent.
+read_engine_stamp() {
+    local cf="$1"
+    [ -f "$cf" ] || return 0
+    awk -v k="$IS_VERSION_KEY" '
+        { sub(/\r$/, "") }
+        $0 ~ "^" k ":" {
+            v = $0; sub(/^[^:]*:[[:space:]]*/, "", v)
+            gsub(/^["\047]|["\047][[:space:]]*$/, "", v)
+            sub(/[[:space:]]+$/, "", v)
+            print v; exit
+        }
+    ' "$cf"
+}
+
+# stamp_version <config_file> <version> — idempotent, transactional upsert of
+# the contract key (replace in place if present, else append at top level).
+# No-op if config.yaml does not exist yet (pre-bootstrap).
+stamp_version() {
+    local cf="$1" ver="$2"
+    [ -f "$cf" ] || return 0
+    local tmp="$cf.ver.tmp"
+    awk -v k="$IS_VERSION_KEY" -v val="$ver" '
+        { sub(/\r$/, "") }
+        $0 ~ "^" k ":" { print k ": \"" val "\""; found=1; next }
+        { print }
+        END { if (!found) print k ": \"" val "\"" }
+    ' "$cf" > "$tmp" && mv "$tmp" "$cf"
+}
+
+# --- bash ↔ skill status contract -------------------------------------------
+# Bash is the deterministic, fail-closed core: it never guesses. Any state it
+# cannot resolve safely is reported as a machine-readable status line on
+# stdout plus a stable exit code, and the intelligence-update SKILL (the
+# intelligent layer) decides what to do. Codes are part of the public
+# contract — do not renumber.
+IS_RC_OK=0                  # success (synced / migrated / nothing to do)
+IS_RC_ERROR=1               # generic error
+IS_RC_CONFIG_MISSING=2      # no config.yaml found
+IS_RC_AMBIGUOUS=3           # conflicting state; skill/human-only — bash never emits this itself, it is reserved for the intelligence-update skill to report
+IS_RC_AHEAD=4               # project stamped newer than this engine understands
+IS_RC_ABORTED_INCOMPLETE=5  # staged module incomplete; legacy left intact
+IS_RC_NEEDS_UPDATE=6        # pending breaking changes (stamp < engine) — run the update flow first
+
+# is_status <code-name> [detail] — emit one parseable line for the skill.
+is_status() {
+    local code="$1" detail="${2:-}"
+    if [ -n "$detail" ]; then
+        echo "IS_STATUS=$code IS_DETAIL=$detail"
+    else
+        echo "IS_STATUS=$code"
+    fi
+}
+
+# Engine version = scripts/VERSION next to this lib (BASH_SOURCE works when
+# sourced). Empty if unreadable — callers treat empty as "no guard".
+engine_version() {
+    local vf
+    vf="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." 2>/dev/null && pwd)/VERSION"
+    [ -f "$vf" ] && tr -d ' \t\r\n' < "$vf"
+}
+
+# _ver_gt A B → true if semver A is strictly greater than B (numeric x.y.z;
+# any non-numeric suffix on a field is ignored). Missing fields = 0.
+# Pre-release/build metadata ordering is intentionally NOT handled — the
+# stamp only ever stores plain x.y.z, so this is sufficient.
+_ver_gt() {
+    local a="$1" b="$2" i ai bi
+    local -a A B
+    IFS=. read -r -a A <<< "$a"
+    IFS=. read -r -a B <<< "$b"
+    for i in 0 1 2; do
+        ai=$(printf '%s' "${A[$i]:-0}" | tr -cd '0-9'); ai=${ai:-0}
+        bi=$(printf '%s' "${B[$i]:-0}" | tr -cd '0-9'); bi=${bi:-0}
+        if [ "$((10#$ai))" -gt "$((10#$bi))" ]; then return 0; fi
+        if [ "$((10#$ai))" -lt "$((10#$bi))" ]; then return 1; fi
+    done
+    return 1
+}
+
+# check_version_compat <config_file> — refuse to operate on a project whose
+# config schema is stamped newer than this engine knows (a stale engine must
+# never rewrite/sync a newer schema). Emits status + returns IS_RC_AHEAD on
+# conflict, else 0.
+check_version_compat() {
+    local cf="$1" stamp eng
+    stamp="$(read_engine_stamp "$cf")"
+    [ -n "$stamp" ] || return 0
+    eng="$(engine_version)"
+    [ -n "$eng" ] || return 0
+    if _ver_gt "$stamp" "$eng"; then
+        is_status ahead-of-engine "stamp=$stamp engine=$eng"
+        echo "  ERROR: project stamped $stamp but this engine is $eng — refusing." >&2
+        echo "         Update the engine first (the intelligence-update skill handles this)." >&2
+        return "$IS_RC_AHEAD"
+    fi
+    return 0
+}
+
+# Set by migrate_to_* when it actually performed work this run, so the caller
+# can report `migrated` vs `ok`.
+IS_MIGRATED=0
+
+# Idempotent directory replace (rsync if present, else rm+cp). Returns non-zero
+# if any step fails: a migration runs in an `||` context, so `set -e` is off and
+# an unchecked copy failure (permissions, full disk) would otherwise sail on to
+# the cleanup and delete the legacy files it never actually copied.
+_mig_copy_dir() {
+    local src="$1" dst="$2"
+    [ -d "$src" ] || return 0
+    if command -v rsync >/dev/null 2>&1; then
+        mkdir -p "$dst" || return 1
+        rsync -a --delete "$src/" "$dst/" || return 1
+    else
+        rm -rf "$dst" || return 1
+        mkdir -p "$(dirname "$dst")" || return 1
+        cp -r "$src" "$dst" || return 1
+    fi
+    return 0
+}
+
+_mig_copy_file() {
+    local src="$1" dst="$2"
+    [ -f "$src" ] || return 0
+    mkdir -p "$(dirname "$dst")" || return 1
+    cp "$src" "$dst" || return 1
+    return 0
+}
+
+# Repo-root-relative path of the umbrella — the prefix every `sources:` entry is
+# resolved against (resolve_source_dir does "$repo_root/$entry"). `basename` is
+# only correct when the umbrella sits directly at the repo root; a nested one
+# (`platform/intelligence/`) would yield `intelligence/...` and register a source
+# that resolves nowhere. Ask git for the real prefix, and fall back to basename
+# when there is no git (a tarball checkout), which is the flat case anyway.
+_mig_umbrella_rel() {
+    local umbrella="$1" prefix=""
+    if command -v git >/dev/null 2>&1; then
+        prefix="$(git -C "$umbrella" rev-parse --show-prefix 2>/dev/null || true)"
+    fi
+    prefix="${prefix%/}"
+    if [ -n "$prefix" ]; then
+        printf '%s' "$prefix"
+    else
+        printf '%s' "$(basename "$umbrella")"
+    fi
+}
+
+# True (0) if <entry> is already listed anywhere in config.yaml (quoted or bare).
+_mig_has_source() {
+    local config="$1" entry="$2"
+    [ -f "$config" ] || return 1
+    grep -Fq -- "\"$entry\"" "$config" || grep -Fq -- "- $entry" "$config"
+}
+
+# Idempotently add one entry to `sources.<section>` in config.yaml. No backup —
+# the edit is a single additive list item. Name-agnostic: the caller passes the
+# already-resolved "<base>/<module>/<dir>". If the section does not exist under
+# `sources:` yet, it is created with the entry as its only item.
+# Usage: _mig_add_source <config.yaml> <rules|agents|skills> <entry>
+_mig_add_source() {
+    local config="$1" section="$2" entry="$3"
+    if [ ! -f "$config" ]; then
+        echo "  [migrate] no config.yaml at $config — add this under sources.$section manually:" >&2
+        echo "      - \"$entry\"" >&2
+        return 0
+    fi
+    _mig_has_source "$config" "$entry" && return 0
+
+    local tmp="$config.mig.tmp"
+    awk -v section="$section" -v entry="$entry" '
+        function emit() { print "    - \"" entry "\""; inserted = 1 }
+        function close_here() {
+            if (in_sec && !inserted) { emit(); in_sec = 0 }
+        }
+        { sub(/\r$/, "") }
+        # Top-level key: ends the sources block (and any open section in it).
+        /^[A-Za-z]/ {
+            close_here()
+            # `sources:` existed but never declared this section — declare it.
+            if (in_src && !inserted) { print "  " section ":"; emit() }
+            in_sec = 0
+            in_src = ($0 ~ /^sources:[[:space:]]*$/) ? 1 : 0
+            print; next
+        }
+        in_src && $0 ~ "^  " section ":[[:space:]]*$" { print; in_sec = 1; next }
+        # Another 2-space sub-key ends this section.
+        in_src && /^  [A-Za-z]/ { close_here(); print; next }
+        in_sec && /^    -[[:space:]]/ { print; next }     # existing item
+        in_sec && /^[[:space:]]*$/ { close_here(); print; next }
+        { print }
+        END {
+            close_here()
+            if (in_src && !inserted) { print "  " section ":"; emit() }
+        }
+    ' "$config" > "$tmp" && mv "$tmp" "$config"
+}
+
+# Back-compat shim: 0.3.1 shipped with this name, and a shipped migration is
+# never rewritten.
+_mig_add_skill_source() {
+    _mig_add_source "$1" "skills" "$2"
+}
+
+# --- migrate_to_0_3_1 -------------------------------------------------------
+# Pre-0.3.1: engine + meta-skills + INIT.md + docs lived flat under the
+# umbrella, mixed with project content. 0.3.1: they move into the self-
+# contained module subfolder <umbrella>/<module>/. Project content
+# (rules/, agents/, non-meta skills/, config.yaml) is never moved or deleted.
+#
+# Ownership of meta-skills is by the reserved `intelligence-` prefix. A
+# project skill must not use that prefix (documented in CONVENTIONS.md).
+#
+# migrate_to_0_3_1 <umbrella_dir> <module_name> [<upstream_module_dir>]
+#   upstream_module_dir set  → authoritative content source (update.sh)
+#   upstream_module_dir empty → relocate local legacy files (sync.sh, offline)
+migrate_to_0_3_1() {
+    local umbrella="$1" module_name="$2" upstream="${3:-}"
+    local module_dir="$umbrella/$module_name"
+    local s
+
+    # Precondition: any legacy upstream-owned artifact directly under the
+    # umbrella. None ⇒ already modular or fresh ⇒ idempotent no-op.
+    #
+    # The flat engine is identified by its entry script `scripts/sync.sh`, never
+    # by the bare `scripts/` directory: a project may legitimately own
+    # <umbrella>/scripts/ for its own tooling, and mistaking it for the engine
+    # would relocate then delete the project's code (the postcondition below
+    # already treats scripts/sync.sh as the engine sentinel).
+    local has_legacy=0
+    local legacy_engine=0
+    [ -f "$umbrella/scripts/sync.sh" ] && legacy_engine=1
+    [ "$legacy_engine" -eq 1 ] && has_legacy=1
+    [ -e "$umbrella/INIT.md" ] && has_legacy=1
+    [ -d "$umbrella/docs" ] && has_legacy=1
+    for s in "$umbrella"/skills/intelligence-*; do
+        [ -e "$s" ] && { has_legacy=1; break; }
+    done
+    # Already modular / fresh ⇒ nothing to relocate. Stamping is owned by the
+    # dispatcher (run_migrations), not here.
+    if [ "$has_legacy" -eq 0 ]; then
+        return 0
+    fi
+
+    echo "  [migrate 0.3.1] legacy flat layout detected — relocating engine into '$module_name/'"
+    IS_MIGRATED=1
+    mkdir -p "$module_dir"
+
+    # Authoritative content source: the fresh upstream clone when update.sh
+    # supplies one, else the project's own legacy files (sync.sh, offline).
+    local src_root="$umbrella"
+    if [ -n "$upstream" ] && [ -d "$upstream" ]; then
+        src_root="$upstream"
+    fi
+
+    # Stage. Every copy's exit status is captured — see _mig_copy_dir.
+    local copy_rc=0
+    _mig_copy_dir  "$src_root/scripts" "$module_dir/scripts" || copy_rc=1
+    _mig_copy_file "$src_root/INIT.md" "$module_dir/INIT.md" || copy_rc=1
+    _mig_copy_dir  "$src_root/docs"    "$module_dir/docs"    || copy_rc=1
+    mkdir -p "$module_dir/skills" || copy_rc=1
+    for s in "$src_root"/skills/intelligence-*; do
+        [ -d "$s" ] || continue
+        _mig_copy_dir "$s" "$module_dir/skills/$(basename "$s")" || copy_rc=1
+    done
+
+    # Verify the FULL postcondition BEFORE any destructive cleanup: every
+    # artifact present at the source must now exist in the module, non-empty.
+    # This is the crash-safety gate — a half-populated module must never
+    # trigger legacy deletion, so two script sentinels are not enough.
+    local missing=""
+    [ "$copy_rc" -eq 0 ] || missing="$missing copy-failed"
+    [ -s "$module_dir/scripts/sync.sh" ] || missing="$missing scripts/sync.sh"
+    [ -s "$module_dir/scripts/lib/common.sh" ] || missing="$missing scripts/lib/common.sh"
+    if [ -f "$src_root/INIT.md" ] && [ ! -s "$module_dir/INIT.md" ]; then
+        missing="$missing INIT.md"
+    fi
+    if [ -d "$src_root/docs" ] && [ -z "$(find "$module_dir/docs" -type f 2>/dev/null | head -1)" ]; then
+        missing="$missing docs/"
+    fi
+    for s in "$src_root"/skills/intelligence-*; do
+        [ -d "$s" ] || continue
+        if [ ! -s "$module_dir/skills/$(basename "$s")/SKILL.md" ]; then
+            missing="$missing skills/$(basename "$s")"
+        fi
+    done
+
+    if [ -n "$missing" ]; then
+        is_status aborted-incomplete "module=$module_name missing=${missing# }"
+        echo "  ERROR: migration aborted — '$module_name/' incomplete (${missing# }); legacy left intact." >&2
+        return "$IS_RC_ABORTED_INCOMPLETE"
+    fi
+
+    # Remove ONLY the legacy upstream-owned locations. Meta-skills / INIT /
+    # docs are never the running process, so these always succeed → no
+    # duplicate intelligence-* ever survives under <umbrella>/skills/.
+    rm -f  "$umbrella/INIT.md"
+    rm -rf "$umbrella/docs"
+    for s in "$umbrella"/skills/intelligence-*; do
+        [ -e "$s" ] && rm -rf "$s"
+    done
+    # The legacy scripts/ dir may host the *currently running* update.sh.
+    # On Linux deleting an open script is fine; some Windows shells refuse
+    # it. Try, and if it lingers print a one-line manual cleanup instead of
+    # failing — the new location, config, and stamp are already correct, and
+    # the next sync/update run removes the dead dir. Guarded by the engine
+    # sentinel so a project-owned <umbrella>/scripts/ (no sync.sh) is never
+    # removed, even if another legacy signal set has_legacy.
+    if [ "$legacy_engine" -eq 1 ]; then
+        rm -rf "$umbrella/scripts" 2>/dev/null || true
+        if [ -d "$umbrella/scripts" ]; then
+            echo "  NOTE: legacy '$umbrella/scripts' still present (likely in use)." >&2
+            echo "        Remove it manually once this process exits:" >&2
+            echo "          rm -rf \"$umbrella/scripts\"" >&2
+        fi
+    fi
+
+    # config.yaml: name-agnostic relative path under the actual umbrella base.
+    _mig_add_skill_source "$umbrella/config.yaml" "$(_mig_umbrella_rel "$umbrella")/$module_name/skills"
+
+    echo "  [migrate 0.3.1] done — engine at '$module_name/', legacy removed, no duplicates"
+}
+
+# --- migrate_to_0_7_0 -------------------------------------------------------
+# 0.7.0 is the first release where the engine ships a RULE and an AGENT of its
+# own (`intelligence-authoring`, `intelligence-architect`), inside the module
+# beside the meta-skills. Those reach the IDEs only if `config.yaml` lists the
+# module's `rules/` and `agents/` directories as sources — so this migration
+# registers them, exactly as 0.3.1 registered the module's `skills/`.
+#
+# Precondition is structural: both entries already present ⇒ applied ⇒ silent
+# no-op. Nothing else in config.yaml is read or rewritten, and no file is
+# deleted, so there is nothing to stage — the postcondition is simply that both
+# entries are readable afterwards.
+#
+# migrate_to_0_7_0 <umbrella_dir> <module_name> [<upstream_module_dir> — unused]
+migrate_to_0_7_0() {
+    local umbrella="$1" module_name="$2"
+    local config="$umbrella/config.yaml"
+    [ -f "$config" ] || return 0
+
+    local base rules_entry agents_entry
+    base="$(_mig_umbrella_rel "$umbrella")"
+    rules_entry="$base/$module_name/rules"
+    agents_entry="$base/$module_name/agents"
+
+    if _mig_has_source "$config" "$rules_entry" && _mig_has_source "$config" "$agents_entry"; then
+        return 0
+    fi
+
+    echo "  [migrate 0.7.0] registering the module's rules/ and agents/ as sources"
+    IS_MIGRATED=1
+    _mig_add_source "$config" "rules"  "$rules_entry"
+    _mig_add_source "$config" "agents" "$agents_entry"
+
+    if ! _mig_has_source "$config" "$rules_entry" || ! _mig_has_source "$config" "$agents_entry"; then
+        is_status error "migrate_to_0_7_0 could not register module sources"
+        echo "  ERROR: failed to add the module's rules/agents to sources in $config." >&2
+        echo "         Add them by hand under 'sources:':" >&2
+        echo "           rules:  - \"$rules_entry\"" >&2
+        echo "           agents: - \"$agents_entry\"" >&2
+        return "$IS_RC_ERROR"
+    fi
+
+    echo "  [migrate 0.7.0] done — sources.rules += $rules_entry, sources.agents += $agents_entry"
+}
+
+# --- migrate_to_0_10_0 ------------------------------------------------------
+
+# Split `git+<url>[@<ref>][#<subpath>]` into _MIG_URL / _MIG_REF / _MIG_SUBPATH.
+# Same grammar resolve_source_dir parses; kept here so a migration never has to
+# source the engine library it is migrating towards.
+#
+# Globals, never a delimited string on stdout: two of the three fields are
+# optional, and `read` with a whitespace IFS collapses a run of delimiters into
+# one — so an unpinned `git+<url>#rules` would come back as ref=rules with no
+# subpath, silently rewriting a whole source into a branch that does not exist.
+_mig_split_git_token() {
+    local rest="${1#git+}" urlref after cand
+    _MIG_SUBPATH=""; _MIG_REF=""
+    case "$rest" in
+        *\#*) _MIG_SUBPATH="${rest#*#}"; urlref="${rest%%#*}" ;;
+        *)    urlref="$rest" ;;
+    esac
+    _MIG_URL="$urlref"
+    after="${urlref#*://}"
+    case "$after" in
+        *@*)
+            cand="${after##*@}"
+            case "$cand" in
+                */*|"") ;;
+                *) _MIG_REF="$cand"; _MIG_URL="${urlref%@$cand}" ;;
+            esac
+            ;;
+    esac
+}
+
+# Pack name from a repo URL: basename minus `.git`, restricted to a safe
+# filename charset. This is the ONLY place a name is still derived, it runs
+# once, and the result is written into config.yaml where a human can rename it.
+_mig_pack_name_from_url() {
+    local name="${1%/}"
+    name="${name##*/}"
+    name="${name%.git}"
+    name="$(printf '%s' "$name" | tr -c 'A-Za-z0-9._-' '-')"
+    case "$name" in ""|.*|-*) name="pack" ;; esac
+    printf '%s' "$name"
+}
+
+# 0.10.0 replaces the single `external: { dir: … }` block with a `packs:` block:
+# a remote source is DECLARED once (url + ref + optional mirror) and referenced
+# from `sources.*` by name (`@<pack>/<subpath>`). That removes the duplicated
+# `url@ref` an inline spec forced into every section, and makes the mirror
+# directory declared rather than derived from the URL.
+#
+# This migration rewrites the config for the project: every inline `git+` spec
+# becomes a declared pack plus an `@name` reference, and `external.dir` becomes
+# each pack's `mirror:` so vendored content keeps landing where it already is.
+# Inline `git+` specs remain legal afterwards — they are simply no longer the
+# only way to reach a remote source, and they are always transient.
+#
+# Precondition is structural, and each key is a one-way marker: `external:` only
+# ever existed BEFORE 0.10.0, `packs:` only ever exists after it. So an
+# `external:` key ⇒ convert; otherwise a `packs:` key ⇒ applied ⇒ silent no-op;
+# otherwise convert only if there is an inline spec to convert. That last clause
+# is what keeps the migration idempotent once inline specs are legal again: the
+# run that converts them writes `packs:`, and every later run stops at the marker
+# instead of appending a SECOND top-level `packs:` key for each spec added since.
+# Fail-closed: the rewrite is staged in a temp file and verified before it
+# replaces config.yaml.
+#
+# migrate_to_0_10_0 <umbrella_dir> <module_name> [<upstream_module_dir> — unused]
+migrate_to_0_10_0() {
+    local umbrella="$1"
+    local config="$umbrella/config.yaml"
+    [ -f "$config" ] || return 0
+
+    local has_external=0
+    grep -q '^external:[[:space:]]*$' "$config" && has_external=1
+    local has_packs=0
+    grep -q '^packs:[[:space:]]*$' "$config" && has_packs=1
+    local has_inline=0
+    # ERE, and anchored to a list entry: `\|` is a GNU BRE extension that BSD
+    # grep (the macOS default) reads as a literal, and matching `git+` anywhere
+    # would fire on the comment that documents the old spec format.
+    grep -qE '^[[:space:]]*-[[:space:]]*["'\'']?git\+' "$config" && has_inline=1
+    if [ "$has_external" -eq 0 ] && { [ "$has_packs" -eq 1 ] || [ "$has_inline" -eq 0 ]; }; then
+        return 0
+    fi
+
+    echo "  [migrate 0.10.0] converting remote sources to declared packs"
+    IS_MIGRATED=1
+
+    # The old external dir, if any — it becomes each pack's mirror parent.
+    local ext_dir=""
+    if [ "$has_external" -eq 1 ]; then
+        ext_dir="$(awk '
+            { sub(/\r$/, "") }
+            /^external:[[:space:]]*$/ { in_ext = 1; next }
+            /^[A-Za-z]/ { in_ext = 0 }
+            in_ext && /^  dir:/ {
+                v = $0
+                sub(/^[[:space:]]*[^:]*:[[:space:]]*/, "", v)
+                # Two subs, never one alternation: POSIX awk takes the LONGEST
+                # match at the leftmost position, so `^["]|["].*$` would match
+                # the whole quoted value at position 1 and erase it.
+                sub(/^["\047]/, "", v)
+                sub(/["\047][[:space:]]*$/, "", v)
+                sub(/[[:space:]]+$/, "", v)
+                print v; exit
+            }
+        ' "$config")"
+        ext_dir="${ext_dir%/}"
+    fi
+
+    # Collect the distinct url@ref pairs across every section, in first-seen
+    # order, assigning each a unique name.
+    local names=() urls=() refs=() seen=()
+    local section token url ref subpath sig i found name base n
+    for section in rules agents skills; do
+        while IFS= read -r token; do
+            case "$token" in git+*) ;; *) continue ;; esac
+            _mig_split_git_token "$token"
+            url="$_MIG_URL"; ref="$_MIG_REF"
+            sig="$url@$ref"
+            # `${#arr[@]}` guards, never `"${!arr[@]}"` on a possibly-empty
+            # array: bash 3.2 (macOS default) treats that as unbound under
+            # `set -u`, which every script here runs with.
+            found=0
+            i=0
+            while [ "$i" -lt "${#seen[@]}" ]; do
+                [ "${seen[$i]}" = "$sig" ] && { found=1; break; }
+                i=$((i + 1))
+            done
+            [ "$found" -eq 1 ] && continue
+            base="$(_mig_pack_name_from_url "$url")"
+            name="$base"; n=2
+            while :; do
+                found=0
+                i=0
+                while [ "$i" -lt "${#names[@]}" ]; do
+                    [ "${names[$i]}" = "$name" ] && { found=1; break; }
+                    i=$((i + 1))
+                done
+                [ "$found" -eq 0 ] && break
+                name="$base-$n"; n=$((n + 1))
+            done
+            seen+=("$sig"); names+=("$name"); urls+=("$url"); refs+=("$ref")
+        done < <(_mig_read_sources "$config" "$section")
+    done
+
+    # Build the packs: block.
+    local packs_block="" mirror
+    i=0
+    while [ "$i" -lt "${#names[@]}" ]; do
+        packs_block="$packs_block  ${names[$i]}:"$'\n'
+        packs_block="$packs_block    url: ${urls[$i]}"$'\n'
+        [ -n "${refs[$i]}" ] && packs_block="$packs_block    ref: ${refs[$i]}"$'\n'
+        if [ -n "$ext_dir" ]; then
+            mirror="$ext_dir/${names[$i]}"
+            packs_block="$packs_block    mirror: \"$mirror\""$'\n'
+        fi
+        i=$((i + 1))
+    done
+
+    # Map every inline spec to its `@name[/subpath]` replacement.
+    local map=""
+    for section in rules agents skills; do
+        while IFS= read -r token; do
+            case "$token" in git+*) ;; *) continue ;; esac
+            _mig_split_git_token "$token"
+            url="$_MIG_URL"; ref="$_MIG_REF"; subpath="$_MIG_SUBPATH"
+            sig="$url@$ref"
+            i=0
+            while [ "$i" -lt "${#seen[@]}" ]; do
+                if [ "${seen[$i]}" = "$sig" ]; then
+                    map="$map$token"$'\t'"@${names[$i]}${subpath:+/$subpath}"$'\n'
+                    break
+                fi
+                i=$((i + 1))
+            done
+        done < <(_mig_read_sources "$config" "$section")
+    done
+
+    # An `external:` block with no remote source at all declares nothing — emit
+    # no `packs:` key rather than a dangling empty one, and drop `external:`.
+    local emit_packs=1
+    [ "${#names[@]}" -eq 0 ] && emit_packs=0
+
+    local tmp="$config.mig.tmp" mapfile_="$config.mig.map"
+    printf '%s' "$map" > "$mapfile_"
+    awk -v packs="$packs_block" -v mapfile="$mapfile_" -v emit="$emit_packs" '
+        BEGIN {
+            while ((getline line < mapfile) > 0) {
+                sub(/\r$/, "", line)
+                t = index(line, "\t")
+                if (t > 0) repl[substr(line, 1, t - 1)] = substr(line, t + 1)
+            }
+            close(mapfile)
+        }
+        { sub(/\r$/, "") }
+        # Drop the whole external: block.
+        /^external:[[:space:]]*$/ { in_ext = 1; next }
+        in_ext && /^[[:space:]]/ { next }
+        in_ext { in_ext = 0 }
+        # Emit packs: immediately before sources:.
+        /^sources:[[:space:]]*$/ && emit == 1 && !done_packs {
+            printf "packs:\n%s\n", packs
+            done_packs = 1
+        }
+        # Rewrite an inline spec in place, preserving indentation and quoting.
+        /^[[:space:]]*-[[:space:]]*["\047]?git\+/ {
+            val = $0
+            sub(/^[[:space:]]*-[[:space:]]*/, "", val)
+            gsub(/^["\047]|["\047][[:space:]]*$/, "", val)
+            if (val in repl) {
+                indent = $0
+                sub(/-.*$/, "", indent)
+                print indent "- \"" repl[val] "\""
+                next
+            }
+        }
+        { print }
+        END { if (emit == 1 && !done_packs) printf "packs:\n%s\n", packs }
+    ' "$config" > "$tmp"
+
+    # Verify the staged file before it replaces anything: `external:` gone, and
+    # EXACTLY the expected number of top-level `packs:` keys — a second one
+    # would be duplicate-key YAML that strict parsers reject.
+    local packs_keys
+    packs_keys="$(grep -c '^packs:[[:space:]]*$' "$tmp" || true)"
+    if [ "$packs_keys" -ne "$emit_packs" ] || grep -q '^external:[[:space:]]*$' "$tmp"; then
+        rm -f "$tmp" "$mapfile_"
+        is_status error "migrate_to_0_10_0 could not rewrite config.yaml"
+        echo "  ERROR: failed to convert remote sources to packs in $config." >&2
+        echo "         Declare each remote under 'packs:' and reference it as '@<name>/<subpath>'." >&2
+        return "$IS_RC_ERROR"
+    fi
+
+    mv "$tmp" "$config"
+    rm -f "$mapfile_"
+    if [ "$emit_packs" -eq 0 ]; then
+        echo "  [migrate 0.10.0] done — no remote source to declare, dropped the empty 'external:' block"
+    else
+        echo "  [migrate 0.10.0] done — ${#names[@]} pack(s) declared${ext_dir:+, mirrored under $ext_dir}"
+    fi
+}
+
+# Read one `sources.<section>` list, one raw value per line (quotes stripped).
+# Local to migrations so the chain never depends on the engine library.
+_mig_read_sources() {
+    local config="$1" section="$2"
+    awk -v section="$section" '
+        { sub(/\r$/, "") }
+        /^sources:[[:space:]]*$/ { in_src = 1; next }
+        /^[A-Za-z]/ { in_src = 0; in_sec = 0 }
+        in_src && $0 ~ "^  " section ":[[:space:]]*$" { in_sec = 1; next }
+        in_src && /^  [A-Za-z]/ { in_sec = 0 }
+        in_sec && /^[[:space:]]*-[[:space:]]*/ {
+            v = $0
+            sub(/^[[:space:]]*-[[:space:]]*/, "", v)
+            gsub(/^["\047]|["\047][[:space:]]*$/, "", v)
+            sub(/[[:space:]]+$/, "", v)
+            if (v != "") print v
+        }
+    ' "$config"
+}
+
+# run_migrations <umbrella_dir> <module_name> [<upstream_module_dir>]
+# The dispatcher of the breaking-change chain. Correctness rests on idempotent
+# structural preconditions, NOT on the stamp: every migrate_to_* self-detects
+# whether its change is already applied and is a silent no-op if so, so the
+# whole chain is simply run in order — a wrong/missing stamp can never cause a
+# needed migration to be skipped. The stamp is only a safety guard
+# (ahead-of-engine / needs-update) + reporting. Returns 0 on success
+# (IS_MIGRATED tells whether work happened) or the failing migration's IS_RC_*
+# code; never partially destroys (each migrate_to_* is transactional and
+# fail-closed). Caller maps the code to an exit status + IS_STATUS line.
+run_migrations() {
+    local umbrella="$1" module_name="$2" upstream="${3:-}"
+    local cf="$umbrella/config.yaml"
+    local v ver rc
+    # A stale engine must never touch a project schema stamped newer than it
+    # knows. (Reads the frozen contract key from config.yaml.)
+    check_version_compat "$cf" || return $?
+    for v in "${MIGRATIONS[@]}"; do
+        ver="$(_mig_ver_dotted "$v")"
+        "migrate_to_$v" "$umbrella" "$module_name" "$upstream"
+        rc=$?
+        if [ "$rc" -ne 0 ]; then return "$rc"; fi
+        # Commit progress: stamp this version so an interrupted chain resumes
+        # from the last good point. Idempotent migrations that no-op'd just
+        # re-assert the same value.
+        stamp_version "$cf" "$ver"
+    done
+    # Fresh project with no stamp at all (e.g. just-bootstrapped, nothing in
+    # the chain applied) → stamp to the engine version so future runs have a
+    # baseline. Safe: migrations already self-skipped.
+    if [ -z "$(read_engine_stamp "$cf")" ]; then
+        stamp_version "$cf" "$(engine_version)"
+    fi
+    return 0
+}