@ainova-systems/intelligence 0.11.0-rc.7 → 0.11.0-rc.9

package/cli/commands/update.sh

@@ -1,87 +1,93 @@
 #!/bin/bash
-# intelligence update [name] [--no-sync]
+# intelligence update [@scope/name] [--preview|--apply]
 #
-# Re-resolve version ranges against the remotes and rewrite the lock. Pinned
-# packages (`ref:`) never move here — repin by editing the manifest or
-# re-adding. `update <name>` limits the pass to one package.
+# One update surface: show the installed-CLI/project/package plan, then either
+# stop, ask interactively, or apply without a prompt. Updating the global npm
+# installation remains an explicit package-manager operation.
 set -euo pipefail
 source "$CLI_DIR/lib/cli-common.sh"
 
-only="" no_sync=0
+only="" mode="ask" preview_seen=0 apply_seen=0
 while [ $# -gt 0 ]; do
     case "$1" in
-        --no-sync) no_sync=1 ;;
-        @*) only="$1" ;;
-        *) die "unknown argument '$1'" ;;
+        --preview) preview_seen=1; mode="preview" ;;
+        --apply) apply_seen=1; mode="apply" ;;
+        @*) [ -z "$only" ] || die "only one package may be selected"; only="$1" ;;
+        *) die "usage: intelligence update [@scope/name] [--preview|--apply]" ;;
     esac
-    shift || true
+    shift
 done
+[ "$preview_seen" -eq 0 ] || [ "$apply_seen" -eq 0 ] || die "choose either --preview or --apply"
 
 require_v2
 manifest="$IP_ROOT/intelligence.yaml"
-lock="$IP_ROOT/intelligence.lock"
+check_version_compat "$manifest"
+eng="$(bundled_engine_version)"
+stamp="$(read_schema_version "$manifest")"
+project_change=0
 
-moved=0 found=0
-while IFS= read -r name; do
-    [ -n "$name" ] || continue
-    # Manifest keys are untrusted input on their way into store paths.
-    assert_valid_pkg_name "$name"
-    [ -n "$only" ] && [ "$name" != "$only" ] && continue
-    # A named package that exists is "found" whatever happens next — a skip
-    # message followed by "not in the manifest" would contradict itself.
-    found=1
-    if [ "$name" = "$SYNC_PKG_NAME" ]; then
-        echo "  $name: engine content moves with the engine — 'intelligence upgrade' owns it"
-        continue
+echo "Update plan"
+echo ""
+echo "CLI:"
+if [ -n "${INTELLIGENCE_NPM_VERSION:-}" ] && [ "${IS_SKIP_NPM_CHECK:-0}" != "1" ] && command -v npm >/dev/null 2>&1; then
+    channel="latest"
+    case "$INTELLIGENCE_NPM_VERSION" in *-*) channel="next" ;; esac
+    available="$(npm view "@ainova-systems/intelligence" "dist-tags.$channel" 2>/dev/null || true)"
+    if [ -z "$available" ]; then
+        echo "  installed: $INTELLIGENCE_NPM_VERSION; registry check unavailable"
+    elif [ "$available" = "$INTELLIGENCE_NPM_VERSION" ]; then
+        echo "  $INTELLIGENCE_NPM_VERSION (up to date on npm $channel)"
+    else
+        echo "  $INTELLIGENCE_NPM_VERSION -> $available (npm $channel)"
+        echo "  run: npm install -g @ainova-systems/intelligence@$channel"
+        echo "  then rerun: intelligence update --apply"
     fi
-    ref="$(qmap_field "$manifest" "packages" "$name" "ref")"
-    [ -n "$ref" ] && { echo "  $name: pinned to ref '$ref' — skipped"; continue; }
-    range="$(qmap_field "$manifest" "packages" "$name" "version")"
-    # An exact version is a pin, same as ref: — update never moves pins.
-    if [ -n "$range" ] && semver_is_stable "$range"; then
-        echo "  $name: pinned to $range — edit the manifest to move it"
-        continue
-    fi
-    url="$(qmap_field "$manifest" "packages" "$name" "url")"
-    path="$(qmap_field "$manifest" "packages" "$name" "path")"
-    if [ -z "$url" ]; then
-        resolve_package_source "$manifest" "$name"
-        url="$RES_URL"; path="$RES_PATH"
-    fi
-    picked="$(list_remote_versions "$url" | semver_pick_highest "$range")"
-    [ -n "$picked" ] || { echo "  $name: nothing satisfies '${range:-*}' at $url" >&2; continue; }
-    read -r tag _ <<< "$(remote_tag_for_version "$url" "$picked")"
-    current="$(qmap_field "$lock" "packages" "$name" "resolved")"
-    cur_url="$(qmap_field "$lock" "packages" "$name" "url")"
-    cur_path="$(qmap_field "$lock" "packages" "$name" "path")"
-    # Same tag is not enough: a registry may re-point a name's source while
-    # keeping the version — the move doctor warns about must be actionable
-    # here, so url/path changes refetch too.
-    if [ "$tag" = "$current" ] && [ "$url" = "$cur_url" ] && [ "$path" = "$cur_path" ]; then
-        echo "  $name: ${current:-<none>} (up to date)"
-        continue
-    fi
-    rel=".intelligence/packages/$name"
-    # Fetch into staging FIRST: a failed clone must leave the current install
-    # fully wired and intact. Only after success is the old shape unwired
-    # (the new version may have dropped a section dir), the store swapped,
-    # and the new shape wired.
-    staging="$IP_ROOT/.intelligence/.staging-$$"
-    rm -rf "$staging"
-    sha="$(fetch_package "$url" "$tag" "$path" "$staging")"
-    unwire_package_sources "$manifest" "$rel"
-    rm -rf "${IP_ROOT:?}/$rel"
-    mkdir -p "$(dirname "$IP_ROOT/$rel")"
-    mv "$staging" "$IP_ROOT/$rel"
-    wire_package_sources "$manifest" "$name" "$rel" "$IP_ROOT"
-    lock_upsert "$lock" "$name" "$range" "$url" "$path" "$tag" "$sha"
-    echo "  $name: ${current:-<none>} -> $tag"
-    moved=$((moved + 1))
-done < <(qmap_keys "$manifest" "packages")
+else
+    echo "  source checkout/registry check skipped; engine $eng"
+fi
+
+echo ""
+echo "Project:"
+if project_needs_upgrade "$IP_ROOT"; then
+    echo "  lifecycle alignment required (stamp ${stamp:-unstamped}, engine $eng)"
+    project_change=1
+else
+    echo "  schema/content $eng (up to date)"
+fi
 
-[ -n "$only" ] && [ "$found" -eq 0 ] && die "package '$only' is not in the manifest"
-echo "updated: $moved package(s)"
+if project_has_packages "$IP_ROOT" && [ ! -f "$IP_ROOT/intelligence.lock" ]; then
+    die "manifest declares packages but intelligence.lock is absent — restore the committed lock before planning or applying updates"
+fi
+
+pkg_args=(--preview)
+[ -z "$only" ] || pkg_args+=("$only")
+pkg_plan="$(bash "$CLI_DIR/internal/package-update.sh" "${pkg_args[@]}")"
+echo ""
+echo "Packages:"
+printf '%s\n' "$pkg_plan"
+package_changes="$(printf '%s\n' "$pkg_plan" | awk '/^updates available:/ {print $3; exit}')"
+package_changes="${package_changes:-0}"
 
-if [ "$moved" -gt 0 ] && [ "$no_sync" -eq 0 ]; then
-    exec bash "$CLI_DIR/commands/sync.sh"
+if [ "$mode" = "preview" ]; then
+    exit 0
+fi
+if [ "$project_change" -eq 0 ] && [ "$package_changes" -eq 0 ]; then
+    echo ""
+    echo "Nothing to apply with the currently installed CLI."
+    exit 0
 fi
+if [ "$mode" = "ask" ]; then
+    [ -t 0 ] || die "update requires confirmation — rerun with --preview or --apply"
+    printf '\nApply this plan? [Y/n] '
+    read -r answer
+    case "$answer" in
+        ""|y|Y|yes|YES) ;;
+        *) echo "update cancelled"; exit 0 ;;
+    esac
+fi
+
+ensure_project_current "$IP_ROOT"
+apply_args=(--no-sync)
+[ -z "$only" ] || apply_args+=("$only")
+bash "$CLI_DIR/internal/package-update.sh" "${apply_args[@]}"
+exec bash "$CLI_DIR/commands/sync.sh"

package/cli/engine-package.yaml

@@ -6,8 +6,8 @@
 # The engine-content package is the one package whose content documents the
 # engine scripts bundled with the CLI: init writes this entry into the
 # manifest (visible, removable), its pin always equals the engine VERSION,
-# `upgrade` moves it, and at the matching version it materializes from the
-# bundle without network.
+# lifecycle preflight aligns it with the installed CLI, and at the matching
+# version it materializes from the bundle without network.
 name: "@ainova-systems/sync"
 url: "https://github.com/ainova-systems/intelligence.git"
 path: "packages/sync"

package/cli/intelligence

@@ -43,19 +43,17 @@ intelligence — build, version and distribute AI agent intelligence
 
 Usage: intelligence <command> [args]
 
-  init                    Set up this project (manifest, content skeleton, targets)
-  add <spec>              Add a package: @scope/name[@range] | github:org/repo[#path] | git+<url>[@ref][#path]
-  remove <name>           Remove a package
-  install [--frozen]      Restore .intelligence/ exactly from intelligence.lock
-  update [name]           Re-resolve version ranges and rewrite the lockfile
-  upgrade                 Upgrade the project to this CLI's engine (restage + restamp)
-  list                    Installed packages with requested/locked versions
-  search [term]           What the registries offer, and what this project has
-  sync [target]           Render intelligence to every enabled tool (.claude, AGENTS.md, ...)
+  init [--preview|--apply]  Initialize, migrate, restore or align this project
+    --targets a,b --dir name --bare --no-sync   New-project options
+    --force               Accept a dirty worktree during v1 conversion
+  sync [adapter]          Restore locked content if needed, then render enabled adapters
+  update [@scope/name]    Show an update plan; ask before applying it
+    --preview             Show the plan without asking or writing
+    --apply               Apply the plan without asking
+  package <command>       add | remove | list | search
+  adapter <command>       list | create | enable | disable | remove
+  status [--check]        Project state; --check runs deep consistency checks
   registry <list|add|remove>  Manage the trusted registry list (add <repo-url>)
-  migrate [--dry-run]     Convert a vendored (v1) setup to the CLI setup
-  doctor                  Check manifest, lockfile, store and engine consistency
-  status                  Project state at a glance
   version                 Print CLI and engine versions
 EOF
         exit 0

package/cli/{commands/doctor.sh → internal/check.sh}

@@ -1,5 +1,5 @@
 #!/bin/bash
-# intelligence doctor — consistency checks, no writes. Exit 1 on problems.
+# Internal deep consistency check. No writes; exits 1 on problems.
 set -euo pipefail
 source "$CLI_DIR/lib/cli-common.sh"
 
@@ -22,7 +22,7 @@ case "$IP_MODE" in
     legacy)
         echo "project: vendored (v1) at $IP_ROOT"
         ok "vendored engine $(tr -d ' \t\r\n' < "$IP_MODULE_DIR/scripts/VERSION")"
-        echo "  → 'intelligence migrate' converts it to the CLI setup"
+        echo "  → 'intelligence init' converts it to the CLI setup"
         exit 0
         ;;
 esac
@@ -31,16 +31,16 @@ echo "project: $IP_ROOT"
 manifest="$IP_ROOT/intelligence.yaml"
 lock="$IP_ROOT/intelligence.lock"
 
-stamp="$(read_engine_stamp "$manifest")"
+stamp="$(read_schema_version "$manifest")"
 eng="$(bundled_engine_version)"
 if [ -z "$stamp" ]; then
-    warn "manifest has no sync_version — run 'intelligence upgrade'"
+    warn "manifest has no schema_version — run 'intelligence init'"
 elif _ver_gt "$stamp" "$eng"; then
     warn "manifest schema $stamp is newer than this CLI's engine $eng — update the CLI: npm i -g @ainova-systems/intelligence@latest"
 elif _ver_gt "$eng" "$stamp"; then
-    warn "manifest schema $stamp behind engine $eng — run 'intelligence upgrade'"
+    warn "manifest schema $stamp behind engine $eng — run 'intelligence init'"
 else
-    ok "sync_version $stamp matches the engine"
+    ok "schema_version $stamp matches the engine"
 fi
 
 # The engine-content package must sit at the bundled engine version — the
@@ -50,32 +50,39 @@ if [ -n "$sync_locked" ]; then
     if [ "${sync_locked#v}" = "$eng" ]; then
         ok "$SYNC_PKG_NAME at $sync_locked (matches the engine)"
     else
-        warn "$SYNC_PKG_NAME locked at $sync_locked but the engine is $eng — run 'intelligence upgrade'"
+        warn "$SYNC_PKG_NAME locked at $sync_locked but the engine is $eng — run 'intelligence init'"
     fi
 fi
 if [ -d "$IP_ROOT/.intelligence/engine" ]; then
-    warn "stale .intelligence/engine directory (pre-package layout) — run 'intelligence upgrade'"
+    warn "stale .intelligence/engine directory (pre-package layout) — run 'intelligence init'"
 fi
 
-# Manifest packages: names valid, locked, installed — and the lock's source
-# still the one resolution would pick today (a registry silently re-pointing
-# an installed name is the dependency-confusion tail this check cuts off).
+# Manifest packages: names valid, requested intent only, locked and installed.
+# The lock is authoritative for resolved source URL/path until an explicit
+# package re-add changes that trust decision.
 while IFS= read -r name; do
     [ -n "$name" ] || continue
     assert_valid_pkg_name "$name"
     if [ -z "$(qmap_field "$lock" "packages" "$name" "url")" ]; then
-        warn "$name is in the manifest but not in intelligence.lock — run 'intelligence install'"
-    elif [ ! -d "$IP_ROOT/.intelligence/packages/$name" ]; then
-        warn "$name is locked but not installed — run 'intelligence install'"
+        warn "$name is in the manifest but not in intelligence.lock — run 'intelligence init'"
     else
-        ok "$name @ $(qmap_field "$lock" "packages" "$name" "resolved")"
-        if [ -z "$(qmap_field "$manifest" "packages" "$name" "url")" ]; then
-            locked_url="$(qmap_field "$lock" "packages" "$name" "url")"
-            resolve_package_source "$manifest" "$name" 2>/dev/null || true
-            if [ -n "${RES_URL:-}" ] && [ -n "$locked_url" ] && [ "$RES_URL" != "$locked_url" ]; then
-                warn "$name now resolves to $RES_URL but the lock pins $locked_url — a registry re-pointed the name; verify before 'intelligence update'"
-            fi
+        m_ver="$(qmap_field "$manifest" "packages" "$name" "version")"
+        m_ref="$(qmap_field "$manifest" "packages" "$name" "ref")"
+        l_req="$(qmap_field "$lock" "packages" "$name" "requested")"
+        l_res="$(qmap_field "$lock" "packages" "$name" "resolved")"
+        [ -z "$m_ver" ] || [ "$m_ver" = "$l_req" ] \
+            || warn "$name requests '$m_ver' but the lock recorded '$l_req' — run 'intelligence update --preview'"
+        [ -z "$m_ref" ] || [ "$m_ref" = "$l_res" ] \
+            || warn "$name pins ref '$m_ref' but the lock resolved '$l_res'"
+        if [ -n "$(qmap_field "$manifest" "packages" "$name" "url")" ] \
+            || [ -n "$(qmap_field "$manifest" "packages" "$name" "path")" ]; then
+            warn "$name stores source details in the manifest — run 'intelligence init --apply' to move them to the lock-only model"
+        fi
+        if [ ! -d "$IP_ROOT/.intelligence/packages/$name" ]; then
+            warn "$name is locked but not installed — run 'intelligence sync'"
+            continue
         fi
+        ok "$name @ $(qmap_field "$lock" "packages" "$name" "resolved")"
     fi
 done < <(qmap_keys "$manifest" "packages")
 
@@ -87,7 +94,7 @@ if [ -f "$lock" ]; then
         while IFS= read -r m; do
             [ "$m" = "$name" ] && found=1
         done < <(qmap_keys "$manifest" "packages")
-        [ "$found" -eq 1 ] || warn "$name is locked but absent from the manifest — 'intelligence remove $name' cleans it up"
+        [ "$found" -eq 1 ] || warn "$name is locked but absent from the manifest — 'intelligence package remove $name' cleans it up"
     done < <(qmap_keys "$lock" "packages")
 fi
 
@@ -102,7 +109,7 @@ for section in rules agents skills; do
         if [ ! -d "$IP_ROOT/$src" ]; then
             case "$src" in
                 # Store content is restorable state: absent means un-installed.
-                .intelligence/*) warn "sources.$section '$src' missing — run 'intelligence install'" ;;
+                .intelligence/*) warn "sources.$section '$src' missing — run 'intelligence sync'" ;;
                 # A project-owned dir that does not exist yet is a legitimate
                 # state — a project consuming only packages authors nothing of
                 # its own — and the engine simply skips it. Declared up front so

package/cli/{commands/migrate.sh → internal/migrate-v1.sh}

@@ -1,5 +1,5 @@
 #!/bin/bash
-# intelligence migrate [--dry-run] [--force] — convert a vendored (v1) setup
+# Internal v1-to-v2 migration operation.
 # to the CLI setup: root intelligence.yaml, .intelligence/ store,
 # intelligence.lock, no vendored engine.
 #
@@ -24,7 +24,7 @@ done
 detect_project
 case "$IP_MODE" in
     legacy) ;;
-    v2) die "already on the CLI setup ($IP_ROOT/intelligence.yaml)" ;;
+    v2) die "already on the v2 setup ($IP_ROOT/intelligence.yaml)" ;;
     *) die "no vendored setup found here — 'intelligence init' starts a fresh project" ;;
 esac
 root="$IP_ROOT"
@@ -32,15 +32,22 @@ umbrella="$IP_UMBRELLA"
 module_dir="$IP_MODULE_DIR"
 config="$umbrella/config.yaml"
 module_rel="${module_dir#"$root"/}"
+umbrella_rel="${umbrella#"$root"/}"
 
-[ -f "$root/intelligence.yaml" ] && die "intelligence.yaml already exists at the root — half-migrated state; resolve it manually"
+for existing in intelligence.yaml intelligence.lock .intelligence; do
+    if [ -e "$root/$existing" ] || [ -L "$root/$existing" ]; then
+        die "$existing already exists at the root — conflicting v2 state; move it aside or restore the project before migrating"
+    fi
+done
 if [ "$dry_run" -eq 0 ] && [ "$force" -eq 0 ]; then
     if [ -n "$(git -C "$root" status --porcelain 2>/dev/null)" ]; then
         die "working tree is not clean — commit or stash first (or --force); migrate wants a one-commit diff you can review and revert"
     fi
 fi
 
-stamp="$(read_engine_stamp "$config")"
+# `sync_version` belongs to the archived v1 format. The v2 contract uses
+# `schema_version`, so conversion reads the legacy scalar explicitly.
+stamp="$(top_scalar "$config" "sync_version")"
 eng="$(bundled_engine_version)"
 [ -n "$stamp" ] && _ver_gt "$stamp" "$eng" && die "project schema $stamp is newer than this CLI's engine $eng — update the CLI first"
 
@@ -50,9 +57,60 @@ get_pack_field() {
     get_nested_yaml_value "$1" "packs" "$2" "$3"
 }
 
+paths_overlap() {
+    case "$1" in "$2"|"$2"/*) return 0 ;; esac
+    case "$2" in "$1"|"$1"/*) return 0 ;; esac
+    return 1
+}
+
+validate_mirror_path() {
+    local pack="$1" mirror="$2" canon rel src src_canon src_rel target output protected mirror_phys
+    [ -n "$mirror" ] || return 0
+    case "$mirror" in
+        .|/*|*..*|*\\*|[A-Za-z]:*) die "pack '$pack' has unsafe mirror path '$mirror'" ;;
+    esac
+    canon="$(normalize_path "$root/$mirror")"
+    case "$canon" in "$root"/*) ;; *) die "pack '$pack' mirror escapes the repository: '$mirror'" ;; esac
+    rel="${canon#"$root"/}"
+
+    # A v1 mirror may live below the content directory (the normal location is
+    # intelligence/external/<pack>), but it must never own the directory itself,
+    # the vendored module, CLI state, authored sources, or generated outputs.
+    case "$umbrella_rel" in "$rel"|"$rel"/*) die "pack '$pack' mirror '$mirror' contains the v1 content directory" ;; esac
+    for protected in .git .intelligence "$module_rel"; do
+        paths_overlap "$rel" "$protected" && die "pack '$pack' mirror '$mirror' overlaps protected path '$protected'"
+    done
+    for section in rules agents skills; do
+        while IFS= read -r src; do
+            case "$src" in ""|git+*|@*) continue ;; esac
+            src_canon="$(normalize_path "$root/$src")"
+            case "$src_canon" in "$root"/*) src_rel="${src_canon#"$root"/}" ;; *) continue ;; esac
+            paths_overlap "$rel" "$src_rel" \
+                && die "pack '$pack' mirror '$mirror' overlaps configured source '$src'"
+        done < <(read_yaml_list "$config" "$section")
+    done
+    while IFS= read -r target; do
+        [ -n "$target" ] || continue
+        output="$(get_target_output "$config" "$target")"
+        [ -n "$output" ] || continue
+        case "$output" in /*|*..*) continue ;; esac
+        paths_overlap "$rel" "${output%/}" \
+            && die "pack '$pack' mirror '$mirror' overlaps target '$target' output '$output'"
+    done < <(read_yaml_keys "$config" "targets")
+
+    if [ -d "$canon" ]; then
+        mirror_phys="$(cd "$canon" && pwd -P)"
+        case "$mirror_phys" in "$root"|"$root"/*) ;; *) die "pack '$pack' mirror resolves outside the repository: '$mirror'" ;; esac
+        [ -f "$canon/.pack" ] || die "pack '$pack' mirror '$mirror' has no .pack ownership stamp — refusing to copy or delete project-owned content"
+    fi
+}
+
 # ---- Stage ----------------------------------------------------------------
-stage="$root/.intelligence-migrate-stage.$$"
-[ "$dry_run" -eq 1 ] && stage="$(mktemp -d -t intelligence-migrate-XXXXXX 2>/dev/null || mktemp -d)"
+if [ "$dry_run" -eq 1 ]; then
+    stage="$(mktemp -d -t intelligence-migrate-XXXXXX 2>/dev/null || mktemp -d)"
+else
+    stage="$(mktemp -d "$root/.intelligence-migrate-stage.XXXXXX")"
+fi
 cleanup_stage() { rm -rf "$stage"; }
 trap cleanup_stage EXIT INT TERM
 mkdir -p "$stage/.intelligence/packages"
@@ -67,7 +125,7 @@ if [ -z "$stamp" ] || _ver_gt "$V1_FINAL_SCHEMA" "$stamp"; then
     echo "ERROR: project schema is ${stamp:-absent (pre-0.3.1)}, older than the final v1 schema $V1_FINAL_SCHEMA." >&2
     echo "       Bring it forward with its own engine first — that still works:" >&2
     echo "         bash $module_rel/scripts/update.sh --yes" >&2
-    echo "       then re-run: intelligence migrate" >&2
+    echo "       then re-run: intelligence init" >&2
     exit 1
 fi
 
@@ -81,12 +139,21 @@ sync_pkg_sha="$(fetch_package "$SYNC_PKG_URL" "v$eng" "$SYNC_PKG_PATH" "$stage/$
 pack_rows="$stage/packs.rows"
 : > "$pack_rows"
 seen_names=" "
+seen_mirrors=" "
 while IFS= read -r pack; do
     [ -n "$pack" ] || continue
     url="$(get_pack_field "$config" "$pack" "url")"
     ref="$(get_pack_field "$config" "$pack" "ref")"
     mirror="$(get_pack_field "$config" "$pack" "mirror")"
     [ -n "$url" ] || die "pack '$pack' has no url in config.yaml"
+    assert_safe_source_url "$url"
+    assert_safe_ref "$ref"
+    validate_mirror_path "$pack" "$mirror"
+    if [ -n "$mirror" ]; then
+        mirror_key="$(normalize_path "$root/$mirror")"
+        case "$seen_mirrors" in *" $mirror_key "*) die "pack '$pack' shares mirror '$mirror' with another pack" ;; esac
+        seen_mirrors="$seen_mirrors$mirror_key "
+    fi
     base="${url%.git}"; base="${base%/}"
     repo="$(basename "$base")"
     org="$(basename "$(dirname "$base")")"
@@ -125,8 +192,9 @@ while IFS="$LOCK_SEP" read -r pack name url ref mirror; do
         echo "  pack '$pack' -> $name (fetched)"
     fi
     if [ -z "$sha" ] || [ "$sha" = "unknown" ]; then
-        sha="$(GIT_TERMINAL_PROMPT=0 git ls-remote "$url" "$ref" 2>/dev/null | awk '{print $1; exit}')"
+        sha="$(GIT_TERMINAL_PROMPT=0 git ls-remote -- "$url" "$ref" 2>/dev/null | awk '{print $1; exit}')"
     fi
+    [ -n "$ref" ] || ref="HEAD"
     printf '%s\037%s\037%s\037%s\037%s\037%s\n' \
         "$name" "" "$url" "" "$ref" "$sha" >> "$lock_rows"
 done < "$pack_rows"
@@ -192,19 +260,16 @@ while IFS= read -r line || [ -n "$line" ]; do
     fi
     echo "$line"
 done < "$config" > "$manifest_stage"
-stamp_version "$manifest_stage" "$eng"
+stamp_schema_version "$manifest_stage" "$eng"
 
-# packages: entries (pin preserved — no invented ranges).
+# packages: requested pins only; resolved source details live in the lock.
 while IFS="$LOCK_SEP" read -r pack name url ref mirror; do
     [ -n "$pack" ] || continue
-    qmap_set "$manifest_stage" "packages" "$name" "url" "$url"
-    [ -n "$ref" ] && qmap_set "$manifest_stage" "packages" "$name" "ref" "$ref"
+    qmap_set "$manifest_stage" "packages" "$name" "ref" "${ref:-HEAD}"
 done < "$pack_rows"
 
 # The engine's own content rides along as a package, pinned to the engine.
 qmap_set "$manifest_stage" "packages" "$SYNC_PKG_NAME" "version" "$eng"
-qmap_set "$manifest_stage" "packages" "$SYNC_PKG_NAME" "url" "$SYNC_PKG_URL"
-qmap_set "$manifest_stage" "packages" "$SYNC_PKG_NAME" "path" "$SYNC_PKG_PATH"
 printf '%s\037%s\037%s\037%s\037%s\037%s\n' \
     "$SYNC_PKG_NAME" "$eng" "$SYNC_PKG_URL" "$SYNC_PKG_PATH" "v$eng" "$sync_pkg_sha" >> "$lock_rows"
 
@@ -221,14 +286,24 @@ for section in rules agents skills; do
         esac
     done < <(read_yaml_list "$manifest_stage" "$section")
 done
-for adapter in agents claude cursor copilot codex pi opencode; do
+target_keys() {
+    awk '
+        /^targets:[[:space:]]*$/ { in_targets=1; next }
+        in_targets && /^[^[:space:]#]/ { exit }
+        in_targets && /^  [A-Za-z_][A-Za-z0-9_]*:/ {
+            line=$0; sub(/^  /, "", line); sub(/:.*/, "", line); print line
+        }
+    ' "$1"
+}
+while IFS= read -r adapter; do
+    [ -n "$adapter" ] || continue
     old_e="$(is_target_enabled "$config" "$adapter")"
     new_e="$(is_target_enabled "$manifest_stage" "$adapter")"
     [ "$old_e" = "$new_e" ] || { echo "  TARGET DRIFT: $adapter enabled '$old_e' -> '$new_e'"; fail=1; }
     old_o="$(get_target_output "$config" "$adapter")"
     new_o="$(get_target_output "$manifest_stage" "$adapter")"
     [ "$old_o" = "$new_o" ] || { echo "  TARGET DRIFT: $adapter output '$old_o' -> '$new_o'"; fail=1; }
-done
+done < <({ target_keys "$config"; target_keys "$manifest_stage"; } | sort -u)
 [ "$fail" -eq 0 ] || die "staged state failed verification — nothing changed"
 
 if [ "$dry_run" -eq 1 ]; then
@@ -250,40 +325,51 @@ if [ -f "$root/.gitignore" ]; then
     gitignore_existed=1
     cp "$root/.gitignore" "$stage/gitignore.orig"
 fi
-if [ ! -f "$root/.gitignore" ] || ! grep -q '^\.intelligence/' "$root/.gitignore"; then
-    {
-        [ -f "$root/.gitignore" ] && [ -n "$(tail -c 1 "$root/.gitignore" 2>/dev/null)" ] && echo ""
-        echo "# intelligence CLI package store (restored by 'intelligence install')"
-        echo ".intelligence/"
-    } >> "$root/.gitignore"
-fi
+commit_active=1
 rollback() {
+    [ "$commit_active" -eq 1 ] || return 0
+    commit_active=0
+    set +e
     rm -rf "$root/.intelligence" "$root/intelligence.yaml" "$root/intelligence.lock"
     if [ "$gitignore_existed" -eq 1 ]; then
         cp "$stage/gitignore.orig" "$root/.gitignore"
     else
         rm -f "$root/.gitignore"
     fi
+    rm -rf "$stage"
     echo "rolled back — the vendored setup is untouched" >&2
 }
-# From the first moved file until success, an interrupt must roll back too.
+rollback_on_exit() {
+    local rc=$?
+    rollback
+    exit "$rc"
+}
+# Every live write through verified sync is covered by rollback, including a
+# plain set -e/EXIT failure rather than only an explicit sync refusal.
+trap rollback_on_exit EXIT
 trap 'rollback; exit 130' INT TERM
+if [ ! -f "$root/.gitignore" ] || ! grep -q '^\.intelligence/' "$root/.gitignore"; then
+    {
+        [ -f "$root/.gitignore" ] && [ -n "$(tail -c 1 "$root/.gitignore" 2>/dev/null)" ] && echo ""
+        echo "# intelligence CLI package store (restored automatically by 'intelligence sync')"
+        echo ".intelligence/"
+    } >> "$root/.gitignore"
+fi
 mv "$stage/.intelligence" "$root/.intelligence"
 cp "$manifest_stage" "$root/intelligence.yaml"
 lock_write_from_tsv "$root/intelligence.lock" "$lock_rows"
 
 sync_out="$(cd "$root" && IS_SUPPRESS_CLI_NOTE=1 bash "$CLI_DIR/commands/sync.sh" 2>&1)" || {
     echo "$sync_out"
-    rollback
-    die "sync of the migrated state failed — rolled back"
+    die "sync of the migrated state failed"
 }
 echo "$sync_out" | grep -q '^IS_STATUS=ok' || {
     echo "$sync_out"
-    rollback
-    die "sync of the migrated state did not report ok — rolled back"
+    die "sync of the migrated state did not report ok"
 }
 # Point of no return: the new state is verified. From here an interrupt must
 # NOT roll back (the old setup is being removed) — only clean the stage.
+commit_active=0
 trap cleanup_stage EXIT INT TERM
 
 # Only now is anything of the old setup removed — and config.yaml is kept as
@@ -298,7 +384,7 @@ while IFS="$LOCK_SEP" read -r pack name url ref mirror; do
     esac
     if [ -d "$root/$mirror" ]; then
         rm -rf "${root:?}/$mirror"
-        # An emptied mirror parent (e.g. <umbrella>/external/) goes with it.
+        # An emptied v1 mirror parent (for example intelligence/external/) goes with it.
         rmdir "$(dirname "$root/$mirror")" 2>/dev/null || true
     fi
 done < "$pack_rows"
@@ -310,4 +396,5 @@ rmdir "$umbrella" 2>/dev/null || true
 
 echo ""
 echo "migrated. Review the diff, then commit. The old config.yaml is kept at .intelligence/backup/config.yaml."
-echo "From now on: intelligence sync | add | install | doctor."
+echo "From now on: intelligence sync | package | update | status."
+echo "Next: ask your agent to run /intelligence-learn-from-repository to review the migrated project context."