@ainova-systems/intelligence 0.11.0-rc.1 → 0.11.0-rc.10

package/cli/internal/package-update.sh

@@ -0,0 +1,103 @@
+#!/bin/bash
+# Internal package range update operation.
+#
+# Resolve requested versions/refs against each package's locked source and
+# rewrite the lock. `update <name>` limits the pass to one package; re-adding
+# is the explicit operation for changing a source URL/path.
+set -euo pipefail
+source "$CLI_DIR/lib/cli-common.sh"
+
+only="" no_sync=0 preview=0
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --no-sync) no_sync=1 ;;
+        --preview) preview=1 ;;
+        @*) only="$1" ;;
+        *) die "unknown argument '$1'" ;;
+    esac
+    shift || true
+done
+
+require_cli_project
+manifest="$IP_ROOT/intelligence.yaml"
+lock="$IP_ROOT/intelligence.lock"
+
+moved=0 found=0
+while IFS= read -r name; do
+    [ -n "$name" ] || continue
+    # Manifest keys are untrusted input on their way into store paths.
+    assert_valid_pkg_name "$name"
+    [ -n "$only" ] && [ "$name" != "$only" ] && continue
+    # A named package that exists is "found" whatever happens next — a skip
+    # message followed by "not in the manifest" would contradict itself.
+    found=1
+    if [ "$name" = "$SYNC_PKG_NAME" ]; then
+        echo "  $name: engine content follows the installed CLI — skipped"
+        continue
+    fi
+    current="$(qmap_field "$lock" "packages" "$name" "resolved")"
+    locked_requested="$(qmap_field "$lock" "packages" "$name" "requested")"
+    url="$(qmap_field "$lock" "packages" "$name" "url")"
+    path="$(qmap_field "$lock" "packages" "$name" "path")"
+    [ -n "$url" ] || die "$name has no source in intelligence.lock — restore the committed lock or re-add the package"
+    ref="$(qmap_field "$manifest" "packages" "$name" "ref")"
+    range="$(qmap_field "$manifest" "packages" "$name" "version")"
+    [ -n "$ref" ] || [ -n "$range" ] || die "$name has neither version nor ref in the manifest"
+
+    if [ -n "$ref" ]; then
+        tag="$ref"
+        requested=""
+    else
+        picked="$(list_remote_versions "$url" | 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"
+    fi
+    if [ "$tag" = "$current" ] && [ "$requested" != "$locked_requested" ]; then
+        if [ "$preview" -eq 1 ]; then
+            echo "  $name: request ${locked_requested:-<none>} -> ${requested:-<ref>} (keeps $current)"
+        else
+            locked_sha="$(qmap_field "$lock" "packages" "$name" "sha")"
+            lock_upsert "$lock" "$name" "$requested" "$url" "$path" "$current" "$locked_sha"
+            echo "  $name: request ${locked_requested:-<none>} -> ${requested:-<ref>} (kept $current)"
+        fi
+        moved=$((moved + 1))
+        continue
+    fi
+    if [ "$tag" = "$current" ]; then
+        echo "  $name: ${current:-<none>} (up to date)"
+        continue
+    fi
+    if [ "$preview" -eq 1 ]; then
+        echo "  $name: ${current:-<none>} -> $tag"
+        moved=$((moved + 1))
+        continue
+    fi
+    rel=".intelligence/packages/$name"
+    # Fetch into staging FIRST: a failed clone must leave the current install
+    # fully wired and intact. Only after success is the old shape unwired
+    # (the new version may have dropped a section dir), the store swapped,
+    # and the new shape wired.
+    staging="$IP_ROOT/.intelligence/.staging-$$"
+    rm -rf "$staging"
+    sha="$(fetch_package "$url" "$tag" "$path" "$staging")"
+    unwire_package_sources "$manifest" "$rel"
+    rm -rf "${IP_ROOT:?}/$rel"
+    mkdir -p "$(dirname "$IP_ROOT/$rel")"
+    mv "$staging" "$IP_ROOT/$rel"
+    wire_package_sources "$manifest" "$name" "$rel" "$IP_ROOT"
+    lock_upsert "$lock" "$name" "$requested" "$url" "$path" "$tag" "$sha"
+    echo "  $name: ${current:-<none>} -> $tag"
+    moved=$((moved + 1))
+done < <(qmap_keys "$manifest" "packages")
+
+[ -n "$only" ] && [ "$found" -eq 0 ] && die "package '$only' is not in the manifest"
+if [ "$preview" -eq 1 ]; then
+    echo "updates available: $moved package(s)"
+else
+    echo "updated: $moved package(s)"
+fi
+
+if [ "$preview" -eq 0 ] && [ "$moved" -gt 0 ] && [ "$no_sync" -eq 0 ]; then
+    exec bash "$CLI_DIR/commands/sync.sh"
+fi

package/cli/internal/restore.sh

@@ -0,0 +1,130 @@
+#!/bin/bash
+# Internal locked-store restore operation.
+#
+# Restore .intelligence/ from intelligence.lock — the fresh-clone command.
+# --frozen additionally refuses any manifest/lock divergence (CI mode) and
+# fails on a sha mismatch instead of re-resolving.
+set -euo pipefail
+source "$CLI_DIR/lib/cli-common.sh"
+
+frozen=0 force=0 no_sync=0
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --frozen) frozen=1 ;;
+        --force) force=1 ;;
+        --no-sync) no_sync=1 ;;
+        *) die "unknown option '$1'" ;;
+    esac
+    shift || true
+done
+
+require_cli_project
+manifest="$IP_ROOT/intelligence.yaml"
+lock="$IP_ROOT/intelligence.lock"
+
+# --frozen is the reproducibility contract: the lock must agree with the
+# manifest on the package SET and on every requested-intent field before a
+# single byte is restored. Anything less lets a manifest edit ride on a stale
+# lock — the exact drift the flag exists to refuse.
+if [ "$frozen" -eq 1 ]; then
+    while IFS= read -r name; do
+        [ -n "$name" ] || continue
+        [ -n "$(qmap_field "$lock" "packages" "$name" "url")" ] \
+            || die "locked restore: $name is in the manifest but not in intelligence.lock"
+        m_ver="$(qmap_field "$manifest" "packages" "$name" "version")"
+        m_ref="$(qmap_field "$manifest" "packages" "$name" "ref")"
+        l_req="$(qmap_field "$lock" "packages" "$name" "requested")"
+        l_res="$(qmap_field "$lock" "packages" "$name" "resolved")"
+        [ -z "$m_ver" ] || [ "$m_ver" = "$l_req" ] \
+            || die "locked restore: $name requests '$m_ver' but the lock recorded '$l_req' — reconcile the manifest and lock"
+        [ -z "$m_ref" ] || [ "$m_ref" = "$l_res" ] \
+            || die "--frozen: $name pins ref '$m_ref' but the lock resolved '$l_res'"
+    done < <(qmap_keys "$manifest" "packages")
+    while IFS= read -r name; do
+        [ -n "$name" ] || continue
+        found=0
+        while IFS= read -r m; do
+            [ "$m" = "$name" ] && found=1
+        done < <(qmap_keys "$manifest" "packages")
+        [ "$found" -eq 1 ] || die "--frozen: $name is locked but absent from the manifest"
+    done < <(qmap_keys "$lock" "packages")
+fi
+
+# Manifest packages missing from the lock: resolve them now (npm install
+# semantics). Under --frozen the drift gate above has already refused.
+missing=""
+while IFS= read -r name; do
+    [ -n "$name" ] || continue
+    assert_valid_pkg_name "$name"
+    if [ ! -f "$lock" ] || [ -z "$(qmap_field "$lock" "packages" "$name" "url")" ]; then
+        missing="$missing $name"
+    fi
+done < <(qmap_keys "$manifest" "packages")
+if [ -n "$missing" ]; then
+    for name in $missing; do
+        # The engine-content package needs no remote resolution: its pin IS
+        # the bundled engine version and it seeds from the bundle, offline.
+        if [ "$name" = "$SYNC_PKG_NAME" ]; then
+            sync_pkg_install "$IP_ROOT"
+            continue
+        fi
+        ref="$(qmap_field "$manifest" "packages" "$name" "ref")"
+        range="$(qmap_field "$manifest" "packages" "$name" "version")"
+        resolve_package_source "$manifest" "$name"
+        url="$RES_URL"; path="$RES_PATH"
+        [ -n "$url" ] || die "no trusted registry declares '$name' and it is absent from intelligence.lock"
+        resolved_tag=""
+        if [ -z "$ref" ]; then
+            picked="$(list_remote_versions "$url" | semver_pick_highest "$range")"
+            [ -n "$picked" ] || die "no tag of $url satisfies '${range:-*}' for $name"
+            read -r resolved_tag _ <<< "$(remote_tag_for_version "$url" "$picked")"
+        fi
+        rel=".intelligence/packages/$name"
+        sha="$(fetch_package "$url" "${ref:-$resolved_tag}" "$path" "$IP_ROOT/$rel")"
+        wire_package_sources "$manifest" "$name" "$rel" "$IP_ROOT"
+        lock_upsert "$lock" "$name" "$range" "$url" "$path" "${ref:-$resolved_tag}" "$sha"
+        echo "+ $name@${resolved_tag:-${ref:-HEAD}} (resolved)"
+    done
+fi
+
+# Restore every locked package that is not already in the store.
+if [ -f "$lock" ]; then
+    while IFS="$LOCK_SEP" read -r name requested url path resolved sha; do
+        [ -n "$name" ] || continue
+        # The lock arrives with a cloned repo — its keys are untrusted input
+        # on their way into rm -rf paths, and its urls into git argv.
+        assert_valid_pkg_name "$name"
+        rel=".intelligence/packages/$name"
+        # --frozen never trusts what is already on disk: a pre-existing
+        # (possibly substituted) store dir would otherwise be synced with no
+        # sha verification at all.
+        if [ -d "$IP_ROOT/$rel" ] && [ "$force" -eq 0 ] && [ "$frozen" -eq 0 ]; then
+            continue
+        fi
+        # Fetch into staging and commit to the store only after the integrity
+        # verdict: content that violates the lock must never be left where a
+        # re-run (whose dir-exists check skips verification) would sync it.
+        staging="$IP_ROOT/.intelligence/.staging-$$"
+        rm -rf "$staging"
+        got="$(fetch_package "$url" "$resolved" "$path" "$staging")"
+        # An empty sha (bundle-seeded content on a dev build) means unknown,
+        # not moved — only two known-and-different shas are a finding.
+        if [ -n "$sha" ] && [ -n "$got" ] && [ "$got" != "$sha" ]; then
+            if [ "$frozen" -eq 1 ]; then
+                rm -rf "$staging"
+                die "$name: fetched $got but the lock pins $sha — the ref moved; refusing under --frozen"
+            fi
+            echo "  WARN: $name resolved to $got, lock had $sha — updating the lock" >&2
+            lock_upsert "$lock" "$name" "$requested" "$url" "$path" "$resolved" "$got"
+        fi
+        rm -rf "${IP_ROOT:?}/$rel"
+        mkdir -p "$(dirname "$IP_ROOT/$rel")"
+        mv "$staging" "$IP_ROOT/$rel"
+        wire_package_sources "$manifest" "$name" "$rel" "$IP_ROOT"
+        echo "= $name@${resolved:-HEAD}"
+    done < <(lock_to_tsv "$lock")
+fi
+
+if [ "$no_sync" -eq 0 ]; then
+    exec bash "$CLI_DIR/commands/sync.sh"
+fi

package/cli/internal/target-state.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# Internal adapter target-state operation.
+#
+# Change only the manifest. Syncing and deleting generated output are separate
+# explicit actions: a generic target command cannot infer a custom adapter's
+# ownership safely.
+set -euo pipefail
+source "$CLI_DIR/lib/cli-common.sh"
+
+action="${1:-}"
+name="${2:-}"
+[ $# -le 2 ] || die "internal target state: expected <enable|disable> <name>"
+case "$action" in enable|disable) ;; *) die "internal target state: expected <enable|disable> <name>" ;; esac
+[ -n "$name" ] || die "internal target state: missing adapter name"
+assert_valid_target_name "$name"
+
+require_cli_project
+manifest="$IP_ROOT/intelligence.yaml"
+content_dir="$(manifest_intelligence_dir "$manifest")"
+
+if [ "$action" = "enable" ]; then
+    project_adapter="$IP_ROOT/$content_dir/adapters/$name.sh"
+    bundled_adapter="$IS_ENGINE_DIR/adapters/$name.sh"
+    if [ ! -f "$project_adapter" ] && [ ! -f "$bundled_adapter" ]; then
+        die "adapter '$name' not found — create it first: intelligence adapter create $name"
+    fi
+
+    # These adapters intentionally omit always-on rules because their tools
+    # read AGENTS.md. Do not create a manifest that full sync must refuse.
+    case "$name" in
+        cursor|copilot|codex|pi|opencode)
+            if [ "$(is_target_enabled "$manifest" "agents")" != "1" ]; then
+                die "target '$name' requires target 'agents' — enable it first"
+            fi
+            ;;
+    esac
+
+    output="$(get_target_output "$manifest" "$name")"
+    [ -n "$output" ] || output="$(default_target_output "$name")"
+    target_set_enabled "$manifest" "$name" true "$output"
+    echo "enabled: $name (output: $output)"
+    exit 0
+fi
+
+target_exists "$manifest" "$name" || die "target '$name' is not in the manifest"
+if [ "$name" = "agents" ]; then
+    for dependent in cursor copilot codex pi opencode; do
+        if [ "$(is_target_enabled "$manifest" "$dependent")" = "1" ]; then
+            die "target 'agents' is required by enabled target '$dependent' — disable '$dependent' first"
+        fi
+    done
+fi
+output="$(get_target_output "$manifest" "$name")"
+[ -n "$output" ] || output="$(default_target_output "$name")"
+target_set_enabled "$manifest" "$name" false "$output"
+echo "disabled: $name"
+echo "  generated output was kept; remove only paths owned by this adapter"

package/cli/lib/cli-common.sh

@@ -7,34 +7,74 @@
 # CLI-owned parsing lives in lib/manifest.sh (quoted-key `packages:` /
 # `registries:` blocks, which the engine deliberately never reads).
 
-# Engine libraries (readers, is_status, IS_RC_*, engine_version). Sourced in
-# the same order sync.sh uses. CLI_DIR / IS_ENGINE_DIR come exported from the
-# dispatcher.
-source "$IS_ENGINE_DIR/scripts/lib/common.sh"
-source "$IS_ENGINE_DIR/scripts/lib/layout.sh"
-source "$IS_ENGINE_DIR/scripts/lib/migrations.sh"
+# Engine libraries (readers, is_status, IS_RC_*, engine_version). CLI_DIR /
+# IS_ENGINE_DIR come exported from the dispatcher.
+source "$IS_ENGINE_DIR/lib/common.sh"
+source "$IS_ENGINE_DIR/lib/contract.sh"
 
 die() {
     echo "ERROR: $*" >&2
     exit 1
 }
 
+# --- Untrusted-input guards ----------------------------------------------
+# Manifest, lock and registry indexes arrive with a cloned repo: every value
+# they carry is attacker-adjacent. URLs and refs reach git argv (a leading
+# `-` would be an option — `--upload-pack=<cmd>` is code execution), names
+# become store paths fed to rm -rf. Guard at the choke points, loudly.
+
+# assert_safe_source_url <url> — scheme allowlist (the engine's own list) or
+# scp-like user@host:path; never option-shaped, never quote-bearing.
+assert_safe_source_url() {
+    local url="$1"
+    case "$url" in
+        ""|-*) die "unsafe source url '$url' — option-shaped or empty" ;;
+        *[\"\'\ ]*) die "unsafe source url '$url' — quotes or spaces" ;;
+        https://*|http://*|ssh://*|git://*|file://*) ;;
+        *@*:*) ;;
+        *) die "unsafe source url '$url' — allowed: https, http, ssh, git, file, or user@host:path" ;;
+    esac
+}
+
+# assert_safe_ref <ref-or-empty> — tags/branches/SHAs; never option-shaped.
+assert_safe_ref() {
+    local ref="$1"
+    [ -z "$ref" ] && return 0
+    case "$ref" in
+        -*) die "unsafe git ref '$ref' — option-shaped" ;;
+        *[\"\'\ \\]*) die "unsafe git ref '$ref'" ;;
+    esac
+}
+
 source "$CLI_DIR/lib/manifest.sh"
 source "$CLI_DIR/lib/semver.sh"
 source "$CLI_DIR/lib/registry.sh"
 source "$CLI_DIR/lib/lockfile.sh"
 
-# Meta-skills that the CLI replaces with first-class commands — staging skips
-# them so a v2 project never carries a skill telling the agent to run a flow
-# the CLI already owns.
-CLI_OBSOLETE_SKILLS="intelligence-update intelligence-sync"
+# The engine-content package: OPTIONAL but auto-selected at init. Package by
+# UX (manifest entry, lockfile row, list/search/remove), bundle by mechanics —
+# at the version the CLI ships, it materializes from the npm bundle without
+# network; only a cross-version acquisition reaches git. The pin is held
+# exactly at the bundled engine version and moved by lifecycle alignment.
+#
+# 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="$(top_scalar "$_EPKG" "name")"
+SYNC_PKG_URL="$(top_scalar "$_EPKG" "url")"
+SYNC_PKG_PATH="$(top_scalar "$_EPKG" "path")"
+# Read by commands (init seeds it) — per-file shellcheck cannot see that.
+# shellcheck disable=SC2034
+DEFAULT_REGISTRY_URL="$(top_scalar "$_EPKG" "default_registry")"
+[ -n "$SYNC_PKG_NAME" ] || die "corrupt CLI installation: $_EPKG is missing or has no 'name'"
+SYNC_PKG_STORE=".intelligence/packages/$SYNC_PKG_NAME"
 
 # --- Project detection ---------------------------------------------------
-# Sets: IP_MODE (v2|legacy|none), IP_ROOT, IP_UMBRELLA, IP_MODULE_DIR.
+# Sets: IP_MODE (cli|legacy|none), IP_ROOT, IP_UMBRELLA, IP_MODULE_DIR.
 # These ARE this lib's public API — every command reads them after calling
 # detect_project, which per-file shellcheck cannot see.
 # shellcheck disable=SC2034
-# v2 wins: the nearest ancestor holding intelligence.yaml. Legacy is a git
+# The CLI product wins: the nearest ancestor holding intelligence.yaml. Legacy is a git
 # repo holding an umbrella (a dir with config.yaml) whose module is identified
 # by role — scripts/sync.sh + scripts/VERSION — never by name.
 detect_project() {
@@ -42,7 +82,7 @@ detect_project() {
     local dir="$PWD"
     while :; do
         if [ -f "$dir/intelligence.yaml" ]; then
-            IP_MODE="v2"
+            IP_MODE="cli"
             IP_ROOT="$(cd "$dir" && pwd)"
             return 0
         fi
@@ -69,11 +109,11 @@ detect_project() {
     return 0
 }
 
-require_v2() {
+require_cli_project() {
     detect_project
     case "$IP_MODE" in
-        v2) ;;
-        legacy) die "this is a vendored (v1) setup — run 'intelligence migrate' first, or keep using its own flow" ;;
+        cli) ;;
+        legacy) die "this is a legacy Intelligence Sync project — run 'intelligence init' to convert it, or keep using its own flow" ;;
         *) die "no intelligence project found here — run 'intelligence init'" ;;
     esac
 }
@@ -86,64 +126,174 @@ manifest_intelligence_dir() {
     printf '%s' "${v:-intelligence}"
 }
 
+default_target_output() {
+    case "$1" in
+        agents) printf '%s' "AGENTS.md" ;;
+        copilot) printf '%s' ".github" ;;
+        *) printf '.%s' "$1" ;;
+    esac
+}
+
 bundled_engine_version() {
-    tr -d ' \t\r\n' < "$IS_ENGINE_DIR/scripts/VERSION"
-}
-
-# --- Engine content staging ----------------------------------------------
-# The v2 project vendors no engine code; the engine's own rules / agents /
-# meta-skills / docs are staged into the package store so sources can reach
-# them as ordinary repo-relative dirs. Re-staged whenever the bundled engine
-# version differs from the `.version` stamp.
-# stage_engine_content <dest-dir> — unconditional copy of the engine's own
-# content into <dest-dir> plus the `.version` stamp.
-stage_engine_content() {
-    local store="$1"
-    rm -rf "$store"
-    mkdir -p "$store"
-    local d s name skip
-    for d in rules agents docs; do
-        [ -d "$IS_ENGINE_DIR/$d" ] && cp -R "$IS_ENGINE_DIR/$d" "$store/$d"
-    done
-    if [ -d "$IS_ENGINE_DIR/skills" ]; then
-        mkdir -p "$store/skills"
-        for s in "$IS_ENGINE_DIR"/skills/*/; do
-            [ -d "$s" ] || continue
-            name="$(basename "$s")"
-            skip=0
-            for d in $CLI_OBSOLETE_SKILLS; do
-                [ "$name" = "$d" ] && skip=1
-            done
-            [ "$skip" = "1" ] && continue
-            cp -R "$s" "$store/skills/$name"
-        done
-    fi
-    bundled_engine_version > "$store/.version"
+    tr -d ' \t\r\n' < "$IS_ENGINE_DIR/VERSION"
 }
 
-ensure_engine_staged() {
-    local root="$1"
-    local store="$root/.intelligence/engine"
-    local bundled_ver staged_ver
-    bundled_ver="$(bundled_engine_version)"
-    staged_ver=""
-    [ -f "$store/.version" ] && staged_ver="$(tr -d ' \t\r\n' < "$store/.version")"
-    [ "$staged_ver" = "$bundled_ver" ] && return 0
-    stage_engine_content "$store"
-    echo "  engine content staged: .intelligence/engine ($bundled_ver)"
+# --- The sync package's manifest/lock plumbing ---------------------------
+# sync_pkg_entry <manifest> — write/refresh only the requested exact pin.
+# The built-in source lives in engine-package.yaml and resolved source state
+# belongs exclusively to intelligence.lock.
+sync_pkg_entry() {
+    local manifest="$1"
+    qmap_set "$manifest" "packages" "$SYNC_PKG_NAME" "version" "$(bundled_engine_version)"
+}
+
+# sync_pkg_install <root> — materialize the package into the store and lock
+# it (offline at the bundled version — fetch_package's bundle-seed guard).
+sync_pkg_install() {
+    local root="$1" ver sha
+    ver="$(bundled_engine_version)"
+    sha="$(fetch_package "$SYNC_PKG_URL" "v$ver" "$SYNC_PKG_PATH" "$root/$SYNC_PKG_STORE")"
+    wire_package_sources "$root/intelligence.yaml" "$SYNC_PKG_NAME" "$SYNC_PKG_STORE" "$root"
+    lock_upsert "$root/intelligence.lock" "$SYNC_PKG_NAME" "$ver" "$SYNC_PKG_URL" "$SYNC_PKG_PATH" "v$ver" "$sha"
+    echo "  engine content installed: $SYNC_PKG_STORE (v$ver)"
 }
 
 # --- The engine env contract ---------------------------------------------
 # Everything the IS_CLI mode of sync.sh needs, derived from the manifest.
 export_engine_env() {
     local root="$1"
-    local umbrella
-    umbrella="$(manifest_intelligence_dir "$root/intelligence.yaml")"
+    local content_rel
+    content_rel="$(manifest_intelligence_dir "$root/intelligence.yaml")"
     export IS_CLI=1
     export CONFIG_FILE="$root/intelligence.yaml"
     export REPO_ROOT="$root"
-    export IS_UMBRELLA_REL="$umbrella"
-    export IS_MODULE_REL=".intelligence/engine"
+    export IS_CONTENT_REL="$content_rel"
+    export IS_MODULE_REL="$SYNC_PKG_STORE"
     export IS_SYNC_CMD="intelligence sync"
-    export IS_PROTECTED_DIRS="$umbrella:.intelligence"
+    export IS_MANIFEST_NAME="intelligence.yaml"
+    export IS_PROTECTED_DIRS="$content_rel:.intelligence"
+}
+
+# --- Project lifecycle preflight -----------------------------------------
+# Public commands are intentionally few. They share this state gate so a CLI
+# installed at a newer engine version brings the current Intelligence project forward
+# before a mutating operation. The npm install itself cannot do that: it runs
+# outside any project and does not know which repositories the user owns.
+
+is_ci_environment() {
+    case "${CI:-}" in
+        1|true|TRUE|True|yes|YES|Yes|on|ON|On) return 0 ;;
+        *) return 1 ;;
+    esac
+}
+
+# Validate a repository-relative project content directory, including every
+# existing symlinked path component. Call before writing a new manifest.
+assert_safe_content_dir() {
+    local root="$1" content_dir="$2" repo_phys probe old_ifs part probe_phys
+    local -a parts
+    case "$content_dir" in
+        ""|/*|.|..|../*|*/../*|*/..|.git|.git/*|.intelligence|.intelligence/*|*\\*|[A-Za-z]:*)
+            die "unsafe content directory '$content_dir'"
+            ;;
+    esac
+    repo_phys="$(cd "$root" && pwd -P)"
+    probe="$root"
+    old_ifs="$IFS"; IFS='/'; read -r -a parts <<< "$content_dir"; IFS="$old_ifs"
+    for part in "${parts[@]}"; do
+        [ -n "$part" ] || continue
+        probe="$probe/$part"
+        if [ -e "$probe" ] || [ -L "$probe" ]; then
+            probe_phys="$(cd "$probe" 2>/dev/null && pwd -P)" \
+                || die "cannot resolve project content path '$content_dir'"
+            case "$probe_phys" in
+                "$repo_phys"|"$repo_phys"/*) ;;
+                *) die "project content directory resolves outside the repository: '$content_dir'" ;;
+            esac
+        fi
+    done
+}
+
+project_needs_upgrade() {
+    local root="$1" manifest="$1/intelligence.yaml" stamp eng pinned locked name
+    [ -f "$manifest" ] || return 1
+    stamp="$(read_schema_version "$manifest")"
+    eng="$(bundled_engine_version)"
+    [ -z "$stamp" ] && return 0
+    [ -n "$(top_scalar "$manifest" "sync_version")" ] && return 0
+    _ver_gt "$eng" "$stamp" && return 0
+    [ -d "$root/.intelligence/engine" ] && return 0
+
+    while IFS= read -r name; do
+        [ -n "$name" ] || continue
+        # Early RC manifests mixed requested intent with resolved source
+        # details. Source URL/path now live only in the required lockfile.
+        [ -n "$(qmap_field "$manifest" "packages" "$name" "url")" ] && return 0
+        [ -n "$(qmap_field "$manifest" "packages" "$name" "path")" ] && return 0
+        if [ "$name" = "$SYNC_PKG_NAME" ]; then
+            pinned="$(qmap_field "$manifest" "packages" "$name" "version")"
+            locked="$(qmap_field "$root/intelligence.lock" "packages" "$name" "resolved")"
+            [ "$pinned" = "$eng" ] || return 0
+            if [ -f "$root/intelligence.lock" ]; then
+                [ -n "$locked" ] || return 0
+                [ "${locked#v}" = "$eng" ] || return 0
+            fi
+        fi
+    done < <(qmap_keys "$manifest" "packages")
+    return 1
+}
+
+# A manifest with packages but no lock has no trustworthy resolved state from
+# which lifecycle alignment can proceed. Never manufacture a partial lock.
+project_has_packages() {
+    local root="$1" name found=1
+    while IFS= read -r name; do
+        [ -n "$name" ] || continue
+        assert_valid_pkg_name "$name"
+        found=0
+    done < <(qmap_keys "$root/intelligence.yaml" "packages")
+    return "$found"
+}
+
+ensure_project_current() {
+    local root="$1" explicit="${2:-}" manifest="$1/intelligence.yaml" stamp eng
+    check_version_compat "$manifest" || 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
+    project_needs_upgrade "$root" || return 0
+    stamp="$(read_schema_version "$manifest")"
+    eng="$(bundled_engine_version)"
+    if is_ci_environment && [ "$explicit" != "--explicit" ]; then
+        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
+}
+
+project_store_missing() {
+    local root="$1" manifest="$1/intelligence.yaml" name src
+    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")
+    for section in rules agents skills; do
+        while IFS= read -r src; do
+            case "$src" in
+                .intelligence/packages/*)
+                    [ -d "$root/$src" ] || return 0
+                    ;;
+            esac
+        done < <(read_yaml_list "$manifest" "$section")
+    done
+    return 1
+}
+
+restore_project_store_if_missing() {
+    local root="$1"
+    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
 }