@ainova-systems/intelligence 0.13.0 → 0.14.0

package/README.md

@@ -34,7 +34,7 @@ intelligence sync
 |---|---|
 | `intelligence init [--preview\|--apply]` | Create, convert, restore or align a project |
 | `intelligence sync [adapter]` | Restore locked content if needed, then render all or one enabled adapter |
-| `intelligence update [@scope/name] [--preview\|--apply]` | Plan or apply project and ranged-package updates |
+| `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 |
 | `intelligence package add\|remove\|list\|search` | Manage versioned Intelligence Packages |
 | `intelligence adapter list\|create\|enable\|disable\|remove` | Manage render adapters |

package/cli/commands/update.sh

@@ -8,17 +8,22 @@
 set -euo pipefail
 source "$CLI_DIR/lib/cli-common.sh"
 
-only="" mode="ask" preview_seen=0 apply_seen=0
+only="" mode="ask" preview_seen=0 apply_seen=0 latest=0
 while [ $# -gt 0 ]; do
     case "$1" in
         --preview) preview_seen=1; mode="preview" ;;
         --apply) apply_seen=1; mode="apply" ;;
+        --latest) latest=1 ;;
         @*) [ -z "$only" ] || die "only one package may be selected"; only="$1" ;;
-        *) die "usage: intelligence update [@scope/name] [--preview|--apply]" ;;
+        *) die "usage: intelligence update [@scope/name] [--latest] [--preview|--apply]" ;;
     esac
     shift
 done
 [ "$preview_seen" -eq 0 ] || [ "$apply_seen" -eq 0 ] || die "choose either --preview or --apply"
+# Crossing a range is one package's decision, and SemVer marks the boundary as
+# the place a changelog has to be read.
+[ "$latest" -eq 0 ] || [ -n "$only" ] \
+    || die "--latest needs the package to move: intelligence update @scope/name --latest"
 
 require_cli_project
 manifest="$IP_ROOT/intelligence.yaml"
@@ -74,6 +79,7 @@ fi
 
 pkg_args=(--preview)
 [ -z "$only" ] || pkg_args+=("$only")
+[ "$latest" -eq 0 ] || pkg_args+=(--latest)
 pkg_plan="$(bash "$CLI_DIR/internal/package-update.sh" "${pkg_args[@]}")"
 echo ""
 echo "Packages:"
@@ -102,5 +108,6 @@ fi
 ensure_project_current "$IP_ROOT"
 apply_args=(--no-sync)
 [ -z "$only" ] || apply_args+=("$only")
+[ "$latest" -eq 0 ] || apply_args+=(--latest)
 bash "$CLI_DIR/internal/package-update.sh" "${apply_args[@]}"
 exec bash "$CLI_DIR/commands/sync.sh"

package/cli/intelligence

@@ -51,6 +51,7 @@ Usage: intelligence <command> [args]
   update [@scope/name]    Show an update plan; ask before applying it
     --preview             Show the plan without asking or writing
     --apply               Apply the plan without asking
+    --latest              Move one named package past its range to the newest version
   upgrade [--next] [--preview|--apply]  Replace the installed CLI with the newest npm version
     --next                Follow the prerelease line instead of the stable one
   package <command>       add | remove | list | search

package/cli/internal/package-update.sh

@@ -7,16 +7,22 @@
 set -euo pipefail
 source "$CLI_DIR/lib/cli-common.sh"
 
-only="" no_sync=0 preview=0
+only="" no_sync=0 preview=0 latest=0
 while [ $# -gt 0 ]; do
     case "$1" in
         --no-sync) no_sync=1 ;;
         --preview) preview=1 ;;
+        --latest) latest=1 ;;
         @*) only="$1" ;;
         *) die "unknown argument '$1'" ;;
     esac
     shift || true
 done
+# Crossing a range is per package on purpose: each boundary SemVer marks is a
+# changelog to read, so a blanket sweep would be one confirmation for several
+# unrelated decisions.
+[ "$latest" -eq 0 ] || [ -n "$only" ] \
+    || die "--latest needs the package to move: intelligence update @scope/name --latest"
 
 require_cli_project
 manifest="$IP_ROOT/intelligence.yaml"
@@ -36,7 +42,7 @@ move_label() {
     fi
 }
 
-moved=0 found=0
+moved=0 found=0 outside=0
 while IFS= read -r name; do
     [ -n "$name" ] || continue
     # Manifest keys are untrusted input on their way into store paths.
@@ -46,6 +52,8 @@ while IFS= read -r name; do
     # message followed by "not in the manifest" would contradict itself.
     found=1
     if [ "$name" = "$SYNC_PKG_NAME" ]; then
+        [ "$latest" -eq 0 ] \
+            || die "$name is the engine content package — its pin follows the installed CLI; use 'intelligence upgrade'"
         echo "  $name: engine content follows the installed CLI — skipped"
         continue
     fi
@@ -59,7 +67,9 @@ 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=""
+    ref_moved=0 remote_sha="" beyond="" range_move=""
+    [ "$latest" -eq 0 ] || [ -z "$ref" ] \
+        || die "$name is pinned to ref '$ref', not a version range — a ref pin is frozen by intent; re-add the package to change it"
     if [ -n "$ref" ]; then
         tag="$ref"
         requested=""
@@ -101,27 +111,56 @@ while IFS= read -r name; do
         fi
         [ -z "$remote_sha" ] || [ "$remote_sha" = "$locked_sha" ] || ref_moved=1
     else
-        picked="$(list_remote_versions "$url" | semver_pick_highest "$range")"
+        # One remote read answers both questions: what the range selects, and
+        # what it excludes.
+        versions="$(list_remote_versions "$url")"
+        picked="$(printf '%s\n' "$versions" | 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"
+        # A range is a ceiling as much as a floor, and on a 0.x package the
+        # caret stops at the minor: a project sits on 0.4.x while 0.6.1 ships
+        # and every plan still reads "up to date". Name what the range leaves
+        # out. Crossing it edits requested intent, which is a manifest change
+        # and never this command's to make.
+        newest="$(printf '%s\n' "$versions" | semver_pick_highest "latest")"
+        if [ -n "$newest" ] && [ "$(semver_cmp "$newest" "$picked")" = "1" ]; then
+            if [ "$latest" -eq 1 ]; then
+                # Asked for by name: take the newest and widen the recorded
+                # intent to match, keeping the caret so the next boundary is
+                # still a decision. The manifest keeps saying what the project
+                # asked for — that is what makes the move reviewable.
+                picked="$newest"
+                read -r tag _ <<< "$(remote_tag_for_version "$url" "$picked")"
+                requested="^$newest"
+                range_move=" (range $range -> $requested)"
+            else
+                beyond=" — $newest available outside '$range'"
+                beyond="$beyond
+      follow it: intelligence update $name --latest"
+                outside=$((outside + 1))
+            fi
+        fi
+        # When the newest version is already inside the range there is nothing
+        # to cross: `--latest` falls through to the ordinary comparison, which
+        # still installs a move the lock is behind on and still widens nothing.
     fi
     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)"
+            echo "  $name: request ${locked_requested:-<none>} -> ${requested:-<ref>} (keeps $current)$beyond"
         else
             lock_upsert "$lock" "$name" "$requested" "$url" "$path" "$current" "$locked_sha"
-            echo "  $name: request ${locked_requested:-<none>} -> ${requested:-<ref>} (kept $current)"
+            echo "  $name: request ${locked_requested:-<none>} -> ${requested:-<ref>} (kept $current)$beyond"
         fi
         moved=$((moved + 1))
         continue
     fi
     if [ "$ref_moved" -eq 0 ] && [ "$tag" = "$current" ]; then
-        echo "  $name: $(pin_label "$ref" "$current" "$locked_sha") (up to date)"
+        echo "  $name: $(pin_label "$ref" "$current" "$locked_sha") (up to date)$beyond"
         continue
     fi
     if [ "$preview" -eq 1 ]; then
-        echo "  $name: $(move_label "$ref" "$current" "$tag" "$locked_sha" "$remote_sha")"
+        echo "  $name: $(move_label "$ref" "$current" "$tag" "$locked_sha" "$remote_sha")$range_move$beyond"
         moved=$((moved + 1))
         continue
     fi
@@ -139,7 +178,11 @@ 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: $(move_label "$ref" "$current" "$tag" "$locked_sha" "$sha")"
+    # The widened intent is recorded only once its content is installed and
+    # wired: a manifest saying ^0.6.1 over a failed fetch would describe a
+    # state the project never reached.
+    [ -z "$range_move" ] || qmap_set "$manifest" "packages" "$name" "version" "$requested"
+    echo "  $name: $(move_label "$ref" "$current" "$tag" "$locked_sha" "$sha")$range_move$beyond"
     moved=$((moved + 1))
 done < <(qmap_keys "$manifest" "packages")
 
@@ -149,6 +192,11 @@ if [ "$preview" -eq 1 ]; then
 else
     echo "updated: $moved package(s)"
 fi
+# Counted apart from the movable ones: no mode of this command installs these,
+# so folding them into "updates available" would promise work --apply skips.
+if [ "$outside" -gt 0 ]; then
+    echo "outside the requested range: $outside package(s) — read the changelog, then run the 'follow it' command above"
+fi
 
 if [ "$preview" -eq 0 ] && [ "$moved" -gt 0 ] && [ "$no_sync" -eq 0 ]; then
     exec bash "$CLI_DIR/commands/sync.sh"

package/engine/ENGINE_SHA

@@ -1 +1 @@
-012f75bfb3c3036df3df9e914597ba937ab75400
+a9cf448bc3f2944c988ce57581822df081195ca2

package/engine/VERSION

@@ -1 +1 @@
-0.13.0
+0.14.0

package/engine/adapters/agents.sh

@@ -58,11 +58,9 @@ agents_md_append_agents_table() {
     local rows=""
     local count=0
 
-    local f
     local -a files=()
-    while IFS= read -r f; do
-        [ -n "$f" ] && files+=("$f")
-    done < <(source_artifact_files "$repo_root" "$config_file" "agents")
+    read_source_artifact_files "$repo_root" "$config_file" "agents"
+    [ "${#IS_SOURCE_FILES[@]}" -eq 0 ] || files=("${IS_SOURCE_FILES[@]}")
 
     if [ "${#files[@]}" -gt 0 ]; then
         local path tier access desc name
@@ -101,11 +99,10 @@ agents_md_append_skills_table() {
     local rows=""
     local count=0
 
-    local f dirname
+    local dirname
     local -a skill_files=()
-    while IFS= read -r f; do
-        [ -n "$f" ] && skill_files+=("$f")
-    done < <(source_artifact_files "$repo_root" "$config_file" "skills")
+    read_source_artifact_files "$repo_root" "$config_file" "skills"
+    [ "${#IS_SOURCE_FILES[@]}" -eq 0 ] || skill_files=("${IS_SOURCE_FILES[@]}")
 
     if [ "${#skill_files[@]}" -gt 0 ]; then
         local path desc
@@ -145,11 +142,9 @@ agents_md_append_rules_list() {
     local count=0
     local global_rule_files=()
 
-    local f
     local -a files=()
-    while IFS= read -r f; do
-        [ -n "$f" ] && files+=("$f")
-    done < <(source_artifact_files "$repo_root" "$config_file" "rules")
+    read_source_artifact_files "$repo_root" "$config_file" "rules"
+    [ "${#IS_SOURCE_FILES[@]}" -eq 0 ] || files=("${IS_SOURCE_FILES[@]}")
 
     if [ "${#files[@]}" -gt 0 ]; then
         local path hp name scope

package/engine/lib/common.sh

@@ -643,14 +643,20 @@ sync_open_skill_dirs() {
 
     local count=0 log="" d skill_file skill_name
     local -a skill_dirs=()
-    while IFS= read -r skill_file; do
-        [ -n "$skill_file" ] || continue
-        d="${skill_file%/SKILL.md}"
-        skill_name="${d##*/}"
-        skill_dirs+=("$d/")
-        count=$((count + 1))
-        log+="  skill: $skill_name"$'\n'
-    done < <(source_artifact_files "$repo_root" "$config_file" "skills")
+    read_source_artifact_files "$repo_root" "$config_file" "skills"
+    # Guard on the count, then expand quoted: Bash 3.2 (macOS) errors on an
+    # empty array under `set -u`, and quoting keeps a path with a space or a
+    # glob character intact.
+    if [ "${#IS_SOURCE_FILES[@]}" -gt 0 ]; then
+        for skill_file in "${IS_SOURCE_FILES[@]}"; do
+            [ -n "$skill_file" ] || continue
+            d="${skill_file%/SKILL.md}"
+            skill_name="${d##*/}"
+            skill_dirs+=("$d/")
+            count=$((count + 1))
+            log+="  skill: $skill_name"$'\n'
+        done
+    fi
     # copy_skill_bundle_dirs owns the frontmatter-quoting pass, so every
     # target gets it — not just this open-standard dir.
     if [ "$count" -gt 0 ]; then
@@ -1335,29 +1341,58 @@ warn_unsynced() {
 
 # Enumerate one manifest source kind using the same depth and ordering
 # everywhere. Source-list order is significant; entries inside each directory
-# use byte-order sorting for cross-platform determinism.
-source_artifact_files() {
+# use byte-order sorting for cross-platform determinism. The result lands in
+# IS_SOURCE_FILES; callers read that array.
+#
+# It is deliberately not streamed out of a subshell. This list decides what
+# every adapter renders, and a truncated one is indistinguishable from a
+# smaller project: a short list renders an incomplete file and the run still
+# reports IS_STATUS=ok. Streaming had two ways to truncate silently — a pipe
+# write cut short (bash's printf surfaces EINTR as `write error: Interrupted
+# system call` and drops the line) and a process substitution, which discards
+# its writer's exit status entirely. Assembling in the caller's shell leaves no
+# writer whose failure can be lost, and the remaining pipeline is checked. An
+# enumeration that cannot answer must stop the run, never shorten the answer.
+read_source_artifact_files() {
     local repo_root="$1"
     local config_file="$2"
     local section="$3"
-    local src f dir
+    local src f dir listing
 
+    IS_SOURCE_FILES=()
     load_yaml_list "$config_file" "$section"
     while IFS= read -r src; do
         [ -n "$src" ] || continue
         dir="$repo_root/$src"
         [ -d "$dir" ] || continue
+        # Command substitution, so the pipeline's status is the assignment's:
+        # `find` or `sort` failing aborts here instead of yielding a short list.
         case "$section" in
             rules|agents)
-                find "$dir" -maxdepth 1 -type f -name '*.md' -print | LC_ALL=C sort
+                listing="$(find "$dir" -maxdepth 1 -type f -name '*.md' -print | LC_ALL=C sort)" || {
+                    echo "ERROR: cannot enumerate $section under '$dir' — refusing to render a partial list." >&2
+                    exit 1
+                }
                 ;;
             skills)
-                while IFS= read -r f; do
-                    [ -n "$f" ] || continue
-                    [ -f "$f/SKILL.md" ] && printf '%s\n' "$f/SKILL.md"
-                done < <(find "$dir" -mindepth 1 -maxdepth 1 -type d -print | LC_ALL=C sort)
+                listing="$(find "$dir" -mindepth 1 -maxdepth 1 -type d -print | LC_ALL=C sort)" || {
+                    echo "ERROR: cannot enumerate $section under '$dir' — refusing to render a partial list." >&2
+                    exit 1
+                }
                 ;;
+            *) continue ;;
         esac
+        [ -n "$listing" ] || continue
+        # A here-string redirect keeps this loop in the current shell, so the
+        # array it fills survives and any failure inside it is this shell's.
+        while IFS= read -r f; do
+            [ -n "$f" ] || continue
+            if [ "$section" = "skills" ]; then
+                [ -f "$f/SKILL.md" ] || continue
+                f="$f/SKILL.md"
+            fi
+            IS_SOURCE_FILES+=("$f")
+        done <<< "$listing"
     done <<< "$IS_YAML_LIST"
 }
 
@@ -1391,9 +1426,8 @@ report_context_source_sizes() {
     local f path has_paths
     local -a rule_files=() always_on_rules=() scoped_rules=() agent_files=() skill_files=()
 
-    while IFS= read -r f; do
-        [ -n "$f" ] && rule_files+=("$f")
-    done < <(source_artifact_files "$repo_root" "$config_file" "rules")
+    read_source_artifact_files "$repo_root" "$config_file" "rules"
+    [ "${#IS_SOURCE_FILES[@]}" -eq 0 ] || rule_files=("${IS_SOURCE_FILES[@]}")
     if [ "${#rule_files[@]}" -gt 0 ]; then
         while IFS=$'\x1f' read -r path has_paths; do
             [ -n "$path" ] || continue
@@ -1405,13 +1439,11 @@ report_context_source_sizes() {
         done < <(frontmatter_index "paths#" "${rule_files[@]}")
     fi
 
-    while IFS= read -r f; do
-        [ -n "$f" ] && agent_files+=("$f")
-    done < <(source_artifact_files "$repo_root" "$config_file" "agents")
+    read_source_artifact_files "$repo_root" "$config_file" "agents"
+    [ "${#IS_SOURCE_FILES[@]}" -eq 0 ] || agent_files=("${IS_SOURCE_FILES[@]}")
 
-    while IFS= read -r f; do
-        [ -n "$f" ] && skill_files+=("$f")
-    done < <(source_artifact_files "$repo_root" "$config_file" "skills")
+    read_source_artifact_files "$repo_root" "$config_file" "skills"
+    [ "${#IS_SOURCE_FILES[@]}" -eq 0 ] || skill_files=("${IS_SOURCE_FILES[@]}")
 
     local always_bytes custom_bytes agents_output agents_bytes=0 agents_status="disabled"
     always_bytes="$(context_files_bytes "${always_on_rules[@]+"${always_on_rules[@]}"}")"

package/package.json

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

@@ -96,6 +96,29 @@ Registries are an ordered trust list and the only resolver for a package name. T
 
 Stable Git tags provide package versions. Semver ranges select the highest matching stable tag; a `ref:` pin names a branch or commit and does not move during `intelligence update`. One package name has one version per project.
 
+### Choosing a range
+
+`package add` without an explicit range writes `^<the version it installed>`, npm's caret. The caret holds the **leftmost non-zero** component, and that is the whole story:
+
+| Requested | Follows automatically | Stops at |
+|---|---|---|
+| `^1.4.0` | every later `1.x` | `2.0.0` |
+| `^0.4.0` | every later `0.4.x` | `0.5.0` |
+| `~1.4.0` | every later `1.4.x` | `1.5.0` |
+| `1.4.0` | nothing | it is a pin |
+| `latest` | every stable tag | nothing |
+
+**A pre-1.0 package therefore follows patches only.** SemVer treats a `0.x` minor as a major, so `^0.4.0` is a ceiling at `0.5.0` and the project stays on `0.4.x` while `0.5`, `0.6` and later ship. That is the correct reading of the range, not a defect — but it is the single most common surprise, because the same spelling behaves differently once the package reaches `1.0.0`.
+
+Practice:
+
+- **Keep the caret.** It is the right default at both stages: automatic patches, and a deliberate decision at every boundary that SemVer says may break.
+- **Read `intelligence update --preview` as two answers.** The move is what the range allows; the `available outside '<range>'` note is what it excludes, and it prints the command that follows it. That note never joins the counter, because no ordinary mode of `update` installs it.
+- **Cross a boundary deliberately, one at a time.** Read the package's changelog for every version crossed, then `intelligence update @scope/name --latest`: it takes the newest stable version and rewrites the requested range to `^<that version>`, so the manifest still records what the project asked for and the next boundary is still a decision. The flag needs the package named — one confirmation must not cover several unrelated changelogs — and it refuses a `ref:` pin, which is frozen by intent. Without it `update` never widens a range, because a command that granted itself permission to install would make the range meaningless.
+- **Review the generated diff, not just the lock.** A package minor may rename or drop an artifact. A renamed skill breaks every `/skill-name` that invoked it, and a renamed artifact silently ends the override relationship a same-named project artifact had, so the project's version stops winning and the package's content appears instead.
+- **`latest` and `*` are for a package you own and release in lockstep.** Anywhere else they hand an upstream author write access to your agents' behavior between two syncs.
+- **Never pin a range to dodge a broken release.** Pin the exact version (`1.4.2`), record why, and remove the pin when the fix ships — a narrowed range hides the reason and outlives the incident.
+
 Commit `intelligence.lock`. It records requested versions, source URLs and paths, resolved refs and commit SHAs. After cloning, `intelligence sync` restores a missing store 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.