@ainova-systems/intelligence 0.22.0 → 0.23.0

package/README.md

@@ -32,7 +32,7 @@ intelligence sync
 
 | Command | What it does |
 |---|---|
-| `intelligence init [--preview\|--apply]` | Create, convert, restore or align a project |
+| `intelligence init [--preview\|--apply]` | Create, convert or restore a project |
 | `intelligence sync [adapter] [--compact] [--force]` | Restore locked content, then render or reuse verified unchanged output; `--force` renders and refreshes repository discovery |
 | `intelligence update [@scope/name] [--latest] [--preview\|--apply]` | Plan or apply project and ranged-package updates; `--latest` crosses one package's range |
 | `intelligence upgrade [--next] [--preview\|--apply]` | Replace the installed CLI with the newest version on its npm channel |

package/cli/commands/adapter.sh

@@ -47,7 +47,7 @@ adapter_create() {
     [ -n "$name" ] && [ $# -eq 0 ] || die "usage: intelligence adapter create <name>"
     assert_valid_target_name "$name"
     require_cli_project
-    ensure_project_current "$IP_ROOT"
+    project_as_committed "$IP_ROOT"
     local manifest="$IP_ROOT/intelligence.yaml" content_dir repo_phys probe old_ifs part probe_phys
     local template adapter_dir adapter_phys dest tmp
     local -a parts
@@ -95,7 +95,7 @@ adapter_remove() {
     [ -n "$name" ] || die "usage: intelligence adapter remove <name> [--apply]"
     assert_valid_target_name "$name"
     require_cli_project
-    ensure_project_current "$IP_ROOT"
+    project_as_committed "$IP_ROOT"
     manifest="$IP_ROOT/intelligence.yaml"
     content_dir="$(manifest_intelligence_dir "$manifest")"
     case "$content_dir" in
@@ -140,7 +140,7 @@ case "$action" in
         require_cli_project
         # Held through the final render: target-state and sync join it.
         project_lock_hold "$IP_ROOT"
-        ensure_project_current "$IP_ROOT"
+        project_as_committed "$IP_ROOT"
         if [ "$action" = "enable" ]; then
             state_stage="$(mktemp -d -t intelligence-adapter-state-XXXXXX)"
             cp "$IP_ROOT/intelligence.yaml" "$state_stage/intelligence.yaml"

package/cli/commands/init.sh

@@ -132,7 +132,11 @@ case "$IP_MODE" in
             if project_stamped_ahead "$IP_ROOT"; then
                 echo "  project schema $(read_schema_version "$IP_ROOT/intelligence.yaml") is ahead of engine $(bundled_engine_version) — left as is (update the CLI)"
             elif project_needs_upgrade "$IP_ROOT"; then
-                echo "  would align project lifecycle with engine $(bundled_engine_version)"
+                if [ "$IS_UPGRADE_KIND" = behind ]; then
+                    echo "  project versions trail engine $(bundled_engine_version) — kept as committed; intelligence update moves them"
+                else
+                    echo "  project needs a migration to engine $(bundled_engine_version) — run: intelligence update"
+                fi
             else
                 echo "  schema/content already match engine $(bundled_engine_version)"
             fi
@@ -151,11 +155,7 @@ case "$IP_MODE" in
             fi
             exit 0
         fi
-        if [ "$apply" -eq 1 ]; then
-            ensure_project_current "$IP_ROOT" --explicit
-        else
-            ensure_project_current "$IP_ROOT"
-        fi
+        project_as_committed "$IP_ROOT"
         restore_project_store_if_missing "$IP_ROOT"
         ensure_manifest_gitignore "$IP_ROOT" "$IP_ROOT/intelligence.yaml"
         ensure_manifest_publisher_ignores "$IP_ROOT" "$IP_ROOT/intelligence.yaml"

package/cli/commands/package.sh

@@ -10,17 +10,17 @@ shift
 case "$action" in
     add)
         require_cli_project
-        ensure_project_current "$IP_ROOT"
+        project_as_committed "$IP_ROOT"
         exec bash "$CLI_DIR/internal/package-add.sh" "$@"
         ;;
     remove)
         require_cli_project
-        ensure_project_current "$IP_ROOT"
+        project_as_committed "$IP_ROOT"
         exec bash "$CLI_DIR/internal/package-remove.sh" "$@"
         ;;
     alias)
         require_cli_project
-        ensure_project_current "$IP_ROOT"
+        project_as_committed "$IP_ROOT"
         exec bash "$CLI_DIR/internal/package-alias.sh" "$@"
         ;;
     list)

package/cli/commands/registry.sh

@@ -40,7 +40,7 @@ case "$sub" in
         esac
         assert_safe_source_url "${url#git+}"
         require_cli_project
-        ensure_project_current "$IP_ROOT"
+        project_as_committed "$IP_ROOT"
         # Fail closed: a URL that cannot produce an index is not a registry,
         # and recording it would turn a typo here into a confusing failure at
         # the first add. --force covers the one honest case: the registry is
@@ -71,7 +71,7 @@ case "$sub" in
         url="${2:-}"
         [ -n "$url" ] || die "usage: intelligence registry remove <url>"
         require_cli_project
-        ensure_project_current "$IP_ROOT"
+        project_as_committed "$IP_ROOT"
         registries_remove "$IP_ROOT/intelligence.yaml" "$url"
         # The retired flat-map form also stored scope keys — drop one if the
         # argument names it, so old manifests clean up with the old command.

package/cli/commands/source.sh

@@ -139,7 +139,7 @@ case "$action" in
         dir="$(normalize_source_dir "$dir")"
         assert_valid_source_dir "$IP_ROOT" "$dir"
         [ "$anchor" != "$dir" ] || die "cannot place '$dir' relative to itself"
-        ensure_project_current "$IP_ROOT"
+        project_as_committed "$IP_ROOT"
         manifest="$IP_ROOT/intelligence.yaml"
 
         # The anchor may be spelled differently from the entry it means — a
@@ -189,7 +189,7 @@ case "$action" in
         require_cli_project
         manifest="$IP_ROOT/intelligence.yaml"
         assert_not_package_reference "$manifest" "$dir" remove
-        ensure_project_current "$IP_ROOT"
+        project_as_committed "$IP_ROOT"
 
         if ! sources_has_entry "$manifest" "$section" "$dir"; then
             echo "not listed: sources.$section does not hold $dir"

package/cli/commands/sync.sh

@@ -58,11 +58,10 @@ run_sync() {
             # One writer per project at a time: the store restore and the
             # render below both rewrite shared state (sync-lock.sh).
             hold_project
-            # `sync` is the normal fresh-clone command. A newer globally installed
-            # CLI aligns the current Intelligence project first (except in CI, where a
-            # tracked migration must be reviewed and committed locally), and a
-            # missing ignored store is restored strictly from the committed lock.
-            ensure_project_current "$IP_ROOT" || return $?
+            # `sync` is the normal fresh-clone command. It renders the project as
+            # committed, whichever CLI runs it, and restores a missing ignored
+            # store strictly from the committed lock.
+            project_as_committed "$IP_ROOT" || return $?
             restore_project_store_if_missing "$IP_ROOT" || return $?
             export_engine_env "$IP_ROOT" || return $?
             sync_with_cache "$target" "$force" || return $?
@@ -88,12 +87,10 @@ run_sync() {
     esac
 }
 
-# run_check — the same preflight as sync, except that tracked alignment is never
-# applied (it is reported as needed, in CI or not) and everything but the
-# verdict goes to stderr. Restoring the ignored package store from the lock is
-# allowed: it is reproducible state, and the comparison needs it.
+# run_check — the same preflight as sync, with everything but the verdict on
+# stderr. Restoring the ignored package store from the lock is allowed: it is
+# reproducible state, and the comparison needs it.
 run_check() {
-    local stamp
     detect_project || return $?
     case "$IP_MODE" in
         cli) ;;
@@ -111,15 +108,7 @@ run_check() {
     # shellcheck disable=SC2034  # read by sync-lock.sh when the lock is taken
     SYNC_LOCK_KIND=check
     hold_project
-    project_preflight "$IP_ROOT" || return $?
-    if project_needs_upgrade "$IP_ROOT"; then
-        read_schema_version_var "$IP_ROOT/intelligence.yaml"
-        stamp="$IS_SCHEMA_VERSION"
-        bundled_engine_version_var
-        IS_CHECK_OUT_OF_DATE=1
-        is_status out-of-date "the project needs alignment (stamp ${stamp:-unstamped}, engine $IS_BUNDLED_ENGINE_VERSION); run 'intelligence init --apply' locally, review and commit the diff"
-        return "$IS_RC_OUT_OF_DATE"
-    fi
+    project_as_committed "$IP_ROOT" || return $?
     restore_project_store_if_missing "$IP_ROOT" keep-sources >&2 || return $?
     export_engine_env "$IP_ROOT" || return $?
     sync_check "$target" "$force" || return $?

package/cli/intelligence

@@ -7,6 +7,12 @@
 
 set -euo pipefail
 
+# Bash keeps a PWD inherited from its parent when it names the current
+# directory, so a Windows caller can hand over `D:/x` or `D:\x` for what every
+# other caller sees as `/d/x`. Taken once here, one spelling gives the project
+# one root and the CLI one location, whoever started it.
+case "$PWD" in [A-Za-z]:*) cd -P . ;; esac
+
 case "$0" in
     */*) CLI_DIR="${0%/*}"; [ -n "$CLI_DIR" ] || CLI_DIR="/" ;;
     *) CLI_DIR="." ;;

package/cli/internal/check.sh

@@ -41,7 +41,7 @@ fi
 stamp="$(read_schema_version "$manifest")"
 eng="$(bundled_engine_version)"
 if [ -z "$stamp" ]; then
-    warn "manifest has no schema_version — run 'intelligence init'"
+    warn "manifest has no schema_version — run 'intelligence update'"
 elif _ver_gt "$stamp" "$eng"; then
     if [ "$(_ver_major "$stamp")" -gt "$(_ver_major "$eng")" ]; then
         warn "manifest schema $stamp is a newer major than this CLI's engine $eng — update the CLI: intelligence upgrade (--next for a prerelease line)"
@@ -49,13 +49,17 @@ elif _ver_gt "$stamp" "$eng"; then
         note "manifest schema $stamp is newer than this CLI's engine $eng — the project uses a newer CLI; update it: intelligence upgrade (--next for a prerelease line)"
     fi
 elif _ver_gt "$eng" "$stamp"; then
-    warn "manifest schema $stamp behind engine $eng — run 'intelligence init'"
+    if [ "$(_ver_major "$stamp")" = "$(_ver_major "$eng")" ]; then
+        note "manifest schema $stamp is older than this CLI's engine $eng — kept as committed; move it with: intelligence update"
+    else
+        warn "manifest schema $stamp is an older major than this CLI's engine $eng — run 'intelligence update'"
+    fi
 else
     ok "schema_version $stamp matches the engine"
 fi
 
-# The engine-content package must sit at the bundled engine version — the
-# content documents exactly the scripts the CLI executes.
+# The engine-content package follows the project's own version: the stamp,
+# not the CLI, decides which content renders (decision 0023).
 sync_locked=""
 if [ "$lock_valid" -eq 1 ]; then
     sync_locked="$(qmap_field "$lock" "packages" "$SYNC_PKG_NAME" "resolved")"
@@ -65,12 +69,14 @@ if [ -n "$sync_locked" ]; then
         ok "$SYNC_PKG_NAME at $sync_locked (matches the engine)"
     elif [ "${sync_locked#v}" = "$stamp" ] && _ver_gt "$stamp" "$eng"; then
         note "$SYNC_PKG_NAME at $sync_locked (matches the project schema; the engine is $eng)"
+    elif [ "${sync_locked#v}" = "$stamp" ] && [ "$(_ver_major "$stamp")" = "$(_ver_major "$eng")" ]; then
+        note "$SYNC_PKG_NAME at $sync_locked (matches the project schema; intelligence update moves it to $eng)"
     else
-        warn "$SYNC_PKG_NAME locked at $sync_locked but the engine is $eng — run 'intelligence init'"
+        warn "$SYNC_PKG_NAME locked at $sync_locked but the engine is $eng — run 'intelligence update'"
     fi
 fi
 if [ -d "$IP_ROOT/.intelligence/engine" ]; then
-    warn "stale .intelligence/engine directory (pre-package layout) — run 'intelligence init'"
+    warn "stale .intelligence/engine directory (pre-package layout) — run 'intelligence update'"
 fi
 
 # Manifest packages: names valid, requested intent only, locked and installed.
@@ -96,7 +102,7 @@ while IFS= read -r name; do
             || 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"
+            warn "$name stores source details in the manifest — run 'intelligence update' 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'"

package/cli/lib/cli-common.sh

@@ -344,17 +344,10 @@ export_engine_env() {
 }
 
 # --- Project lifecycle preflight -----------------------------------------
-# Public commands are intentionally few. They share this state gate so a CLI
-# installed at a newer engine version brings the current Intelligence project forward
-# before a mutating operation. The npm install itself cannot do that: it runs
-# outside any project and does not know which repositories the user owns.
-
-is_ci_environment() {
-    case "${CI:-}" in
-        1|true|TRUE|True|yes|YES|Yes|on|ON|On) return 0 ;;
-        *) return 1 ;;
-    esac
-}
+# Public commands are intentionally few. They share this state gate. Only
+# `update` moves a project's versions forward (decision 0023); every other
+# command works on the project as committed, or refuses one that needs a
+# migration first.
 
 # Validate a repository-relative project content directory, including every
 # existing symlinked path component. Call before writing a new manifest.
@@ -395,23 +388,37 @@ project_stamped_ahead() {
     [ -n "$stamp" ] && _ver_gt "$stamp" "$IS_BUNDLED_ENGINE_VERSION"
 }
 
+# project_needs_upgrade <root> — true when `update` would align the project.
+# IS_UPGRADE_KIND says how far behind it is: `behind` when only the schema
+# stamp or the sync content pin trails this engine within its major, which
+# every command renders around, with IS_UPGRADE_DESC naming what trails;
+# `migrate` when the project needs a change only alignment applies (no stamp,
+# an older major, a legacy manifest shape, a sync content pin that is no
+# version).
 project_needs_upgrade() {
     local root="$1" manifest="$1/intelligence.yaml" stamp eng pinned locked name url path rows
-    local lname _requested _url _path resolved _sha
+    local lname _requested _url _path resolved _sha behind=0 pin_behind="" value
+    IS_UPGRADE_KIND="" IS_UPGRADE_DESC=""
     [ -f "$manifest" ] || return 1
     read_schema_version_var "$manifest"
     stamp="$IS_SCHEMA_VERSION"
     bundled_engine_version_var
     eng="$IS_BUNDLED_ENGINE_VERSION"
-    [ -z "$stamp" ] && return 0
+    if [ -z "$stamp" ]; then IS_UPGRADE_KIND=migrate; return 0; fi
     # A project stamped ahead belongs to a newer CLI. Aligning it here would
     # restamp the schema and re-pin the engine content DOWNWARD, and the next
     # teammate on the current CLI would move both back: leave it as found.
     project_stamped_ahead "$root" && return 1
     _qmap_read_var top "$manifest" '' sync_version || true
-    [ -z "$IS_QMAP_OUT" ] || return 0
-    _ver_gt "$eng" "$stamp" && return 0
-    [ -d "$root/.intelligence/engine" ] && return 0
+    if [ -n "$IS_QMAP_OUT" ] || [ -d "$root/.intelligence/engine" ]; then
+        IS_UPGRADE_KIND=migrate; return 0
+    fi
+    if _ver_gt "$eng" "$stamp"; then
+        if [ "$(_ver_major "$stamp")" != "$(_ver_major "$eng")" ]; then
+            IS_UPGRADE_KIND=migrate; return 0
+        fi
+        behind=1
+    fi
 
     # One manifest pass for every package's fields, not a reader per field.
     _qmap_read_var fieldrows "$manifest" packages '' 'url path version' || true
@@ -420,8 +427,7 @@ project_needs_upgrade() {
         [ -n "$name" ] || continue
         # Early RC manifests mixed requested intent with resolved source
         # details. Source URL/path now live only in the required lockfile.
-        [ -n "$url" ] && return 0
-        [ -n "$path" ] && return 0
+        if [ -n "$url" ] || [ -n "$path" ]; then IS_UPGRADE_KIND=migrate; return 0; fi
         if [ "$name" = "$SYNC_PKG_NAME" ]; then
             # The first lock row for the name: what qmap_field would decode.
             locked=""
@@ -431,14 +437,52 @@ project_needs_upgrade() {
                 locked="$resolved"
                 break
             done <<< "$IS_QMAP_OUT"
-            [ "$pinned" = "$eng" ] || return 0
-            if [ -f "$root/intelligence.lock" ]; then
-                [ -n "$locked" ] || return 0
-                [ "${locked#v}" = "$eng" ] || return 0
+            if [ -f "$root/intelligence.lock" ] && [ -z "$locked" ]; then
+                IS_UPGRADE_KIND=migrate; return 0
             fi
+            # The manifest pin, then the lock row. One ahead of this engine is
+            # a newer CLI's, left as found like a stamp ahead (decision 0005).
+            for value in "$pinned" "${locked#v}"; do
+                [ -n "$value" ] && [ "$value" != "$eng" ] || continue
+                case "$value" in [0-9]*.[0-9]*.[0-9]*) ;; *) IS_UPGRADE_KIND=migrate; return 0 ;; esac
+                _ver_gt "$eng" "$value" || continue
+                [ "$(_ver_major "$value")" = "$(_ver_major "$eng")" ] || { IS_UPGRADE_KIND=migrate; return 0; }
+                behind=1
+                [ -n "$pin_behind" ] || pin_behind="$value"
+            done
         fi
     done <<< "$rows"
-    return 1
+    [ "$behind" = 1 ] || return 1
+    IS_UPGRADE_KIND=behind
+    # What the warning names: only the versions that actually trail.
+    if _ver_gt "$eng" "$stamp"; then IS_UPGRADE_DESC="schema $stamp"; fi
+    [ -z "$pin_behind" ] || IS_UPGRADE_DESC="${IS_UPGRADE_DESC:+$IS_UPGRADE_DESC, }$SYNC_PKG_NAME $pin_behind"
+}
+
+# project_as_committed <root> — the gate of every project-aware command but
+# `update`: the preflight, then the project as committed. One whose versions
+# only trail this engine within its major proceeds behind one warning and
+# keeps its tracked bytes; one that needs a migration is refused with
+# IS_STATUS=needs-update and exit 6.
+project_as_committed() {
+    local root="$1" stamp
+    project_preflight "$root" || return $?
+    project_needs_upgrade "$root" || return 0
+    read_schema_version_var "$root/intelligence.yaml"
+    stamp="$IS_SCHEMA_VERSION"
+    bundled_engine_version_var
+    if [ "$IS_UPGRADE_KIND" = behind ]; then
+        # Once per command, however many processes check on the way to the
+        # engine; unindented, so `sync --compact` keeps it.
+        if [ "${IS_PROJECT_BEHIND_WARNED:-}" != "$stamp" ]; then
+            echo "WARNING: project versions ($IS_UPGRADE_DESC) trail this CLI's engine $IS_BUNDLED_ENGINE_VERSION — they stay as committed; move them with: intelligence update" >&2
+            export IS_PROJECT_BEHIND_WARNED="$stamp"
+        fi
+        return 0
+    fi
+    is_status needs-update "stamp=${stamp:-unstamped} engine=$IS_BUNDLED_ENGINE_VERSION"
+    echo "ERROR: the project needs a migration this command does not apply (schema ${stamp:-unstamped}, engine $IS_BUNDLED_ENGINE_VERSION) — run: intelligence update" >&2
+    return "$IS_RC_NEEDS_UPDATE"
 }
 
 # A manifest with packages but no lock has no trustworthy resolved state from
@@ -466,17 +510,16 @@ project_preflight() {
     fi
 }
 
+# ensure_project_current <root> — align the project to this engine. `update`
+# alone calls it (decision 0023).
 ensure_project_current() {
-    local root="$1" explicit="${2:-}" manifest="$1/intelligence.yaml" stamp eng
+    local root="$1" manifest="$1/intelligence.yaml" stamp eng
     project_preflight "$root" || return $?
     project_needs_upgrade "$root" || return 0
     read_schema_version_var "$manifest"
     stamp="$IS_SCHEMA_VERSION"
     bundled_engine_version_var
     eng="$IS_BUNDLED_ENGINE_VERSION"
-    if is_ci_environment && [ "$explicit" != "--explicit" ]; then
-        die "project lifecycle requires alignment (stamp ${stamp:-unstamped}, engine $eng) — run 'intelligence init --apply' locally, review and commit the diff"
-    fi
     echo "  project alignment: stamp ${stamp:-unstamped}, engine $eng"
     bash "$CLI_DIR/internal/align-project.sh" --no-sync || return $?
     project_reads_refresh "$root"

package/cli/lib/lockfile.sh

@@ -70,6 +70,15 @@ lock_validate_checks() {
                 continue
             fi
         fi
+        if [ -z "$sha" ] && [ "$url" = "$SYNC_PKG_URL" ] && [ "$path" = "$SYNC_PKG_PATH" ]; then
+            # Bundle metadata pins the content a CLI ships; only this CLI's own
+            # version restores without a commit. update moves an older pin to it;
+            # a newer one needs a newer CLI.
+            if [[ "$resolved" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] && _ver_gt "${resolved#v}" "$current"; then
+                die "locked restore: $name $resolved has a missing or invalid commit SHA, and this CLI bundles v$current — update the CLI: intelligence upgrade"
+            fi
+            die "locked restore: $name $resolved has a missing or invalid commit SHA, and this CLI bundles v$current — run: intelligence update"
+        fi
         [[ "$sha" =~ ^[0-9a-f]{40}$ || "$sha" =~ ^[0-9a-f]{64}$ ]] \
             || die "locked restore: $name has a missing or invalid commit SHA — restore a valid intelligence.lock"
     done <<< "$rows"
@@ -128,16 +137,19 @@ lock_write_from_tsv() {
 }
 
 # lock_upsert <lock> <name> <requested> <url> <path> <resolved> <sha>
-# Replace-or-append one entry, keeping the others.
+# Replace one entry where it stands, or append a new one, keeping the others:
+# an update changes only that package's lines in the committed lock.
 lock_upsert() {
     local lock="$1" name="$2" requested="$3" url="$4" path="$5" resolved="$6" sha="$7"
-    local tsv
+    local tsv row
     tsv="$(mktemp -t intelligence-lock-XXXXXX 2>/dev/null || mktemp)"
-    {
-        lock_to_tsv "$lock" | awk -F"$LOCK_SEP" -v n="$name" '$1 != n'
-        printf '%s\037%s\037%s\037%s\037%s\037%s\n' \
-            "$name" "$requested" "$url" "$path" "$resolved" "$sha"
-    } > "$tsv"
+    printf -v row '%s\037%s\037%s\037%s\037%s\037%s' \
+        "$name" "$requested" "$url" "$path" "$resolved" "$sha"
+    lock_to_tsv "$lock" | IS_LOCK_ROW="$row" awk -F"$LOCK_SEP" -v n="$name" '
+        $1 == n { if (!done) print ENVIRON["IS_LOCK_ROW"]; done = 1; next }
+        { print }
+        END { if (!done) print ENVIRON["IS_LOCK_ROW"] }
+    ' > "$tsv"
     lock_write_from_tsv "$lock" "$tsv"
     rm -f "$tsv"
 }

package/cli/lib/sync-cache.sh

@@ -4,19 +4,19 @@
 #
 # The record keeps three fingerprints apart (decision 0018), so a check can say
 # which side moved:
-#   tooling  the CLI and engine code, plus the invocation and environment that
-#            shape rendering — target filter, root, layout, bash, locale, PATH,
-#            umask. A change here is not the project's: a check renders rather
-#            than answer "sync needed" from it.
+#   tooling  the CLI and engine code and the adapter filter. A change here is
+#            not the project's: a check renders rather than answer "sync
+#            needed" from it.
 #   inputs   the manifest, the lock, every configured source including skill
 #            resources and installed packages, and the project adapter folder.
 #   outputs  every path the enabled built-in adapters own or manage.
-# Each fingerprint lists names, entry kinds and executable state beside content
-# hashes; timestamps never count. `.intelligence/sync-cache/state` holds the
+# Each fingerprint lists relative names, entry kinds and executable state beside
+# content hashes; timestamps, the project's location and the caller's
+# environment never count. `.intelligence/sync-cache/state` holds the
 # record and the report a hit replays; `seal` holds the state file's own hash,
 # so a record is trusted only whole.
 
-SC_FORMAT='intelligence-sync-cache-v2'
+SC_FORMAT='intelligence-sync-cache-v3'
 SC_SAFE_SEEN=$'\n'
 
 sync_cache_safe_path() {
@@ -155,6 +155,19 @@ sync_cache_dependencies() {
 }
 
 # --- Fingerprint ---------------------------------------------------------------
+# sync_cache_label_var <path> — IS_SC_LABEL, the name a fingerprint records for
+# a path: relative to the engine or CLI directory for tooling, to the project
+# otherwise. Where the project or the CLI lives, and how that path is spelled,
+# never decides whether the same files are current.
+sync_cache_label_var() {
+    case "$1" in
+        "$IS_ENGINE_DIR"|"$IS_ENGINE_DIR"/*) IS_SC_LABEL="engine${1#"$IS_ENGINE_DIR"}" ;;
+        "$CLI_DIR"|"$CLI_DIR"/*) IS_SC_LABEL="cli${1#"$CLI_DIR"}" ;;
+        "$REPO_ROOT"/*) IS_SC_LABEL="${1#"$REPO_ROOT/"}" ;;
+        *) IS_SC_LABEL="$1" ;;
+    esac
+}
+
 # _sync_cache_starts <group> <path>... — queue a group's start points. A missing
 # one is recorded as missing; a repeated one is walked once.
 _sync_cache_starts() {
@@ -171,7 +184,8 @@ _sync_cache_starts() {
             SC_STARTS+=("$path")
             SC_START_GROUPS+=("$group")
         else
-            SC_MISSING+=("$group missing $path")
+            sync_cache_label_var "$path"
+            SC_MISSING+=("$group missing $IS_SC_LABEL")
         fi
     done
 }
@@ -190,7 +204,7 @@ _SC_AWK_LISTING='
         starts = split(ENVIRON["SC_AWK_STARTS"], rows, "\n")
         for (i = 1; i <= starts; i++) {
             split(rows[i], field, "\t")
-            group[i] = field[1]; posix[i] = field[2]; native[i] = field[3]
+            group[i] = field[1]; posix[i] = field[2]; native[i] = field[3]; label[i] = field[4]
         }
         probe = ENVIRON["SC_AWK_EXEC_PROBE"]
         stream = (ENVIRON["SC_AWK_STREAM"] == 1)
@@ -209,7 +223,7 @@ _SC_AWK_LISTING='
             if (!last) { bad = 1; return }
         }
         g = group[last]
-        listing[g] = listing[g] kind " " entry "\037"
+        listing[g] = listing[g] kind " " label[last] substr(entry, length(posix[last]) + 1) "\037"
         if (kind == "d") return
         k = ++files[g]
         path = native[last] substr(entry, length(posix[last]) + 1)
@@ -248,7 +262,7 @@ _SC_AWK_LISTING='
 # the listing stage tells kinds without a stat per entry. git hashes the files
 # while the walk is still running.
 sync_cache_fingerprint() {
-    local target="$1" hashes i j n value ordered=0 starts_env="" state="" umask_value
+    local target="$1" hashes i j n value ordered=0 starts_env="" state=""
     local tooling inputs outputs listing saved_ifs="$IFS"
     local -a hash_lines=() expression=() keep=() starts=() groups=() natives=() parts=() count=()
     SC_STARTS=() SC_START_GROUPS=() SC_MISSING=() SC_START_SEEN=$'\n'
@@ -299,7 +313,8 @@ sync_cache_fingerprint() {
     for ((j = 0; j < ${#starts[@]}; j++)); do
         value="${starts[j]}"
         [ "$SC_TRANSLATE" != 1 ] || value="${natives[j]}"
-        starts_env="$starts_env${groups[j]}"$'\t'"${starts[j]}"$'\t'"$value"$'\n'
+        sync_cache_label_var "${starts[j]}"
+        starts_env="$starts_env${groups[j]}"$'\t'"${starts[j]}"$'\t'"$value"$'\t'"$IS_SC_LABEL"$'\n'
     done
     starts_env="${starts_env%$'\n'}"
     expression=(\( ! -type d ! -type f -exec false {} + \)
@@ -359,15 +374,11 @@ sync_cache_fingerprint() {
     [ "${count[0]}" -eq 0 ] || { printf -v value '%s\037' "${hash_lines[@]:0:${count[0]}}"; tooling="$tooling$value"; }
     [ "${count[1]}" -eq 0 ] || { printf -v value '%s\037' "${hash_lines[@]:${count[0]}:${count[1]}}"; inputs="$inputs$value"; }
     [ "${count[2]}" -eq 0 ] || { printf -v value '%s\037' "${hash_lines[@]:$((count[0] + count[1])):${count[2]}}"; outputs="$outputs$value"; }
-    # Explicit values that affect rendering, discovery or parsing. No secrets
-    # or inherited environment dump are persisted. umask prints into a file so
-    # reading it costs no subshell.
-    umask > "$SC_SCRATCH.umask" || return 1
-    IFS= read -r umask_value < "$SC_SCRATCH.umask" || return 1
-    for value in "$target" "$REPO_ROOT" "$CONFIG_FILE" "$IS_CONTENT_REL" "$IS_MODULE_REL" \
-        "$IS_SYNC_CMD" "$IS_MANIFEST_NAME" "$IS_PROTECTED_DIRS" "$BASH_VERSION" "${OSTYPE:-}" \
-        "${LANG:-}" "${LC_ALL:-}" "${LC_CTYPE:-}" "${LC_COLLATE:-}" "${PATH:-}" "$umask_value" \
-        "exec-probe=$SC_EXEC_PROBE" "walk-ordered=$ordered"; do
+    # The adapter filter selects what renders; the two listing flags say how
+    # the listings above were made. Nothing else of the invocation counts:
+    # the code, the manifest and the files decide what sync writes, wherever
+    # the project lives and whoever starts the CLI.
+    for value in "filter=$target" "exec-probe=$SC_EXEC_PROBE" "walk-ordered=$ordered"; do
         case "$value" in *[[:cntrl:]]*) return 1 ;; esac
         tooling="${tooling}env $value"$'\037'
     done
@@ -514,9 +525,15 @@ sync_with_cache() {
 
 # The write contract marks links whose spelling must remain unchanged: they
 # are compared, never dereferenced, and are not renderer read inputs.
+#
+# SC_CHECK_OUTPUTS holds the selected adapters' paths; SC_CHECK_ALL_OUTPUTS
+# every enabled adapter's, since a filtered render still reads what the others
+# generated. SC_CHECK_PROJECT_ADAPTER is 1 when an enabled adapter is the
+# project's own code.
 sync_check_write_paths() {
     local filter="$1" dir file name i output adapter kind value
     local -a names=() files=() batch=()
+    SC_CHECK_PROJECT_ADAPTER=0
     for dir in "$IS_ENGINE_DIR/adapters" "$REPO_ROOT/$IS_CONTENT_REL/adapters"; do
         for file in "$dir"/*.sh; do
             [ -f "$file" ] || continue
@@ -530,41 +547,142 @@ sync_check_write_paths() {
     i=0
     while [ "$i" -lt "${#names[@]}" ]; do
         name="${names[i]}"; file="${files[i]}"; i=$((i + 1))
-        [ -z "$filter" ] || [ "$name" = "$filter" ] || continue
         target_enabled_var "$CONFIG_FILE" "$name"
         [ "$IS_TGT_ENABLED" = 1 ] || continue
+        case "$file" in "$REPO_ROOT/$IS_CONTENT_REL/adapters/"*) SC_CHECK_PROJECT_ADAPTER=1 ;; esac
         target_output_var "$CONFIG_FILE" "$name"
         output="${IS_TGT_OUTPUT:-.$name}"
         batch+=("$name" "$file" "$output")
     done
-    SC_CHECK_OUTPUTS=()
+    SC_CHECK_OUTPUTS=() SC_CHECK_ALL_OUTPUTS=()
     [ "${#batch[@]}" -gt 0 ] || return 0
     adapter_contract_records_batch "$SC_SCRATCH.check-contract" "${batch[@]}" > "$SC_SCRATCH.check-records" || return 1
     while IFS=$'\t' read -r adapter kind value; do
-        case "$kind" in owned|managed) SC_CHECK_OUTPUTS+=("$value") ;; esac
+        case "$kind" in
+            owned|managed)
+                SC_CHECK_ALL_OUTPUTS+=("$value")
+                [ -z "$filter" ] || [ "$adapter" = "$filter" ] || continue
+                SC_CHECK_OUTPUTS+=("$value")
+                ;;
+        esac
     done < "$SC_SCRATCH.check-records"
 }
 
+# sync_check_unlinked_path <rel> — true when no existing component of the
+# project path, the last included, is a link. Copying such a path alone would
+# leave its link pointing at something the copy does not hold.
+sync_check_unlinked_path() {
+    local rest="$1" probe="$REPO_ROOT" part
+    while [ -n "$rest" ]; do
+        part="${rest%%/*}"
+        if [ "$part" = "$rest" ]; then rest=""; else rest="${rest#*/}"; fi
+        probe="$probe/$part"
+        [ ! -L "$probe" ] || return 1
+        [ -e "$probe" ] || return 0
+    done
+}
+
+# sync_check_copy_paths — SC_CHECK_COPY, the existing project paths a render
+# by built-in adapters reads or writes, none inside another. Return 1 when only
+# a copy of the whole project is faithful: a project adapter may read any file,
+# and a link on the way to an input may point anywhere in the project.
+# Everything else the engine reads in the project is a directory listing the
+# check takes from the live tree (warn_unsynced).
+sync_check_copy_paths() {
+    local section src rel other kept
+    local -a wanted=("${CONFIG_FILE#"$REPO_ROOT/"}" intelligence.lock .intelligence/packages
+        "$IS_CONTENT_REL/adapters" .agents/rules .agents/agents)
+    SC_CHECK_COPY=()
+    [ "$SC_CHECK_PROJECT_ADAPTER" = 0 ] || return 1
+    for section in rules agents skills; do
+        load_yaml_list "$CONFIG_FILE" "$section"
+        while IFS= read -r src; do
+            case "$src" in
+                ''|/*|..|../*|*/..|*/../*) continue ;; # Outside the project: read where it is.
+            esac
+            wanted+=("$src")
+        done <<< "$IS_YAML_LIST"
+    done
+    wanted+=(${SC_CHECK_ALL_OUTPUTS[@]+"${SC_CHECK_ALL_OUTPUTS[@]}"})
+    for rel in "${wanted[@]}"; do
+        normalize_path_var "/$rel"
+        rel="${IS_NORM_PATH#/}"
+        case "$rel" in ''|.git|.git/*) return 1 ;; esac
+        sync_check_unlinked_path "$rel" || return 1
+        [ -e "$REPO_ROOT/$rel" ] || continue
+        kept=()
+        for other in ${SC_CHECK_COPY[@]+"${SC_CHECK_COPY[@]}"}; do
+            case "$rel" in "$other"|"$other"/*) continue 2 ;; esac
+            case "$other" in "$rel"/*) continue ;; esac
+            kept+=("$other")
+        done
+        SC_CHECK_COPY=(${kept[@]+"${kept[@]}"} "$rel")
+    done
+}
+
+# sync_check_holds <private-project> <rel> — true when the private copy holds
+# the project path: inside a copied entry, never a directory made only as the
+# parent of one. An empty SC_CHECK_COPY means the whole project was copied.
+sync_check_holds() {
+    local entry
+    [ -e "$1/$2" ] || [ -L "$1/$2" ] || return 1
+    [ "${#SC_CHECK_COPY[@]}" -gt 0 ] || return 0
+    for entry in "${SC_CHECK_COPY[@]}"; do
+        case "$2" in "$entry"|"$entry"/*) return 0 ;; esac
+    done
+    return 1
+}
+
 # Check renders use a private project tree. A rollback in the live tree would
-# overwrite unrelated edits made while the renderer was running.
+# overwrite unrelated edits made while the renderer was running. The tree holds
+# only what the render reads and writes: a copy of the whole project took
+# minutes and gigabytes where dependency and build trees sit beside the sources.
 sync_check_render() (
-    local target="$1" verdict="$2" staging entry link target_link manifest_rel rel output is_output original_target original_root="$REPO_ROOT" rc=0
-    local -a SC_CHECK_OUTPUTS=()
+    local target="$1" verdict="$2" staging entry link target_link manifest_rel rel output is_output original_target original_root="$REPO_ROOT" rc=0 parent
+    local -a SC_CHECK_OUTPUTS=() SC_CHECK_ALL_OUTPUTS=() SC_CHECK_COPY=() parents=() batch=()
+    local SC_CHECK_PROJECT_ADAPTER=0
     sync_check_write_paths "$target" || return 1
     manifest_rel="${CONFIG_FILE#"$REPO_ROOT/"}"
     staging="$(mktemp -d -t intelligence-check-XXXXXX)" || return 1
     trap 'rm -rf "$staging"' EXIT
     trap 'exit 130' INT
     trap 'exit 143' TERM
-    mkdir "$staging/project" || { rm -rf "$staging"; return 1; }
-    for entry in "$REPO_ROOT"/* "$REPO_ROOT"/.[!.]* "$REPO_ROOT"/..?*; do
-        [ -e "$entry" ] || [ -L "$entry" ] || continue
-        # Git history is not a renderer input. The project lock contains the
-        # check's scratch buffers and must stay solely in the real project.
-        [ "${entry##*/}" != .git ] || continue
-        cp -a "$entry" "$staging/project/" || rc=$?
-        [ "$rc" = 0 ] || break
-    done
+    # A run killed outright never reaches its trap; the lock's release or
+    # takeover removes the copy it names here.
+    : > "$staging/.intelligence-check" || return 1
+    printf '%s\n' "$staging" > "$SC_SCRATCH.tmpdir" || return 1
+    mkdir "$staging/project" || return 1
+    if sync_check_copy_paths; then
+        # One copy per parent directory: on Git Bash each process costs tens
+        # of milliseconds.
+        for rel in ${SC_CHECK_COPY[@]+"${SC_CHECK_COPY[@]}"}; do
+            parent=.
+            case "$rel" in */*) parent="${rel%/*}" ;; esac
+            for entry in ${parents[@]+"${parents[@]}"}; do
+                [ "$entry" != "$parent" ] || continue 2
+            done
+            parents+=("$parent")
+        done
+        for parent in ${parents[@]+"${parents[@]}"}; do
+            batch=()
+            for rel in "${SC_CHECK_COPY[@]}"; do
+                entry=.
+                case "$rel" in */*) entry="${rel%/*}" ;; esac
+                [ "$entry" != "$parent" ] || batch+=("$REPO_ROOT/$rel")
+            done
+            mkdir -p "$staging/project/$parent" && cp -a "${batch[@]}" "$staging/project/$parent/" || { rc=1; break; }
+        done
+    else
+        SC_CHECK_COPY=()
+        for entry in "$REPO_ROOT"/* "$REPO_ROOT"/.[!.]* "$REPO_ROOT"/..?*; do
+            [ -e "$entry" ] || [ -L "$entry" ] || continue
+            # Git history is not a renderer input. The project lock contains the
+            # check's scratch buffers and must stay solely in the real project.
+            [ "${entry##*/}" != .git ] || continue
+            cp -a "$entry" "$staging/project/" || rc=$?
+            [ "$rc" = 0 ] || break
+        done
+    fi
     if [ "$rc" = 0 ]; then
         # Never remove or rewrite through a copied directory link: it may
         # still point at the live project or an external source.
@@ -575,7 +693,9 @@ sync_check_render() (
         while IFS= read -r -d '' link; do
             target_link="$(readlink "$link")" || { rc=1; break; }
             # Output links need no relocation: comparison never follows them.
-            # Internal absolute links still move with their copied project.
+            # Internal absolute links still move with their copied project;
+            # one into a part of the project the copy does not hold keeps
+            # reading the live path, which a render only ever reads.
             rel="${link#"$staging/project/"}"
             is_output=0
             for output in ${SC_CHECK_OUTPUTS[@]+"${SC_CHECK_OUTPUTS[@]}"}; do
@@ -586,6 +706,7 @@ sync_check_render() (
                     rm "$link" && ln -s "$staging/project" "$link" || { rc=1; break; }
                     ;;
                 "$REPO_ROOT"/*)
+                    sync_check_holds "$staging/project" "${target_link#"$REPO_ROOT/"}" || continue
                     rm "$link" && ln -s "$staging/project/${target_link#"$REPO_ROOT/"}" "$link" || { rc=1; break; }
                     ;;
                 /*) ;; # Absolute external links already retain their resolution.
@@ -596,7 +717,10 @@ sync_check_render() (
                     original_target="$IS_NORM_PATH"
                     case "$original_target" in
                         "$REPO_ROOT") original_target="$staging/project" ;;
-                        "$REPO_ROOT"/*) original_target="$staging/project/${original_target#"$REPO_ROOT/"}" ;;
+                        "$REPO_ROOT"/*)
+                            entry="${original_target#"$REPO_ROOT/"}"
+                            if sync_check_holds "$staging/project" "$entry"; then original_target="$staging/project/$entry"; fi
+                            ;;
                     esac
                     normalize_path_var "${link%/*}/$target_link"
                     [ "$IS_NORM_PATH" != "$original_target" ] || continue

package/cli/lib/sync-lock.sh

@@ -117,6 +117,36 @@ sync_lock_held_by_check() {
     [ "$kind" = check ]
 }
 
+# sync_lock_tmpdirs <lock> — SYNC_LOCK_TMPDIRS, the temporary directories
+# outside the lock that its holder's runs named in `scratch.<pid>.tmpdir`
+# files. A run killed outright never reaches the trap that removes its own, so
+# whoever releases or takes over the lock removes them. A record is only a
+# file in the project, so it names nothing to remove unless the directory is
+# one the CLI made: an absolute, real `intelligence-check-*` directory holding
+# the marker `.intelligence-check` that the check writes first.
+sync_lock_tmpdirs() {
+    local record dir
+    SYNC_LOCK_TMPDIRS=()
+    for record in "$1"/scratch.*.tmpdir; do
+        [ -f "$record" ] || continue
+        dir=""
+        IFS= read -r dir < "$record" || [ -n "$dir" ] || continue
+        case "$dir" in /*) ;; *) continue ;; esac
+        case "$dir" in *[[:cntrl:]]*|*/./*|*/../*|*/.|*/..) continue ;; esac
+        case "${dir##*/}" in intelligence-check-?*) ;; *) continue ;; esac
+        [ -d "$dir" ] && [ ! -L "$dir" ] && [ -f "$dir/.intelligence-check" ] || continue
+        SYNC_LOCK_TMPDIRS+=("$dir")
+    done
+}
+
+# Removing an abandoned copy can take long; it never keeps the lock looking
+# ownerless or a takeover in progress.
+sync_lock_remove_tmpdirs() {
+    [ "${#SYNC_LOCK_TMPDIRS[@]}" -eq 0 ] || rm -rf "${SYNC_LOCK_TMPDIRS[@]}" 2>/dev/null || true
+    SYNC_LOCK_TMPDIRS=()
+}
+SYNC_LOCK_TMPDIRS=()
+
 # sync_lock_acquire <root> — take <root>/.intelligence/sync.lock, or refuse.
 # A writer waits for each check that holds it for up to SYNC_LOCK_CHECK_WAIT
 # seconds; a check refuses at once.
@@ -127,6 +157,7 @@ sync_lock_acquire() {
     [ -d "$root/.intelligence" ] || mkdir -p "$root/.intelligence" || die "cannot create $root/.intelligence"
     while :; do
         took=0
+        SYNC_LOCK_TMPDIRS=()
         if mkdir "$lock" 2>/dev/null; then
             took=1
         elif sync_lock_is_stale "$lock" && mkdir "$lock.takeover" 2>/dev/null; then
@@ -136,10 +167,15 @@ sync_lock_acquire() {
             # Judge again under it: another run may have taken the lock over
             # since this one looked.
             if sync_lock_is_stale "$lock"; then
+                sync_lock_tmpdirs "$lock"
                 rm -rf "$lock"
                 mkdir "$lock" 2>/dev/null && took=1
             fi
             rmdir "$lock.takeover"
+            # Their records went with the lock: remove them now even when
+            # another run took it first. A lock this run took gets its owner
+            # before any of that time is spent.
+            [ "$took" = 1 ] || sync_lock_remove_tmpdirs
         elif [ -d "$lock.takeover" ] && [ -n "$(find "$lock.takeover" -maxdepth 0 -mmin +1 2>/dev/null)" ]; then
             # A takeover runs for milliseconds. Removing an abandoned one is itself
             # a check-then-delete race, so it is left to a person.
@@ -147,6 +183,7 @@ sync_lock_acquire() {
         fi
         if [ "$took" = 1 ]; then
             sync_lock_write_owner "$lock" || { rm -rf "$lock"; die "cannot write $lock/owner"; }
+            sync_lock_remove_tmpdirs
             SYNC_LOCK_HELD="$lock"
             return 0
         fi
@@ -224,6 +261,9 @@ project_lock_hold() {
 sync_lock_release() {
     [ -n "$SYNC_LOCK_HELD" ] || return 0
     if sync_lock_read_owner "$SYNC_LOCK_HELD" && [ "$IS_LOCK_TOKEN" = "$SYNC_LOCK_TOKEN" ]; then
+        # While the owner still stands, so a waiter keeps waiting.
+        sync_lock_tmpdirs "$SYNC_LOCK_HELD"
+        sync_lock_remove_tmpdirs
         # A check's owner goes first: `rm -rf` alone could expose a moment with
         # the owner still there and the kind gone, and a command waiting for
         # the check would be refused in it. Without the owner, a waiter sees a

package/engine/ENGINE_SHA

@@ -1 +1 @@
-ee05b0f09bc74b1914e04c067cce1e87a75bd18a
+79201cedae74ec96e67c3aa94e267f6b1e226c23

package/engine/VERSION

@@ -1 +1 @@
-0.22.0
+0.23.0

package/engine/adapters/claude-plugin/hooks/register.js

@@ -196,6 +196,9 @@ async function runCheck($) {
   // session's check — is not a fault: the last verdict stays, and the check
   // asks again shortly instead of queueing ahead of a waiting sync.
   else if (LOCK_REFUSAL.test(result.stderr || '')) retrySoon($)
+  // A project that needs a migration names the command that applies it on
+  // stderr; the status detail only names the versions.
+  else if (parsed.status === 'needs-update') setState('error', reasonLine(result.stderr) || 'run intelligence update')
   else setState('error', parsed.detail || reasonLine(result.stderr) || 'exit ' + result.exitCode)
   show($)
 }

package/engine/lib/contract.sh

@@ -83,9 +83,9 @@ IS_RC_CONFIG_MISSING=2      # no manifest found
 IS_RC_AMBIGUOUS=3           # conflicting state; agent/human-only — bash never emits this itself
 IS_RC_AHEAD=4               # project stamped newer than this engine understands
 IS_RC_ABORTED_INCOMPLETE=5  # staged state incomplete; the project was left untouched
-IS_RC_NEEDS_UPDATE=6        # pending schema changes (stamp < engine) — run `intelligence init --apply`
+IS_RC_NEEDS_UPDATE=6        # a migration only `intelligence update` applies (no stamp, older major)
 # `intelligence sync --check` only: generated files differ from what sync would
-# leave, or alignment is pending (IS_STATUS=out-of-date). It shares 2 with
+# leave (IS_STATUS=out-of-date). It shares 2 with
 # config-missing, which a check never reports: the CLI found the manifest, and
 # the check turns any other failure that ends in 2 into 1.
 IS_RC_OUT_OF_DATE=2

package/engine/sync.sh

@@ -39,10 +39,10 @@ _vc_rc=0
 check_version_compat "$_cf" || _vc_rc=$?
 if [ "$_vc_rc" -ne 0 ]; then exit "$_vc_rc"; fi
 
-# Schema gap → refuse. sync is a PURE synchronizer: it never changes schemas,
-# so the CLI lifecycle preflight must align the project first. An ABSENT stamp
-# means the same thing — a manifest with no
-# `schema_version` must not silently sync past a schema change.
+# sync is a PURE synchronizer: it never changes a schema. The manifest is
+# additive within a major, so an older stamp of the same major renders as
+# committed behind one warning (decision 0023); an older major, or no stamp at
+# all, needs the migration only `intelligence update` applies.
 read_schema_version_var "$_cf"
 _stamp="$IS_SCHEMA_VERSION"
 engine_version_var
@@ -51,13 +51,18 @@ _eng="$IS_ENGINE_VERSION"
 if [ -z "$_stamp" ]; then
     is_status needs-update "stamped= engine=$_eng (no schema_version)"
     echo "ERROR: the manifest has no schema_version — schema un-applied." >&2
-    echo "       Run: intelligence init --apply" >&2
+    echo "       Run: intelligence update" >&2
     exit "$IS_RC_NEEDS_UPDATE"
 elif [ -n "$_eng" ] && _ver_gt "$_eng" "$_stamp"; then
-    is_status needs-update "stamped=$_stamp engine=$_eng"
-    echo "ERROR: project at $_stamp but engine is $_eng — pending schema changes." >&2
-    echo "       Run: intelligence init --apply" >&2
-    exit "$IS_RC_NEEDS_UPDATE"
+    if [ "$(_ver_major "$_stamp")" != "$(_ver_major "$_eng")" ]; then
+        is_status needs-update "stamped=$_stamp engine=$_eng"
+        echo "ERROR: project at $_stamp but engine is $_eng — an older major schema." >&2
+        echo "       Run: intelligence update" >&2
+        exit "$IS_RC_NEEDS_UPDATE"
+    fi
+    if [ "${IS_PROJECT_BEHIND_WARNED:-}" != "$_stamp" ]; then
+        echo "WARNING: project versions (schema $_stamp) trail this CLI's engine $_eng — they stay as committed; move them with: intelligence update" >&2
+    fi
 fi
 
 # Normalize REPO_ROOT and CONFIG_FILE to one `cd && pwd` spelling so
@@ -742,10 +747,14 @@ SYNC_TX_ACTIVE=0
 #     defaults move forward — e.g., gpt-5.5 -> gpt-5.6).
 # Concurrently, the scan runs beside the other two and beside removing the
 # snapshots; the buffers print in the order above.
+# A check renders in a copy that holds only the project's inputs and outputs; the
+# scan lists directories and reads no bytes, so it looks at the live project.
+UNSYNCED_ROOT="$REPO_ROOT"
+[ -z "${IS_SYNC_CHECK:-}" ] || [ -z "${IS_SYNC_CHECK_ROOT:-}" ] || UNSYNCED_ROOT="$IS_SYNC_CHECK_ROOT"
 if [ "$SYNC_PARALLEL" = 1 ]; then
     rm -rf "$SYNC_TX_DIR/data" &
     SYNC_BG_PIDS+=("$!")
-    warn_unsynced "$REPO_ROOT" "$CONFIG_FILE" > "$SYNC_TX_DIR/unsynced" 2>&1 &
+    warn_unsynced "$UNSYNCED_ROOT" "$CONFIG_FILE" > "$SYNC_TX_DIR/unsynced" 2>&1 &
     SYNC_BG_PIDS+=("$!")
     {
         report_context_source_sizes "$REPO_ROOT" "$CONFIG_FILE"
@@ -758,7 +767,7 @@ if [ "$SYNC_PARALLEL" = 1 ]; then
 else
     rm -rf "$SYNC_TX_DIR"
     trap - EXIT INT TERM
-    warn_unsynced "$REPO_ROOT" "$CONFIG_FILE"
+    warn_unsynced "$UNSYNCED_ROOT" "$CONFIG_FILE"
     report_context_source_sizes "$REPO_ROOT" "$CONFIG_FILE"
     report_model_drift "$CONFIG_FILE"
 fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainova-systems/intelligence",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Build, version and distribute AI agent intelligence across your organization — one CLI, versioned Intelligence Packages, and a sync engine for Claude Code, Cursor, Copilot, Codex, Pi and OpenCode.",
   "bin": {
     "intelligence": "bin/intelligence.js"

package/packages/sync/references/conventions.md

@@ -125,7 +125,7 @@ Practice:
 
 Commit `intelligence.lock`. It records requested versions, source URLs and paths, resolved refs and commit SHAs. After cloning, or after a pull that moved the lock, `intelligence sync` restores every package the store lacks or holds at another commit, strictly from that lock, before rendering; manifest/lock or SHA drift is refused. Re-run `package add` when deliberately changing a source.
 
-`@ainova-systems/sync` is ordinary package content exact-pinned to the bundled engine version. `intelligence init` installs it unless `--bare` is used. Lifecycle preflight keeps that pin and `schema_version` aligned with the installed CLI; package-range updates never move it independently.
+`@ainova-systems/sync` is ordinary package content exact-pinned to the bundled engine version. `intelligence init` installs it unless `--bare` is used. Only `intelligence update` moves that pin and `schema_version` to the installed CLI; every other command keeps them as committed, and package-range updates never move the pin independently.
 
 ## Layout tokens
 
@@ -504,15 +504,15 @@ The permanent applied-schema key is the top-level scalar `schema_version` in `in
 
 The public lifecycle is deliberately compact:
 
-- `intelligence init [--preview|--apply]` is universal: it creates a new setup, aligns an existing Intelligence project, or plans/applies conversion of an eligible legacy Intelligence Sync project.
-- `intelligence sync [adapter] [--compact] [--force] [--check]` first aligns an existing Intelligence project with the installed CLI and restores every package the store lacks or holds at another commit, strictly from `intelligence.lock`. It skips rendering when local inputs and outputs match a previous successful run. Changes or missing outputs trigger rendering; `--force` always renders and refreshes the search for unconfigured source directories. An unchanged run replays the last full run's useful diagnostics. Compact mode shows context sizes, actionable warnings and final status on success, and all diagnostics on failure. In CI it refuses an alignment that would change tracked files and points to a local `intelligence init --apply` plus review/commit. `--check` changes no generated file: it prints one `IS_STATUS` line and exits 0 when generated files are up to date and 2 (`out-of-date`) when sync would change them or alignment is pending; it never applies alignment.
+- `intelligence init [--preview|--apply]` is universal: it creates a new setup, restores an existing Intelligence project as committed, or plans/applies conversion of an eligible legacy Intelligence Sync project.
+- `intelligence sync [adapter] [--compact] [--force] [--check]` first restores every package the store lacks or holds at another commit, strictly from `intelligence.lock`. It skips rendering when local inputs and outputs match a previous successful run. Changes or missing outputs trigger rendering; `--force` always renders and refreshes the search for unconfigured source directories. An unchanged run replays the last full run's useful diagnostics. Compact mode shows context sizes, actionable warnings and final status on success, and all diagnostics on failure. It renders an Intelligence project at its committed versions: versions that trail the installed CLI within its major render behind one warning naming `intelligence update`; a project that needs a migration first — no `schema_version` or an older major — is refused with `needs-update`, locally and in CI alike. `--check` changes no generated file: it prints one `IS_STATUS` line and exits 0 when generated files are up to date and 2 (`out-of-date`) when sync would change them; it never moves a version.
 - `intelligence update [@scope/name] [--preview|--apply]` is the only update surface. It prints the CLI/project/package plan; default mode prompts, `--preview` never writes, and `--apply` does not prompt. It never moves `ref:` pins.
 - `intelligence upgrade [--next] [--preview|--apply]` replaces the installed CLI with the newest version on its npm channel (`next` for a prerelease or with `--next`, otherwise `latest`) with the same modes. It touches no project, never downgrades, and refuses an installation that npm did not make.
 - `intelligence package add|remove|list|search` owns package inventory.
 - `intelligence adapter list|create|enable|disable|remove` owns adapter inventory and target state.
 - `intelligence status [--check]` reports state; `--check` runs deep consistency checks.
 
-Implement Intelligence schema changes as idempotent structural checks. Stage and verify replacement state before deleting or replacing prior state. A stale engine refuses a manifest whose `schema_version` is a newer major; a newer minor or patch within the same major warns once and proceeds without restamping the project. Normal project entry points close a behind-project gap through lifecycle preflight.
+Implement Intelligence schema changes as idempotent structural checks. Stage and verify replacement state before deleting or replacing prior state. A stale engine refuses a manifest whose `schema_version` is a newer major; a newer minor or patch within the same major warns once and proceeds without restamping the project. A project behind the engine stays as committed until `intelligence update` closes the gap.
 
 Breaking changelog entries use a `### Breaking` checklist of verifiable post-conditions. The `intelligence-upgrade` skill reads every release across the version gap, chooses the package/CLI/project command sequence and verifies those conditions after the deterministic command completes.
 
@@ -526,11 +526,11 @@ The engine emits one machine-readable line, `IS_STATUS=<code> [IS_DETAIL=...]`,
 | `migrated` | 0 | Initialization converted an older layout |
 | `error` | 1 | Generic failure |
 | `config-missing` | 2 | Required manifest is absent |
-| `out-of-date` | 2 | `sync --check` only: sync would change generated files, or alignment is pending. A check never reports `config-missing`, and turns any other failure that would end in 2 into 1 |
+| `out-of-date` | 2 | `sync --check` only: sync would change generated files. A check never reports `config-missing`, and turns any other failure that would end in 2 into 1 |
 | `ambiguous` | 3 | Conflicting state requiring agent/human judgment; reserved |
 | `ahead-of-engine` | 4 | Manifest schema is a newer major than the engine (a newer minor or patch warns and continues) |
 | `aborted-incomplete` | 5 | Staged replacement was incomplete; prior state remains |
-| `needs-update` | 6 | Project schema is behind the engine; rerun through a public lifecycle command |
+| `needs-update` | 6 | The project needs a migration only `intelligence update` applies: no `schema_version`, or an older major |
 
 Callers capture the real code with `command || rc=$?`. Do not use `if ! command; then rc=$?`; inside that branch `$?` is the status of the negation.
 

package/packages/sync/skills/intelligence-learn-from-repository/SKILL.md

@@ -28,8 +28,11 @@ mechanics; this skill supplies repository judgement.
 3. Run `intelligence status --check`. If the project is missing, inconsistent,
    or its first sync failed, run `intelligence init --preview`, show the exact
    repair plan, and request approval. After approval run
-   `intelligence init --apply`. Do not reproduce manifest, package, adapter,
-   backup, or ignore-file mechanics manually.
+   `intelligence init --apply`. When the check or the plan names
+   `intelligence update` instead, the project's versions need moving: show
+   `intelligence update --preview` and run `intelligence update --apply` only
+   after approval. Do not reproduce manifest, package, adapter, backup, or
+   ignore-file mechanics manually.
 4. Run `intelligence sync`. Sync is transactional: a failure restores every
    adapter-owned path. Resolve the reported cause and retry. Do not begin
    semantic migration until `IS_STATUS=ok` and `intelligence status --check`

package/packages/sync/skills/intelligence-sync/SKILL.md

@@ -8,16 +8,17 @@ context: fork
 # Sync intelligence
 
 1. Run `intelligence sync` (or `intelligence sync <adapter>` when one adapter
-   was requested). For Intelligence projects, this command first aligns project schema/content
-   with the installed CLI and restores a missing package store strictly from
-   `intelligence.lock`. Unchanged inputs and outputs can reuse a successful run.
+   was requested). For Intelligence projects, this command renders the project
+   at its committed versions and first restores a missing package store strictly
+   from `intelligence.lock`. Unchanged inputs and outputs can reuse a successful run.
    Use `--force` when a fresh render or a new search for unconfigured source
    directories is requested; an unchanged run replays the previous diagnostics.
 2. Require final `IS_STATUS=ok`; relay reported counts and any integrity,
    model-drift or unsynced-source warnings.
-3. In CI, a required tracked project upgrade is intentionally refused. Report
-   the instruction to run `intelligence init --apply` locally, review and
-   commit its diff; never bypass the gate. A frozen restore refusal means the
+3. A warning that project versions trail the CLI is not a failure: relay it.
+   `IS_STATUS=needs-update` (exit 6) means the project needs a migration only
+   `intelligence update` applies; report that, and never edit the manifest or
+   lock by hand to get past it. A frozen restore refusal means the
    manifest and lock disagree or the locked commit cannot be verified/restored—report it without
    hand-copying package content.
 4. On a probable Intelligence defect, first ask whether to collect a sanitized