@ainova-systems/intelligence 0.11.5 → 0.11.7

package/cli/commands/init.sh

@@ -124,7 +124,9 @@ case "$IP_MODE" in
         if [ "$preview" -eq 1 ]; then
             check_version_compat "$IP_ROOT/intelligence.yaml"
             echo "project: Intelligence CLI at $IP_ROOT"
-            if project_needs_upgrade "$IP_ROOT"; then
+            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)"
             else
                 echo "  schema/content already match engine $(bundled_engine_version)"

package/cli/commands/update.sh

@@ -48,7 +48,9 @@ fi
 
 echo ""
 echo "Project:"
-if project_needs_upgrade "$IP_ROOT"; then
+if project_stamped_ahead "$IP_ROOT"; then
+    echo "  schema $stamp is ahead of engine $eng — left as is; update the CLI to align it"
+elif project_needs_upgrade "$IP_ROOT"; then
     echo "  lifecycle alignment required (stamp ${stamp:-unstamped}, engine $eng)"
     project_change=1
 else

package/cli/internal/align-project.sh

@@ -24,8 +24,10 @@ legacy_key_count="$(awk '/^sync_version:[[:space:]]*/ { n++ } END { print n + 0
 eng="$(bundled_engine_version)"
 [ "$schema_key_count" -le 1 ] || die "manifest has duplicate schema_version keys"
 [ "$legacy_key_count" -le 1 ] || die "manifest has duplicate sync_version keys"
+# Alignment only ever moves a project UP to this engine. A project stamped
+# ahead is never restamped downward, whatever the gap.
 if [ -n "$stamp" ] && _ver_gt "$stamp" "$eng"; then
-    die "manifest schema $stamp is newer than this CLI's engine $eng — update the global CLI first"
+    die "manifest schema $stamp is newer than this CLI's engine $eng — refusing to align it downward; update the global CLI first"
 fi
 if [ -n "$legacy_stamp" ] && _ver_gt "$legacy_stamp" "$eng"; then
     die "manifest schema $legacy_stamp is newer than this CLI's engine $eng — update the global CLI first"

package/cli/internal/check.sh

@@ -5,6 +5,7 @@ source "$CLI_DIR/lib/cli-common.sh"
 
 problems=0
 warn() { echo "  ✗ $*"; problems=$((problems + 1)); }
+note() { echo "  ! $*"; }
 ok()   { echo "  ✓ $*"; }
 
 echo "environment:"
@@ -36,7 +37,11 @@ eng="$(bundled_engine_version)"
 if [ -z "$stamp" ]; then
     warn "manifest has no schema_version — run 'intelligence init'"
 elif _ver_gt "$stamp" "$eng"; then
-    warn "manifest schema $stamp is newer than this CLI's engine $eng — update the CLI: npm i -g @ainova-systems/intelligence@latest"
+    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: npm i -g @ainova-systems/intelligence@latest"
+    else
+        note "manifest schema $stamp is newer than this CLI's engine $eng — the project uses a newer CLI; update it: npm i -g @ainova-systems/intelligence@latest"
+    fi
 elif _ver_gt "$eng" "$stamp"; then
     warn "manifest schema $stamp behind engine $eng — run 'intelligence init'"
 else
@@ -49,6 +54,8 @@ sync_locked="$(qmap_field "$lock" "packages" "$SYNC_PKG_NAME" "resolved")"
 if [ -n "$sync_locked" ]; then
     if [ "${sync_locked#v}" = "$eng" ]; 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)"
     else
         warn "$SYNC_PKG_NAME locked at $sync_locked but the engine is $eng — run 'intelligence init'"
     fi
@@ -82,7 +89,7 @@ while IFS= read -r name; do
             warn "$name is locked but not installed — run 'intelligence sync'"
             continue
         fi
-        ok "$name @ $(qmap_field "$lock" "packages" "$name" "resolved")"
+        ok "$name @ $(pin_label "$m_ref" "$l_res" "$(qmap_field "$lock" "packages" "$name" "sha")")"
     fi
 done < <(qmap_keys "$manifest" "packages")
 

package/cli/internal/package-list.sh

@@ -14,6 +14,7 @@ while IFS= read -r name; do
     range="$(qmap_field "$manifest" "packages" "$name" "version")"
     ref="$(qmap_field "$manifest" "packages" "$name" "ref")"
     resolved="$(qmap_field "$lock" "packages" "$name" "resolved")"
+    sha="$(qmap_field "$lock" "packages" "$name" "sha")"
     if [ ! -f "$lock" ]; then
         state="lock missing — restore committed intelligence.lock"
     elif [ -d "$IP_ROOT/.intelligence/packages/$name" ]; then
@@ -24,7 +25,7 @@ while IFS= read -r name; do
     printf '%s  %s  locked:%s  %s\n' \
         "$name" \
         "${ref:+ref:$ref}${ref:-${range:-*}}" \
-        "${resolved:-<none>}" \
+        "$(pin_label "$ref" "$resolved" "$sha")" \
         "$state"
 done < <(qmap_keys "$manifest" "packages")
 

package/cli/internal/package-update.sh

@@ -22,6 +22,20 @@ require_cli_project
 manifest="$IP_ROOT/intelligence.yaml"
 lock="$IP_ROOT/intelligence.lock"
 
+# move_label <ref-or-empty> <from-resolved> <to-resolved> <from-sha> <to-sha>
+# A version pin moves between tags, a ref pin between commits under one name —
+# printing "main -> main" would report the move by hiding what moved.
+move_label() {
+    local ref="$1" from="$2" to="$3" from_sha="$4" to_sha="$5"
+    if [ -z "$ref" ]; then
+        printf '%s -> %s' "${from:-<none>}" "$to"
+    elif [ -n "$from" ] && [ "$from" != "$ref" ]; then
+        printf '%s -> %s@%s' "$from" "$ref" "$(short_sha "$to_sha")"
+    else
+        printf '%s %s -> %s' "$ref" "$(short_sha "$from_sha")" "$(short_sha "$to_sha")"
+    fi
+}
+
 moved=0 found=0
 while IFS= read -r name; do
     [ -n "$name" ] || continue
@@ -37,6 +51,7 @@ while IFS= read -r name; do
     fi
     current="$(qmap_field "$lock" "packages" "$name" "resolved")"
     locked_requested="$(qmap_field "$lock" "packages" "$name" "requested")"
+    locked_sha="$(qmap_field "$lock" "packages" "$name" "sha")"
     url="$(qmap_field "$lock" "packages" "$name" "url")"
     path="$(qmap_field "$lock" "packages" "$name" "path")"
     [ -n "$url" ] || die "$name has no source in intelligence.lock — restore the committed lock or re-add the package"
@@ -44,32 +59,69 @@ while IFS= read -r name; do
     range="$(qmap_field "$manifest" "packages" "$name" "version")"
     [ -n "$ref" ] || [ -n "$range" ] || die "$name has neither version nor ref in the manifest"
 
+    ref_moved=0 remote_sha=""
     if [ -n "$ref" ]; then
         tag="$ref"
         requested=""
+        # A ref is requested INTENT, and the lock's `resolved` column holds
+        # that same ref name — comparing the two asks a question no branch can
+        # ever answer differently. The sha column is the only record of where
+        # the ref actually pointed, so a ref pin is compared commit to commit:
+        # a moved branch, a re-cut tag and a `HEAD` pin all become visible,
+        # while a pin that IS a commit stays immutable by construction.
+        probe_rc=0
+        remote_sha="$(remote_sha_for_ref "$url" "$ref")" || probe_rc=$?
+        if [ "$probe_rc" -ne 0 ]; then
+            # No answer is not "no change": reporting up to date here would
+            # freeze the pin exactly as the ref-name comparison used to.
+            echo "  WARN: $name: cannot reach $url — ref '$ref' was not checked" >&2
+            echo "  $name: $ref (not checked — remote unreachable)"
+            continue
+        fi
+        # ls-remote advertises refs, not arbitrary objects, so a commit pin
+        # legitimately matches nothing — and cannot move. This verdict applies
+        # only once the lock already resolved to this ref; a manifest that now
+        # names a ref the lock never resolved is an ordinary move, and falls
+        # through to the fetch below.
+        if [ -z "$remote_sha" ] && [ "$ref" = "$current" ]; then
+            # The lock records the commit this ref resolved to, so a ref that
+            # prefixes it IS that commit. Asking the lock beats guessing from
+            # the ref's shape: a deleted branch named like a hex string would
+            # otherwise pass for a pin and swallow its own disappearance.
+            case "$locked_sha" in
+                "$ref"*)
+                    echo "  $name: $(short_sha "$ref") (pinned commit)"
+                    ;;
+                *)
+                    echo "  WARN: $name pins ref '$ref', which $url no longer advertises" >&2
+                    echo "  $name: $ref (unresolvable — gone upstream)"
+                    ;;
+            esac
+            continue
+        fi
+        [ -z "$remote_sha" ] || [ "$remote_sha" = "$locked_sha" ] || ref_moved=1
     else
         picked="$(list_remote_versions "$url" | semver_pick_highest "$range")"
         [ -n "$picked" ] || { echo "  $name: nothing satisfies '$range' at $url" >&2; continue; }
         read -r tag _ <<< "$(remote_tag_for_version "$url" "$picked")"
         requested="$range"
     fi
-    if [ "$tag" = "$current" ] && [ "$requested" != "$locked_requested" ]; then
+    if [ "$ref_moved" -eq 0 ] && [ "$tag" = "$current" ] && [ "$requested" != "$locked_requested" ]; then
         if [ "$preview" -eq 1 ]; then
             echo "  $name: request ${locked_requested:-<none>} -> ${requested:-<ref>} (keeps $current)"
         else
-            locked_sha="$(qmap_field "$lock" "packages" "$name" "sha")"
             lock_upsert "$lock" "$name" "$requested" "$url" "$path" "$current" "$locked_sha"
             echo "  $name: request ${locked_requested:-<none>} -> ${requested:-<ref>} (kept $current)"
         fi
         moved=$((moved + 1))
         continue
     fi
-    if [ "$tag" = "$current" ]; then
-        echo "  $name: ${current:-<none>} (up to date)"
+    if [ "$ref_moved" -eq 0 ] && [ "$tag" = "$current" ]; then
+        echo "  $name: $(pin_label "$ref" "$current" "$locked_sha") (up to date)"
         continue
     fi
     if [ "$preview" -eq 1 ]; then
-        echo "  $name: ${current:-<none>} -> $tag"
+        echo "  $name: $(move_label "$ref" "$current" "$tag" "$locked_sha" "$remote_sha")"
         moved=$((moved + 1))
         continue
     fi
@@ -87,7 +139,7 @@ while IFS= read -r name; do
     mv "$staging" "$IP_ROOT/$rel"
     wire_package_sources "$manifest" "$name" "$rel" "$IP_ROOT"
     lock_upsert "$lock" "$name" "$requested" "$url" "$path" "$tag" "$sha"
-    echo "  $name: ${current:-<none>} -> $tag"
+    echo "  $name: $(move_label "$ref" "$current" "$tag" "$locked_sha" "$sha")"
     moved=$((moved + 1))
 done < <(qmap_keys "$manifest" "packages")
 

package/cli/lib/cli-common.sh

@@ -47,6 +47,27 @@ assert_safe_ref() {
     esac
 }
 
+# --- Resolved-pin display ------------------------------------------------
+# A `ref:` pin's resolved column holds the ref NAME, which never changes: the
+# sha is the only field that says which commit is installed. Every surface
+# reporting such a pin prints both, so a branch that stopped moving is visible
+# without asking the remote.
+
+short_sha() {
+    [ -n "$1" ] || { printf '<none>'; return 0; }
+    printf '%s' "${1:0:7}"
+}
+
+# pin_label <ref-or-empty> <resolved> <sha>
+pin_label() {
+    local ref="$1" resolved="$2" sha="$3"
+    if [ -n "$ref" ]; then
+        printf '%s@%s' "${resolved:-$ref}" "$(short_sha "$sha")"
+    else
+        printf '%s' "${resolved:-<none>}"
+    fi
+}
+
 source "$CLI_DIR/lib/manifest.sh"
 source "$CLI_DIR/lib/semver.sh"
 source "$CLI_DIR/lib/registry.sh"
@@ -218,12 +239,26 @@ assert_safe_content_dir() {
     done
 }
 
+# project_stamped_ahead <root> — the manifest is stamped newer than this CLI's
+# engine, at any SemVer level. Every caller runs check_version_compat first,
+# which has already refused a newer major, so what reaches this predicate is
+# the admitted minor/patch gap; the predicate itself does not re-judge the gap.
+project_stamped_ahead() {
+    local stamp
+    stamp="$(read_schema_version "$1/intelligence.yaml")"
+    [ -n "$stamp" ] && _ver_gt "$stamp" "$(bundled_engine_version)"
+}
+
 project_needs_upgrade() {
     local root="$1" manifest="$1/intelligence.yaml" stamp eng pinned locked name
     [ -f "$manifest" ] || return 1
     stamp="$(read_schema_version "$manifest")"
     eng="$(bundled_engine_version)"
     [ -z "$stamp" ] && return 0
+    # 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
     [ -n "$(top_scalar "$manifest" "sync_version")" ] && return 0
     _ver_gt "$eng" "$stamp" && return 0
     [ -d "$root/.intelligence/engine" ] && return 0

package/cli/lib/semver.sh

@@ -120,6 +120,39 @@ remote_tag_for_version() {
             }'
 }
 
+# remote_sha_for_ref <git-url> <ref> — the commit a branch/tag/HEAD pin points
+# at on the remote right now; empty when the remote advertises no such ref
+# (a pin that IS a commit, or a ref deleted upstream). Exit 2 means the remote
+# could not be asked at all: a check that produced no answer must never be
+# read by the caller as "nothing changed".
+#
+# Three git behaviours this mirrors deliberately, because a sha that is not the
+# one `fetch_package` would land on is worse than no answer:
+#   - `git ls-remote <url> main` also matches `refs/heads/feature/main`
+#     (patterns match at slash boundaries), so candidates are selected by full
+#     ref name, never by the pattern that fetched them;
+#   - an annotated tag advertises the tag OBJECT on `refs/tags/<t>` and the
+#     commit on the peeled `refs/tags/<t>^{}`, while the lock records the
+#     commit — so peeled wins, and the peel line only appears when its own
+#     pattern is asked for;
+#   - on a name shared by a branch and a tag, `git clone --branch <ref>` takes
+#     the branch, so `refs/heads` outranks `refs/tags` here too.
+remote_sha_for_ref() {
+    local url="$1" ref="$2" out
+    assert_safe_source_url "$url"
+    assert_safe_ref "$ref"
+    [ -n "$ref" ] || return 0
+    out="$(GIT_TERMINAL_PROMPT=0 git ls-remote -- "$url" \
+        "$ref" "$ref^{}" "refs/heads/$ref" "refs/tags/$ref" "refs/tags/$ref^{}" 2>/dev/null)" \
+        || return 2
+    printf '%s\n' "$out" | awk -v ref="$ref" '
+        { sub(/\r$/, ""); if ($2 != "") seen[$2] = $1 }
+        END {
+            split("refs/heads/" ref "\037refs/tags/" ref "^{}\037refs/tags/" ref "\037" ref "^{}\037" ref, C, "\037")
+            for (i = 1; i <= 5; i++) if (C[i] in seen) { print seen[C[i]]; exit }
+        }'
+}
+
 # semver_pick_highest <range> — reads versions on stdin, prints the highest
 # one matching the range (empty output when nothing matches).
 semver_pick_highest() {

package/engine/ENGINE_SHA

@@ -1 +1 @@
-bd688bcdb5443d808a72ed4e63805a65255a7d02
+00308bfbdcd92ebf37924bb1083cee142e655fd7

package/engine/VERSION

@@ -1 +1 @@
-0.11.5
+0.11.7

package/engine/lib/contract.sh

@@ -100,21 +100,41 @@ _ver_gt() {
     return 1
 }
 
-# check_version_compat <config_file> — refuse to operate on a project whose
-# config schema is stamped newer than this engine knows (a stale engine must
-# never rewrite/sync a newer schema). Emits status + returns IS_RC_AHEAD on
-# conflict, else 0.
+# _ver_major V → the leading numeric field of a version ("0.11.6" → 0).
+_ver_major() {
+    local m="${1%%.*}"
+    m="${m//[!0-9]/}"
+    printf '%s' "$((10#${m:-0}))"
+}
+
+# check_version_compat <config_file> — a stale engine on a project stamped
+# NEWER than itself. The gap decides:
+#   * a newer MAJOR is refused: the manifest may carry shapes this engine
+#     cannot read, and rendering or rewriting it would destroy them. Emits
+#     status + returns IS_RC_AHEAD;
+#   * a newer minor or patch within the same major warns once and returns 0:
+#     the schema is additive there, so an older engine renders what it
+#     understands. It never restamps the project — the CLI's preflight leaves
+#     a project stamped ahead exactly as it found it (project_needs_upgrade).
 check_version_compat() {
     local cf="$1" stamp eng
     stamp="$(read_schema_version "$cf")"
     [ -n "$stamp" ] || return 0
     eng="$(engine_version)"
     [ -n "$eng" ] || return 0
-    if _ver_gt "$stamp" "$eng"; then
+    _ver_gt "$stamp" "$eng" || return 0
+    if [ "$(_ver_major "$stamp")" -gt "$(_ver_major "$eng")" ]; then
         is_status ahead-of-engine "stamp=$stamp engine=$eng"
-        echo "  ERROR: project stamped $stamp but this engine is $eng — refusing." >&2
+        echo "  ERROR: project stamped $stamp but this engine is $eng — a newer major schema; refusing." >&2
         echo "         Update the CLI first: npm i -g @ainova-systems/intelligence@latest" >&2
         return "$IS_RC_AHEAD"
     fi
+    # One warning per command, however many processes re-check on the way to
+    # the engine (CLI preflight first, then the engine itself). The line has
+    # no indent on purpose: `sync --compact` keeps `WARNING:` lines.
+    if [ "${IS_SCHEMA_AHEAD_WARNED:-}" != "$stamp" ]; then
+        echo "WARNING: project schema $stamp is newer than this CLI's engine $eng — the project uses a newer CLI; update it: npm i -g @ainova-systems/intelligence@latest" >&2
+        export IS_SCHEMA_AHEAD_WARNED="$stamp"
+    fi
     return 0
 }

package/engine/sync.sh

@@ -31,7 +31,8 @@ fi
 # Schema version lives in the manifest (the frozen contract key).
 _cf="$CONFIG_FILE"
 
-# Stale engine vs project schema stamped NEWER (ahead-of-engine) → refuse.
+# Stale engine vs project schema stamped NEWER (ahead-of-engine): a newer
+# major refuses, a newer minor/patch warns and renders (see contract.sh).
 _vc_rc=0
 check_version_compat "$_cf" || _vc_rc=$?
 if [ "$_vc_rc" -ne 0 ]; then exit "$_vc_rc"; fi

package/package.json

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

@@ -391,7 +391,7 @@ The public lifecycle is deliberately compact:
 - `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 newer; 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. Normal project entry points close a behind-project gap through lifecycle preflight.
 
 Breaking changelog entries use a `### Breaking` checklist of verifiable post-conditions. The update skill reads every release across the version gap, chooses the package/CLI/project command sequence and verifies those conditions after the deterministic command completes.
 
@@ -406,7 +406,7 @@ The engine emits one machine-readable line, `IS_STATUS=<code> [IS_DETAIL=...]`,
 | `error` | 1 | Generic failure |
 | `config-missing` | 2 | Required manifest is absent |
 | `ambiguous` | 3 | Conflicting state requiring agent/human judgment; reserved |
-| `ahead-of-engine` | 4 | Manifest schema is newer than the engine |
+| `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 |