@ainova-systems/intelligence 0.11.0-rc.8 → 0.11.0

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 —
@@ -70,11 +74,11 @@ DEFAULT_REGISTRY_URL="$(top_scalar "$_EPKG" "default_registry")"
 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() {
@@ -82,7 +86,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
@@ -109,11 +113,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 init' to migrate it, 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
 }
@@ -139,14 +143,12 @@ bundled_engine_version() {
 }
 
 # --- The sync package's manifest/lock plumbing ---------------------------
-# sync_pkg_entry <manifest> — write/refresh the package's manifest entry:
-# name + exact pin + explicit url/path, so resolution never depends on any
-# registry (a project registry shadowing the name cannot brick the engine).
+# 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)"
-    qmap_set "$manifest" "packages" "$SYNC_PKG_NAME" "url" "$SYNC_PKG_URL"
-    qmap_set "$manifest" "packages" "$SYNC_PKG_NAME" "path" "$SYNC_PKG_PATH"
 }
 
 # sync_pkg_install <root> — materialize the package into the store and lock
@@ -178,7 +180,7 @@ export_engine_env() {
 
 # --- 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 v2 project forward
+# 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.
 
@@ -227,13 +229,19 @@ project_needs_upgrade() {
     [ -d "$root/.intelligence/engine" ] && return 0
 
     while IFS= read -r name; do
-        [ "$name" = "$SYNC_PKG_NAME" ] || continue
-        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
+        [ -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
@@ -264,7 +272,7 @@ 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/upgrade-v2.sh" --no-sync
+    bash "$CLI_DIR/internal/align-project.sh" --no-sync
 }
 
 project_store_missing() {

package/cli/lib/gitignore.sh

@@ -0,0 +1,174 @@
+#!/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")
+}
+
+# Publishing/build tools do not share Git's ignore policy. In particular,
+# .vscodeignore and .npmignore become the packager's own filter, while Docker
+# always builds from its independent context filter. Only amend files the
+# project already has: their presence is the explicit signal that this root is
+# packaged or sent as a build context.
+publisher_ignore_file_names() {
+    printf '%s\n' .vscodeignore .npmignore .dockerignore
+}
+
+publisher_ignore_add_line() {
+    local file="$1" line="$2"
+    if grep -Fqx -- "$line" "$file" 2>/dev/null; then
+        return 0
+    fi
+    printf '%s\n' "$line" >> "$file"
+    PUBLISH_IGNORE_FILE_CHANGED=1
+}
+
+publisher_ignore_add_path() {
+    local file="$1" path="${2#./}"
+    path="${path%/}"
+    [ -n "$path" ] || return 0
+    publisher_ignore_add_line "$file" "$path"
+    publisher_ignore_add_line "$file" "$path/**"
+}
+
+ensure_manifest_publisher_ignores() {
+    local root="$1" manifest="$2" rel file content_dir target output records kind value
+    content_dir="$(manifest_intelligence_dir "$manifest")"
+    while IFS= read -r rel; do
+        [ -n "$rel" ] || continue
+        file="$root/$rel"
+        [ -f "$file" ] || continue
+        PUBLISH_IGNORE_FILE_CHANGED=0
+        if ! grep -Fqx '# Intelligence development context and generated output' "$file" 2>/dev/null; then
+            if [ -s "$file" ] && [ -n "$(tail -c 1 "$file" 2>/dev/null)" ]; then
+                printf '\n' >> "$file"
+            fi
+            printf '%s\n' '# Intelligence development context and generated output' >> "$file"
+            PUBLISH_IGNORE_FILE_CHANGED=1
+        fi
+        publisher_ignore_add_path "$file" '.intelligence'
+        publisher_ignore_add_line "$file" 'intelligence.yaml'
+        publisher_ignore_add_line "$file" 'intelligence.lock'
+        publisher_ignore_add_path "$file" "$content_dir"
+        while IFS= read -r target; do
+            [ -n "$target" ] || continue
+            [ "$(is_target_enabled "$manifest" "$target")" = "1" ] || continue
+            output="$(get_target_output "$manifest" "$target")"
+            [ -n "$output" ] || output="$(default_target_output "$target")"
+            publisher_ignore_add_path "$file" "$output"
+            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
+                    owned|managed|legacy) publisher_ignore_add_path "$file" "$value" ;;
+                esac
+            done <<< "$records"
+        done < <(target_names "$manifest")
+        if [ "$PUBLISH_IGNORE_FILE_CHANGED" -eq 1 ]; then
+            echo "packaging exclusions updated: $rel"
+        fi
+    done < <(publisher_ignore_file_names)
+}
+
+managed_gitignore_patterns() {
+    local root="$1" manifest="$2" content_dir target output records kind value
+    content_dir="$(manifest_intelligence_dir "$manifest")"
+    printf '%s\n' '.intelligence/' "$content_dir/_backup/"
+    while IFS= read -r target; do
+        [ -n "$target" ] || continue
+        [ "$(is_target_enabled "$manifest" "$target")" = "1" ] || continue
+        output="$(get_target_output "$manifest" "$target")"
+        [ -n "$output" ] || output="$(default_target_output "$target")"
+        records="$(adapter_records_for "$root" "$content_dir" "$target" "$output")" \
+            || return 1
+        while IFS=$'\t' read -r kind value; do
+            case "$kind" in
+                ignore) printf '%s\n' "$value" ;;
+                include) printf '!%s\n' "$value" ;;
+            esac
+        done <<< "$records"
+    done < <(target_names "$manifest")
+}
+
+# Git does not apply ignore rules retroactively to files already in its index.
+# Name each affected path and print a command which only untracks it; the local
+# file remains available as migration input.
+report_tracked_managed_ignores() {
+    local root="$1" manifest="$2" patterns tracked path quoted posix_quoted powershell_quoted
+    git -C "$root" rev-parse --is-inside-work-tree >/dev/null 2>&1 || return 0
+    patterns="$(mktemp -t intelligence-gitignore-XXXXXX)"
+    tracked="$(mktemp -t intelligence-tracked-XXXXXX)"
+    managed_gitignore_patterns "$root" "$manifest" > "$patterns" || {
+        rm -f "$patterns" "$tracked"
+        return 0
+    }
+    git -C "$root" ls-files -z -ci --exclude-from="$patterns" > "$tracked" 2>/dev/null || true
+    rm -f "$patterns"
+    [ -s "$tracked" ] || {
+        rm -f "$tracked"
+        return 0
+    }
+    echo "  Tracked files still bypass these .gitignore rules. Untrack them without deleting local copies:"
+    while IFS= read -r -d '' path; do
+        [ -n "$path" ] || continue
+        if [[ "$path" == *"'"* ]]; then
+            # macOS still ships Bash 3.2; use portable sed rather than newer
+            # parameter-replacement behavior for the embedded quote.
+            posix_quoted="$(printf '%s' "$path" | sed "s/'/'\\\\''/g")"
+            powershell_quoted="$(printf '%s' "$path" | sed "s/'/''/g")"
+            printf "    POSIX:      git rm --cached -- '%s'\n" "$posix_quoted"
+            printf "    PowerShell: git rm --cached -- '%s'\n" "$powershell_quoted"
+        else
+            quoted="'$path'"
+            printf '    git rm --cached -- %s\n' "$quoted"
+        fi
+    done < "$tracked"
+    rm -f "$tracked"
+}

package/cli/lib/manifest.sh

@@ -60,16 +60,38 @@ 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.
 target_set_enabled() {
     local file="$1" target="$2" enabled="$3" output="$4"
+    local target_missing=1
     [ -f "$file" ] || die "no such file: $file"
     case "$enabled" in true|false) ;; *) die "internal: invalid target state '$enabled'" ;; esac
+    target_exists "$file" "$target" && target_missing=0
     output="$(_yq_esc "$output")"
-    _qmap_stage "$file" -v target="$target" -v enabled="$enabled" -v output="$output" '
+    _qmap_stage "$file" -v target="$target" -v enabled="$enabled" -v output="$output" -v target_missing="$target_missing" '
         function entry() { return "  " target ": { enabled: " enabled ", output: \"" output "\" }" }
+        function insert_missing_target() {
+            if (in_targets && target_missing && !target_seen) { print entry(); target_seen = 1 }
+        }
         function add_enabled_to_inline(line,    p) {
             p = index(line, "{")
             if (p > 0) return substr(line, 1, p) " enabled: " enabled "," substr(line, p + 1)
@@ -86,8 +108,20 @@ target_set_enabled() {
         }
         { sub(/\r$/, "") }
         /^targets:[[:space:]]*$/ { targets_seen = 1; in_targets = 1; print; next }
+        in_targets && target_missing && target_entry_seen && /^#/ {
+            flush_target()
+            insert_missing_target()
+            print
+            next
+        }
+        in_targets && target_missing && target_entry_seen && !in_target && /^[[:space:]]*$/ {
+            insert_missing_target()
+            print
+            next
+        }
         in_targets && /^[A-Za-z]/ { flush_targets() }
         in_targets && /^  [A-Za-z]/ {
+            target_entry_seen = 1
             flush_target()
             if ($0 ~ "^  " target ":[[:space:]]*") {
                 target_seen = 1
@@ -301,6 +335,29 @@ qmap_delete_key() {
     '
 }
 
+# qmap_delete_field <file> <block> <key> <field> — drop one field from a
+# quoted-key entry without disturbing its other fields or surrounding YAML.
+qmap_delete_field() {
+    local file="$1" block="$2" key="$3" field="$4"
+    [ -f "$file" ] || return 0
+    _qmap_stage "$file" -v block="$block" -v key="$key" -v field="$field" '
+        { sub(/\r$/, "") }
+        $0 ~ "^" block ":[ \t]*$" { inb = 1; print; next }
+        inb && /^[^ #]/ { inb = 0; ink = 0 }
+        inb && /^  "/ {
+            s = substr($0, 4); q = index(s, "\"")
+            ink = (q > 0 && substr(s, 1, q - 1) == key)
+            print; next
+        }
+        inb && ink && /^    [A-Za-z_]/ {
+            line = $0; sub(/^    /, "", line)
+            c = index(line, ":")
+            if (c > 0 && substr(line, 1, c - 1) == field) next
+        }
+        { print }
+    '
+}
+
 # --- registries: a trust LIST, not a scope map -----------------------------
 # The block holds registry repo URLs in trust order. Two shapes are read so
 # early manifests keep working: the list form (`- "url"`) and the retired

package/cli/lib/onboarding.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# Preserve the pre-Intelligence state described by enabled adapter contracts.
+# The snapshot is data-only and explicitly identifies itself as initial
+# onboarding state so recovery skills never mistake it for generated output.
+
+onboarding_source_paths() {
+    local root="$1" content_dir="$2" targets="$3" target output
+    for target in $targets; do
+        output="$(default_target_output "$target")"
+        adapter_contract_paths "$root" "$content_dir" "$target" "$output"
+    done | awk 'NF && !seen[$0]++'
+}
+
+onboarding_source_count() {
+    local root="$1" content_dir="$2" targets="$3" rel count=0
+    while IFS= read -r rel; do
+        [ -e "$root/$rel" ] || [ -L "$root/$rel" ] || continue
+        count=$((count + 1))
+    done < <(onboarding_source_paths "$root" "$content_dir" "$targets")
+    printf '%s\n' "$count"
+}
+
+preserve_onboarding_sources() {
+    local root="$1" content_dir="$2" targets="$3"
+    local rel src dest backup_rel backup stage target
+    backup_rel="$content_dir/_backup"
+    backup="$root/$backup_rel"
+    ONBOARDING_BACKUP_COUNT="$(onboarding_source_count "$root" "$content_dir" "$targets")"
+    ONBOARDING_BACKUP_REL=""
+    export ONBOARDING_BACKUP_COUNT ONBOARDING_BACKUP_REL
+    [ "$ONBOARDING_BACKUP_COUNT" -gt 0 ] || return 0
+    [ ! -e "$backup" ] || die "onboarding backup already exists at $backup_rel - review or move it before rerunning init"
+
+    mkdir -p "$root/$content_dir"
+    stage="$root/$content_dir/.backup-stage.$$"
+    [ ! -e "$stage" ] || die "temporary onboarding backup path already exists"
+    mkdir -p "$stage"
+
+    {
+        printf '# Intelligence initial-state backup contract v1\n'
+        printf 'state\tinitial-onboarding\n'
+        printf 'source\tpre-intelligence\n'
+        for target in $targets; do printf 'target\t%s\n' "$target"; done
+    } > "$stage/manifest.tsv"
+
+    while IFS= read -r rel; do
+        src="$root/$rel"
+        [ -e "$src" ] || [ -L "$src" ] || continue
+        dest="$stage/$rel"
+        mkdir -p "$(dirname "$dest")"
+        if ! cp -R "$src" "$dest"; then
+            rm -rf "$stage"
+            die "failed to preserve initial AI instruction path '$rel'"
+        fi
+        printf 'path\t%s\n' "$rel" >> "$stage/manifest.tsv"
+    done < <(onboarding_source_paths "$root" "$content_dir" "$targets")
+
+    mv "$stage" "$backup"
+    ensure_gitignore_header "$root"
+    gitignore_add_line "$root" "$backup_rel/"
+    ONBOARDING_BACKUP_REL="$backup_rel"
+    export ONBOARDING_BACKUP_REL
+}

package/engine/ENGINE_SHA

@@ -1 +1 @@
-f2bfc5e3722bf6fb2f7309db2d248368d5b0cc5e
+88a9c74ddb8bee338671c7badbebd07669b668c0

package/engine/adapters/_template.sh

@@ -7,8 +7,9 @@
 # occurrence with your adapter name before sourcing.
 #
 # Required:
-#   1. Implement sync_to_<name>() and its three content transforms
-#   2. Enable it after implementation: intelligence adapter enable <name>
+#   1. Keep adapter_contract_<name>() accurate for every path this file writes
+#   2. Implement sync_to_<name>() and its three content transforms
+#   3. Enable it after implementation: intelligence adapter enable <name>
 #      This adds the target to intelligence.yaml when it is absent:
 #      targets:
 #        <name>: { enabled: true, output: ".<name>" }
@@ -35,6 +36,22 @@
 # loaded. Keep this template position-independent: after scaffolding it lives
 # under the project's content directory, not beside engine/lib/.
 
+# Ownership contract. Paths are repository-relative and derive from the
+# configured target output passed as $1. `owned` paths are exclusively managed;
+# `managed` paths share a directory with another adapter or hand-authored files.
+# Add `legacy` inputs to the initial backup, `preserve` for settings that must
+# never be replaced, and explicit ignore/include records for Git policy.
+adapter_contract_<name>() {
+    local output="${1%/}"
+    adapter_contract_version 1
+    adapter_contract_owned "$output/rules"
+    adapter_contract_owned "$output/agents"
+    adapter_contract_owned "$output/skills"
+    adapter_contract_ignore "$output/rules/"
+    adapter_contract_ignore "$output/agents/"
+    adapter_contract_ignore "$output/skills/"
+}
+
 # Sync rules for <agent-name>
 # Typical transformations:
 #   - Copy as-is (like Claude)

package/engine/adapters/agents.sh

@@ -223,6 +223,16 @@ agents_md_append_rules_list() {
 }
 
 # Main entry point for AGENTS.md adapter
+adapter_contract_agents() {
+    local output="$1"
+    if [[ "$output" == */ ]] || [[ "$output" != *.md ]]; then
+        output="${output%/}/AGENTS.md"
+    fi
+    adapter_contract_version 1
+    adapter_contract_owned "$output"
+    adapter_contract_legacy "AGENTS.md"
+}
+
 sync_to_agents() {
     local repo_root="$1"
     local config_file="$2"
@@ -231,10 +241,11 @@ sync_to_agents() {
     echo "=== AGENTS.md ==="
 
     # output_dir points at the target file path (e.g., /repo/AGENTS.md).
-    # If it looks like a directory (trailing slash, existing dir, or no .md
-    # extension), append default filename.
+    # If it looks like a directory lexically (trailing slash or no .md
+    # extension), append the default filename. The ownership contract uses the
+    # same rule, so filesystem state cannot make its write-set ambiguous.
     local output_file="$output_dir"
-    if [ -d "$output_file" ] || [[ "$output_file" == */ ]] || [[ "$output_file" != *.md ]]; then
+    if [[ "$output_file" == */ ]] || [[ "$output_file" != *.md ]]; then
         output_file="${output_file%/}/AGENTS.md"
     fi
 

package/engine/adapters/claude.sh

@@ -8,6 +8,21 @@
 
 source "$(dirname "${BASH_SOURCE[0]}")/../lib/common.sh"
 
+adapter_contract_claude() {
+    local output="${1%/}"
+    adapter_contract_version 1
+    adapter_contract_owned "$output/rules"
+    adapter_contract_owned "$output/agents"
+    adapter_contract_owned "$output/skills"
+    adapter_contract_legacy "CLAUDE.md"
+    adapter_contract_legacy "$output/commands"
+    adapter_contract_preserve "$output/settings.json"
+    adapter_contract_preserve "$output/settings.local.json"
+    adapter_contract_ignore "CLAUDE.md"
+    adapter_contract_ignore "$output/*"
+    adapter_contract_include "$output/settings.json"
+}
+
 # Sync rules to Claude format (copy as-is, normalize LF)
 sync_claude_rules() {
     local repo_root="$1"

package/engine/adapters/codex.sh

@@ -13,6 +13,16 @@
 
 source "$(dirname "${BASH_SOURCE[0]}")/../lib/common.sh"
 
+adapter_contract_codex() {
+    local output="${1%/}"
+    adapter_contract_version 1
+    adapter_contract_requires agents
+    adapter_contract_managed ".agents/skills"
+    adapter_contract_owned "$output/agents"
+    adapter_contract_ignore ".agents/skills/"
+    adapter_contract_ignore "$output/agents/"
+}
+
 # Sync skills to Codex format (.agents/skills/{name}/SKILL.md)
 sync_codex_skills() {
     local repo_root="$1"
@@ -111,7 +121,7 @@ sync_to_codex() {
     sync_codex_skills "$repo_root" "$config_file" "$skills_dir"
 
     # Agents -> .codex/agents/
-    local agents_dir="$repo_root/.codex/agents"
+    local agents_dir="$output_dir/agents"
     rm -rf "$agents_dir"
     mkdir -p "$agents_dir"
     sync_codex_agents "$repo_root" "$config_file" "$agents_dir"

package/engine/adapters/copilot.sh

@@ -14,6 +14,17 @@
 
 source "$(dirname "${BASH_SOURCE[0]}")/../lib/common.sh"
 
+adapter_contract_copilot() {
+    local output="${1%/}"
+    adapter_contract_version 1
+    adapter_contract_requires agents
+    adapter_contract_owned "$output/instructions"
+    adapter_contract_owned "$output/prompts"
+    adapter_contract_owned "$output/agents"
+    adapter_contract_owned "$output/skills"
+    adapter_contract_legacy "$output/copilot-instructions.md"
+}
+
 # Sync rules to Copilot format. Only path-scoped rules are emitted —
 # always-on rules live in AGENTS.md (read by Copilot natively).
 sync_copilot_rules() {

package/engine/adapters/cursor.sh

@@ -13,6 +13,21 @@
 
 source "$(dirname "${BASH_SOURCE[0]}")/../lib/common.sh"
 
+adapter_contract_cursor() {
+    local output="${1%/}"
+    adapter_contract_version 1
+    adapter_contract_requires agents
+    adapter_contract_owned "$output/rules"
+    adapter_contract_owned "$output/agents"
+    adapter_contract_owned "$output/skills"
+    adapter_contract_legacy ".cursorrules"
+    adapter_contract_legacy "$output/commands"
+    adapter_contract_preserve "$output/settings.json"
+    adapter_contract_ignore ".cursorrules"
+    adapter_contract_ignore "$output/*"
+    adapter_contract_include "$output/settings.json"
+}
+
 # Sync rules to Cursor format (.md -> .mdc, paths -> globs)
 sync_cursor_rules() {
     local repo_root="$1"

package/engine/adapters/opencode.sh

@@ -26,6 +26,17 @@
 
 source "$(dirname "${BASH_SOURCE[0]}")/../lib/common.sh"
 
+adapter_contract_opencode() {
+    local output="${1%/}"
+    adapter_contract_version 1
+    adapter_contract_requires agents
+    adapter_contract_managed ".agents/skills"
+    adapter_contract_owned "$output/agents"
+    adapter_contract_managed "$output/commands"
+    adapter_contract_ignore ".agents/skills/"
+    adapter_contract_ignore "$output/agents/"
+}
+
 # Strip frontmatter, return body only.
 # Direct call to the shared `strip_frontmatter` helper in lib/common.sh —
 # duplicating the awk block here would violate the "all parsing in common.sh"