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

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 @@
-9be4945e8194e82d53d510e72b7a30769ff30e95
+5b60eb9e97337751d1e5390cae4919aedf26ab7a

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"

package/engine/adapters/pi.sh

@@ -15,6 +15,20 @@
 
 source "$(dirname "${BASH_SOURCE[0]}")/../lib/common.sh"
 
+adapter_contract_pi() {
+    local output="${1%/}"
+    adapter_contract_version 1
+    adapter_contract_requires agents
+    adapter_contract_managed ".agents/skills"
+    adapter_contract_owned "$output/intelligence-sync"
+    adapter_contract_managed "$output/extensions"
+    adapter_contract_managed "$output/prompts"
+    adapter_contract_ignore ".agents/skills/"
+    adapter_contract_ignore "$output/intelligence-sync/"
+    adapter_contract_ignore "$output/extensions/intelligence-sync-rules.ts"
+    adapter_contract_ignore "$output/prompts/intelligence-agent-*.md"
+}
+
 pi_ts_escape() {
     local s="$1"
     s="${s//\\/\\\\}"
@@ -193,13 +207,12 @@ sync_pi_agents() {
 
             access_note=""
             if [ "$access" = "readonly" ]; then
-                access_note=$(cat <<'EOF'
-## Access Mode
+                # Bash 3.2 (the macOS system shell) misparses an apostrophe in
+                # a quoted heredoc nested inside command substitution.
+                access_note="## Access Mode
 
 Default to read-only analysis. Do not change files or run mutating commands unless the user explicitly asks you to override this agent's normal restriction.
-
-EOF
-)
+"
             fi
 
             {

package/engine/lib/adapter-contract.sh

@@ -0,0 +1,100 @@
+#!/bin/bash
+# Declarative adapter ownership contract shared by the engine and CLI.
+#
+# Every adapter exposes adapter_contract_<name> <configured-output>. The
+# function emits tab-separated records through the helpers below. Keeping the
+# declaration beside sync_to_<name>() makes backup, rollback, git policy and
+# lifecycle checks consume the same ownership model as the writer itself.
+
+adapter_contract_version()  { printf 'version\t%s\n' "$1"; }
+adapter_contract_requires() { printf 'requires\t%s\n' "$1"; }
+adapter_contract_owned()    { printf 'owned\t%s\n' "$1"; }
+adapter_contract_managed()  { printf 'managed\t%s\n' "$1"; }
+adapter_contract_legacy()   { printf 'legacy\t%s\n' "$1"; }
+adapter_contract_preserve() { printf 'preserve\t%s\n' "$1"; }
+adapter_contract_ignore()   { printf 'ignore\t%s\n' "$1"; }
+adapter_contract_include()  { printf 'include\t%s\n' "$1"; }
+
+adapter_contract_function() {
+    printf 'adapter_contract_%s' "$1"
+}
+
+# Reject records that could address anything outside the repository. Contract
+# paths are always repo-relative; ignore/include records may contain globs.
+adapter_contract_safe_path() {
+    local path="$1"
+    case "$path" in
+        ""|/*|*\\*|[A-Za-z]:*|..|../*|*/../*|*/..|*$'\t'*|*$'\n'*) return 1 ;;
+        *) return 0 ;;
+    esac
+}
+
+adapter_contract_safe_concrete_path() {
+    adapter_contract_safe_path "$1" || return 1
+    case "$1" in
+        *'*'*|*'?'*|*'['*) return 1 ;;
+        *) return 0 ;;
+    esac
+}
+
+# adapter_contract_records <adapter-name> <adapter-file> <configured-output>
+# Source and query in a subshell so a project adapter cannot leak shell state
+# into the caller. Project adapters are trusted executable code during sync;
+# the isolation here is for correctness, not a security boundary.
+adapter_contract_records() (
+    local name="$1" file="$2" output="$3" fn line kind value saw_version=0
+    # shellcheck source=/dev/null
+    source "$file"
+    fn="$(adapter_contract_function "$name")"
+    declare -F "$fn" >/dev/null 2>&1 || {
+        echo "ERROR: adapter '$name' has no $fn contract" >&2
+        return 1
+    }
+    while IFS= read -r line; do
+        [ -n "$line" ] || continue
+        kind="${line%%$'\t'*}"
+        if [ "$kind" = "$line" ]; then
+            echo "ERROR: adapter '$name' emitted a malformed contract record" >&2
+            return 1
+        fi
+        value="${line#*$'\t'}"
+        case "$kind" in
+            version)
+                [ "$value" = "1" ] || {
+                    echo "ERROR: adapter '$name' uses unsupported contract version '$value'" >&2
+                    return 1
+                }
+                saw_version=1
+                ;;
+            requires)
+                case "$value" in
+                    ""|[!abcdefghijklmnopqrstuvwxyz]*|*[!abcdefghijklmnopqrstuvwxyz0123456789_]*)
+                        echo "ERROR: adapter '$name' declares invalid requirement '$value'" >&2
+                        return 1
+                        ;;
+                esac
+                ;;
+            owned|managed|legacy|preserve)
+                adapter_contract_safe_concrete_path "$value" || {
+                    echo "ERROR: adapter '$name' declares unsafe $kind path '$value'" >&2
+                    return 1
+                }
+                ;;
+            ignore|include)
+                adapter_contract_safe_path "$value" || {
+                    echo "ERROR: adapter '$name' declares unsafe $kind path '$value'" >&2
+                    return 1
+                }
+                ;;
+            *)
+                echo "ERROR: adapter '$name' emitted unknown contract record '$kind'" >&2
+                return 1
+                ;;
+        esac
+        printf '%s\n' "$line"
+    done < <("$fn" "$output")
+    [ "$saw_version" -eq 1 ] || {
+        echo "ERROR: adapter '$name' contract did not declare version 1" >&2
+        return 1
+    }
+)

package/engine/sync.sh

@@ -19,6 +19,7 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
 source "$SCRIPT_DIR/lib/common.sh"
 source "$SCRIPT_DIR/lib/contract.sh"
+source "$SCRIPT_DIR/lib/adapter-contract.sh"
 
 if [ -z "${CONFIG_FILE:-}" ] || [ ! -f "${CONFIG_FILE:-}" ]; then
     is_status config-missing "CONFIG_FILE=${CONFIG_FILE:-}"
@@ -85,31 +86,6 @@ echo "  Config: $CONFIG_FILE"
 echo "  Root:   $REPO_ROOT"
 echo ""
 
-# Invariant: AGENTS.md is the canonical carrier of always-on rules for
-# Cursor / Copilot / Codex / Pi / opencode (their adapters skip always-on
-# rules to avoid duplication, since each tool reads AGENTS.md natively for
-# baseline project context). If those targets are enabled, `agents` must
-# also be enabled — otherwise always-on rules go nowhere for those tools.
-# Skip the check when the user requested a single target via $TARGET_FILTER:
-# they may be syncing only one IDE intentionally.
-if [ -z "$TARGET_FILTER" ]; then
-    agents_enabled=$(is_target_enabled "$CONFIG_FILE" "agents")
-    if [ "$agents_enabled" != "1" ]; then
-        # AGENTS.md-dependent adapters: any tool whose adapter skips always-on
-        # rule emission (because the tool reads AGENTS.md natively) must be
-        # listed here. Add new adapters to this list when they ship.
-        for tool in cursor copilot codex pi opencode; do
-            if [ "$(is_target_enabled "$CONFIG_FILE" "$tool")" = "1" ]; then
-                echo "ERROR: targets.$tool is enabled but targets.agents is not." >&2
-                echo "  $tool relies on AGENTS.md to deliver always-on rules — without it," >&2
-                echo "  always-on rules would be invisible to $tool." >&2
-                echo "  Either enable targets.agents in $CONFIG_FILE, or disable targets.$tool." >&2
-                exit 1
-            fi
-        done
-    fi
-fi
-
 # Lint frontmatter across all source files (rules, agents, skills).
 # Catches issues like unquoted colons that strict YAML consumers reject.
 for section in rules agents skills; do
@@ -167,6 +143,88 @@ for adapters_dir in "$SCRIPT_DIR/adapters" "$INTELLIGENCE_DIR/adapters"; do
     done
 done
 
+# Validate every selected adapter contract before any output is touched, then
+# snapshot the declared write-set. If a later adapter fails, the EXIT handler
+# restores all earlier adapter outputs so sync is atomic from the repository's
+# point of view.
+SYNC_TX_DIR="$(mktemp -d -t intelligence-sync-XXXXXX)"
+SYNC_TX_INDEX="$SYNC_TX_DIR/paths.tsv"
+SYNC_TX_SEEN="$SYNC_TX_DIR/seen"
+mkdir -p "$SYNC_TX_DIR/data"
+: > "$SYNC_TX_INDEX"
+: > "$SYNC_TX_SEEN"
+SYNC_TX_ACTIVE=0
+
+snapshot_sync_path() {
+    local adapter_name="$1" rel="$2" src index present=0
+    grep -Fqx -- "$rel" "$SYNC_TX_SEEN" && return 0
+    printf '%s\n' "$rel" >> "$SYNC_TX_SEEN"
+    validate_output_path "$REPO_ROOT" "$CONFIG_FILE" "$adapter_name" "$REPO_ROOT/$rel"
+    index="$(wc -l < "$SYNC_TX_INDEX" | tr -d ' ')"
+    src="$REPO_ROOT/$rel"
+    if [ -e "$src" ] || [ -L "$src" ]; then
+        cp -a "$src" "$SYNC_TX_DIR/data/$index"
+        present=1
+    fi
+    printf '%s\t%s\t%s\n' "$index" "$rel" "$present" >> "$SYNC_TX_INDEX"
+}
+
+restore_sync_snapshot() {
+    local index rel present dst
+    while IFS=$'\t' read -r index rel present; do
+        [ -n "$rel" ] || continue
+        dst="$REPO_ROOT/$rel"
+        rm -rf "$dst"
+        if [ "$present" = "1" ]; then
+            mkdir -p "$(dirname "$dst")"
+            cp -a "$SYNC_TX_DIR/data/$index" "$dst"
+        fi
+    done < "$SYNC_TX_INDEX"
+}
+
+finish_sync_transaction() {
+    local rc=$?
+    trap - EXIT INT TERM
+    set +e
+    if [ "${SYNC_TX_ACTIVE:-0}" = "1" ] && [ "$rc" -ne 0 ]; then
+        restore_sync_snapshot
+        echo "ERROR: sync failed; all adapter-owned paths were restored to their pre-sync state." >&2
+    fi
+    rm -rf "$SYNC_TX_DIR"
+    exit "$rc"
+}
+trap finish_sync_transaction EXIT
+trap 'exit 130' INT TERM
+
+preflight_idx=0
+while [ "$preflight_idx" -lt "${#ADAPTERS[@]}" ]; do
+    adapter="${ADAPTERS[$preflight_idx]}"
+    adapter_file="${ADAPTER_FILES[$preflight_idx]}"
+    preflight_idx=$((preflight_idx + 1))
+    if [ -n "$TARGET_FILTER" ] && [ "$adapter" != "$TARGET_FILTER" ]; then
+        continue
+    fi
+    [ "$(is_target_enabled "$CONFIG_FILE" "$adapter")" = "1" ] || continue
+    output="$(get_target_output "$CONFIG_FILE" "$adapter")"
+    [ -n "$output" ] || output=".$adapter"
+    validate_output_path "$REPO_ROOT" "$CONFIG_FILE" "$adapter" "$REPO_ROOT/$output"
+    records="$(adapter_contract_records "$adapter" "$adapter_file" "$output")" || exit 1
+    while IFS=$'\t' read -r kind value; do
+        [ "$kind" = "requires" ] || continue
+        if [ "$(is_target_enabled "$CONFIG_FILE" "$value")" != "1" ]; then
+            echo "ERROR: targets.$adapter requires enabled target '$value'." >&2
+            echo "       Enable it first: intelligence adapter enable $value" >&2
+            exit 1
+        fi
+    done <<< "$records"
+    while IFS=$'\t' read -r kind value; do
+        case "$kind" in
+            owned|managed) snapshot_sync_path "$adapter" "$value" ;;
+        esac
+    done <<< "$records"
+done
+SYNC_TX_ACTIVE=1
+
 synced=0
 adapter_count=${#ADAPTERS[@]}
 adapter_idx=0
@@ -224,6 +282,10 @@ if [ $synced -eq 0 ]; then
     exit 1
 fi
 
+SYNC_TX_ACTIVE=0
+rm -rf "$SYNC_TX_DIR"
+trap - EXIT INT TERM
+
 # Warn about unsynced directories
 warn_unsynced "$REPO_ROOT" "$CONFIG_FILE"
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainova-systems/intelligence",
-  "version": "0.11.0-rc.11",
+  "version": "0.11.0-rc.13",
   "description": "Build, version and distribute AI agent intelligence across your organization — one CLI, versioned Intelligence Packages, and a sync engine for Claude Code, Cursor, Copilot, Codex, Pi and OpenCode.",
   "bin": {
     "intelligence": "bin/intelligence.js"

package/packages/sync/agents/intelligence-architect.md

@@ -47,7 +47,7 @@ The per-artifact checks are procedure, so they live in the meta-skills rather th
 | `intelligence-extract-skill` | turn an observed workflow into a skill |
 | `intelligence-review-skills` | audit the layer for duplication, drift, size, hardcoded paths |
 | `intelligence-learn-from-repository` | propose the initial project-owned layer from repository evidence |
-| `intelligence-learn-from-context` | fold a session's lessons back into the layer |
+| `intelligence-learn-from-context` | recover/finalize onboarding, or later fold a session lesson into the layer |
 | `intelligence-sync` | project the source to every tool channel |
 | `intelligence-update` | interpret and apply the CLI's unified update plan |
 | `intelligence-install-adapter` / `intelligence-uninstall-adapter` | research and manage a tool adapter |

package/packages/sync/references/adapters.md

@@ -42,14 +42,25 @@ To stop syncing a target:
 intelligence adapter disable mytool
 ```
 
-Disabling changes only target state. Generated output is deliberately kept because a generic command cannot know which paths a custom adapter owns. Remove only documented owned paths after reviewing them. A disabled project adapter can be deleted with `intelligence adapter remove mytool`; removal prompts by default, accepts `--apply` for explicit non-interactive use, and also keeps generated output. Built-in adapter source cannot be removed. Use `intelligence adapter list` to inspect source, state and output.
+Disabling changes only target state. Generated output is deliberately kept so disabling is reversible; the adapter contract identifies its paths for review. A disabled project adapter can be deleted with `intelligence adapter remove mytool`; removal prompts by default, accepts `--apply` for explicit non-interactive use, and also keeps generated output. Built-in adapter source cannot be removed. Use `intelligence adapter list` to inspect source, state and output.
 
-## Required function
+## Required interface
 
-The file name and function name form the adapter's identity:
+The file name, contract function and sync function form the adapter's identity:
 
 ```bash
 # <content-dir>/adapters/mytool.sh
+adapter_contract_mytool() {
+    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_to_mytool() {
     local repo_root="$1"
     local config_file="$2"
@@ -59,6 +70,25 @@ sync_to_mytool() {
 }
 ```
 
+The contract accepts the configured repo-relative output path and emits only
+records through these helpers:
+
+| Record | Meaning |
+|---|---|
+| `adapter_contract_version 1` | Required interface version |
+| `adapter_contract_requires <name>` | Another target that must be enabled for a full sync |
+| `adapter_contract_owned <path>` | Path exclusively regenerated by this adapter |
+| `adapter_contract_managed <path>` | Shared or marker-managed path modified by this adapter |
+| `adapter_contract_legacy <path>` | Pre-Intelligence input preserved in the initial backup |
+| `adapter_contract_preserve <path>` | Settings or state preserved in place and included in the initial backup |
+| `adapter_contract_ignore <pattern>` | Exact `.gitignore` pattern managed on enable/init |
+| `adapter_contract_include <pattern>` | Exact negated `.gitignore` pattern managed on enable/init |
+
+All paths are repository-relative. The CLI refuses missing, malformed, unsafe,
+or unsupported contracts before enabling or syncing an adapter. `owned` and
+`managed` paths form the transactional write-set: if any adapter fails, the
+engine restores every selected adapter path to its pre-sync state.
+
 The engine calls:
 
 ```text
@@ -177,8 +207,8 @@ Call `finalize_output_file` on every text file after transformation. It expands
 
 Adapters regenerate output, so cleanup is part of their public contract.
 
-1. Delete only paths the adapter owns. Preserve sibling settings, commands, extensions, workflows and hand-authored files.
-2. Make ownership obvious in `sync_to_<name>()`; the same list is what a user removes after disabling or uninstalling the adapter.
+1. Delete only paths declared `owned`. Preserve sibling settings, commands, extensions, workflows and hand-authored files.
+2. Keep `adapter_contract_<name>()` exactly aligned with every path `sync_to_<name>()` writes or deletes.
 3. Use marker-based cleanup when generated and hand-authored files share a directory. The OpenCode adapter is the reference implementation.
 4. Use `sync_open_skill_dirs` for `.agents/skills/`; multiple adapters share it.
 5. Write only beneath the supplied `output_dir`, except for an explicitly shared standard path handled by a shared helper.
@@ -211,6 +241,13 @@ sync_mytool_rules() {
     done < <(read_yaml_list "$config_file" "rules")
 }
 
+adapter_contract_mytool() {
+    local output="${1%/}"
+    adapter_contract_version 1
+    adapter_contract_owned "$output/rules"
+    adapter_contract_ignore "$output/rules/"
+}
+
 sync_to_mytool() {
     local repo_root="$1" config_file="$2" output_dir="$3"
 
@@ -234,6 +271,8 @@ Verify:
 - skill resources are present;
 - no literal layout tokens remain;
 - hand-authored siblings under the tool root survive;
+- a deliberately failing later adapter restores all earlier output byte-for-byte;
+- `intelligence status --check` accepts the contract and its Git policy;
 - output paths cannot overlap sources or escape the repository;
 - a second sync produces no Git diff.