@ainova-systems/intelligence 0.11.0-rc.11 → 0.11.0-rc.13

package/cli/commands/adapter.sh

@@ -137,10 +137,32 @@ case "$action" in
         assert_valid_target_name "$name"
         require_cli_project
         ensure_project_current "$IP_ROOT"
-        bash "$CLI_DIR/internal/target-state.sh" "$action" "$name"
         if [ "$action" = "enable" ]; then
-            exec bash "$CLI_DIR/commands/sync.sh"
+            state_stage="$(mktemp -d -t intelligence-adapter-state-XXXXXX)"
+            cp "$IP_ROOT/intelligence.yaml" "$state_stage/intelligence.yaml"
+            gitignore_existed=0
+            if [ -f "$IP_ROOT/.gitignore" ]; then
+                gitignore_existed=1
+                cp "$IP_ROOT/.gitignore" "$state_stage/gitignore"
+            fi
+            enable_rc=0
+            bash "$CLI_DIR/internal/target-state.sh" "$action" "$name" || enable_rc=$?
+            if [ "$enable_rc" -eq 0 ]; then
+                bash "$CLI_DIR/commands/sync.sh" || enable_rc=$?
+            fi
+            if [ "$enable_rc" -ne 0 ]; then
+                cp "$state_stage/intelligence.yaml" "$IP_ROOT/intelligence.yaml"
+                if [ "$gitignore_existed" -eq 1 ]; then
+                    cp "$state_stage/gitignore" "$IP_ROOT/.gitignore"
+                else
+                    rm -f "$IP_ROOT/.gitignore"
+                fi
+                echo "ERROR: adapter enable failed; manifest and Git policy were restored." >&2
+            fi
+            rm -rf "$state_stage"
+            exit "$enable_rc"
         fi
+        bash "$CLI_DIR/internal/target-state.sh" "$action" "$name"
         ;;
     remove)
         [ -n "$name" ] || die "usage: intelligence adapter remove <name> [--apply]"
@@ -148,6 +170,14 @@ case "$action" in
         adapter_remove "$@"
         ;;
     *)
+        case "$name" in
+            list)
+                die "adapter action comes first - run: intelligence adapter list"
+                ;;
+            create|enable|disable|remove)
+                die "adapter action comes first - run: intelligence adapter $name $action"
+                ;;
+        esac
         die "usage: intelligence adapter <list|create|enable|disable|remove> [name]"
         ;;
 esac

package/cli/commands/init.sh

@@ -12,6 +12,47 @@ source "$CLI_DIR/lib/cli-common.sh"
 
 targets_arg="" no_sync=0 content_dir="intelligence" bare=0
 targets_set=0 dir_set=0 bare_set=0 preview=0 apply=0 force=0
+
+print_new_project_onboarding() {
+    local heading="Intelligence ready"
+    [ "$no_sync" -eq 0 ] || heading="Next steps"
+
+    echo ""
+    echo "=== $heading ==="
+    if [ -n "${ONBOARDING_BACKUP_REL:-}" ]; then
+        echo "  Existing AI instructions preserved:"
+        echo "    $ONBOARDING_BACKUP_REL ($ONBOARDING_BACKUP_COUNT path(s))"
+        if [ "$bare" -eq 0 ]; then
+            echo "    The learn skill will migrate them before proposing backup removal."
+        else
+            echo "    Review and migrate them before removing this backup."
+        fi
+    fi
+    if [ "$no_sync" -eq 1 ]; then
+        echo "  Run first:"
+        echo "    intelligence sync"
+    fi
+    if [ "$bare" -eq 0 ]; then
+        echo "  Finalize repository onboarding:"
+        echo "    Ask your agent to run /intelligence-learn-from-context"
+        echo "    It recognizes the initial backup, recovers setup if needed, then proposes repository-specific migration after approval."
+        echo "  Recommended starter package:"
+        echo "    intelligence package add @ainova-systems/core"
+    fi
+    echo "  Review adapters:"
+    echo "    intelligence adapter list"
+    echo "    intelligence adapter enable codex"
+    echo "    intelligence adapter disable cursor"
+    echo "  Version control:"
+    echo "    Generated adapter output is gitignored by CLI-owned path."
+    echo "    Commit intelligence.yaml, intelligence.lock, intelligence/, AGENTS.md, and .github/."
+    echo "    Shared tool settings remain trackable; review the exact ownership policy:"
+    echo "    https://github.com/ainova-systems/intelligence/blob/main/packages/sync/references/conventions.md#generated-output-and-version-control"
+    echo "  Write your own:"
+    echo "    create $content_dir/rules/context.md, then intelligence sync"
+    echo "  Docs: https://github.com/ainova-systems/intelligence#readme"
+}
+
 while [ $# -gt 0 ]; do
     case "$1" in
         --targets) shift; targets_arg="${1:-}"; targets_set=1 ;;
@@ -68,9 +109,25 @@ case "$IP_MODE" in
             ensure_project_current "$IP_ROOT"
         fi
         restore_project_store_if_missing "$IP_ROOT"
+        ensure_manifest_gitignore "$IP_ROOT" "$IP_ROOT/intelligence.yaml"
         [ "$no_sync" -eq 1 ] && exit 0
         cd "$IP_ROOT"
-        exec bash "$CLI_DIR/commands/sync.sh"
+        sync_rc=0
+        bash "$CLI_DIR/commands/sync.sh" || sync_rc=$?
+        if [ "$sync_rc" -ne 0 ]; then
+            content_dir="$(manifest_intelligence_dir "$IP_ROOT/intelligence.yaml")"
+            recovery_backup=""
+            if [ -f "$IP_ROOT/$content_dir/_backup/manifest.tsv" ]; then
+                recovery_backup="; initial backup: $content_dir/_backup/manifest.tsv"
+            fi
+            echo "" >&2
+            echo "=== Intelligence setup needs recovery ===" >&2
+            echo "  No partial adapter update was kept; sync restored its pre-run outputs." >&2
+            echo "  Ask your agent to read:" >&2
+            echo "    $SYNC_PKG_STORE/skills/intelligence-learn-from-context/SKILL.md" >&2
+            echo "  and finalize this Intelligence setup$recovery_backup." >&2
+        fi
+        exit "$sync_rc"
         ;;
     legacy)
         [ "$targets_set" -eq 0 ] || die "--targets applies only when creating a new project"
@@ -117,17 +174,30 @@ if [ -n "$targets_arg" ]; then
     done
 else
     if [ -d "$root/.claude" ] || [ -f "$root/CLAUDE.md" ]; then targets="$targets claude"; fi
-    [ -d "$root/.cursor" ] && targets="$targets cursor"
-    [ -d "$root/.codex" ] && targets="$targets codex"
+    if [ -d "$root/.cursor" ] || [ -f "$root/.cursorrules" ]; then targets="$targets cursor"; fi
+    if [ -d "$root/.codex" ] || [ -d "$root/.agents" ]; then targets="$targets codex"; fi
     [ -d "$root/.pi" ] && targets="$targets pi"
     [ -d "$root/.opencode" ] && targets="$targets opencode"
-    [ -d "$root/.github" ] && [ -d "$root/.github/instructions" ] && targets="$targets copilot"
+    if [ -f "$root/.github/copilot-instructions.md" ] \
+        || [ -d "$root/.github/instructions" ] \
+        || [ -d "$root/.github/agents" ] \
+        || [ -d "$root/.github/skills" ]; then
+        targets="$targets copilot"
+    fi
     if [ "$targets" = "agents" ]; then
         echo "  NOTE: no tool markers found (.claude/, CLAUDE.md, .cursor/, …) — only AGENTS.md is enabled." >&2
         echo "        Name your tools explicitly: intelligence init --targets claude,cursor  (or edit targets: later)" >&2
     fi
 fi
 
+onboarding_count="$(onboarding_source_count "$root" "$content_dir" "$targets")"
+onboarding_has_agents=0
+[ -f "$root/AGENTS.md" ] && onboarding_has_agents=1
+if [ "$preview" -eq 0 ] && [ "$onboarding_count" -gt 0 ] \
+    && [ -e "$root/$content_dir/_backup" ]; then
+    die "onboarding backup already exists at $content_dir/_backup - review or move it before rerunning init"
+fi
+
 if [ "$preview" -eq 1 ]; then
     echo "project: no Intelligence setup found"
     echo "  would create intelligence.yaml and intelligence.lock"
@@ -141,6 +211,9 @@ if [ "$preview" -eq 1 ]; then
     else
         echo "  would enable adapters:$targets, then sync"
     fi
+    if [ "$onboarding_count" -gt 0 ]; then
+        echo "  would preserve $onboarding_count existing AI instruction path(s) in $content_dir/_backup before sync"
+    fi
     exit 0
 fi
 
@@ -175,7 +248,21 @@ manifest="$root/intelligence.yaml"
     echo "# Generated output, one entry per tool. Add or drop tools freely."
     echo "targets:"
     for t in $targets; do
-        echo "  $t: { enabled: true, output: \"$(default_target_output "$t")\" }"
+        if [ "$t" = "agents" ] && [ "$onboarding_has_agents" -eq 1 ]; then
+            echo "  agents:"
+            echo "    enabled: true"
+            echo "    output: \"AGENTS.md\""
+            echo "    header: |"
+            echo "      > Intelligence onboarding is pending. Before repository work, read"
+            echo "      > \`$content_dir/_backup/AGENTS.md\`, which preserves the original project instructions."
+            if [ "$bare" -eq 0 ]; then
+                echo "      > Run /intelligence-learn-from-context to migrate and verify them before removing the backup."
+            else
+                echo "      > Review and migrate that backup before removing it."
+            fi
+        else
+            echo "  $t: { enabled: true, output: \"$(default_target_output "$t")\" }"
+        fi
     done
     echo ""
     echo "# Packages are managed with 'intelligence package add|search|list':"
@@ -202,13 +289,10 @@ manifest="$root/intelligence.yaml"
 } > "$manifest"
 
 # The package store is restorable state, never committed — the npm model.
-if [ ! -f "$root/.gitignore" ] || ! grep -q '^\.intelligence/' "$root/.gitignore"; then
-    {
-        [ -f "$root/.gitignore" ] && [ -n "$(tail -c 1 "$root/.gitignore" 2>/dev/null)" ] && echo ""
-        echo "# intelligence CLI package store (restored automatically by 'intelligence sync')"
-        echo ".intelligence/"
-    } >> "$root/.gitignore"
-fi
+ensure_base_gitignore "$root"
+for target in $targets; do
+    ensure_target_gitignore "$root" "$manifest" "$target"
+done
 
 # The engine's own content (meta-skills, authoring rule, engine agents) is an
 # ordinary package: auto-selected, opted out with --bare, removable later with
@@ -218,16 +302,27 @@ if [ "$bare" -eq 0 ]; then
     sync_pkg_install "$root"
 fi
 
+preserve_onboarding_sources "$root" "$content_dir" "$targets"
+
 echo "initialized: intelligence.yaml (targets:$(printf ' %s' $targets))"
 [ "$bare" -eq 1 ] && echo "  bare setup: no packages — engine meta-skills not installed"
-echo "  add packages:  intelligence package add @ainova-systems/core   (browse: intelligence package search)"
-echo "  write your own: create $content_dir/rules/context.md, then intelligence sync"
-if [ "$bare" -eq 0 ]; then
-    echo "  tailor this repository: ask your agent to run /intelligence-learn-from-repository after sync"
-fi
-echo "  docs: https://github.com/ainova-systems/intelligence#readme"
-
 if [ "$no_sync" -eq 0 ]; then
     cd "$root"
-    exec bash "$CLI_DIR/commands/sync.sh"
+    sync_rc=0
+    bash "$CLI_DIR/commands/sync.sh" --compact || sync_rc=$?
+    if [ "$sync_rc" -ne 0 ]; then
+        echo "" >&2
+        echo "=== Intelligence setup needs recovery ===" >&2
+        echo "  No partial adapter update was kept; sync restored its pre-run outputs." >&2
+        if [ "$bare" -eq 0 ]; then
+            echo "  Ask your agent to read:" >&2
+            echo "    $SYNC_PKG_STORE/skills/intelligence-learn-from-context/SKILL.md" >&2
+            echo "  and finalize the initial Intelligence setup. The snapshot is $content_dir/_backup/manifest.tsv." >&2
+        else
+            echo "  Fix the reported error, then rerun: intelligence init" >&2
+        fi
+        exit "$sync_rc"
+    fi
 fi
+
+print_new_project_onboarding

package/cli/commands/sync.sh

@@ -1,27 +1,80 @@
 #!/bin/bash
-# intelligence sync [target] — render intelligence to every enabled tool.
+# intelligence sync [target] [--compact] - render intelligence to enabled tools.
 set -euo pipefail
 source "$CLI_DIR/lib/cli-common.sh"
 
-detect_project
-case "$IP_MODE" in
-    cli)
-        # `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
-        # missing ignored store is restored strictly from the committed lock.
-        ensure_project_current "$IP_ROOT"
-        restore_project_store_if_missing "$IP_ROOT"
-        export_engine_env "$IP_ROOT"
-        exec bash "$IS_ENGINE_DIR/sync.sh" "$@"
-        ;;
-    legacy)
-        # A vendored project syncs with ITS engine — its pin is the contract,
-        # and a newer bundled engine must not generate against an older schema.
-        echo "NOTE: legacy Intelligence Sync project — delegating to $IP_MODULE_DIR/scripts/sync.sh. 'intelligence init' converts it into an Intelligence project." >&2
-        exec bash "$IP_MODULE_DIR/scripts/sync.sh" "$@"
-        ;;
-    *)
-        die "no intelligence project found here — run 'intelligence init'"
-        ;;
-esac
+compact=0
+target=""
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --compact) compact=1 ;;
+        -*) die "unknown option '$1'" ;;
+        *)
+            [ -z "$target" ] || die "usage: intelligence sync [adapter] [--compact]"
+            target="$1"
+            ;;
+    esac
+    shift
+done
+
+run_sync() {
+    detect_project || return $?
+    case "$IP_MODE" in
+        cli)
+            # `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
+            # missing ignored store is restored strictly from the committed lock.
+            ensure_project_current "$IP_ROOT" || return $?
+            restore_project_store_if_missing "$IP_ROOT" || return $?
+            export_engine_env "$IP_ROOT" || return $?
+            if [ -n "$target" ]; then
+                bash "$IS_ENGINE_DIR/sync.sh" "$target" || return $?
+            else
+                bash "$IS_ENGINE_DIR/sync.sh" || return $?
+            fi
+            ;;
+        legacy)
+            [ "$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
+            # contract, and a newer bundled engine must not generate against an
+            # older schema.
+            echo "NOTE: legacy Intelligence Sync project - delegating to $IP_MODULE_DIR/scripts/sync.sh. 'intelligence init' converts it into an Intelligence project." >&2
+            if [ -n "$target" ]; then
+                bash "$IP_MODULE_DIR/scripts/sync.sh" "$target" || return $?
+            else
+                bash "$IP_MODULE_DIR/scripts/sync.sh" || return $?
+            fi
+            ;;
+        *)
+            die "no intelligence project found here - run 'intelligence init'"
+            ;;
+    esac
+}
+
+if [ "$compact" -eq 0 ]; then
+    run_sync
+    exit $?
+fi
+
+# Compact mode is intentionally quiet only on success. Buffering the complete
+# combined stream means a failure still returns every diagnostic emitted by
+# lifecycle preflight, locked restore or the engine, together with its real rc.
+compact_output="$(mktemp -t intelligence-sync-XXXXXX)"
+trap 'rm -f "$compact_output"' EXIT
+rc=0
+(run_sync) > "$compact_output" 2>&1 || rc=$?
+if [ "$rc" -ne 0 ]; then
+    cat "$compact_output" >&2
+    exit "$rc"
+fi
+
+status_line="$(grep '^IS_STATUS=ok\($\| \)' "$compact_output" | tail -1 || true)"
+done_line="$(grep '^=== Done:' "$compact_output" | tail -1 || true)"
+if [ -z "$status_line" ] || [ -z "$done_line" ]; then
+    cat "$compact_output" >&2
+    echo "ERROR: sync succeeded without its final status contract" >&2
+    exit 1
+fi
+echo "$status_line"
+echo "$done_line"

package/cli/intelligence

@@ -46,7 +46,8 @@ 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]          Restore locked content if needed, then render enabled adapters
+  sync [adapter] [--compact]  Restore locked content, then render enabled adapters
+    --compact            On success show only final status; on failure show diagnostics
   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
@@ -76,6 +77,20 @@ case "$cmd" in
 esac
 cmd_file="$CLI_DIR/commands/$cmd.sh"
 if [ ! -f "$cmd_file" ]; then
+    case "$cmd" in
+        adapters)
+            echo "ERROR: unknown command 'adapters'. Use the singular command: intelligence adapter list" >&2
+            exit 1
+            ;;
+        packages)
+            echo "ERROR: unknown command 'packages'. Use the singular command: intelligence package list" >&2
+            exit 1
+            ;;
+        registries)
+            echo "ERROR: unknown command 'registries'. Use the singular command: intelligence registry list" >&2
+            exit 1
+            ;;
+    esac
     echo "ERROR: unknown command '$cmd'. Run 'intelligence help'." >&2
     exit 1
 fi

package/cli/internal/check.sh

@@ -86,6 +86,46 @@ while IFS= read -r name; do
     fi
 done < <(qmap_keys "$manifest" "packages")
 
+# Adapter contracts are the shared source of truth for dependencies, rollback,
+# onboarding backup and Git policy. Validate every declared target, including
+# disabled ones, so a later enable cannot reveal a stale custom adapter.
+content_dir="$(manifest_intelligence_dir "$manifest")"
+while IFS= read -r target; do
+    [ -n "$target" ] || continue
+    output="$(get_target_output "$manifest" "$target")"
+    [ -n "$output" ] || output="$(default_target_output "$target")"
+    adapter_file="$(adapter_file_for "$IP_ROOT" "$content_dir" "$target" 2>/dev/null || true)"
+    if [ -z "$adapter_file" ]; then
+        warn "adapter '$target' is declared but its implementation is missing"
+        continue
+    fi
+    records="$(adapter_contract_records "$target" "$adapter_file" "$output" 2>/dev/null || true)"
+    if ! printf '%s\n' "$records" | grep -Fqx $'version\t1'; then
+        warn "adapter '$target' has an invalid ownership contract"
+        continue
+    fi
+    while IFS=$'\t' read -r kind value; do
+        if [ "$kind" = "requires" ] \
+            && [ "$(is_target_enabled "$manifest" "$target")" = "1" ] \
+            && [ "$(is_target_enabled "$manifest" "$value")" != "1" ]; then
+            warn "enabled adapter '$target' requires enabled adapter '$value'"
+        fi
+        if [ "$(is_target_enabled "$manifest" "$target")" = "1" ]; then
+            case "$kind" in
+                ignore)
+                    grep -Fqx -- "$value" "$IP_ROOT/.gitignore" 2>/dev/null \
+                        || warn "adapter '$target' Git policy is missing '$value'"
+                    ;;
+                include)
+                    grep -Fqx -- "!$value" "$IP_ROOT/.gitignore" 2>/dev/null \
+                        || warn "adapter '$target' Git policy is missing '!$value'"
+                    ;;
+            esac
+        fi
+    done <<< "$records"
+    ok "adapter $target contract v1"
+done < <(target_names "$manifest")
+
 # Lock orphans.
 if [ -f "$lock" ]; then
     while IFS= read -r name; do

package/cli/internal/convert-legacy.sh

@@ -348,16 +348,10 @@ rollback_on_exit() {
 # plain set -e/EXIT failure rather than only an explicit sync refusal.
 trap rollback_on_exit EXIT
 trap 'rollback; exit 130' INT TERM
-if [ ! -f "$root/.gitignore" ] || ! grep -q '^\.intelligence/' "$root/.gitignore"; then
-    {
-        [ -f "$root/.gitignore" ] && [ -n "$(tail -c 1 "$root/.gitignore" 2>/dev/null)" ] && echo ""
-        echo "# intelligence CLI package store (restored automatically by 'intelligence sync')"
-        echo ".intelligence/"
-    } >> "$root/.gitignore"
-fi
 mv "$stage/.intelligence" "$root/.intelligence"
 cp "$manifest_stage" "$root/intelligence.yaml"
 lock_write_from_tsv "$root/intelligence.lock" "$lock_rows"
+ensure_manifest_gitignore "$root" "$root/intelligence.yaml"
 
 sync_out="$(cd "$root" && IS_SUPPRESS_CLI_NOTE=1 bash "$CLI_DIR/commands/sync.sh" 2>&1)" || {
     echo "$sync_out"
@@ -397,4 +391,4 @@ rmdir "$umbrella" 2>/dev/null || true
 echo ""
 echo "converted. Review the diff, then commit. The old config.yaml is kept at .intelligence/backup/config.yaml."
 echo "From now on: intelligence sync | package | update | status."
-echo "Next: ask your agent to run /intelligence-learn-from-repository to review the converted project context."
+echo "Next: ask your agent to run /intelligence-learn-from-context to verify setup and review the converted project context."

package/cli/internal/target-state.sh

@@ -25,31 +25,38 @@ if [ "$action" = "enable" ]; 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")"
+    validate_adapter_contract_for "$IP_ROOT" "$content_dir" "$name" "$output" \
+        || die "adapter '$name' has an invalid ownership contract"
+    while IFS= read -r required; do
+        [ -n "$required" ] || continue
+        if [ "$(is_target_enabled "$manifest" "$required")" != "1" ]; then
+            die "target '$name' requires target '$required' — enable it first"
+        fi
+    done < <(adapter_records_for "$IP_ROOT" "$content_dir" "$name" "$output" \
+        | awk -F '\t' '$1 == "requires" { print $2 }')
     target_set_enabled "$manifest" "$name" true "$output"
+    ensure_target_gitignore "$IP_ROOT" "$manifest" "$name"
     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
+while IFS= read -r dependent; do
+    [ -n "$dependent" ] || continue
+    [ "$dependent" = "$name" ] && continue
+    [ "$(is_target_enabled "$manifest" "$dependent")" = "1" ] || continue
+    dependent_output="$(get_target_output "$manifest" "$dependent")"
+    [ -n "$dependent_output" ] || dependent_output="$(default_target_output "$dependent")"
+    dependent_records="$(adapter_records_for "$IP_ROOT" "$content_dir" "$dependent" "$dependent_output")" \
+        || die "adapter '$dependent' has an invalid ownership contract"
+    if awk -F '\t' -v required="$name" \
+        '$1 == "requires" && $2 == required { found=1 } END { exit(found ? 0 : 1) }' \
+        <<< "$dependent_records"; then
+        die "target '$name' is required by enabled target '$dependent' — disable '$dependent' first"
+    fi
+done < <(target_names "$manifest")
 output="$(get_target_output "$manifest" "$name")"
 [ -n "$output" ] || output="$(default_target_output "$name")"
 target_set_enabled "$manifest" "$name" false "$output"

package/cli/lib/adapter-lifecycle.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# CLI consumers of the engine's declarative adapter contract.
+
+adapter_file_for() {
+    local root="$1" content_dir="$2" name="$3"
+    if [ -f "$root/$content_dir/adapters/$name.sh" ]; then
+        printf '%s\n' "$root/$content_dir/adapters/$name.sh"
+    elif [ -f "$IS_ENGINE_DIR/adapters/$name.sh" ]; then
+        printf '%s\n' "$IS_ENGINE_DIR/adapters/$name.sh"
+    else
+        return 1
+    fi
+}
+
+adapter_records_for() {
+    local root="$1" content_dir="$2" name="$3" output="$4" file
+    file="$(adapter_file_for "$root" "$content_dir" "$name")" || {
+        echo "ERROR: adapter '$name' not found" >&2
+        return 1
+    }
+    adapter_contract_records "$name" "$file" "$output"
+}
+
+validate_adapter_contract_for() {
+    local root="$1" content_dir="$2" name="$3" output="$4"
+    adapter_records_for "$root" "$content_dir" "$name" "$output" >/dev/null
+}
+
+adapter_contract_paths() {
+    local root="$1" content_dir="$2" name="$3" output="$4"
+    adapter_records_for "$root" "$content_dir" "$name" "$output" \
+        | awk -F '\t' '$1 == "owned" || $1 == "managed" || $1 == "legacy" || $1 == "preserve" { print $2 }'
+}

package/cli/lib/cli-common.sh

@@ -11,6 +11,7 @@
 # IS_ENGINE_DIR come exported from the dispatcher.
 source "$IS_ENGINE_DIR/lib/common.sh"
 source "$IS_ENGINE_DIR/lib/contract.sh"
+source "$IS_ENGINE_DIR/lib/adapter-contract.sh"
 
 die() {
     echo "ERROR: $*" >&2
@@ -50,6 +51,9 @@ source "$CLI_DIR/lib/manifest.sh"
 source "$CLI_DIR/lib/semver.sh"
 source "$CLI_DIR/lib/registry.sh"
 source "$CLI_DIR/lib/lockfile.sh"
+source "$CLI_DIR/lib/adapter-lifecycle.sh"
+source "$CLI_DIR/lib/gitignore.sh"
+source "$CLI_DIR/lib/onboarding.sh"
 
 # The engine-content package: OPTIONAL but auto-selected at init. Package by
 # UX (manifest entry, lockfile row, list/search/remove), bundle by mechanics —

package/cli/lib/gitignore.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# Generated-output policy derived from each adapter's ownership contract.
+
+gitignore_add_line() {
+    local root="$1" line="$2" file="$1/.gitignore"
+    if [ -f "$file" ] && grep -Fqx -- "$line" "$file"; then
+        return 0
+    fi
+    printf '%s\n' "$line" >> "$file"
+}
+
+ensure_gitignore_header() {
+    local root="$1" file="$1/.gitignore"
+    if [ ! -f "$file" ] || ! grep -Fqx '# Intelligence generated state and tool output' "$file"; then
+        if [ -f "$file" ] && [ -s "$file" ] && [ -n "$(tail -c 1 "$file" 2>/dev/null)" ]; then
+            printf '\n' >> "$file"
+        fi
+        printf '%s\n' '# Intelligence generated state and tool output' >> "$file"
+    fi
+}
+
+ensure_base_gitignore() {
+    local root="$1"
+    ensure_gitignore_header "$root"
+    gitignore_add_line "$root" '.intelligence/'
+}
+
+ensure_target_gitignore() {
+    local root="$1" manifest="$2" target="$3" content_dir output kind value records
+    ensure_gitignore_header "$root"
+    content_dir="$(manifest_intelligence_dir "$manifest")"
+    output="$(get_target_output "$manifest" "$target")"
+    [ -n "$output" ] || output="$(default_target_output "$target")"
+    records="$(adapter_records_for "$root" "$content_dir" "$target" "$output")" \
+        || die "adapter '$target' has an invalid ownership contract"
+    while IFS=$'\t' read -r kind value; do
+        case "$kind" in
+            ignore)  gitignore_add_line "$root" "$value" ;;
+            include) gitignore_add_line "$root" "!$value" ;;
+        esac
+    done <<< "$records"
+}
+
+ensure_manifest_gitignore() {
+    local root="$1" manifest="$2" target
+    ensure_base_gitignore "$root"
+    while IFS= read -r target; do
+        [ -n "$target" ] || continue
+        if [ "$(is_target_enabled "$manifest" "$target")" = "1" ]; then
+            ensure_target_gitignore "$root" "$manifest" "$target"
+        fi
+    done < <(target_names "$manifest")
+}

package/cli/lib/manifest.sh

@@ -60,6 +60,23 @@ target_exists() {
     ' "$file"
 }
 
+# target_names <manifest> — declared target keys in manifest order.
+target_names() {
+    local file="$1"
+    [ -f "$file" ] || return 0
+    awk '
+        { sub(/\r$/, "") }
+        /^targets:[[:space:]]*$/ { in_targets = 1; next }
+        in_targets && /^[A-Za-z]/ { in_targets = 0 }
+        in_targets && /^  [a-z][a-z0-9_]*:/ {
+            line = $0
+            sub(/^  /, "", line)
+            sub(/:.*/, "", line)
+            print line
+        }
+    ' "$file"
+}
+
 # target_set_enabled <manifest> <name> <true|false> <default-output>
 # Transactionally update only `enabled`, preserving every other target field
 # and comment. A missing target is added in the compact form used by init.