@ainova-systems/intelligence 0.22.1 → 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/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/engine/ENGINE_SHA

@@ -1 +1 @@
-4a95c37c037291cd55c305b72571decae77d7767
+79201cedae74ec96e67c3aa94e267f6b1e226c23

package/engine/VERSION

@@ -1 +1 @@
-0.22.1
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainova-systems/intelligence",
-  "version": "0.22.1",
+  "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