@ainova-systems/intelligence 0.19.0 → 0.21.0

package/cli/commands/init.sh

@@ -356,7 +356,8 @@ manifest="$root/intelligence.yaml"
 } > "$manifest"
 
 # The package store is restorable state, never committed — the npm model.
-ensure_base_gitignore "$root"
+# Local rules, agents and skills stay on this machine (decision 0021).
+ensure_base_gitignore "$root" "$content_dir"
 for target in $targets; do
     ensure_target_gitignore "$root" "$manifest" "$target"
 done

package/cli/commands/registry.sh

@@ -51,7 +51,7 @@ case "$sub" in
             echo "  index.yaml reachable — $n package(s):"
             qmap_keys "$index" "packages" | sed 's/^/    /'
         elif [ "$force" -eq 1 ]; then
-            echo "  WARN: no index.yaml at $url — recording anyway (--force)." >&2
+            echo "WARNING: no index.yaml at $url — recording anyway (--force)." >&2
         else
             echo "ERROR: no index.yaml found at $url — not adding it." >&2
             echo "  A registry is a git repo with index.yaml at its root, mapping names to sources:" >&2

package/cli/commands/source.sh

@@ -168,7 +168,7 @@ case "$action" in
             echo "added: $dir"
         fi
         if [ ! -d "$IP_ROOT/$dir" ]; then
-            echo "  WARN: $dir does not exist yet — sync skips a missing source and renders it once the directory appears." >&2
+            echo "WARNING: $dir does not exist yet — sync skips a missing source and renders it once the directory appears." >&2
         fi
         print_section "$manifest" "$IP_ROOT" "$section"
         echo "Run 'intelligence sync' to render it."

package/cli/commands/sync.sh

@@ -1,14 +1,27 @@
 #!/bin/bash
-# intelligence sync [target] [--compact] [--force] - render intelligence to enabled tools.
+# intelligence sync [target] [--compact] [--force] [--check] - render intelligence
+# to enabled tools, or report whether rendering would change anything.
 set -euo pipefail
 
+# Only sync_check may request a comparison from the engine.
+unset IS_SYNC_CHECK IS_SYNC_CHECK_ROOT
+
 # Print before library loading and lifecycle checks so a content verification
-# never looks idle. Compact output remains a buffered machine-readable report.
+# never looks idle. Compact output remains a buffered machine-readable report,
+# and a check prints only its verdict.
 compact=0
+check=0
 for argument in "$@"; do
-    [ "$argument" != --compact ] || compact=1
+    case "$argument" in
+        --compact) compact=1 ;;
+        --check) check=1 ;;
+    esac
 done
-[ "$compact" -ne 0 ] || echo 'Checking project...'
+[ "$compact" -ne 0 ] || [ "$check" -ne 0 ] || echo 'Checking project...'
+# The CLI's package descriptor is read in the same pass as the project's
+# manifest and lock, once this command holds the project lock.
+# shellcheck disable=SC2034  # read by cli-common.sh while it loads
+CLI_DEFER_SYNC_PKG=1
 source "$CLI_DIR/lib/cli-common.sh"
 force=0
 target=""
@@ -16,22 +29,35 @@ while [ $# -gt 0 ]; do
     case "$1" in
         --compact) compact=1 ;;
         --force) force=1 ;;
+        --check) check=1 ;;
         -*) die "unknown option '$1'" ;;
         *)
-            [ -z "$target" ] || die "usage: intelligence sync [adapter] [--compact] [--force]"
+            [ -z "$target" ] || die "usage: intelligence sync [adapter] [--compact] [--force] [--check]"
             target="$1"
             ;;
     esac
     shift
 done
 
+# Set where a check concludes that sync is needed, so a failure that happens to
+# end in the same status is never mistaken for that verdict.
+IS_CHECK_OUT_OF_DATE=0
+
+# hold_project — take the project lock, then read the package descriptor,
+# manifest and lock once for the whole preflight.
+hold_project() {
+    project_lock_hold "$IP_ROOT"
+    project_reads_preload "$IP_ROOT"
+    load_sync_package_identity
+}
+
 run_sync() {
     detect_project || return $?
     case "$IP_MODE" in
         cli)
             # One writer per project at a time: the store restore and the
             # render below both rewrite shared state (sync-lock.sh).
-            project_lock_hold "$IP_ROOT"
+            hold_project
             # `sync` is the normal fresh-clone command. A newer globally installed
             # CLI aligns the current Intelligence project first (except in CI, where a
             # tracked migration must be reviewed and committed locally), and a
@@ -42,6 +68,7 @@ run_sync() {
             sync_with_cache "$target" "$force" || return $?
             ;;
         legacy)
+            load_sync_package_identity
             [ "$force" -eq 0 ] || die "--force is unavailable for a legacy Intelligence Sync project - run 'intelligence init' to convert it first"
             [ "$compact" -eq 0 ] || die "--compact is unavailable for a legacy Intelligence Sync project - run 'intelligence init' to convert it first"
             # A vendored project syncs with its own engine: its pin is the
@@ -55,11 +82,56 @@ run_sync() {
             fi
             ;;
         *)
+            load_sync_package_identity
             die "no intelligence project found here - run 'intelligence init'"
             ;;
     esac
 }
 
+# run_check — the same preflight as sync, except that tracked alignment is never
+# applied (it is reported as needed, in CI or not) and everything but the
+# verdict goes to stderr. Restoring the ignored package store from the lock is
+# allowed: it is reproducible state, and the comparison needs it.
+run_check() {
+    local stamp
+    detect_project || return $?
+    case "$IP_MODE" in
+        cli) ;;
+        legacy)
+            load_sync_package_identity
+            die "--check is unavailable for a legacy Intelligence Sync project - run 'intelligence init' to convert it first"
+            ;;
+        *)
+            load_sync_package_identity
+            die "no intelligence project found here - run 'intelligence init'"
+            ;;
+    esac
+    hold_project
+    project_preflight "$IP_ROOT" || return $?
+    if project_needs_upgrade "$IP_ROOT"; then
+        read_schema_version_var "$IP_ROOT/intelligence.yaml"
+        stamp="$IS_SCHEMA_VERSION"
+        bundled_engine_version_var
+        IS_CHECK_OUT_OF_DATE=1
+        is_status out-of-date "the project needs alignment (stamp ${stamp:-unstamped}, engine $IS_BUNDLED_ENGINE_VERSION); run 'intelligence init --apply' locally, review and commit the diff"
+        return "$IS_RC_OUT_OF_DATE"
+    fi
+    restore_project_store_if_missing "$IP_ROOT" keep-sources >&2 || return $?
+    export_engine_env "$IP_ROOT" || return $?
+    sync_check "$target" "$force" || return $?
+}
+
+if [ "$check" -eq 1 ]; then
+    # --compact changes nothing here: the verdict is already one status line,
+    # and a failure's diagnostics already reach stderr.
+    rc=0
+    run_check || rc=$?
+    if [ "$rc" = "$IS_RC_OUT_OF_DATE" ] && [ "$IS_CHECK_OUT_OF_DATE" != 1 ]; then
+        rc=1
+    fi
+    exit "$rc"
+fi
+
 if [ "$compact" -eq 0 ]; then
     run_sync
     exit $?

package/cli/intelligence

@@ -11,7 +11,11 @@ case "$0" in
     */*) CLI_DIR="${0%/*}"; [ -n "$CLI_DIR" ] || CLI_DIR="/" ;;
     *) CLI_DIR="." ;;
 esac
-CLI_DIR="$(cd "$CLI_DIR" && pwd)"
+# An absolute spelling without `.` or `..` segments or doubled slashes is
+# already what `cd && pwd` prints; on Git Bash that subshell costs a fork.
+case "$CLI_DIR" in
+    */|*/./*|*/.|*/../*|*/..|*//*|[!/]*) CLI_DIR="$(cd "$CLI_DIR" && pwd)" ;;
+esac
 export CLI_DIR
 
 # Engine discovery, by role (sync.sh + VERSION). The repo and the npm package
@@ -52,9 +56,10 @@ Usage: intelligence <command> [args]
   init [--preview|--apply]  Initialize, convert, restore or align this project
     --targets a,b --dir name --bare --no-sync   New-project options
     --force               Accept a dirty worktree during legacy project conversion
-  sync [adapter] [--compact] [--force]  Restore locked content, then render enabled adapters
+  sync [adapter] [--compact] [--force] [--check]  Restore locked content, then render enabled adapters
     --compact            On success show context, warnings and final status; on failure show diagnostics
     --force              Render again and refresh discovery of unconfigured source directories
+    --check              Change no generated file; exit 0 when up to date, 2 when sync is needed
   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
@@ -109,4 +114,12 @@ if [ ! -f "$cmd_file" ]; then
     echo "ERROR: unknown command '$cmd'. Run 'intelligence help'." >&2
     exit 1
 fi
+# `sync` runs on every save hook and CI check, so it runs in this process: a
+# second bash start is a large share of an unchanged sync on Git Bash. It
+# exits on every path and reads nothing of this script but the exports.
+if [ "$cmd" = sync ]; then
+    # shellcheck source=commands/sync.sh
+    source "$cmd_file"
+    exit $?
+fi
 exec bash "$cmd_file" "$@"

package/cli/internal/check.sh

@@ -198,6 +198,14 @@ while IFS= read -r target; do
     ok "adapter $target contract v1"
 done < <(target_names "$manifest")
 
+# A local rule, agent or skill is one these patterns name (decision 0021): the
+# engine keeps it out of every committed output, and without the pattern Git
+# would still offer to commit the file itself.
+while IFS= read -r pattern; do
+    ignore_file_has_line "$IP_ROOT/.gitignore" "$pattern" \
+        || warn "local artifact Git policy is missing '$pattern' — run 'intelligence init'"
+done < <(local_artifact_ignore_patterns "$content_dir")
+
 # Lock orphans.
 if [ "$lock_valid" -eq 1 ] && [ -f "$lock" ]; then
     while IFS= read -r name; do
@@ -214,6 +222,7 @@ fi
 # is exactly why doctor names it). Each entry is judged by the directory the
 # engine renders it as, read through the same parser: a package reference by
 # its store path, one that resolves to nothing by why.
+local_specs=()
 for section in rules agents skills; do
     seen=$'\n'
     while IFS=$'\037' read -r src state dir alias holders; do
@@ -269,10 +278,40 @@ for section in rules agents skills; do
                 # authoring later needs no config edit.
                 *) ok "sources.$section '$src' — not created yet (optional)" ;;
             esac
+            continue
         fi
+        # A project-owned source is where a tracked file can carry a local
+        # name; store content is restorable state Git never tracks.
+        case "$dir" in
+            .intelligence/*) ;;
+            *)
+                if [ "$section" = skills ]; then
+                    local_specs+=(":(glob)${dir%/}/*.local/SKILL.md")
+                else
+                    local_specs+=(":(glob)${dir%/}/*.local.md")
+                fi
+                ;;
+        esac
     done < <(read_source_entries "$manifest" "$section")
 done
 
+# A name makes an artifact local (decision 0021), and .gitignore never applies
+# to a file Git already tracks: one committed before its name meant anything,
+# or added by hand, renders only into ignored output while every clone holds
+# it. Git and the engine would disagree about it, so it is named here.
+if [ "${#local_specs[@]}" -gt 0 ] \
+    && git -C "$IP_ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    if tracked_local="$(git -C "$IP_ROOT" -c core.quotePath=false ls-files -- "${local_specs[@]}")"; then
+        while IFS= read -r path; do
+            [ -n "$path" ] || continue
+            case "$path" in */SKILL.md) path="${path%/SKILL.md}/" ;; esac
+            warn "$path is tracked by Git, but its name makes it local: sync renders it only into ignored output — rename it to share it, or 'git rm --cached' it to keep it on this machine"
+        done <<< "$tracked_local"
+    else
+        warn "tracked local artifacts could not be listed — 'git ls-files' failed"
+    fi
+fi
+
 if [ "$problems" -eq 0 ]; then
     echo "all good."
 else

package/cli/internal/convert-legacy.sh

@@ -435,7 +435,7 @@ while IFS="$LOCK_SEP" read -r pack name url ref mirror; do
     # Containment before deletion: a mirror value is config input, and rm -rf
     # must never follow it out of the repository.
     case "$mirror" in
-        ""|/*|*..*) [ -n "$mirror" ] && echo "  WARN: mirror '$mirror' not repo-contained — left in place" >&2; continue ;;
+        ""|/*|*..*) [ -n "$mirror" ] && echo "WARNING: mirror '$mirror' not repo-contained — left in place" >&2; continue ;;
     esac
     if [ -d "$root/$mirror" ]; then
         rm -rf "${root:?}/$mirror"

package/cli/internal/package-search.sh

@@ -63,7 +63,7 @@ if [ -n "$manifest" ]; then
         [ -n "$url" ] || continue
         index="$(_fetch_index "${url#git+}")"
         if [ -z "$index" ]; then
-            echo "  WARN: registry unreachable or missing index.yaml: $url" >&2
+            echo "WARNING: registry unreachable or missing index.yaml: $url" >&2
             continue
         fi
         emit_index "$index" "$url"

package/cli/internal/package-update.sh

@@ -85,7 +85,7 @@ while IFS= read -r name; do
         if [ "$probe_rc" -ne 0 ]; then
             # No answer is not "no change": reporting up to date here would
             # freeze the pin exactly as the ref-name comparison used to.
-            echo "  WARN: $name: cannot reach $url — ref '$ref' was not checked" >&2
+            echo "WARNING: $name: cannot reach $url — ref '$ref' was not checked" >&2
             echo "  $name: $ref (not checked — remote unreachable)"
             continue
         fi
@@ -104,7 +104,7 @@ while IFS= read -r name; do
                     echo "  $name: $(short_sha "$ref") (pinned commit)"
                     ;;
                 *)
-                    echo "  WARN: $name pins ref '$ref', which $url no longer advertises" >&2
+                    echo "WARNING: $name pins ref '$ref', which $url no longer advertises" >&2
                     echo "  $name: $ref (unresolvable — gone upstream)"
                     ;;
             esac

package/cli/internal/restore.sh

@@ -7,12 +7,13 @@
 set -euo pipefail
 source "$CLI_DIR/lib/cli-common.sh"
 
-frozen=0 force=0 no_sync=0
+frozen=0 force=0 no_sync=0 keep_sources=0
 while [ $# -gt 0 ]; do
     case "$1" in
         --frozen) frozen=1 ;;
         --force) force=1 ;;
         --no-sync) no_sync=1 ;;
+        --keep-sources) keep_sources=1 ;;
         *) die "unknown option '$1'" ;;
     esac
     shift || true
@@ -117,7 +118,7 @@ if [ -f "$lock" ]; then
         mkdir -p "$(dirname "$IP_ROOT/$rel")"
         mv "$staging" "$IP_ROOT/$rel"
         store_record_set "$IP_ROOT" "$name" "$url" "$path" "$resolved" "$sha"
-        wire_package_sources "$manifest" "$name" "$rel" "$IP_ROOT"
+        [ "$keep_sources" = 1 ] || wire_package_sources "$manifest" "$name" "$rel" "$IP_ROOT"
         echo "= $name@${resolved:-HEAD}"
     done < <(lock_to_tsv "$lock")
 fi

package/cli/lib/cli-common.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
-# Shared plumbing for every CLI command. Commands are separate processes (the
-# dispatcher execs them), so each one sources this file first.
+# Shared plumbing for every CLI command. Each command is its own script (the
+# dispatcher execs it, or sources `sync`), so each one sources this file first.
 #
 # All YAML reading goes through the engine's lib/common.sh — the CLI never
 # grows a parallel parser for shapes the engine can already read. The only
@@ -99,23 +99,32 @@ source "$CLI_DIR/lib/sync-lock.sh"
 # Its identity is DATA shipped with the distribution (cli/engine-package.yaml),
 # never a name compiled into cli code — a fork edits the file.
 _EPKG="$CLI_DIR/engine-package.yaml"
-SYNC_PKG_NAME="" SYNC_PKG_URL="" SYNC_PKG_PATH=""
+_EPKG_FIELDS='name url path default_registry'
+SYNC_PKG_NAME="" SYNC_PKG_URL="" SYNC_PKG_PATH="" SYNC_PKG_STORE=""
 # Read by commands (init seeds it) — per-file shellcheck cannot see that.
 # shellcheck disable=SC2034
 DEFAULT_REGISTRY_URL=""
-# Every command loads this file first: read the four fields in one pass.
+
+# load_sync_package_identity — read the four fields in one pass. Every command
+# loads this file first and gets them at once; `sync` sets CLI_DEFER_SYNC_PKG
+# before sourcing and reads them in the same awk pass as the project's manifest
+# and lock (project_reads_preload), once it holds the project lock.
 # shellcheck disable=SC2034  # DEFAULT_REGISTRY_URL is read by commands, as above
-while IFS="$LOCK_SEP" read -r _epkg_key _epkg_value; do
-    case "$_epkg_key" in
-        name) SYNC_PKG_NAME="$_epkg_value" ;;
-        url) SYNC_PKG_URL="$_epkg_value" ;;
-        path) SYNC_PKG_PATH="$_epkg_value" ;;
-        default_registry) DEFAULT_REGISTRY_URL="$_epkg_value" ;;
-    esac
-done <<< "$(_qmap_read tops "$_EPKG" '' 'name url path default_registry')"
-unset _epkg_key _epkg_value
-[ -n "$SYNC_PKG_NAME" ] || die "corrupt CLI installation: $_EPKG is missing or has no 'name'"
-SYNC_PKG_STORE=".intelligence/packages/$SYNC_PKG_NAME"
+load_sync_package_identity() {
+    local key value
+    _qmap_read_var tops "$_EPKG" '' "$_EPKG_FIELDS" || true
+    while IFS="$LOCK_SEP" read -r key value; do
+        case "$key" in
+            name) SYNC_PKG_NAME="$value" ;;
+            url) SYNC_PKG_URL="$value" ;;
+            path) SYNC_PKG_PATH="$value" ;;
+            default_registry) DEFAULT_REGISTRY_URL="$value" ;;
+        esac
+    done <<< "$IS_QMAP_OUT"
+    [ -n "$SYNC_PKG_NAME" ] || die "corrupt CLI installation: $_EPKG is missing or has no 'name'"
+    SYNC_PKG_STORE=".intelligence/packages/$SYNC_PKG_NAME"
+}
+[ "${CLI_DEFER_SYNC_PKG:-0}" = 1 ] || load_sync_package_identity
 
 # --- Project detection ---------------------------------------------------
 # Sets: IP_MODE (cli|legacy|none), IP_ROOT, IP_UMBRELLA, IP_MODULE_DIR.
@@ -257,9 +266,14 @@ source_entry_problem() {
 }
 
 manifest_intelligence_dir() {
-    local manifest="$1" v
-    v="$(get_yaml_field "$manifest" "project" "intelligence_dir")"
-    printf '%s' "${v:-intelligence}"
+    manifest_intelligence_dir_var "$1"
+    printf '%s' "$IS_CONTENT_DIR"
+}
+
+# manifest_intelligence_dir_var <manifest> — the same answer in IS_CONTENT_DIR.
+manifest_intelligence_dir_var() {
+    get_yaml_field_var "$1" "project" "intelligence_dir"
+    IS_CONTENT_DIR="${IS_YAML_FIELD:-intelligence}"
 }
 
 default_target_output() {
@@ -317,7 +331,8 @@ sync_pkg_install() {
 export_engine_env() {
     local root="$1"
     local content_rel
-    content_rel="$(manifest_intelligence_dir "$root/intelligence.yaml")"
+    manifest_intelligence_dir_var "$root/intelligence.yaml"
+    content_rel="$IS_CONTENT_DIR"
     export IS_CLI=1
     export CONFIG_FILE="$root/intelligence.yaml"
     export REPO_ROOT="$root"
@@ -382,6 +397,7 @@ project_stamped_ahead() {
 
 project_needs_upgrade() {
     local root="$1" manifest="$1/intelligence.yaml" stamp eng pinned locked name url path rows
+    local lname _requested _url _path resolved _sha
     [ -f "$manifest" ] || return 1
     read_schema_version_var "$manifest"
     stamp="$IS_SCHEMA_VERSION"
@@ -392,12 +408,14 @@ project_needs_upgrade() {
     # restamp the schema and re-pin the engine content DOWNWARD, and the next
     # teammate on the current CLI would move both back: leave it as found.
     project_stamped_ahead "$root" && return 1
-    [ -n "$(top_scalar "$manifest" "sync_version")" ] && return 0
+    _qmap_read_var top "$manifest" '' sync_version || true
+    [ -z "$IS_QMAP_OUT" ] || return 0
     _ver_gt "$eng" "$stamp" && return 0
     [ -d "$root/.intelligence/engine" ] && return 0
 
     # One manifest pass for every package's fields, not a reader per field.
-    rows="$(_qmap_read fieldrows "$manifest" packages '' 'url path version')"
+    _qmap_read_var fieldrows "$manifest" packages '' 'url path version' || true
+    rows="$IS_QMAP_OUT"
     while IFS="$LOCK_SEP" read -r name url path pinned; do
         [ -n "$name" ] || continue
         # Early RC manifests mixed requested intent with resolved source
@@ -405,7 +423,14 @@ project_needs_upgrade() {
         [ -n "$url" ] && return 0
         [ -n "$path" ] && return 0
         if [ "$name" = "$SYNC_PKG_NAME" ]; then
-            locked="$(qmap_field "$root/intelligence.lock" "packages" "$name" "resolved")"
+            # The first lock row for the name: what qmap_field would decode.
+            locked=""
+            _qmap_read_var rows "$root/intelligence.lock" packages || true
+            while IFS="$LOCK_SEP" read -r lname _requested _url _path resolved _sha; do
+                [ "$lname" = "$name" ] || continue
+                locked="$resolved"
+                break
+            done <<< "$IS_QMAP_OUT"
             [ "$pinned" = "$eng" ] || return 0
             if [ -f "$root/intelligence.lock" ]; then
                 [ -n "$locked" ] || return 0
@@ -420,21 +445,30 @@ project_needs_upgrade() {
 # which lifecycle alignment can proceed. Never manufacture a partial lock.
 project_has_packages() {
     local root="$1" name found=1
+    _qmap_read_var keys "$root/intelligence.yaml" "packages" || true
     while IFS= read -r name; do
         [ -n "$name" ] || continue
         assert_valid_pkg_name "$name"
         found=0
-    done < <(qmap_keys "$root/intelligence.yaml" "packages")
+    done <<< "$IS_QMAP_OUT"
     return "$found"
 }
 
-ensure_project_current() {
-    local root="$1" explicit="${2:-}" manifest="$1/intelligence.yaml" stamp eng
-    check_version_compat "$manifest" || return $?
+# project_preflight <root> — what every project-aware command checks before it
+# may align or write: schema compatibility (a newer major refuses with 4), a
+# valid lock, and a lock for whatever packages the manifest declares.
+project_preflight() {
+    local root="$1"
+    check_version_compat "$root/intelligence.yaml" || return $?
     validate_project_lock "$root" || return $?
     if project_has_packages "$root" && [ ! -f "$root/intelligence.lock" ]; then
         die "manifest declares packages but intelligence.lock is absent — restore the committed lock before running project lifecycle commands"
     fi
+}
+
+ensure_project_current() {
+    local root="$1" explicit="${2:-}" manifest="$1/intelligence.yaml" stamp eng
+    project_preflight "$root" || return $?
     project_needs_upgrade "$root" || return 0
     read_schema_version_var "$manifest"
     stamp="$IS_SCHEMA_VERSION"
@@ -444,7 +478,8 @@ ensure_project_current() {
         die "project lifecycle requires alignment (stamp ${stamp:-unstamped}, engine $eng) — run 'intelligence init --apply' locally, review and commit the diff"
     fi
     echo "  project alignment: stamp ${stamp:-unstamped}, engine $eng"
-    bash "$CLI_DIR/internal/align-project.sh" --no-sync
+    bash "$CLI_DIR/internal/align-project.sh" --no-sync || return $?
+    project_reads_refresh "$root"
 }
 
 # A present lock is validated even when there is no missing store to restore.
@@ -452,7 +487,8 @@ ensure_project_current() {
 validate_project_lock() {
     local lock="$1/intelligence.lock" output line rc=0
     if [ -e "$lock" ] || [ -L "$lock" ]; then
-        output="$(lock_validate "$lock" "${2---metadata}" "$1/intelligence.yaml" 2>&1)" || rc=$?
+        # The capture is the subshell that contains the guards' `die`.
+        output="$(lock_validate_checks "$lock" "${2---metadata}" "$1/intelligence.yaml" 2>&1)" || rc=$?
         while IFS= read -r line; do
             [ -n "$line" ] || continue
             case "$line" in
@@ -472,6 +508,74 @@ validate_project_lock() {
     fi
 }
 
+# --- Reads shared by one command's preflight -----------------------------
+# A sync reads the CLI's package descriptor, the manifest and the lock several
+# times on its way to the engine. Once it holds the project lock it answers all
+# of those reads with one qmap pass and one pass of the engine's manifest
+# readers; a child that may rewrite either document (alignment, restore) is
+# followed by project_reads_refresh. Without a preload every reader takes its
+# ordinary path.
+IS_PROJECT_READS_ROOT=""
+
+project_reads_preload() {
+    local root="$1" manifest="$1/intelligence.yaml" lock="$1/intelligence.lock" s=$'\037'
+    local qmap=0 view=0 out qmap_pid="" view_pid=""
+    local -a view_args=("$manifest" project intelligence_dir rules agents skills)
+    project_reads_reset
+    qmap_preload_plan \
+        "tops$s$_EPKG$s$s$_EPKG_FIELDS$s$s" \
+        "keys$s$manifest${s}packages$s$s$s" \
+        "fieldrows$s$manifest${s}packages$s${s}url path version$s" \
+        "top$s$manifest$s${s}sync_version$s$s" \
+        "lock$s$lock${s}packages$s$s$s$LOCKFILE_VERSION" \
+        "rows$s$lock${s}packages$s$s$s" && qmap=1
+    [ ! -f "$manifest" ] || [ ! -r "$manifest" ] || view=1
+    if project_lock_scratch "$root"; then
+        # Both passes at once: starting their processes is most of their cost.
+        if [ "$qmap" = 1 ]; then
+            qmap_preload_run > "$IS_LOCK_SCRATCH.qmap" &
+            qmap_pid=$!
+        fi
+        if [ "$view" = 1 ]; then
+            manifest_view_run "${view_args[@]}" > "$IS_LOCK_SCRATCH.view" &
+            view_pid=$!
+        fi
+        if [ "$qmap" = 1 ] && wait "$qmap_pid"; then
+            qmap_preload_store "$(< "$IS_LOCK_SCRATCH.qmap")"
+        fi
+        if [ "$view" = 1 ]; then
+            if wait "$view_pid"; then
+                manifest_view_store "$(< "$IS_LOCK_SCRATCH.view")" "${view_args[@]}"
+            else
+                manifest_view_reset
+            fi
+        fi
+    else
+        if [ "$qmap" = 1 ] && out="$(qmap_preload_run)"; then
+            qmap_preload_store "$out"
+        fi
+        [ "$view" = 0 ] || load_manifest_view "${view_args[@]}" || manifest_view_reset
+    fi
+    IS_PROJECT_READS_ROOT="$root"
+}
+
+project_reads_reset() {
+    qmap_memo_reset
+    manifest_view_reset
+    IS_PROJECT_READS_ROOT=""
+}
+
+# project_reads_refresh <root> — after a child may have rewritten the manifest
+# or the lock: read them again if this process preloaded them.
+project_reads_refresh() {
+    [ "$IS_PROJECT_READS_ROOT" = "$1" ] || return 0
+    project_reads_preload "$1"
+}
+
+# CLI and engine share one list-cache format. Writers invalidate both the
+# qmap answers and the engine view through qmap_memo_reset.
+_yaml_list_var() { load_yaml_list "$1" "$2"; }
+
 # Read-only diagnosis must distinguish usable installed metadata from metadata
 # which could actually restore a missing store.
 check_project_lock() {
@@ -540,28 +644,31 @@ _store_record_write() {
 # project_store_missing <root> — a package the manifest or lock names is absent
 # from the store, or holds something other than its lock row pins.
 project_store_missing() {
-    local root="$1" manifest="$1/intelligence.yaml" name src
+    local root="$1" manifest="$1/intelligence.yaml" name src section
+    _qmap_read_var keys "$manifest" "packages" || true
     while IFS= read -r name; do
         [ -n "$name" ] || continue
         assert_valid_pkg_name "$name"
         [ -d "$root/.intelligence/packages/$name" ] || return 0
-    done < <(qmap_keys "$manifest" "packages")
+    done <<< "$IS_QMAP_OUT"
     # The parser hands a package reference over as the store directory it
     # names, so every spelling is checked here as that directory.
     for section in rules agents skills; do
+        _yaml_list_var "$manifest" "$section"
         while IFS= read -r src; do
             case "$src" in
                 .intelligence/packages/*)
                     [ -d "$root/$src" ] || return 0
                     ;;
             esac
-        done < <(read_yaml_list "$manifest" "$section")
+        done <<< "$IS_YAML_LIST"
     done
     # Present is not enough: a `git pull` moves the lock and leaves the ignored
     # store on the commit it held before.
     local rows _requested url path resolved sha
     [ -f "$root/intelligence.lock" ] || return 1
-    rows="$(lock_to_tsv "$root/intelligence.lock")"
+    _qmap_read_var rows "$root/intelligence.lock" packages || true
+    rows="$IS_QMAP_OUT"
     while IFS="$LOCK_SEP" read -r name _requested url path resolved sha; do
         [ -n "$name" ] || continue
         assert_valid_pkg_name "$name"
@@ -576,5 +683,10 @@ restore_project_store_if_missing() {
     project_store_missing "$root" || return 0
     [ -f "$root/intelligence.lock" ] || die "package store is missing and intelligence.lock is absent — run 'intelligence init'"
     echo "  restoring package store from intelligence.lock"
-    bash "$CLI_DIR/internal/restore.sh" --frozen --no-sync
+    if [ "${2:-}" = keep-sources ]; then
+        bash "$CLI_DIR/internal/restore.sh" --frozen --no-sync --keep-sources || return $?
+    else
+        bash "$CLI_DIR/internal/restore.sh" --frozen --no-sync || return $?
+    fi
+    project_reads_refresh "$root"
 }