@ainova-systems/intelligence 0.13.0 → 0.15.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
+b12551947be83587f4f74e79c5a56765a18dd52f

package/engine/VERSION

@@ -1 +1 @@
-0.13.0
+0.15.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/engine/lib/contract.sh

@@ -53,7 +53,7 @@ stamp_schema_version() {
 # --- bash ↔ skill status contract -------------------------------------------
 # Bash is the deterministic, fail-closed core: it never guesses. Any state it
 # cannot resolve safely is reported as a machine-readable status line on
-# stdout plus a stable exit code, and the intelligence-update SKILL (the
+# stdout plus a stable exit code, and the intelligence-upgrade SKILL (the
 # intelligent layer) decides what to do. Codes are part of the public
 # contract — do not renumber.
 IS_RC_OK=0                  # success (synced / migrated / nothing to do)

package/package.json

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

@@ -4,14 +4,10 @@ description: "Design and prune the intelligence layer - rule vs skill vs agent,
 tier: heavy
 access: full
 skills:
-  - intelligence-add-rule
-  - intelligence-add-agent
-  - intelligence-add-skill
-  - intelligence-extract-skill
-  - intelligence-compact-context
-  - intelligence-review-skills
+  - intelligence-update-context
+  - intelligence-review-context
   - intelligence-learn-from-repository
-  - intelligence-learn-from-context
+  - intelligence-learn-from-session
 ---
 
 # Intelligence architect
@@ -44,14 +40,12 @@ The per-artifact checks are procedure, so they live in the meta-skills rather th
 
 | Skill | Use it to |
 |---|---|
-| `intelligence-add-rule` / `intelligence-add-agent` / `intelligence-add-skill` | author one artifact |
-| `intelligence-extract-skill` | turn an observed workflow into a skill |
-| `intelligence-compact-context` | reduce context without changing behavior or teaching terse output |
-| `intelligence-review-skills` | audit the layer for duplication, drift, size, hardcoded paths |
+| `intelligence-update-context` | create, revise, or remove rules, agents, and skills |
+| `intelligence-review-context` | audit the layer and propose reductions that preserve behavior |
 | `intelligence-learn-from-repository` | recover and complete first-time repository onboarding |
-| `intelligence-learn-from-context` | fold one later session lesson into an established layer |
+| `intelligence-learn-from-session` | capture session lessons and observed workflows |
 | `intelligence-sync` | project the source to every tool channel |
-| `intelligence-update` | interpret and apply the CLI's unified update plan |
-| `intelligence-install-adapter` / `intelligence-uninstall-adapter` | research and manage a tool adapter |
+| `intelligence-upgrade` | interpret and apply the CLI's unified update plan |
+| `intelligence-manage-adapters` | enable, disable, remove, and assess output cleanup |
 
 A change is done when the sync is green and the skill you invoked reports clean. Size is a separate judgement: the caps are ceilings, not quotas, and a short artifact is not a defect.

package/packages/sync/agents/intelligence-operator.md

@@ -5,9 +5,8 @@ tier: standard
 access: full
 skills:
   - intelligence-sync
-  - intelligence-update
-  - intelligence-install-adapter
-  - intelligence-uninstall-adapter
+  - intelligence-upgrade
+  - intelligence-manage-adapters
 ---
 
 # Intelligence operator
@@ -27,7 +26,7 @@ the operation in prose.
 ## Boundaries
 
 - **Every flow goes through its skill.** The steps and their guards live in `intelligence-sync`,
-  `intelligence-update`, `intelligence-install-adapter` and `intelligence-uninstall-adapter`;
+  `intelligence-upgrade` and `intelligence-manage-adapters`;
   improvising around them produces an unverified version of the same work.
 - **Operating is not authoring.** A change to what an artifact says - a rule body, an agent persona,
   a skill's steps - belongs to `intelligence-architect` and the authoring meta-skills. This agent

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.
@@ -399,7 +422,7 @@ The public lifecycle is deliberately compact:
 
 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.
+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.
 
 ### Engine status contract
 

package/packages/sync/rules/intelligence-authoring.md

@@ -109,6 +109,6 @@ The goal is subtraction, above. These are only the line past which something is
 
 ## Verifying a change to this layer
 
-The per-artifact checks are a procedure, not a constraint to hold in mind while doing other work — so they live in the meta-skills, not here. Invoke the one that matches what you are doing: `intelligence-add-rule`, `intelligence-add-agent`, `intelligence-add-skill`, `intelligence-extract-skill`, `intelligence-review-skills`, `intelligence-learn-from-repository`, `intelligence-learn-from-context`, `intelligence-sync`, `intelligence-update`, `intelligence-install-adapter`, `intelligence-uninstall-adapter`.
+The per-artifact authoring checks belong to `intelligence-update-context`. Session learning, repository onboarding, and accepted review findings use that same procedure. Invoke `intelligence-learn-from-session` to capture a lesson or workflow, `intelligence-learn-from-repository` for initial migration and recovery, and `intelligence-review-context` for audits and reductions. Operational work uses `intelligence-sync`, `intelligence-upgrade`, or `intelligence-manage-adapters`.
 
 A change to this layer is done when `<sync-cmd>` reports `IS_STATUS=ok` and the skill you invoked reports clean.

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

@@ -39,8 +39,7 @@ mechanics; this skill supplies repository judgement.
 
 5. Read `<manifest>` and resolve the configured source directories. Load
    `<module>/references/conventions.md` and the bundled
-   `intelligence-add-rule`, `intelligence-add-skill`, and
-   `intelligence-add-agent` skills before proposing authored content. When
+   `intelligence-update-context` skill before proposing authored content. When
    preserved or legacy instructions exist, also read
    `<module>/references/onboarding-migration.md` and use its inventory,
    reverse-mapping, packaging-safety, and stale-reference procedures.
@@ -87,10 +86,10 @@ explains itself well.
 
 ## Apply after approval
 
-9. Apply only accepted proposals. Delegate new artifacts to
-   `intelligence-add-rule`, `intelligence-add-skill`, or
-   `intelligence-add-agent`; update an existing project-owned artifact directly
-   when smaller, and edit an accepted manifest header directly. Never edit
+9. Apply only accepted proposals. Pass all artifact changes to
+   `intelligence-update-context`, retaining the migration evidence and acceptance
+   scope. Defer its batch sync to step 10 so the accepted manifest header and
+   content are verified together. Edit an accepted header directly. Never edit
    installed package content or generated tool output.
 10. Run `intelligence sync`, then `intelligence status --check`. Inspect the
     relevant generated `AGENTS.md`, Cursor rules, Claude rules, and any
@@ -106,6 +105,6 @@ explains itself well.
 
 ## Later learning
 
-After onboarding is complete, use `/intelligence-learn-from-context` to capture
+After onboarding is complete, use `/intelligence-learn-from-session` to capture
 a durable lesson from a working session. It does not repeat repository
 onboarding.

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

@@ -0,0 +1,50 @@
+---
+name: intelligence-learn-from-session
+description: "Capture session lessons and workflows in project context"
+agent: intelligence-architect
+---
+
+# Learn from a session
+
+Capture a durable preference, working pattern, recurring friction, or successful
+workflow from a session in an established Intelligence project. This skill owns
+identifying and generalizing the lesson; `intelligence-update-context` owns writing it.
+
+## Verify readiness
+
+1. Locate `<manifest>`, `<content-dir>`, and `<module>`, then run
+   `intelligence status --check`. Missing or inconsistent setup, an onboarding
+   pending header, or unresolved preserved instructions routes to
+   `/intelligence-learn-from-repository` for repair and migration. Stop session
+   capture until onboarding is complete. A retained backup manifest or converted
+   legacy config alone does not mean onboarding is incomplete.
+
+## Analyze and propose
+
+2. Identify the lesson from the conversation or explicit user input. For a
+   workflow, list the actual steps performed, user decisions, branches, failure
+   recovery, and verification. Retain the sequence that worked.
+3. Generalize the evidence by removing instance-specific filenames, dates, and
+   phrasing. Keep the reason needed to apply the lesson to the next task. Prefer
+   a positive instruction such as "Default to one recommendation" for "Stop
+   generating three options". Preserve safety prohibitions; confirm a translation
+   if changing the negation changes meaning. Keep a negative example only when
+   paired with its replacement and useful for recognizing the pattern.
+4. Inspect configured sources for an existing owner. A preference or constraint
+   belongs in a rule, path-specific context in a scoped rule, an observed
+   repeatable procedure in a skill, and a persona or expertise boundary in an
+   agent. Prefer extending an existing artifact over adding a sibling.
+5. Present each proposal with its action (`CREATE`, `UPDATE`, or `ARCHIVE`),
+   source path, concrete draft, and one-line reason. This phase is read-only;
+   only user-accepted lessons become persistent instructions. Reuse approval
+   already given for the exact proposal.
+
+## Apply and verify
+
+6. Pass accepted proposals and their session evidence to
+   `/intelligence-update-context`. It handles artifact-specific authoring,
+   references, a single batch sync, and the final status check.
+7. Compare the resulting source changes with the accepted lesson. For a workflow,
+   verify that its decisions, working steps, recovery, and proof of completion
+   remain executable without this conversation. Report the saved lesson, its
+   owner, and verification; a session-specific transcript is not completion.