@ainova-systems/intelligence 0.11.6 → 0.11.8

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

package/cli/internal/restore.sh

@@ -2,8 +2,8 @@
 # Internal locked-store restore operation.
 #
 # Restore .intelligence/ from intelligence.lock — the fresh-clone command.
-# --frozen additionally refuses any manifest/lock divergence (CI mode) and
-# fails on a sha mismatch instead of re-resolving.
+# --frozen additionally refuses manifest/lock divergence (CI mode).
+# Locked packages always restore their recorded commit, never the ref's new HEAD.
 set -euo pipefail
 source "$CLI_DIR/lib/cli-common.sh"
 
@@ -50,6 +50,20 @@ if [ "$frozen" -eq 1 ]; then
     done < <(qmap_keys "$lock" "packages")
 fi
 
+# Check every required commit identity before restoring any package. Only the
+# matching bundled content may carry the historical empty development-build SHA.
+while IFS="$LOCK_SEP" read -r name _requested url path resolved sha; do
+    [ -n "$name" ] || continue
+    assert_valid_pkg_name "$name"
+    assert_safe_source_url "$url"
+    assert_safe_ref "$resolved"
+    if [ -z "$sha" ] && is_bundle_source "$url" "$resolved" "$path"; then
+        continue
+    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 < <(lock_to_tsv "$lock")
+
 # Manifest packages missing from the lock: resolve them now (npm install
 # semantics). Under --frozen the drift gate above has already refused.
 missing=""
@@ -89,7 +103,7 @@ fi
 
 # Restore every locked package that is not already in the store.
 if [ -f "$lock" ]; then
-    while IFS="$LOCK_SEP" read -r name requested url path resolved sha; do
+    while IFS="$LOCK_SEP" read -r name _requested url path resolved sha; do
         [ -n "$name" ] || continue
         # The lock arrives with a cloned repo — its keys are untrusted input
         # on their way into rm -rf paths, and its urls into git argv.
@@ -106,17 +120,7 @@ if [ -f "$lock" ]; then
         # re-run (whose dir-exists check skips verification) would sync it.
         staging="$IP_ROOT/.intelligence/.staging-$$"
         rm -rf "$staging"
-        got="$(fetch_package "$url" "$resolved" "$path" "$staging")"
-        # An empty sha (bundle-seeded content on a dev build) means unknown,
-        # not moved — only two known-and-different shas are a finding.
-        if [ -n "$sha" ] && [ -n "$got" ] && [ "$got" != "$sha" ]; then
-            if [ "$frozen" -eq 1 ]; then
-                rm -rf "$staging"
-                die "$name: fetched $got but the lock pins $sha — the ref moved; refusing under --frozen"
-            fi
-            echo "  WARN: $name resolved to $got, lock had $sha — updating the lock" >&2
-            lock_upsert "$lock" "$name" "$requested" "$url" "$path" "$resolved" "$got"
-        fi
+        fetch_package "$url" "$resolved" "$path" "$staging" "$sha" >/dev/null
         rm -rf "${IP_ROOT:?}/$rel"
         mkdir -p "$(dirname "$IP_ROOT/$rel")"
         mv "$staging" "$IP_ROOT/$rel"

package/cli/lib/cli-common.sh

@@ -239,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/registry.sh

@@ -106,13 +106,20 @@ suggest_similar() {
     fi
 }
 
-# fetch_package <url> <ref> <subpath> <dest-dir>
+# is_bundle_source <url> <ref> <subpath>
+is_bundle_source() {
+    [ "$1" = "$SYNC_PKG_URL" ] && [ "$3" = "$SYNC_PKG_PATH" ] \
+        && [ "${2#v}" = "$(bundled_engine_version)" ]
+}
+
+# fetch_package <url> <ref> <subpath> <dest-dir> [locked-sha]
 # Shallow-clones url@ref (tag, branch, or SHA fallback), copies <subpath>
 # (or the repo root) into <dest-dir>, prints the resolved commit sha.
+# A locked SHA selects and verifies the commit independently of the ref name.
 # The clone pins autocrlf/eol/symlinks exactly like the engine does, so the
 # store holds the bytes the package published.
 fetch_package() {
-    local url="$1" ref="$2" subpath="$3" dest="$4"
+    local url="$1" ref="$2" subpath="$3" dest="$4" locked_sha="${5:-}" bundle_sha=""
     assert_safe_source_url "$url"
     assert_safe_ref "$ref"
     # Bundle seed: the engine-content package at the CLI's own version copies
@@ -120,34 +127,63 @@ fetch_package() {
     # archived-project conversion offline. Keyed on the
     # full (url, path, ref) triple; any other version or source falls through
     # to the normal clone.
-    if [ "$url" = "$SYNC_PKG_URL" ] && [ "$subpath" = "$SYNC_PKG_PATH" ] \
-        && [ "${ref#v}" = "$(bundled_engine_version)" ]; then
+    if is_bundle_source "$url" "$ref" "$subpath"; then
+        if [ -f "$IS_ENGINE_DIR/ENGINE_SHA" ]; then
+            bundle_sha="$(tr -d ' \t\r\n' < "$IS_ENGINE_DIR/ENGINE_SHA")"
+        fi
+    fi
+    if is_bundle_source "$url" "$ref" "$subpath" \
+        && { [ -z "$locked_sha" ] || [ -z "$bundle_sha" ] || [ "$locked_sha" = "$bundle_sha" ]; }; then
         [ -n "${IS_BUNDLED_PKG_DIR:-}" ] && [ -d "$IS_BUNDLED_PKG_DIR" ] \
             || die "bundled engine content not found next to the CLI — reinstall @ainova-systems/intelligence"
         rm -rf "$dest"
         mkdir -p "$dest"
         cp -R "$IS_BUNDLED_PKG_DIR/." "$dest/"
         rm -rf "$dest/.git"
-        if [ -f "$IS_ENGINE_DIR/ENGINE_SHA" ]; then
-            tr -d ' \t\r\n' < "$IS_ENGINE_DIR/ENGINE_SHA"
+        if [ "$#" -ge 5 ] && { [ -z "$locked_sha" ] || [ -z "$bundle_sha" ]; }; then
+            echo "WARNING: bundled sync content restored without commit verification (development bundle or lock has no SHA)" >&2
         fi
+        printf '%s' "$bundle_sha"
         return 0
     fi
     local tmp sha src
     local -a branch_arg=()
     [ -n "$ref" ] && branch_arg=(--branch "$ref")
     tmp="$(mktemp -d -t intelligence-pkg-XXXXXX 2>/dev/null || mktemp -d)"
-    if ! GIT_TERMINAL_PROMPT=0 git -c core.symlinks=false -c core.autocrlf=false -c core.eol=lf \
+    if [ -n "$locked_sha" ]; then
+        local -a format_arg=()
+        [ "${#locked_sha}" -ne 64 ] || format_arg=(--object-format=sha256)
+        git init --quiet "${format_arg[@]+"${format_arg[@]}"}" "$tmp/clone" \
+            || { rm -rf "$tmp"; die "cannot stage locked commit $locked_sha"; }
+        # Request the object directly, including retained commits no longer named
+        # by a branch/tag. Servers that forbid SHA wants may still advertise a
+        # descendant; fetch their history before declaring the commit unavailable.
+        if ! GIT_TERMINAL_PROMPT=0 git -C "$tmp/clone" fetch --quiet --no-tags --depth 1 -- "$url" "$locked_sha" 2>/dev/null; then
+            GIT_TERMINAL_PROMPT=0 git -C "$tmp/clone" fetch --quiet --tags -- "$url" \
+                '+refs/heads/*:refs/remotes/locked/*' 2>/dev/null \
+                || { rm -rf "$tmp"; die "cannot fetch locked commit $locked_sha from $url — check source access and commit availability"; }
+        fi
+        [ "$(git -C "$tmp/clone" cat-file -t "$locked_sha" 2>/dev/null || true)" = commit ] \
+            || { rm -rf "$tmp"; die "locked commit $locked_sha unavailable from $url — refusing to substitute '$ref' or HEAD"; }
+        git -c core.symlinks=false -c core.autocrlf=false -c core.eol=lf \
+            -C "$tmp/clone" checkout --quiet --detach "$locked_sha" -- \
+            || { rm -rf "$tmp"; die "cannot check out locked commit $locked_sha from $url"; }
+    elif ! GIT_TERMINAL_PROMPT=0 git -c core.symlinks=false -c core.autocrlf=false -c core.eol=lf \
             clone --depth 1 "${branch_arg[@]+"${branch_arg[@]}"}" --quiet -- "$url" "$tmp/clone" 2>/dev/null; then
         # A SHA is not clonable with --branch — fall back to a full clone + checkout.
         rm -rf "$tmp/clone"
         GIT_TERMINAL_PROMPT=0 git -c core.symlinks=false -c core.autocrlf=false -c core.eol=lf \
             clone --quiet -- "$url" "$tmp/clone" 2>/dev/null \
             || { rm -rf "$tmp"; die "cannot clone $url"; }
-        [ -z "$ref" ] || git -C "$tmp/clone" checkout --quiet "$ref" -- \
+        [ -z "$ref" ] || git -c core.symlinks=false -c core.autocrlf=false -c core.eol=lf \
+            -C "$tmp/clone" checkout --quiet "$ref" -- \
             || { rm -rf "$tmp"; die "ref '$ref' not found in $url"; }
     fi
     sha="$(git -C "$tmp/clone" rev-parse HEAD)"
+    if [ -n "$locked_sha" ] && [ "$sha" != "$locked_sha" ]; then
+        rm -rf "$tmp"
+        die "fetched $sha but the lock pins $locked_sha — refusing package replacement"
+    fi
     src="$tmp/clone"
     if [ -n "$subpath" ]; then
         case "$subpath" in

package/engine/ENGINE_SHA

@@ -1 +1 @@
-512d06382f43fa910c32ccc275a5fc286500d4e2
+3413f7d6f9ef181368b16b90e36d77360cb5f479

package/engine/VERSION

@@ -1 +1 @@
-0.11.6
+0.11.8

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.6",
+  "version": "0.11.8",
   "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 |
 

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

@@ -11,12 +11,12 @@ context: fork
    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`.
-2. Require final `IS_STATUS=ok`; relay per-adapter counts and any model-drift
-   or unsynced-source warnings.
+2. Require final `IS_STATUS=ok`; relay per-adapter 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
-   manifest and lock disagree or a pinned ref moved—report it without
+   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
    issue draft; collect nothing before approval and never use telemetry. Include