@ainova-systems/intelligence 0.21.0 → 0.22.1

package/cli/commands/sync.sh

@@ -106,6 +106,10 @@ run_check() {
             die "no intelligence project found here - run 'intelligence init'"
             ;;
     esac
+    # A check marks the lock it holds, so a sync started meanwhile waits for
+    # it instead of refusing (sync-lock.sh).
+    # shellcheck disable=SC2034  # read by sync-lock.sh when the lock is taken
+    SYNC_LOCK_KIND=check
     hold_project
     project_preflight "$IP_ROOT" || return $?
     if project_needs_upgrade "$IP_ROOT"; then
@@ -144,6 +148,11 @@ fi
 compact_output="$(mktemp -t intelligence-sync-XXXXXX)"
 trap 'rm -f "$compact_output"' EXIT
 rc=0
+# The one line that must not wait for the buffer: a wait for a check holding
+# the lock can last minutes (sync-lock.sh). Descriptor 9 keeps the real stderr.
+exec 9>&2
+# shellcheck disable=SC2034  # read by sync-lock.sh while the lock is taken
+IS_LOCK_NOTICE_FD=9
 (run_sync) > "$compact_output" 2>&1 || rc=$?
 if [ "$rc" -ne 0 ]; then
     cat "$compact_output" >&2

package/cli/intelligence

@@ -7,6 +7,12 @@
 
 set -euo pipefail
 
+# Bash keeps a PWD inherited from its parent when it names the current
+# directory, so a Windows caller can hand over `D:/x` or `D:\x` for what every
+# other caller sees as `/d/x`. Taken once here, one spelling gives the project
+# one root and the CLI one location, whoever started it.
+case "$PWD" in [A-Za-z]:*) cd -P . ;; esac
+
 case "$0" in
     */*) CLI_DIR="${0%/*}"; [ -n "$CLI_DIR" ] || CLI_DIR="/" ;;
     *) CLI_DIR="." ;;

package/cli/lib/sync-cache.sh

@@ -4,19 +4,19 @@
 #
 # The record keeps three fingerprints apart (decision 0018), so a check can say
 # which side moved:
-#   tooling  the CLI and engine code, plus the invocation and environment that
-#            shape rendering — target filter, root, layout, bash, locale, PATH,
-#            umask. A change here is not the project's: a check renders rather
-#            than answer "sync needed" from it.
+#   tooling  the CLI and engine code and the adapter filter. A change here is
+#            not the project's: a check renders rather than answer "sync
+#            needed" from it.
 #   inputs   the manifest, the lock, every configured source including skill
 #            resources and installed packages, and the project adapter folder.
 #   outputs  every path the enabled built-in adapters own or manage.
-# Each fingerprint lists names, entry kinds and executable state beside content
-# hashes; timestamps never count. `.intelligence/sync-cache/state` holds the
+# Each fingerprint lists relative names, entry kinds and executable state beside
+# content hashes; timestamps, the project's location and the caller's
+# environment never count. `.intelligence/sync-cache/state` holds the
 # record and the report a hit replays; `seal` holds the state file's own hash,
 # so a record is trusted only whole.
 
-SC_FORMAT='intelligence-sync-cache-v2'
+SC_FORMAT='intelligence-sync-cache-v3'
 SC_SAFE_SEEN=$'\n'
 
 sync_cache_safe_path() {
@@ -155,6 +155,19 @@ sync_cache_dependencies() {
 }
 
 # --- Fingerprint ---------------------------------------------------------------
+# sync_cache_label_var <path> — IS_SC_LABEL, the name a fingerprint records for
+# a path: relative to the engine or CLI directory for tooling, to the project
+# otherwise. Where the project or the CLI lives, and how that path is spelled,
+# never decides whether the same files are current.
+sync_cache_label_var() {
+    case "$1" in
+        "$IS_ENGINE_DIR"|"$IS_ENGINE_DIR"/*) IS_SC_LABEL="engine${1#"$IS_ENGINE_DIR"}" ;;
+        "$CLI_DIR"|"$CLI_DIR"/*) IS_SC_LABEL="cli${1#"$CLI_DIR"}" ;;
+        "$REPO_ROOT"/*) IS_SC_LABEL="${1#"$REPO_ROOT/"}" ;;
+        *) IS_SC_LABEL="$1" ;;
+    esac
+}
+
 # _sync_cache_starts <group> <path>... — queue a group's start points. A missing
 # one is recorded as missing; a repeated one is walked once.
 _sync_cache_starts() {
@@ -171,7 +184,8 @@ _sync_cache_starts() {
             SC_STARTS+=("$path")
             SC_START_GROUPS+=("$group")
         else
-            SC_MISSING+=("$group missing $path")
+            sync_cache_label_var "$path"
+            SC_MISSING+=("$group missing $IS_SC_LABEL")
         fi
     done
 }
@@ -190,7 +204,7 @@ _SC_AWK_LISTING='
         starts = split(ENVIRON["SC_AWK_STARTS"], rows, "\n")
         for (i = 1; i <= starts; i++) {
             split(rows[i], field, "\t")
-            group[i] = field[1]; posix[i] = field[2]; native[i] = field[3]
+            group[i] = field[1]; posix[i] = field[2]; native[i] = field[3]; label[i] = field[4]
         }
         probe = ENVIRON["SC_AWK_EXEC_PROBE"]
         stream = (ENVIRON["SC_AWK_STREAM"] == 1)
@@ -209,7 +223,7 @@ _SC_AWK_LISTING='
             if (!last) { bad = 1; return }
         }
         g = group[last]
-        listing[g] = listing[g] kind " " entry "\037"
+        listing[g] = listing[g] kind " " label[last] substr(entry, length(posix[last]) + 1) "\037"
         if (kind == "d") return
         k = ++files[g]
         path = native[last] substr(entry, length(posix[last]) + 1)
@@ -248,7 +262,7 @@ _SC_AWK_LISTING='
 # the listing stage tells kinds without a stat per entry. git hashes the files
 # while the walk is still running.
 sync_cache_fingerprint() {
-    local target="$1" hashes i j n value ordered=0 starts_env="" state="" umask_value
+    local target="$1" hashes i j n value ordered=0 starts_env="" state=""
     local tooling inputs outputs listing saved_ifs="$IFS"
     local -a hash_lines=() expression=() keep=() starts=() groups=() natives=() parts=() count=()
     SC_STARTS=() SC_START_GROUPS=() SC_MISSING=() SC_START_SEEN=$'\n'
@@ -299,7 +313,8 @@ sync_cache_fingerprint() {
     for ((j = 0; j < ${#starts[@]}; j++)); do
         value="${starts[j]}"
         [ "$SC_TRANSLATE" != 1 ] || value="${natives[j]}"
-        starts_env="$starts_env${groups[j]}"$'\t'"${starts[j]}"$'\t'"$value"$'\n'
+        sync_cache_label_var "${starts[j]}"
+        starts_env="$starts_env${groups[j]}"$'\t'"${starts[j]}"$'\t'"$value"$'\t'"$IS_SC_LABEL"$'\n'
     done
     starts_env="${starts_env%$'\n'}"
     expression=(\( ! -type d ! -type f -exec false {} + \)
@@ -359,15 +374,11 @@ sync_cache_fingerprint() {
     [ "${count[0]}" -eq 0 ] || { printf -v value '%s\037' "${hash_lines[@]:0:${count[0]}}"; tooling="$tooling$value"; }
     [ "${count[1]}" -eq 0 ] || { printf -v value '%s\037' "${hash_lines[@]:${count[0]}:${count[1]}}"; inputs="$inputs$value"; }
     [ "${count[2]}" -eq 0 ] || { printf -v value '%s\037' "${hash_lines[@]:$((count[0] + count[1])):${count[2]}}"; outputs="$outputs$value"; }
-    # Explicit values that affect rendering, discovery or parsing. No secrets
-    # or inherited environment dump are persisted. umask prints into a file so
-    # reading it costs no subshell.
-    umask > "$SC_SCRATCH.umask" || return 1
-    IFS= read -r umask_value < "$SC_SCRATCH.umask" || return 1
-    for value in "$target" "$REPO_ROOT" "$CONFIG_FILE" "$IS_CONTENT_REL" "$IS_MODULE_REL" \
-        "$IS_SYNC_CMD" "$IS_MANIFEST_NAME" "$IS_PROTECTED_DIRS" "$BASH_VERSION" "${OSTYPE:-}" \
-        "${LANG:-}" "${LC_ALL:-}" "${LC_CTYPE:-}" "${LC_COLLATE:-}" "${PATH:-}" "$umask_value" \
-        "exec-probe=$SC_EXEC_PROBE" "walk-ordered=$ordered"; do
+    # The adapter filter selects what renders; the two listing flags say how
+    # the listings above were made. Nothing else of the invocation counts:
+    # the code, the manifest and the files decide what sync writes, wherever
+    # the project lives and whoever starts the CLI.
+    for value in "filter=$target" "exec-probe=$SC_EXEC_PROBE" "walk-ordered=$ordered"; do
         case "$value" in *[[:cntrl:]]*) return 1 ;; esac
         tooling="${tooling}env $value"$'\037'
     done
@@ -514,9 +525,15 @@ sync_with_cache() {
 
 # The write contract marks links whose spelling must remain unchanged: they
 # are compared, never dereferenced, and are not renderer read inputs.
+#
+# SC_CHECK_OUTPUTS holds the selected adapters' paths; SC_CHECK_ALL_OUTPUTS
+# every enabled adapter's, since a filtered render still reads what the others
+# generated. SC_CHECK_PROJECT_ADAPTER is 1 when an enabled adapter is the
+# project's own code.
 sync_check_write_paths() {
     local filter="$1" dir file name i output adapter kind value
     local -a names=() files=() batch=()
+    SC_CHECK_PROJECT_ADAPTER=0
     for dir in "$IS_ENGINE_DIR/adapters" "$REPO_ROOT/$IS_CONTENT_REL/adapters"; do
         for file in "$dir"/*.sh; do
             [ -f "$file" ] || continue
@@ -530,41 +547,142 @@ sync_check_write_paths() {
     i=0
     while [ "$i" -lt "${#names[@]}" ]; do
         name="${names[i]}"; file="${files[i]}"; i=$((i + 1))
-        [ -z "$filter" ] || [ "$name" = "$filter" ] || continue
         target_enabled_var "$CONFIG_FILE" "$name"
         [ "$IS_TGT_ENABLED" = 1 ] || continue
+        case "$file" in "$REPO_ROOT/$IS_CONTENT_REL/adapters/"*) SC_CHECK_PROJECT_ADAPTER=1 ;; esac
         target_output_var "$CONFIG_FILE" "$name"
         output="${IS_TGT_OUTPUT:-.$name}"
         batch+=("$name" "$file" "$output")
     done
-    SC_CHECK_OUTPUTS=()
+    SC_CHECK_OUTPUTS=() SC_CHECK_ALL_OUTPUTS=()
     [ "${#batch[@]}" -gt 0 ] || return 0
     adapter_contract_records_batch "$SC_SCRATCH.check-contract" "${batch[@]}" > "$SC_SCRATCH.check-records" || return 1
     while IFS=$'\t' read -r adapter kind value; do
-        case "$kind" in owned|managed) SC_CHECK_OUTPUTS+=("$value") ;; esac
+        case "$kind" in
+            owned|managed)
+                SC_CHECK_ALL_OUTPUTS+=("$value")
+                [ -z "$filter" ] || [ "$adapter" = "$filter" ] || continue
+                SC_CHECK_OUTPUTS+=("$value")
+                ;;
+        esac
     done < "$SC_SCRATCH.check-records"
 }
 
+# sync_check_unlinked_path <rel> — true when no existing component of the
+# project path, the last included, is a link. Copying such a path alone would
+# leave its link pointing at something the copy does not hold.
+sync_check_unlinked_path() {
+    local rest="$1" probe="$REPO_ROOT" part
+    while [ -n "$rest" ]; do
+        part="${rest%%/*}"
+        if [ "$part" = "$rest" ]; then rest=""; else rest="${rest#*/}"; fi
+        probe="$probe/$part"
+        [ ! -L "$probe" ] || return 1
+        [ -e "$probe" ] || return 0
+    done
+}
+
+# sync_check_copy_paths — SC_CHECK_COPY, the existing project paths a render
+# by built-in adapters reads or writes, none inside another. Return 1 when only
+# a copy of the whole project is faithful: a project adapter may read any file,
+# and a link on the way to an input may point anywhere in the project.
+# Everything else the engine reads in the project is a directory listing the
+# check takes from the live tree (warn_unsynced).
+sync_check_copy_paths() {
+    local section src rel other kept
+    local -a wanted=("${CONFIG_FILE#"$REPO_ROOT/"}" intelligence.lock .intelligence/packages
+        "$IS_CONTENT_REL/adapters" .agents/rules .agents/agents)
+    SC_CHECK_COPY=()
+    [ "$SC_CHECK_PROJECT_ADAPTER" = 0 ] || return 1
+    for section in rules agents skills; do
+        load_yaml_list "$CONFIG_FILE" "$section"
+        while IFS= read -r src; do
+            case "$src" in
+                ''|/*|..|../*|*/..|*/../*) continue ;; # Outside the project: read where it is.
+            esac
+            wanted+=("$src")
+        done <<< "$IS_YAML_LIST"
+    done
+    wanted+=(${SC_CHECK_ALL_OUTPUTS[@]+"${SC_CHECK_ALL_OUTPUTS[@]}"})
+    for rel in "${wanted[@]}"; do
+        normalize_path_var "/$rel"
+        rel="${IS_NORM_PATH#/}"
+        case "$rel" in ''|.git|.git/*) return 1 ;; esac
+        sync_check_unlinked_path "$rel" || return 1
+        [ -e "$REPO_ROOT/$rel" ] || continue
+        kept=()
+        for other in ${SC_CHECK_COPY[@]+"${SC_CHECK_COPY[@]}"}; do
+            case "$rel" in "$other"|"$other"/*) continue 2 ;; esac
+            case "$other" in "$rel"/*) continue ;; esac
+            kept+=("$other")
+        done
+        SC_CHECK_COPY=(${kept[@]+"${kept[@]}"} "$rel")
+    done
+}
+
+# sync_check_holds <private-project> <rel> — true when the private copy holds
+# the project path: inside a copied entry, never a directory made only as the
+# parent of one. An empty SC_CHECK_COPY means the whole project was copied.
+sync_check_holds() {
+    local entry
+    [ -e "$1/$2" ] || [ -L "$1/$2" ] || return 1
+    [ "${#SC_CHECK_COPY[@]}" -gt 0 ] || return 0
+    for entry in "${SC_CHECK_COPY[@]}"; do
+        case "$2" in "$entry"|"$entry"/*) return 0 ;; esac
+    done
+    return 1
+}
+
 # Check renders use a private project tree. A rollback in the live tree would
-# overwrite unrelated edits made while the renderer was running.
+# overwrite unrelated edits made while the renderer was running. The tree holds
+# only what the render reads and writes: a copy of the whole project took
+# minutes and gigabytes where dependency and build trees sit beside the sources.
 sync_check_render() (
-    local target="$1" verdict="$2" staging entry link target_link manifest_rel rel output is_output original_target original_root="$REPO_ROOT" rc=0
-    local -a SC_CHECK_OUTPUTS=()
+    local target="$1" verdict="$2" staging entry link target_link manifest_rel rel output is_output original_target original_root="$REPO_ROOT" rc=0 parent
+    local -a SC_CHECK_OUTPUTS=() SC_CHECK_ALL_OUTPUTS=() SC_CHECK_COPY=() parents=() batch=()
+    local SC_CHECK_PROJECT_ADAPTER=0
     sync_check_write_paths "$target" || return 1
     manifest_rel="${CONFIG_FILE#"$REPO_ROOT/"}"
     staging="$(mktemp -d -t intelligence-check-XXXXXX)" || return 1
     trap 'rm -rf "$staging"' EXIT
     trap 'exit 130' INT
     trap 'exit 143' TERM
-    mkdir "$staging/project" || { rm -rf "$staging"; return 1; }
-    for entry in "$REPO_ROOT"/* "$REPO_ROOT"/.[!.]* "$REPO_ROOT"/..?*; do
-        [ -e "$entry" ] || [ -L "$entry" ] || continue
-        # Git history is not a renderer input. The project lock contains the
-        # check's scratch buffers and must stay solely in the real project.
-        [ "${entry##*/}" != .git ] || continue
-        cp -a "$entry" "$staging/project/" || rc=$?
-        [ "$rc" = 0 ] || break
-    done
+    # A run killed outright never reaches its trap; the lock's release or
+    # takeover removes the copy it names here.
+    : > "$staging/.intelligence-check" || return 1
+    printf '%s\n' "$staging" > "$SC_SCRATCH.tmpdir" || return 1
+    mkdir "$staging/project" || return 1
+    if sync_check_copy_paths; then
+        # One copy per parent directory: on Git Bash each process costs tens
+        # of milliseconds.
+        for rel in ${SC_CHECK_COPY[@]+"${SC_CHECK_COPY[@]}"}; do
+            parent=.
+            case "$rel" in */*) parent="${rel%/*}" ;; esac
+            for entry in ${parents[@]+"${parents[@]}"}; do
+                [ "$entry" != "$parent" ] || continue 2
+            done
+            parents+=("$parent")
+        done
+        for parent in ${parents[@]+"${parents[@]}"}; do
+            batch=()
+            for rel in "${SC_CHECK_COPY[@]}"; do
+                entry=.
+                case "$rel" in */*) entry="${rel%/*}" ;; esac
+                [ "$entry" != "$parent" ] || batch+=("$REPO_ROOT/$rel")
+            done
+            mkdir -p "$staging/project/$parent" && cp -a "${batch[@]}" "$staging/project/$parent/" || { rc=1; break; }
+        done
+    else
+        SC_CHECK_COPY=()
+        for entry in "$REPO_ROOT"/* "$REPO_ROOT"/.[!.]* "$REPO_ROOT"/..?*; do
+            [ -e "$entry" ] || [ -L "$entry" ] || continue
+            # Git history is not a renderer input. The project lock contains the
+            # check's scratch buffers and must stay solely in the real project.
+            [ "${entry##*/}" != .git ] || continue
+            cp -a "$entry" "$staging/project/" || rc=$?
+            [ "$rc" = 0 ] || break
+        done
+    fi
     if [ "$rc" = 0 ]; then
         # Never remove or rewrite through a copied directory link: it may
         # still point at the live project or an external source.
@@ -575,7 +693,9 @@ sync_check_render() (
         while IFS= read -r -d '' link; do
             target_link="$(readlink "$link")" || { rc=1; break; }
             # Output links need no relocation: comparison never follows them.
-            # Internal absolute links still move with their copied project.
+            # Internal absolute links still move with their copied project;
+            # one into a part of the project the copy does not hold keeps
+            # reading the live path, which a render only ever reads.
             rel="${link#"$staging/project/"}"
             is_output=0
             for output in ${SC_CHECK_OUTPUTS[@]+"${SC_CHECK_OUTPUTS[@]}"}; do
@@ -586,6 +706,7 @@ sync_check_render() (
                     rm "$link" && ln -s "$staging/project" "$link" || { rc=1; break; }
                     ;;
                 "$REPO_ROOT"/*)
+                    sync_check_holds "$staging/project" "${target_link#"$REPO_ROOT/"}" || continue
                     rm "$link" && ln -s "$staging/project/${target_link#"$REPO_ROOT/"}" "$link" || { rc=1; break; }
                     ;;
                 /*) ;; # Absolute external links already retain their resolution.
@@ -596,7 +717,10 @@ sync_check_render() (
                     original_target="$IS_NORM_PATH"
                     case "$original_target" in
                         "$REPO_ROOT") original_target="$staging/project" ;;
-                        "$REPO_ROOT"/*) original_target="$staging/project/${original_target#"$REPO_ROOT/"}" ;;
+                        "$REPO_ROOT"/*)
+                            entry="${original_target#"$REPO_ROOT/"}"
+                            if sync_check_holds "$staging/project" "$entry"; then original_target="$staging/project/$entry"; fi
+                            ;;
                     esac
                     normalize_path_var "${link%/*}/$target_link"
                     [ "$IS_NORM_PATH" != "$original_target" ] || continue

package/cli/lib/sync-lock.sh

@@ -12,9 +12,25 @@
 # join instead of refusing, and a holder that died can be told from one whose
 # writers still run. Taking over a dead holder's lock happens under a second
 # lock, so two runs that judged the same lock stale cannot both take it.
+#
+# `sync --check` holds the lock too, because it may restore the package store
+# and compares a copy of the live outputs. It writes nothing a person keeps, so
+# a holder that is a check marks its lock with a `kind` file, and a writing
+# command that finds such a holder waits for it instead of refusing (decision
+# 0022): a status check that runs every few minutes must never make the
+# person's own sync fail. A check never waits in line — it refuses any holder
+# at once — so it is never queued behind a writer; one that arrives as a lock is
+# released can still take it first, and the waiting writer's bound then starts
+# again for that check. A writing holder is refused at once, as before.
 
 SYNC_LOCK_HELD=""
 SYNC_LOCK_TOKEN=""
+# What this process takes the lock for: "check" for `sync --check`, empty for
+# every writer. Set before the lock is taken.
+SYNC_LOCK_KIND=""
+# How long a writer waits for each check that holds the lock, in seconds. Kept
+# in the environment only so the lock suite can exercise the bound quickly.
+SYNC_LOCK_CHECK_WAIT="${INTELLIGENCE_SYNC_LOCK_CHECK_WAIT:-300}"
 
 sync_lock_now() {
     if [ -n "${EPOCHSECONDS:-}" ]; then
@@ -47,6 +63,9 @@ sync_lock_pgid() {
 }
 
 sync_lock_write_owner() {
+    # The kind goes first, before anything that costs time: whoever can read
+    # the owner can read the kind too.
+    [ -z "$SYNC_LOCK_KIND" ] || printf '%s\n' "$SYNC_LOCK_KIND" > "$1/kind"
     sync_lock_now
     sync_lock_pgid
     SYNC_LOCK_TOKEN="$$.$IS_NOW.$RANDOM$RANDOM"
@@ -88,31 +107,126 @@ sync_lock_is_stale() {
     [ -d "$1" ] && [ -n "$(find "$1" -maxdepth 0 -mmin +1 2>/dev/null)" ]
 }
 
-# sync_lock_acquire <root> — take <root>/.intelligence/sync.lock or refuse.
+# sync_lock_held_by_check <lock> — true when the holder marked its lock as a
+# `sync --check`. A lock without the mark is a writer's, or an older CLI's.
+sync_lock_held_by_check() {
+    local kind=""
+    # The group silences the redirection too: a kind released between the
+    # test and the read must not print a stray error a caller would show.
+    [ -f "$1/kind" ] && { IFS= read -r kind < "$1/kind"; } 2>/dev/null
+    [ "$kind" = check ]
+}
+
+# sync_lock_tmpdirs <lock> — SYNC_LOCK_TMPDIRS, the temporary directories
+# outside the lock that its holder's runs named in `scratch.<pid>.tmpdir`
+# files. A run killed outright never reaches the trap that removes its own, so
+# whoever releases or takes over the lock removes them. A record is only a
+# file in the project, so it names nothing to remove unless the directory is
+# one the CLI made: an absolute, real `intelligence-check-*` directory holding
+# the marker `.intelligence-check` that the check writes first.
+sync_lock_tmpdirs() {
+    local record dir
+    SYNC_LOCK_TMPDIRS=()
+    for record in "$1"/scratch.*.tmpdir; do
+        [ -f "$record" ] || continue
+        dir=""
+        IFS= read -r dir < "$record" || [ -n "$dir" ] || continue
+        case "$dir" in /*) ;; *) continue ;; esac
+        case "$dir" in *[[:cntrl:]]*|*/./*|*/../*|*/.|*/..) continue ;; esac
+        case "${dir##*/}" in intelligence-check-?*) ;; *) continue ;; esac
+        [ -d "$dir" ] && [ ! -L "$dir" ] && [ -f "$dir/.intelligence-check" ] || continue
+        SYNC_LOCK_TMPDIRS+=("$dir")
+    done
+}
+
+# Removing an abandoned copy can take long; it never keeps the lock looking
+# ownerless or a takeover in progress.
+sync_lock_remove_tmpdirs() {
+    [ "${#SYNC_LOCK_TMPDIRS[@]}" -eq 0 ] || rm -rf "${SYNC_LOCK_TMPDIRS[@]}" 2>/dev/null || true
+    SYNC_LOCK_TMPDIRS=()
+}
+SYNC_LOCK_TMPDIRS=()
+
+# sync_lock_acquire <root> — take <root>/.intelligence/sync.lock, or refuse.
+# A writer waits for each check that holds it for up to SYNC_LOCK_CHECK_WAIT
+# seconds; a check refuses at once.
 sync_lock_acquire() {
-    local root="$1" lock="$1/.intelligence/sync.lock" took=0 age=""
+    local root="$1" lock="$1/.intelligence/sync.lock" took age="" started="$SECONDS" told=0 ownerless=""
+    local holder="" seen
     # A process start costs tens of milliseconds on Git Bash: skip the usual case.
     [ -d "$root/.intelligence" ] || mkdir -p "$root/.intelligence" || die "cannot create $root/.intelligence"
-    if mkdir "$lock" 2>/dev/null; then
-        took=1
-    elif mkdir "$lock.takeover" 2>/dev/null; then
-        # Judge again under the takeover lock: another run may have taken
-        # it over since this one looked.
-        if sync_lock_is_stale "$lock"; then
-            rm -rf "$lock"
-            mkdir "$lock" 2>/dev/null && took=1
+    while :; do
+        took=0
+        SYNC_LOCK_TMPDIRS=()
+        if mkdir "$lock" 2>/dev/null; then
+            took=1
+        elif sync_lock_is_stale "$lock" && mkdir "$lock.takeover" 2>/dev/null; then
+            # The takeover lock is taken only for a lock that already looks
+            # stale: a command waiting for a live check must never hold it,
+            # since one interrupted mid-wait would leave it behind for good.
+            # Judge again under it: another run may have taken the lock over
+            # since this one looked.
+            if sync_lock_is_stale "$lock"; then
+                sync_lock_tmpdirs "$lock"
+                rm -rf "$lock"
+                mkdir "$lock" 2>/dev/null && took=1
+            fi
+            rmdir "$lock.takeover"
+            # Their records went with the lock: remove them now even when
+            # another run took it first. A lock this run took gets its owner
+            # before any of that time is spent.
+            [ "$took" = 1 ] || sync_lock_remove_tmpdirs
+        elif [ -d "$lock.takeover" ] && [ -n "$(find "$lock.takeover" -maxdepth 0 -mmin +1 2>/dev/null)" ]; then
+            # A takeover runs for milliseconds. Removing an abandoned one is itself
+            # a check-then-delete race, so it is left to a person.
+            die "a takeover of $lock was abandoned; if no intelligence command is running in this project, remove $lock.takeover"
         fi
-        rmdir "$lock.takeover"
-    elif [ -n "$(find "$lock.takeover" -maxdepth 0 -mmin +1 2>/dev/null)" ]; then
-        # A takeover runs for milliseconds. Removing an abandoned one is itself
-        # a check-then-delete race, so it is left to a person.
-        die "a takeover of $lock was abandoned; if no intelligence command is running in this project, remove $lock.takeover"
-    fi
-    if [ "$took" = 1 ]; then
-        sync_lock_write_owner "$lock" || { rm -rf "$lock"; die "cannot write $lock/owner"; }
-        SYNC_LOCK_HELD="$lock"
-        return 0
-    fi
+        if [ "$took" = 1 ]; then
+            sync_lock_write_owner "$lock" || { rm -rf "$lock"; die "cannot write $lock/owner"; }
+            sync_lock_remove_tmpdirs
+            SYNC_LOCK_HELD="$lock"
+            return 0
+        fi
+        if [ "$SYNC_LOCK_KIND" != check ] && sync_lock_held_by_check "$lock"; then
+            # A later ownerless moment belongs to another holder's start or
+            # release, and gets its own few seconds.
+            ownerless=""
+            # The bound is per check: one that took the lock while this
+            # command waited starts its own count.
+            if sync_lock_read_owner "$lock"; then
+                seen="$IS_LOCK_PID $IS_LOCK_SINCE $IS_LOCK_TOKEN"
+                if [ "$seen" != "$holder" ]; then
+                    holder="$seen"
+                    started="$SECONDS"
+                fi
+            fi
+            [ $((SECONDS - started)) -lt "$SYNC_LOCK_CHECK_WAIT" ] || break
+            if [ "$told" = 0 ]; then
+                # A caller that buffers this command's output (sync --compact)
+                # names a descriptor for the terminal, so a wait of minutes
+                # is never silent.
+                # Not one `>&"${fd:-2}"`: the group's 2>/dev/null, which keeps
+                # a closed descriptor quiet, would swallow the default too.
+                if [ -n "${IS_LOCK_NOTICE_FD:-}" ]; then
+                    { echo "waiting for intelligence sync --check to release $lock" >&"$IS_LOCK_NOTICE_FD"; } 2>/dev/null \
+                        || echo "waiting for intelligence sync --check to release $lock" >&2
+                else
+                    echo "waiting for intelligence sync --check to release $lock" >&2
+                fi
+                told=1
+            fi
+        elif ! sync_lock_read_owner "$lock"; then
+            # No owner: a holder between its mkdir and its owner file, or one
+            # being released. Both last moments, so look again for a few
+            # seconds from the first sight before calling it a run that is
+            # still starting.
+            [ -n "$ownerless" ] || ownerless="$SECONDS"
+            [ $((SECONDS - ownerless)) -lt 3 ] || break
+        else
+            break
+        fi
+        sleep 1
+    done
     if sync_lock_read_owner "$lock"; then
         sync_lock_now
         case "$IS_LOCK_SINCE" in ''|*[!0-9]*) ;; *) age=", for $((IS_NOW - IS_LOCK_SINCE))s" ;; esac
@@ -147,6 +261,14 @@ project_lock_hold() {
 sync_lock_release() {
     [ -n "$SYNC_LOCK_HELD" ] || return 0
     if sync_lock_read_owner "$SYNC_LOCK_HELD" && [ "$IS_LOCK_TOKEN" = "$SYNC_LOCK_TOKEN" ]; then
+        # While the owner still stands, so a waiter keeps waiting.
+        sync_lock_tmpdirs "$SYNC_LOCK_HELD"
+        sync_lock_remove_tmpdirs
+        # A check's owner goes first: `rm -rf` alone could expose a moment with
+        # the owner still there and the kind gone, and a command waiting for
+        # the check would be refused in it. Without the owner, a waiter sees a
+        # check or a lock still starting, and waits either way.
+        [ ! -f "$SYNC_LOCK_HELD/kind" ] || rm -f "$SYNC_LOCK_HELD/owner"
         rm -rf "$SYNC_LOCK_HELD"
     fi
     SYNC_LOCK_HELD=""

package/engine/ENGINE_SHA

@@ -1 +1 @@
-af0a0fdbc3f505e4f063ae516c9243c92db6e376
+4a95c37c037291cd55c305b72571decae77d7767

package/engine/VERSION

@@ -1 +1 @@
-0.21.0
+0.22.1

package/engine/adapters/claude-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "intelligence",
+  "version": "__INTELLIGENCE_VERSION__",
+  "description": "Shows this project's Intelligence sync status above the prompt and runs intelligence sync from Claude Code",
+  "author": { "name": "Ainova Systems" }
+}

package/engine/adapters/claude-plugin/README.md

@@ -0,0 +1,14 @@
+# Intelligence sync status for Claude Code
+
+`intelligence sync` renders this plugin into a project's
+`.claude/skills/intelligence/` from the Intelligence engine's
+`adapters/claude-plugin/` template when `targets.claude.plugin` is `true` in
+`intelligence.yaml`. Change the template in the engine, never a rendered copy:
+the next sync rewrites the copy, and setting the flag to `false` removes it.
+
+It is a Claude Code plugin whose hooks module (`hooks/register.js`) checks
+`intelligence sync --check` when a session starts and every five minutes,
+shows the result in a line above the prompt while something needs attention,
+and runs `intelligence sync` from a `Sync now` button there or the
+`/intelligence sync` command. Its requirements and limits are defined in the
+Intelligence CLI reference, `docs/cli.md`, under `intelligence sync`.

package/engine/adapters/claude-plugin/hooks/hooks.json

@@ -0,0 +1,3 @@
+{
+  "modules": ["./register.js"]
+}

package/engine/adapters/claude-plugin/hooks/register.js

@@ -0,0 +1,324 @@
+// Intelligence sync status for Claude Code.
+//
+// `intelligence sync` renders this file from the engine's claude-plugin
+// template when targets.claude.plugin is true (decision 0022). It is a Claude
+// Code mod: a hooks module with no Node.js APIs, reaching the project only
+// through the mods API `$`. It asks `intelligence sync --check` whether the
+// generated output is current when a session starts and every five minutes,
+// shows the answer in one line above the prompt while a check runs or
+// something needs attention, and runs `intelligence sync` from a button there
+// or the /intelligence command. It registers no tool and never submits a
+// prompt: it informs the person, never Claude.
+
+// A cold `sync --check` renders the project in a private copy, which takes
+// minutes on Git Bash; a warm one answers from its record in seconds. The
+// timeout stays just under the interval, so a slow check is waited for rather
+// than reported as a failure. A tick never starts a check while one of ours is
+// pending; one abandoned at the timeout can still finish beside the next.
+const CHECK_EVERY_MS = 300000
+const CHECK_TIMEOUT_MS = 290000
+// `$.process.run` allows ten minutes at most, which a full sync may need: it
+// first waits for any check holding the project lock (decision 0022).
+const SYNC_TIMEOUT_MS = 600000
+// Another command holding the project lock is asked again this soon, then
+// after doubling pauses up to the regular interval, so a lock that stays held
+// costs a few processes, not one every 15 seconds.
+const RETRY_MS = 15000
+// The spinner Claude Code draws while it works.
+const FRAMES = ['·', '✢', '✳', '✶', '✻', '✽', '✻', '✶', '✳', '✢']
+const FRAME_MS = 120
+// The CLI's refusal when another command holds the project lock.
+const LOCK_REFUSAL = /another intelligence sync is (running|starting)/
+// The CLI's word that the project was stamped by a newer CLI than itself: a
+// warning for a newer minor or patch, a refusal for a newer major.
+const CLI_BEHIND = /newer than this CLI's engine|IS_STATUS=ahead-of-engine/
+
+// What the last check found. `status` is one of unknown (no verdict yet), ok,
+// stale, error, missing-cli or old-cli; `busy` is true while a sync started
+// from here is running.
+const state = { status: 'unknown', detail: '', checkedAt: null, busy: false }
+// A check already in flight answers the next caller too, so a timer tick and
+// a /intelligence check never run two CLI processes side by side.
+let pendingCheck = null
+let retry = null
+let retryMs = RETRY_MS
+let ticker = null
+let frame = 0
+// The terminal and the Desktop app draw the band above the prompt; elsewhere,
+// such as the VS Code extension, the status line under the prompt carries the
+// text. The footer under the prompt is Claude Code's own and stays untouched.
+let band = false
+
+// The CLI reports its result as one `IS_STATUS=<status> IS_DETAIL=<text>`
+// line; everything else on stdout is progress.
+function parseStatus(stdout) {
+  const match = /^IS_STATUS=(\S+)(?: IS_DETAIL=(.*))?$/m.exec(stdout || '')
+  return { status: match ? match[1] : '', detail: match && match[2] ? match[2].trim() : '' }
+}
+
+function firstLine(text) {
+  const line = (text || '').split(/\r?\n/).find((l) => l.trim() !== '')
+  return line ? line.trim() : ''
+}
+
+// A failing CLI prints its progress before the reason, so the first line is
+// often a banner: prefer the line that says what went wrong.
+function reasonLine(text) {
+  const line = (text || '').split(/\r?\n/).find((l) => /^\s*ERROR:/.test(l))
+  return line ? line.trim().replace(/^ERROR:\s*/, '') : firstLine(text)
+}
+
+function errorMessage(err) {
+  return String(err && err.message ? err.message : err)
+}
+
+function clock(date) {
+  const hh = String(date.getHours()).padStart(2, '0')
+  const mm = String(date.getMinutes()).padStart(2, '0')
+  return hh + ':' + mm
+}
+
+function setState(status, detail) {
+  // A verdict ends a run of retries; the next held lock starts at 15 s again.
+  retryMs = RETRY_MS
+  state.status = status
+  state.detail = detail || ''
+  state.checkedAt = new Date()
+}
+
+function animating() {
+  return state.busy || state.status === 'unknown'
+}
+
+// The band's line: one short phrase, with Claude Code's spinner while a check
+// or a sync has not answered yet.
+function label() {
+  if (state.busy) return FRAMES[frame] + ' intelligence: syncing'
+  switch (state.status) {
+    case 'stale':
+      return 'intelligence: sync needed'
+    case 'missing-cli':
+      return 'intelligence: CLI not found'
+    case 'old-cli':
+      return 'intelligence: update the CLI'
+    case 'error':
+      return 'intelligence: check failed'
+    default:
+      return FRAMES[frame] + ' intelligence: checking'
+  }
+}
+
+// The full sentence: the /intelligence reply, and the status line where no
+// band draws. Claude Code prefixes a status line with the plugin's name.
+function statusText() {
+  if (state.busy) return 'syncing…'
+  const at = state.checkedAt ? ' · ' + clock(state.checkedAt) : ''
+  switch (state.status) {
+    case 'ok':
+      return 'up to date' + at
+    case 'stale':
+      return 'sync needed — run /intelligence sync' + at
+    case 'missing-cli':
+      return 'CLI not found on PATH'
+    case 'old-cli':
+      return 'the intelligence CLI on PATH is older than this project — run: intelligence upgrade'
+    case 'error':
+      return 'check failed: ' + state.detail + at
+    default:
+      return 'checking…'
+  }
+}
+
+// Every state change redraws the band above the prompt; the spinner turns only
+// while something is pending.
+function show($) {
+  if (animating() && !ticker) {
+    ticker = $.clock.every(FRAME_MS, () => {
+      frame = (frame + 1) % FRAMES.length
+      $.ui.invalidate('ui.render')
+    })
+  } else if (!animating() && ticker) {
+    ticker.cancel()
+    ticker = null
+  }
+  $.ui.status(band ? undefined : statusText())
+  $.ui.invalidate('ui.render')
+}
+
+// Ask again soon after a command that held the project lock; the verdict
+// shown meanwhile is the last one, never a guess.
+function retrySoon($) {
+  if (retry) return
+  retry = $.clock.after(retryMs, () => {
+    retry = null
+    check($)
+  })
+  retryMs = Math.min(retryMs * 2, CHECK_EVERY_MS)
+}
+
+async function check($) {
+  if (state.busy) return
+  if (pendingCheck) return pendingCheck
+  pendingCheck = runCheck($).finally(() => {
+    pendingCheck = null
+  })
+  return pendingCheck
+}
+
+async function runCheck($) {
+  let result
+  let cwd = ''
+  try {
+    // The project root, not the shell's cwd: a session started in a
+    // subdirectory still checks the project the plugin was rendered for.
+    cwd = await $.session.root()
+    result = await $.process.run(['intelligence', 'sync', '--check'], { cwd, timeoutMs: CHECK_TIMEOUT_MS })
+  } catch (err) {
+    // The call rejects when the program cannot start or outlives its
+    // timeout; the result arrives whatever the exit code otherwise.
+    const message = errorMessage(err)
+    if (/failed to start/i.test(message)) setState('missing-cli', message)
+    else if (await lockHeld($, cwd)) retrySoon($)
+    else setState('error', message)
+    show($)
+    return
+  }
+  const parsed = parseStatus(result.stdout)
+  // An older CLI renders this project with its own engine, so its verdict
+  // says nothing about what this project's CLI would write, and its sync
+  // would drop this plugin: say so instead of offering one.
+  if (CLI_BEHIND.test((result.stderr || '') + ' ' + (result.stdout || ''))) setState('old-cli', reasonLine(result.stderr))
+  // Exit 0 is up to date and 2 is `out-of-date`, the only verdicts sync
+  // --check gives; anything else is the CLI refusing to answer.
+  else if (result.exitCode === 0) setState('ok', parsed.detail)
+  else if (result.exitCode === 2) setState('stale', parsed.detail || 'sync needed')
+  // Another holder of the project lock — someone's sync, or another
+  // session's check — is not a fault: the last verdict stays, and the check
+  // asks again shortly instead of queueing ahead of a waiting sync.
+  else if (LOCK_REFUSAL.test(result.stderr || '')) retrySoon($)
+  else setState('error', parsed.detail || reasonLine(result.stderr) || 'exit ' + result.exitCode)
+  show($)
+}
+
+// A check cut off at its timeout behind another command, or still finishing
+// on its own, leaves the project lock in place: that is a command still
+// running, not a failed check. The process the timeout abandoned keeps running.
+async function lockHeld($, root) {
+  if (!root) return false
+  try {
+    return await $.fs.exists(root + '/.intelligence/sync.lock')
+  } catch {
+    return false
+  }
+}
+
+async function runSync($) {
+  if (state.busy) return
+  if (state.status === 'old-cli') {
+    $.ui.toast('update the intelligence CLI first: intelligence upgrade')
+    return 'not run'
+  }
+  state.busy = true
+  show($)
+  let outcome
+  let cwd = ''
+  try {
+    // A check of ours still running holds the project lock; the CLI would
+    // wait for it too, but waiting here keeps its late answer from landing
+    // after the sync's own.
+    if (pendingCheck) await pendingCheck
+    cwd = await $.session.root()
+    const result = await $.process.run(['intelligence', 'sync', '--compact'], { cwd, timeoutMs: SYNC_TIMEOUT_MS })
+    if (result.exitCode === 0) {
+      outcome = 'sync finished'
+    } else {
+      const reason = reasonLine(result.stderr) || parseStatus(result.stdout).detail || 'exit ' + result.exitCode
+      outcome = 'sync failed: ' + reason
+    }
+  } catch (err) {
+    // A sync past its timeout, which includes waiting for a check, keeps
+    // running and holding the lock: it has not failed yet.
+    if (!/failed to start/i.test(errorMessage(err)) && (await lockHeld($, cwd))) {
+      outcome = 'sync is still running; the status updates when it ends'
+    } else {
+      outcome = 'sync could not run: ' + errorMessage(err)
+    }
+  }
+  // The check, not the sync's own exit code, decides what the status shows:
+  // it is the same judgement the next timer tick would make. Until it answers
+  // the status is `checking`, so the band never offers `Sync now` again for
+  // the verdict the sync just replaced.
+  state.status = 'unknown'
+  state.detail = ''
+  state.busy = false
+  show($)
+  $.ui.toast(outcome)
+  await check($)
+  return outcome
+}
+
+export function register(on) {
+  on('session.start', async ($, e, next) => {
+    // A build without surfaces() draws in the terminal; the band is the default.
+    try {
+      band = (await $.session.surfaces()).some((s) => s === 'terminal' || s === 'desktop')
+    } catch {
+      band = true
+    }
+    // The label shows at once, turning, while a cold first check can take
+    // minutes.
+    show($)
+    // Neither the first check nor the timer is awaited: the session must
+    // never wait on the CLI.
+    check($)
+    $.clock.every(CHECK_EVERY_MS, () => check($))
+    // Registered last and guarded: a taken name throws, and a hook that
+    // throws is skipped from that line on.
+    try {
+      await $.command.register({
+        name: 'intelligence',
+        description: 'Show Intelligence sync status or run sync',
+        argumentHint: '[sync|check]',
+        immediate: true,
+      })
+    } catch (err) {
+      $.ui.log('/intelligence not registered: ' + errorMessage(err), { to: 'debug' })
+    }
+    return next(e)
+  })
+
+  on('command.run', { command: 'intelligence' }, async ($, e) => {
+    const args = (e.args || '').trim()
+    if (args === 'sync') {
+      if (state.busy) return { text: 'a sync started from here is still running' }
+      const outcome = await runSync($)
+      return { text: outcome + ' — ' + statusText() }
+    }
+    if (args === 'check') {
+      await check($)
+      return { text: statusText() }
+    }
+    if (args === '') {
+      const detail = state.detail && state.status !== 'ok' ? ' (' + state.detail + ')' : ''
+      return { text: statusText() + detail }
+    }
+    return { text: 'usage: /intelligence [sync|check]' }
+  })
+
+  // The band above the prompt, where Claude Code draws nothing of its own,
+  // carries the status while there is something to wait for or act on, and
+  // is gone while the project is up to date.
+  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
+    if (state.status === 'ok' && !state.busy) return next(e)
+    const { Box, Text, Button } = $.ui.resolve(e)
+    const color = state.status === 'error' || state.status === 'old-cli' ? 'red' : state.status === 'stale' ? 'yellow' : undefined
+    const children = [Text({ color, dimColor: animating(), children: [label()] })]
+    // A digit hotkey on the band also fires from an empty prompt, typed and
+    // left for a moment; a letter would need the band focused first. Plain,
+    // because only a plain button shows its hotkey in the terminal.
+    if (state.status === 'stale' && !state.busy) {
+      children.push(Button({ key: 'sync', label: 'Sync now', hotkey: '1', plain: true, onPress: () => runSync($) }))
+    }
+    return Box({ flexDirection: 'row', columnGap: 2, children })
+  })
+}

package/engine/adapters/claude.sh

@@ -6,6 +6,11 @@
 # Skills: copy skill directories in full (SKILL.md + bundled resources),
 #   effort -> Claude's effort level
 # Agents: tier -> model, effort -> effort, access -> tools/disallowedTools
+# Plugin: with `targets.claude.plugin: true`, the Claude Code mod in
+#   adapters/claude-plugin/ is rendered into <output>/skills/intelligence/
+#   (decision 0022). Claude Code loads a plugin from a project's skills
+#   directory, so the plugin lives inside a path this contract already owns:
+#   ownership, Git policy, snapshots and `sync --check` need no new record.
 #
 # Every per-file loop batches its work into one awk process (see the batched
 # helpers in lib/common.sh): process spawns dominate sync time on Windows.
@@ -29,6 +34,52 @@ adapter_contract_claude() {
     adapter_contract_include "$output/settings.json"
 }
 
+# claude_plugin_var <manifest> — the one reader of targets.claude.plugin. Sets
+# IS_CLAUDE_PLUGIN to 1 when the project renders the Claude Code plugin and 0
+# for the default; returns 1 for a value target_bool_var refuses.
+claude_plugin_var() {
+    local rc=0
+    target_bool_var "$1" claude plugin || rc=1
+    IS_CLAUDE_PLUGIN="$IS_TARGET_BOOL"
+    return "$rc"
+}
+
+# The directory name the plugin takes under <output>/skills: a source skill
+# rendered under this name would be overwritten, so sync refuses the pair.
+IS_CLAUDE_PLUGIN_NAME=intelligence
+
+# render_claude_plugin <output_dir> — copy the plugin template byte for byte,
+# stamp the engine version into its manifest and normalize line endings. The
+# template is in the engine's adapter directory, never in the content package:
+# it is executable tooling, and the bundle copies all of engine/. It is found
+# through the engine root, so a project's own claude.sh renders it too.
+render_claude_plugin() {
+    local output_dir="$1" tpl
+    local dst="$output_dir/skills/$IS_CLAUDE_PLUGIN_NAME"
+    # Rendered beside the destination, under a name no skill can take, and
+    # swapped in only when it differs: a running session reloads the mod on
+    # every file change, and announces each reload in its transcript.
+    local tmp="$output_dir/skills/.$IS_CLAUDE_PLUGIN_NAME.render.$$"
+    engine_root_var
+    tpl="$IS_ENGINE_ROOT/adapters/claude-plugin"
+    engine_version_var
+    rm -rf "$tmp"
+    mkdir -p "$tmp/.claude-plugin" "$tmp/hooks"
+    cp "$tpl/hooks/hooks.json" "$tpl/hooks/register.js" "$tmp/hooks/"
+    cp "$tpl/README.md" "$tmp/README.md"
+    awk -v v="$IS_ENGINE_VERSION" '{ sub(/__INTELLIGENCE_VERSION__/, v); print }' \
+        "$tpl/.claude-plugin/plugin.json" > "$tmp/.claude-plugin/plugin.json"
+    finalize_output_files "$tmp/.claude-plugin/plugin.json" "$tmp/hooks/hooks.json" \
+        "$tmp/hooks/register.js" "$tmp/README.md"
+    if [ -d "$dst" ] && [ ! -L "$dst" ] && diff -r -q "$tmp" "$dst" >/dev/null 2>&1; then
+        rm -rf "$tmp"
+    else
+        rm -rf "$dst"
+        mv "$tmp" "$dst"
+    fi
+    echo "  plugin: $IS_CLAUDE_PLUGIN_NAME (Claude Code mod $IS_ENGINE_VERSION)"
+}
+
 # Sync rules to Claude format (copy as-is, normalize LF)
 sync_claude_rules() {
     local repo_root="$1"
@@ -53,13 +104,32 @@ sync_claude_skills() {
     local config_file="$2"
     local output_dir="$3"
 
-    local i name
+    local i name clash="" nocase=0
     local -a skill_dirs=()
     # The catalog's skills are the ones the inventory renders, symlinked ones
     # included (decision 0017).
     output_rel_var "$repo_root" "$output_dir"
     source_artifacts_var "$repo_root" "$config_file" skills claude "$IS_OUTPUT_REL/skills/{}"
     [ "${#IS_SOURCE_FILES[@]}" -gt 0 ] || return 0
+    # The plugin takes one skill directory name; a skill rendered under it and
+    # the plugin would each erase the other, so neither is written. Names
+    # compare without case: on Windows and macOS `Intelligence/` is the same
+    # directory. (nocasematch, not ${name,,}: macOS ships bash 3.2.)
+    if [ "${IS_CLAUDE_PLUGIN:-0}" = 1 ]; then
+        shopt -q nocasematch && nocase=1
+        shopt -s nocasematch
+        for ((i = 0; i < ${#IS_SOURCE_FILES[@]}; i++)); do
+            if [[ "${IS_SOURCE_NAMES[i]}" == "$IS_CLAUDE_PLUGIN_NAME" ]]; then
+                clash="${IS_SOURCE_FILES[i]#"$repo_root/"}"
+                break
+            fi
+        done
+        [ "$nocase" = 1 ] || shopt -u nocasematch
+        if [ -n "$clash" ]; then
+            echo "ERROR: skill $clash renders as $IS_OUTPUT_REL/skills/$IS_CLAUDE_PLUGIN_NAME, the directory targets.claude.plugin: true reserves for the Claude Code plugin. Rename the skill or set targets.claude.plugin to false." >&2
+            return 1
+        fi
+    fi
     for ((i = 0; i < ${#IS_SOURCE_FILES[@]}; i++)); do
         skill_dirs+=("${IS_SOURCE_FILES[i]%/SKILL.md}/")
     done
@@ -156,18 +226,39 @@ sync_to_claude() {
 
     echo "=== Claude Code ==="
 
+    # The flag is read before anything is removed: a malformed value refuses
+    # the sync with the reason, and the output stays exactly as it was.
+    claude_plugin_var "$config_file" || {
+        echo "ERROR: targets.claude.plugin must be true or false: true renders the Claude Code plugin into ${output_dir#"$repo_root/"}/skills/$IS_CLAUDE_PLUGIN_NAME, false or omission does not." >&2
+        return 1
+    }
+
     # Clean generated content only — preserve any project-level files
     # the user manages directly (settings.json, settings.local.json,
     # commands/, statusline.sh, etc.).
     rm -rf "$output_dir/rules" "$output_dir/agents"
     if [ -d "$output_dir/skills" ]; then
-        find "$output_dir/skills" -mindepth 1 -maxdepth 1 \( -type d -o -type l \) -exec rm -rf {} +
+        # The plugin directory stays while the flag holds: Claude Code reloads
+        # a mod whose files change, so render_claude_plugin rewrites it only
+        # when its content differs. A skill of that name was refused above.
+        if [ "$IS_CLAUDE_PLUGIN" = 1 ]; then
+            find "$output_dir/skills" -mindepth 1 -maxdepth 1 \( -type d -o -type l \) \
+                ! -name "$IS_CLAUDE_PLUGIN_NAME" -exec rm -rf {} +
+        else
+            find "$output_dir/skills" -mindepth 1 -maxdepth 1 \( -type d -o -type l \) -exec rm -rf {} +
+        fi
     fi
     mkdir -p "$output_dir/rules" "$output_dir/skills" "$output_dir/agents"
 
     sync_claude_rules "$repo_root" "$config_file" "$output_dir"
+    # Called plainly, never on the left of `||`: that would turn errexit off
+    # for every copy inside, and a failed one would no longer fail the sync.
     sync_claude_skills "$repo_root" "$config_file" "$output_dir"
     sync_claude_agents "$repo_root" "$config_file" "$output_dir"
+    # The skills renderer has refused a skill of the plugin's name by now, so
+    # the plugin never lands on top of one. Cleared above with every other
+    # skill directory, it exists only while the flag says so.
+    [ "$IS_CLAUDE_PLUGIN" = 0 ] || render_claude_plugin "$output_dir"
 
     count_matching_files "$output_dir/rules" "*.md" \
         "$output_dir/skills" "SKILL.md" "$output_dir/agents" "*.md"

package/engine/adapters/copilot.sh

@@ -55,19 +55,13 @@ adapter_contract_copilot() {
 
 # copilot_commit_output_var <manifest> — the one reader of
 # targets.copilot.commit_output. Sets IS_COPILOT_COMMIT_OUTPUT to 1 when the
-# project commits generated output and 0 for the default; returns 1 for any
-# value other than true or false. No manifest — a caller reading ownership
-# only — is the default.
+# project commits generated output and 0 for the default; returns 1 for a value
+# target_bool_var refuses.
 copilot_commit_output_var() {
-    local manifest="$1" setting
-    IS_COPILOT_COMMIT_OUTPUT=0
-    [ -n "$manifest" ] && [ -f "$manifest" ] || return 0
-    setting="$(get_target_field "$manifest" "copilot" "commit_output")"
-    case "$setting" in
-        ''|false) ;;
-        true) IS_COPILOT_COMMIT_OUTPUT=1 ;;
-        *) return 1 ;;
-    esac
+    local rc=0
+    target_bool_var "$1" copilot commit_output || rc=1
+    IS_COPILOT_COMMIT_OUTPUT="$IS_TARGET_BOOL"
+    return "$rc"
 }
 
 # copilot_paths_rows <file>... — batch form of the old per-file `paths:`

package/engine/lib/common.sh

@@ -3629,6 +3629,24 @@ is_target_enabled() {
     ' "$file"
 }
 
+# target_bool_var <manifest> <target> <field> — the one reading of a boolean
+# target field (targets.copilot.commit_output, targets.claude.plugin). Sets
+# IS_TARGET_BOOL to 1 for true and 0 for false, omission or an empty value;
+# returns 1 for anything else, so a typo never decides silently. No manifest —
+# a caller reading ownership only — is the default.
+# shellcheck disable=SC2034  # IS_TARGET_BOOL is the return channel
+target_bool_var() {
+    local setting
+    IS_TARGET_BOOL=0
+    [ -n "$1" ] && [ -f "$1" ] || return 0
+    setting="$(get_target_field "$1" "$2" "$3")"
+    case "$setting" in
+        ''|false) ;;
+        true) IS_TARGET_BOOL=1 ;;
+        *) return 1 ;;
+    esac
+}
+
 # Get an arbitrary field from a target's config block.
 # Handles both inline (`claude: { enabled: true, output: ".claude" }`)
 # and block form. Uses POSIX awk only — no gawk-specific 3-arg match().

package/engine/lib/contract.sh

@@ -100,18 +100,27 @@ is_status() {
     fi
 }
 
+# engine_root_var — set IS_ENGINE_ROOT to the engine directory, one level above
+# this lib. A project adapter that overrides a built-in finds the engine's own
+# files through it, never beside itself.
+engine_root_var() {
+    local lib="${BASH_SOURCE[0]}"
+    case "$lib" in
+        */*) lib="${lib%/*}" ;;
+        *) lib="." ;;
+    esac
+    IS_ENGINE_ROOT="$lib/.."
+}
+
 # Engine version = VERSION one level above this lib (BASH_SOURCE works when
 # sourced). Empty if unreadable — callers treat empty as "no guard".
 # engine_version_var sets IS_ENGINE_VERSION, and IS_ENGINE_VERSION_FOUND=1 when
 # the file exists; it reads the file once per process.
 engine_version_var() {
     [ -z "${IS_ENGINE_VERSION_FOUND:-}" ] || return 0
-    local lib="${BASH_SOURCE[0]}" vf content=""
-    case "$lib" in
-        */*) lib="${lib%/*}" ;;
-        *) lib="." ;;
-    esac
-    vf="$lib/../VERSION"
+    local vf content=""
+    engine_root_var
+    vf="$IS_ENGINE_ROOT/VERSION"
     IS_ENGINE_VERSION=""
     IS_ENGINE_VERSION_FOUND=0
     [ -f "$vf" ] || return 0

package/engine/sync.sh

@@ -742,10 +742,14 @@ SYNC_TX_ACTIVE=0
 #     defaults move forward — e.g., gpt-5.5 -> gpt-5.6).
 # Concurrently, the scan runs beside the other two and beside removing the
 # snapshots; the buffers print in the order above.
+# A check renders in a copy that holds only the project's inputs and outputs; the
+# scan lists directories and reads no bytes, so it looks at the live project.
+UNSYNCED_ROOT="$REPO_ROOT"
+[ -z "${IS_SYNC_CHECK:-}" ] || [ -z "${IS_SYNC_CHECK_ROOT:-}" ] || UNSYNCED_ROOT="$IS_SYNC_CHECK_ROOT"
 if [ "$SYNC_PARALLEL" = 1 ]; then
     rm -rf "$SYNC_TX_DIR/data" &
     SYNC_BG_PIDS+=("$!")
-    warn_unsynced "$REPO_ROOT" "$CONFIG_FILE" > "$SYNC_TX_DIR/unsynced" 2>&1 &
+    warn_unsynced "$UNSYNCED_ROOT" "$CONFIG_FILE" > "$SYNC_TX_DIR/unsynced" 2>&1 &
     SYNC_BG_PIDS+=("$!")
     {
         report_context_source_sizes "$REPO_ROOT" "$CONFIG_FILE"
@@ -758,7 +762,7 @@ if [ "$SYNC_PARALLEL" = 1 ]; then
 else
     rm -rf "$SYNC_TX_DIR"
     trap - EXIT INT TERM
-    warn_unsynced "$REPO_ROOT" "$CONFIG_FILE"
+    warn_unsynced "$UNSYNCED_ROOT" "$CONFIG_FILE"
     report_context_source_sizes "$REPO_ROOT" "$CONFIG_FILE"
     report_model_drift "$CONFIG_FILE"
 fi

package/package.json

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

@@ -129,6 +129,17 @@ Code ignore theirs, and never `.github/` itself. `targets.copilot.commit_output:
 true` keeps them tracked for Copilot on github.com; the setting is defined in
 [Generated output and version control](conventions.md#generated-output-and-version-control).
 
+The Claude adapter renders a Claude Code plugin into `<output>/skills/intelligence/`
+when `targets.claude.plugin` is `true` (decision 0022): a mod that checks
+`intelligence sync --check` at session start and every five minutes, shows the
+verdict in a line above the prompt and runs sync from a button there or
+`/intelligence sync`.
+The template is `engine/adapters/claude-plugin/`, copied with the engine version
+stamped into `plugin.json`. It lives inside the owned `skills` path, so it needs
+no contract record of its own. The field's values, the name collision it refuses
+and the plugin's limits are defined in the
+[CLI reference](https://github.com/ainova-systems/intelligence/blob/main/docs/cli.md#intelligence-sync).
+
 The engine calls:
 
 ```text
@@ -373,7 +384,7 @@ For a built-in adapter, add the same assertions to the repository's smoke or lif
 |---|---|
 | `agents` | `AGENTS.md` |
 | `antigravity` | `.agents/rules`, `.agents/agents`, `.agents/skills` |
-| `claude` | `.claude/rules`, `.claude/agents`, `.claude/skills` |
+| `claude` | `.claude/rules`, `.claude/agents`, `.claude/skills` (with `plugin: true`, `.claude/skills/intelligence` is the Claude Code plugin) |
 | `cursor` | `.cursor/rules`, `.cursor/agents`, `.cursor/skills` |
 | `copilot` | `.github/instructions`, `.github/agents`, `.github/skills` |
 | `codex` | `.codex/agents`, `.agents/skills`, marker-owned `AGENTS.override.md` |