@ainova-systems/intelligence 0.19.0 → 0.21.0

package/engine/lib/contract.sh

@@ -84,6 +84,11 @@ IS_RC_AMBIGUOUS=3           # conflicting state; agent/human-only — bash never
 IS_RC_AHEAD=4               # project stamped newer than this engine understands
 IS_RC_ABORTED_INCOMPLETE=5  # staged state incomplete; the project was left untouched
 IS_RC_NEEDS_UPDATE=6        # pending schema changes (stamp < engine) — run `intelligence init --apply`
+# `intelligence sync --check` only: generated files differ from what sync would
+# leave, or alignment is pending (IS_STATUS=out-of-date). It shares 2 with
+# config-missing, which a check never reports: the CLI found the manifest, and
+# the check turns any other failure that ends in 2 into 1.
+IS_RC_OUT_OF_DATE=2
 
 # is_status <code-name> [detail] — emit one parseable line for the skill.
 is_status() {

package/engine/sync.sh

@@ -10,6 +10,8 @@
 #   IS_CONTENT_REL     the project's content dir, repo-relative
 #   IS_MODULE_REL      the installed sync package, repo-relative
 #   IS_PROTECTED_DIRS  dirs an adapter output may never overlap
+#   IS_SYNC_CHECK      optional: render, compare and restore, then write
+#                      `same` or `differs` to this file (`sync --check`)
 #
 # Usage: intelligence sync [target]
 
@@ -111,45 +113,19 @@ while IFS=$'\037' read -r section src state _dir alias holders; do
     echo "WARNING: sources.$section '$src' $IS_SOURCE_PROBLEM — skipped; 'intelligence status --check' reports it" >&2
 done <<< "${IS_YL_UNRESOLVED:-}"
 
-# Lint frontmatter across all source files (rules, agents, skills).
-# Catches issues like unquoted colons that strict YAML consumers reject.
-LINT_FILES=()
-LINT_SKILL_DIRS=()
-for section in rules agents skills; do
-    load_yaml_list "$CONFIG_FILE" "$section"
-    while IFS= read -r src; do
-        [ -z "$src" ] && continue
-        src_dir="$REPO_ROOT/$src"
-        [ -d "$src_dir" ] || continue
-        if [ "$section" = "skills" ]; then
-            LINT_SKILL_DIRS+=("$src_dir")
-        else
-            for f in "$src_dir"/*.md; do
-                [ -f "$f" ] && LINT_FILES+=("$f")
-            done
-        fi
-    done <<< "$IS_YAML_LIST"
-done
-# One find for every skills source: it walks its start points in order.
-if [ "${#LINT_SKILL_DIRS[@]}" -gt 0 ]; then
-    while IFS= read -r f; do
-        [ -n "$f" ] && LINT_FILES+=("$f")
-    done < <(find "${LINT_SKILL_DIRS[@]}" -mindepth 2 -maxdepth 2 -name 'SKILL.md' 2>/dev/null)
-fi
-if [ "${#LINT_FILES[@]}" -gt 0 ]; then
-    lint_frontmatter_files "${LINT_FILES[@]}"
-fi
 
 # Sources stay read-only for the whole run (validate_output_path refuses an
-# output inside one), so read_source_artifact_files enumerates each section
-# once, in this shell, and its later callers — the agents adapter, the shared
-# skill directory, the context report — replay it. Adapters that list sources
-# with in-shell globs spawn nothing and keep their own, locale-ordered listing.
+# output inside one), so the source catalog is built once, in this shell, and
+# every renderer replays it: AGENTS.md, every adapter, the shared skill
+# directory and the context report read sources through source_artifacts_var
+# (decision 0021). Building it names every artifact, settles which of a name
+# renders, refuses ambiguous names before any output is touched, settles every
+# symlink in a skills source (decision 0017), and lints the frontmatter of every
+# source — skills as the inventory renders them: SKILL.md behind a link inside
+# its source is linted, one that leaves its source is never read.
 # shellcheck disable=SC2034  # read by read_source_artifact_files in lib/common.sh
 IS_SOURCE_FILES_MEMO=1
-for section in rules agents skills; do
-    read_source_artifact_files "$REPO_ROOT" "$CONFIG_FILE" "$section"
-done
+source_catalog_build "$REPO_ROOT" "$CONFIG_FILE" lint
 
 # Adapters come from two places, discovered by filename (minus `.sh`,
 # `_template` excluded):
@@ -190,6 +166,11 @@ for adapters_dir in "$SCRIPT_DIR/adapters" "$INTELLIGENCE_DIR/adapters"; do
     done
 done
 
+# A `targets:` or `exclude_targets:` id must name an adapter this project has,
+# enabled or not, or the group `committed` (decision 0021). Refused here,
+# before anything is snapshotted or written.
+source_catalog_check_ids "$REPO_ROOT" "${ADAPTERS[*]}" || exit 1
+
 # 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
@@ -211,6 +192,17 @@ SYNC_PARALLEL=1
 SYNC_BG_PIDS=()
 SYNC_COPY_INDEXES=()
 
+# An accepted output-root directory link is a write path, unlike a nested
+# generated asset link. Checks must retain the bytes behind that root too.
+snapshot_sync_entry() {
+    local src="$1" index="$2"
+    cp -a "$src" "$SYNC_TX_DIR/data/$index" || return $?
+    if [ -n "${IS_SYNC_CHECK:-}" ] && [ -L "$src" ] && [ -d "$src" ]; then
+        mkdir -p "$SYNC_TX_DIR/targets/$index" || return $?
+        cp -a "$src/." "$SYNC_TX_DIR/targets/$index" || return $?
+    fi
+}
+
 snapshot_sync_path() {
     local adapter_name="$1" rel="$2" src index present=0
     case "$SYNC_TX_SEEN_LIST" in
@@ -224,11 +216,11 @@ snapshot_sync_path() {
         # Copies of distinct paths into distinct slots: they can overlap, and
         # The snapshot wait before the render collects every status.
         if [ "$SYNC_PARALLEL" = 1 ]; then
-            cp -a "$src" "$SYNC_TX_DIR/data/$index" 2> "$SYNC_TX_DIR/copy.$index.err" &
+            snapshot_sync_entry "$src" "$index" 2> "$SYNC_TX_DIR/copy.$index.err" &
             SYNC_BG_PIDS+=("$!")
             SYNC_COPY_INDEXES+=("$index")
         else
-            cp -a "$src" "$SYNC_TX_DIR/data/$index"
+            snapshot_sync_entry "$src" "$index"
         fi
         present=1
     fi
@@ -274,6 +266,68 @@ wait_sync_jobs() {
     return "$first"
 }
 
+# Compare each entry without following links: copied relative and dangling
+# links describe their targets, not bytes at the snapshot's new location.
+compare_sync_entries() {
+    local snap="$1" live="$2" rc=0 target before
+    if [ -L "$snap" ]; then
+        [ -L "$live" ] || return 1
+        before="$(readlink "$snap")" || return 2
+        target="$(readlink "$live")" || return 2
+        # Source links inside the private copy refer to its root. Compare the
+        # generated target in the original project's coordinate system.
+        if [ -n "${IS_SYNC_CHECK_ROOT:-}" ] && [ -n "${IS_SYNC_CHECK:-}" ]; then
+            case "$before" in "$REPO_ROOT") before="$IS_SYNC_CHECK_ROOT" ;; "$REPO_ROOT"/*) before="$IS_SYNC_CHECK_ROOT/${before#"$REPO_ROOT/"}" ;; esac
+            case "$target" in "$REPO_ROOT") target="$IS_SYNC_CHECK_ROOT" ;; "$REPO_ROOT"/*) target="$IS_SYNC_CHECK_ROOT/${target#"$REPO_ROOT/"}" ;; esac
+        fi
+        [ "$before" = "$target" ] || return 1
+    elif [ -L "$live" ]; then
+        return 1
+    elif [ -f "$snap" ] && [ -f "$live" ]; then
+        cmp -s "$snap" "$live" || rc=$?
+        case "$rc" in 0) ;; 1) return 1 ;; *) return 2 ;; esac
+        if [ -x "$snap" ]; then [ -x "$live" ] || return 1; else [ ! -x "$live" ] || return 1; fi
+    elif [ -d "$snap" ] && [ -d "$live" ]; then
+        return 0
+    else
+        return 1
+    fi
+}
+
+compare_sync_snapshot() {
+    local index rel present live snap entry sub
+    while IFS=$'\t' read -r index rel present; do
+        [ -n "$rel" ] || continue
+        live="$REPO_ROOT/$rel"
+        snap="$SYNC_TX_DIR/data/$index"
+        if [ "$present" != 1 ]; then
+            if [ -e "$live" ] || [ -L "$live" ]; then return 1; fi
+            continue
+        fi
+        compare_sync_entries "$snap" "$live" || return $?
+        if [ -d "$SYNC_TX_DIR/targets/$index" ]; then
+            # validate_output_path permitted this physical directory inside
+            # the private project. Only its root is followed; descendants
+            # still use the entry-kind and literal-target comparison.
+            snap="$SYNC_TX_DIR/targets/$index"
+            live="$(cd "$live" && pwd -P)" || return 2
+        fi
+        [ ! -L "$snap" ] && [ -d "$snap" ] || continue
+        # NUL-delimited paths also preserve whitespace and newlines. find's
+        # default walk does not dereference links on GNU or BSD userland.
+        find "$snap" -print0 > "$SYNC_TX_DIR/snapshot.list" || return 2
+        find "$live" -print0 > "$SYNC_TX_DIR/live.list" || return 2
+        while IFS= read -r -d '' entry; do
+            sub="${entry#"$snap"}"
+            compare_sync_entries "$entry" "$live$sub" || return $?
+        done < "$SYNC_TX_DIR/snapshot.list"
+        while IFS= read -r -d '' entry; do
+            sub="${entry#"$live"}"
+            [ -e "$snap$sub" ] || [ -L "$snap$sub" ] || return 1
+        done < "$SYNC_TX_DIR/live.list"
+    done < "$SYNC_TX_INDEX"
+}
+
 finish_sync_transaction() {
     local rc=$?
     trap - EXIT INT TERM
@@ -305,6 +359,20 @@ note_agents_dependent() {
 }
 SELECTED_RECORDS=()
 RENDER_PARALLEL="$SYNC_PARALLEL"
+# What a source may render into depends on Git policy only when the catalog
+# holds a local artifact: then every contract is read with the manifest, which
+# may choose that policy (targets.copilot.commit_output), and its ignore and
+# include records become IS_COMMIT_POLICY. Every other sync reads ownership
+# alone, as decision 0020 keeps it (decision 0021).
+policy_manifest=""
+[ "$IS_CAT_NEED_COMMITTED" != 1 ] || policy_manifest="$CONFIG_FILE"
+IS_COMMIT_POLICY=""
+# The tools that read .agents/skills/ and AGENTS.md, by their contracts: a
+# skill lands in .agents/skills/ when it is for any of them, and a shared path
+# that delivers an artifact to a tool outside its targets is named.
+IS_OPEN_SKILLS_READERS=""
+IS_AGENTS_READERS=""
+IS_ENABLED_ADAPTERS=""
 preflight_idx=0
 while [ "$preflight_idx" -lt "${#ADAPTERS[@]}" ]; do
     adapter="${ADAPTERS[$preflight_idx]}"
@@ -315,13 +383,26 @@ while [ "$preflight_idx" -lt "${#ADAPTERS[@]}" ]; do
     target_output_var "$CONFIG_FILE" "$adapter"
     output="$IS_TGT_OUTPUT"
     [ -n "$output" ] || output=".$adapter"
-    records="$(adapter_contract_records "$adapter" "$adapter_file" "$output")" || exit 1
+    records="$(adapter_contract_records "$adapter" "$adapter_file" "$output" "$policy_manifest")" || exit 1
 
     if ! adapter_claims_add_records "$adapter" "$records"; then
         echo "ERROR: $IS_ADAPTER_CLAIM_CONFLICT." >&2
         echo "       Give each adapter its own output: intelligence adapter list" >&2
         exit 1
     fi
+    IS_ENABLED_ADAPTERS="$IS_ENABLED_ADAPTERS${IS_ENABLED_ADAPTERS:+ }$adapter"
+    while IFS=$'\t' read -r kind value; do
+        case "$kind" in
+            requires) [ "$value" != agents ] || IS_AGENTS_READERS="$IS_AGENTS_READERS${IS_AGENTS_READERS:+ }$adapter" ;;
+            ignore|include) IS_COMMIT_POLICY="$IS_COMMIT_POLICY$adapter"$'\t'"$kind"$'\t'"$value"$'\n' ;;
+            owned|managed)
+                adapter_contract_rel_path "$value"
+                if [ "$IS_ADAPTER_REL_PATH" = ".agents/skills" ]; then
+                    IS_OPEN_SKILLS_READERS="$IS_OPEN_SKILLS_READERS${IS_OPEN_SKILLS_READERS:+ }$adapter"
+                fi
+                ;;
+        esac
+    done <<< "$records"
 
     if [ -n "$TARGET_FILTER" ] && [ "$adapter" != "$TARGET_FILTER" ]; then
         # Not selected: its claims are registered, its output is not touched.
@@ -356,6 +437,13 @@ while [ "$preflight_idx" -lt "${#ADAPTERS[@]}" ]; do
         esac
     done <<< "$records"
 done
+# shellcheck disable=SC2034  # read by output_committed in lib/common.sh
+[ -z "$policy_manifest" ] || IS_COMMIT_POLICY_SET=1
+# A local artifact that names a committed output in its targets is refused
+# before any adapter writes; then every shared path that delivers an artifact
+# beyond its targets, and every target no channel reaches, is named once.
+source_catalog_check_local "$REPO_ROOT" || exit 1
+source_catalog_warn "$REPO_ROOT"
 
 # Every adapter that requires `agents` skips always-on rules because AGENTS.md
 # carries them — and each of those tools reads AGENTS.md at the workspace root
@@ -625,6 +713,25 @@ if [ $synced -eq 0 ]; then
     exit 1
 fi
 
+# A check renders exactly like a sync, then compares every snapshotted path
+# with what the render left and restores the snapshot whatever the answer: it
+# never changes a file. The transaction stays active until the restore is
+# complete, so an interrupted restore is finished by the EXIT handler.
+if [ -n "${IS_SYNC_CHECK:-}" ]; then
+    check_rc=0
+    compare_sync_snapshot || check_rc=$?
+    case "$check_rc" in
+        0) check_verdict=same ;;
+        1) check_verdict=differs ;;
+        *)
+            echo "ERROR: sync --check could not compare the rendered output with its snapshot." >&2
+            exit 1
+            ;;
+    esac
+    restore_sync_snapshot
+    printf '%s\n' "$check_verdict" > "$IS_SYNC_CHECK"
+fi
+
 SYNC_TX_ACTIVE=0
 
 # After rendering, three read-only reports, in this order:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainova-systems/intelligence",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "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/references/adapters.md

@@ -141,22 +141,26 @@ The engine has already loaded `engine/lib/common.sh` before it sources the adapt
 
 `sources.rules`, `sources.agents` and `sources.skills` contain repo-relative directory paths. Packages have already been resolved, fetched and pinned by the CLI, so package content appears as an ordinary path under `.intelligence/packages/`. The manifest may name a package's directory by the package's full name or alias instead; `read_yaml_list` and `load_yaml_list` hand an adapter the store path either way, and leave out a reference that names nothing, so an adapter reads every source the same way. Adapters never perform network access or parse `packages:`.
 
-Iterate a source section in manifest order:
+Read a section through the source catalog, never with a glob of your own. `AGENTS.md`, every built-in adapter and the template read it the same way (decision 0021):
 
 ```bash
-while IFS= read -r src; do
-    [ -n "$src" ] || continue
-    dir="$(resolve_source_dir "$repo_root" "$src")"
-    [ -d "$dir" ] || continue
-
-    for file in "$dir"/*.md; do
-        [ -f "$file" ] || continue
-        # transform file
-    done
-done < <(read_yaml_list "$config_file" "rules")
+output_rel_var "$repo_root" "$output_dir"
+source_artifacts_var "$repo_root" "$config_file" rules mytool "$IS_OUTPUT_REL/rules/{}.md"
+for ((i = 0; i < ${#IS_SOURCE_FILES[@]}; i++)); do
+    # IS_SOURCE_FILES[i] is the source, IS_SOURCE_NAMES[i] its rendered name,
+    # IS_SOURCE_SCOPED[i] is 1 for a rule with paths:
+    :
+done
 ```
 
-Later sources intentionally overwrite same-named artifacts from earlier sources. Package sources are wired before project sources, so project content can override a package artifact by name.
+The last argument is the repository-relative path an artifact lands at, `{}` standing for its name. The catalog lists sources in manifest order and each directory's entries in byte order, and settles four things before any adapter runs:
+
+- **Names.** An artifact is named by its file name without a leading `.`, `.md` and a trailing `.local`, a skill by its directory name without the leading `.` and `.local`: `.draft.md` renders as `draft`, `deploy.local/` as `deploy/`. Write each output under `IS_SOURCE_NAMES`, never under the source file name; `finalize_copy_named` and `copy_skill_bundle_dirs_named` take the `IS_SOURCE_NAME_MAP` the call leaves.
+- **Overrides.** Of two artifacts with one name, only the later source's is listed. Package sources are wired before project sources, so project content overrides a package artifact by name. Two of one name in one directory, or a local and a non-local one anywhere, refuse the sync before any adapter runs.
+- **Local artifacts.** A `*.local.md` rule or agent and a `*.local/` skill are listed only for an output path no `ignore` record of your contract covers — what Git tracks never holds one. That is why the path must be the real one: an adapter that globs sources itself, or names a path it does not write, can put a teammate's local file into a committed output.
+- **Targets.** An artifact whose `targets:` leaves your adapter out, or whose `exclude_targets:` names it, is not listed for it; `committed` in either field is resolved against the path you pass ([Selecting adapters](conventions.md#selecting-adapters)). Your adapter's id is a valid target as soon as its file exists, and sync has removed both fields from every copy the shared helpers write; strip them from any frontmatter you copy yourself.
+
+`IS_SOURCE_IN_AGENTS` is 1 when `AGENTS.md` carries the artifact too. An adapter whose tool reads `AGENTS.md` renders an always-on rule only where it is 0: that is a local rule, or one whose targets leave `agents` out, and the tool's own always-on channel is the only way it arrives.
 
 ## Shared functions
 
@@ -164,6 +168,10 @@ Use the engine library instead of copying parsers or file-handling logic.
 
 | Function | Purpose |
 |---|---|
+| `source_artifacts_var(root, config, section, adapters, output)` | The artifacts of a section that render for one of `adapters` at `output` (`{}` is the name): `IS_SOURCE_FILES`, `IS_SOURCE_NAMES`, `IS_SOURCE_SCOPED`, `IS_SOURCE_IN_AGENTS`, `IS_SOURCE_NAME_MAP`. |
+| `output_rel_var(root, output_dir)` | The output's repository-relative path in `IS_OUTPUT_REL`, as `source_artifacts_var` takes it. |
+| `finalize_copy_named(dest, map, src...)` | Copy-and-finalize every source into `dest` under its rendered name, in one process. |
+| `copy_skill_bundle_dirs_named(tool, dest_root, map, src...)` | `copy_skill_bundle_dirs_for` with each skill copied under its rendered name. |
 | `resolve_source_dir(repo_root, source)` | Resolve a manifest source to its local directory. |
 | `read_yaml_list(config, section)` | Stream entries from `sources.<section>`, package references as their store paths. |
 | `load_yaml_list(config, section)` | Same list into `IS_YAML_LIST`, cached — no subprocess on repeat reads. |
@@ -195,23 +203,27 @@ Prefer the batched forms inside per-file loops: a process spawn costs tens of mi
 
 Rules without `paths:` are always-on. Rules with `paths:` are scoped.
 
-Intelligence routes always-on rules once through `AGENTS.md` for tools that consume it. An adapter for such a tool should not copy those rules again. If the tool has a native scoped-rule channel, transform `paths:` to the tool's equivalent.
+Intelligence routes always-on rules once through `AGENTS.md` for tools that consume it. An adapter for such a tool should not copy those rules again — except one `AGENTS.md` does not carry (`IS_SOURCE_IN_AGENTS` is 0), which reaches the tool only through its own always-on channel. If the tool has a native scoped-rule channel, transform `paths:` to the tool's equivalent.
 
-| Built-in | Always-on rules | Scoped rules |
-|---|---|---|
-| `agents` | Inline in `AGENTS.md` | List with links |
-| `antigravity` | Omit; reads `AGENTS.md` | `.agents/rules/*.md` with `trigger: glob` and `globs:` |
-| `claude` | Copy | Copy with `paths:` preserved |
-| `cursor` | Omit; reads `AGENTS.md` | `.mdc` with `globs:` |
-| `copilot` | Omit; reads `AGENTS.md` | `.instructions.md` with `applyTo:` |
-| `codex` | Omit; reads `AGENTS.md` | No native channel |
-| `pi` | Omit; reads `AGENTS.md` | Generated on-demand files and extension |
-| `opencode` | Omit; reads `AGENTS.md` | No native channel |
+| Built-in | Always-on rules | Always-on, not in `AGENTS.md` | Scoped rules |
+|---|---|---|---|
+| `agents` | Inline in `AGENTS.md` | — | List with links |
+| `antigravity` | Omit; reads `AGENTS.md` | `.agents/rules/*.md` with `trigger: always_on` | `.agents/rules/*.md` with `trigger: glob` and `globs:` |
+| `claude` | Copy | Copy | Copy with `paths:` preserved |
+| `cursor` | Omit; reads `AGENTS.md` | `.mdc` with `alwaysApply: true` | `.mdc` with `globs:` |
+| `copilot` | Omit; reads `AGENTS.md` | `.instructions.md` with `applyTo: "**"` | `.instructions.md` with `applyTo:` |
+| `codex` | Omit; reads `AGENTS.md` | `AGENTS.override.md`: all of `AGENTS.md` plus these rules | No native channel |
+| `pi` | Omit; reads `AGENTS.md` | Added to the system prompt by the generated extension | Generated on-demand files and extension |
+| `opencode` | Omit; reads `AGENTS.md` | No channel; sync warns | No native channel |
+
+Codex reads `AGENTS.override.md` instead of `AGENTS.md` in the same directory, so the Codex adapter writes it — the whole rendered `AGENTS.md`, then the rules only Codex receives — while such a rule exists, and removes it when none does. Its contract manages and ignores the path; a file there that Intelligence did not generate is never touched, and a render that needs the path refuses until it is moved.
 
 If a new adapter relies on `AGENTS.md` for always-on rules, its target must require `agents`. Add that invariant to `engine/sync.sh` when contributing the adapter upstream.
 
 Every successful sync prints an adapter-agnostic `CONTEXT:` summary with source byte totals and file counts. It separates always-on rules from custom context (scoped rules, agent prompts and skill entry points), then reports a numeric `agents-md` byte count and `generated`, `not-generated`, or `disabled` status; supporting skill assets are excluded until explicitly read. Adapter-specific hard limits and suppression controls stay inside the adapter that owns them.
 
+Print an adapter warning on stderr as one unindented line starting `WARNING:`. `sync --compact`, which `intelligence init` runs, keeps exactly those lines and drops indented progress, so a warning in any other form never reaches the reader.
+
 The Codex adapter checks its `project_doc_max_bytes` default (32 KiB). When generated `AGENTS.md` exceeds it, sync prints the byte count and a sufficient Codex setting. The warning says "may truncate" because a developer can already have a larger override. `targets.codex.warn_project_doc_limit` accepts `true` or omission for the default threshold, a positive byte count to match another effective limit, or `false` to disable the Intelligence warning. Both inline and block target forms work, and the field does not change Codex configuration. The warning remains visible in `sync --compact`.
 
 The Antigravity adapter checks the 12,000-character limit its documentation
@@ -237,7 +249,9 @@ Skills follow the [Agent Skills standard](https://agentskills.io). Copy each ski
 copy_skill_bundle "$source_skill_dir" "$output_dir/skills/$skill_name"
 ```
 
-Do not use plain `cp` for skill bundles. `copy_skill_bundle` preserves non-Markdown assets, avoids materializing symlink targets, normalizes Markdown, expands layout tokens and quotes `description` and `argument-hint` where strict YAML readers require strings. It renders `effort:` as the shared tree does; a tree only one tool reads uses `copy_skill_bundle_dirs_for <tool>`, so the copy carries that tool's level or no effort at all.
+Do not use plain `cp` for skill bundles. `copy_skill_bundle` preserves non-Markdown assets, normalizes Markdown, expands layout tokens and quotes `description` and `argument-hint` where strict YAML readers require strings. It renders `effort:` as the shared tree does; a tree only one tool reads uses `copy_skill_bundle_dirs_for <tool>`, so the copy carries that tool's level or no effort at all. It never writes a symlink; how a link in a skills source renders is defined in [conventions](conventions.md#skill-body-and-resources).
+
+`source_artifacts_var ... skills` lists only the skills sync renders: one whose directory or `SKILL.md` is a link leaving its source is left out of every output, and sync has already warned about it once. Copy them with `copy_skill_bundle_dirs_named` and the call's `IS_SOURCE_NAME_MAP`, so `deploy.local/` lands as `deploy/`.
 
 Antigravity, Codex, Pi and OpenCode share `.agents/skills/`. Any adapter writing that open-standard directory must call `sync_open_skill_dirs`; it is the single lifecycle owner for immediate skill subdirectories.
 
@@ -303,21 +317,16 @@ This example copies rules without frontmatter. A real adapter must decide how th
 #!/bin/bash
 
 sync_mytool_rules() {
-    local repo_root="$1" config_file="$2" output_dir="$3"
+    local repo_root="$1" config_file="$2" output_dir="$3" i out
     mkdir -p "$output_dir/rules"
 
-    while IFS= read -r src; do
-        [ -n "$src" ] || continue
-        local dir
-        dir="$(resolve_source_dir "$repo_root" "$src")"
-        [ -d "$dir" ] || continue
-
-        for file in "$dir"/*.md; do
-            [ -f "$file" ] || continue
-            strip_frontmatter "$file" > "$output_dir/rules/$(basename "$file")"
-            finalize_output_file "$output_dir/rules/$(basename "$file")"
-        done
-    done < <(read_yaml_list "$config_file" "rules")
+    output_rel_var "$repo_root" "$output_dir"
+    source_artifacts_var "$repo_root" "$config_file" rules mytool "$IS_OUTPUT_REL/rules/{}.md"
+    for ((i = 0; i < ${#IS_SOURCE_FILES[@]}; i++)); do
+        out="$output_dir/rules/${IS_SOURCE_NAMES[i]}.md"
+        strip_frontmatter "${IS_SOURCE_FILES[i]}" > "$out"
+        finalize_output_file "$out"
+    done
 }
 
 adapter_contract_mytool() {
@@ -347,6 +356,7 @@ Verify:
 
 - native file names, frontmatter and model/permission mappings;
 - scoped and always-on routing without duplicated context;
+- a dotfile or `*.local.md` source renders under its name, and a local one only into outputs the contract ignores;
 - skill resources are present;
 - no literal layout tokens remain;
 - hand-authored siblings under the tool root survive;
@@ -366,6 +376,6 @@ For a built-in adapter, add the same assertions to the repository's smoke or lif
 | `claude` | `.claude/rules`, `.claude/agents`, `.claude/skills` |
 | `cursor` | `.cursor/rules`, `.cursor/agents`, `.cursor/skills` |
 | `copilot` | `.github/instructions`, `.github/agents`, `.github/skills` |
-| `codex` | `.codex/agents`, `.agents/skills` |
+| `codex` | `.codex/agents`, `.agents/skills`, marker-owned `AGENTS.override.md` |
 | `pi` | `.pi/intelligence-sync`, `.pi/extensions`, `.pi/prompts`, `.agents/skills` |
 | `opencode` | `.opencode/agents`, marker-owned `.opencode/commands`, `.agents/skills` |

package/packages/sync/references/conventions.md

@@ -73,7 +73,7 @@ sources:
 
 A package's directory may also be named by the package instead of its store path: `@ainova-systems/sync/rules` names folder `rules` of the package `packages:` declares as `@ainova-systems/sync`, and `sync:rules` names it through the alias that package declares (`intelligence package alias @ainova-systems/sync sync`). Both render exactly as the store path, and both are installed package content like it: edit that content in its source repository. The CLI writes store paths and never rewrites a reference a person wrote; an `@scope/name/...` entry for a package `packages:` does not declare is an ordinary project path.
 
-Missing project-owned source directories are skipped, so a package-only project need not create empty `rules/`, `agents/` or `skills/` directories. Source order matters: later files with the same artifact name overwrite earlier ones. Package sources are wired before project sources so the project can override a package artifact deliberately.
+Missing project-owned source directories are skipped, so a package-only project need not create empty `rules/`, `agents/` or `skills/` directories. Source order matters: of two artifacts with one name, the later source's renders everywhere, `AGENTS.md` included, and the earlier one renders nowhere (see [Artifact names](#artifact-names-and-local-artifacts)). Package sources are wired before project sources so the project can override a package artifact deliberately.
 
 Project-owned entries are managed with `intelligence source add|remove|list` rather than by hand — it validates the path against the way the engine resolves it and prints the resulting order. `add` appends by default; `--before <entry>` / `--after <entry>` place content that should behave like a package ahead of the project's own directories.
 
@@ -164,6 +164,41 @@ Common skill verbs:
 
 The verb describes the outcome, not whether the skill implements the work or delegates to another command or skill.
 
+## Artifact names and local artifacts
+
+An artifact's name is its file name without a leading `.`, `.md` and a trailing `.local`; a skill's is its directory name without the leading `.` and the trailing `.local`. `backend.md`, `.backend.md` and `backend.local.md` are all the rule `backend`, `deploy.local/` is the skill `deploy`, and every generated copy carries the name: `.claude/rules/backend.md`, `.cursor/rules/backend.mdc`, `.claude/skills/deploy/`. A leading dot means nothing — a dotfile source renders like any other.
+
+Names stay unique. Across sources the later source's artifact renders and the earlier one does not, in `AGENTS.md` as in every tool's output; a skill a later source overrides is replaced whole, resources included. Sync refuses two artifacts with one name in one source directory (`backend.md` beside `.backend.md`), and a local and a non-local artifact with one name anywhere in the sources: a local file that overrode or yielded to a committed one would change what committed output holds.
+
+A **local** artifact is personal or machine-specific guidance — the OS, the shell, a local service, a personal habit — that only this clone loads: a rule or agent named `*.local.md`, or a skill directory named `*.local/`. `intelligence init` writes the matching patterns, for the project's content directory, into its managed `.gitignore` block, so Git and sync agree on which files are local:
+
+```gitignore
+intelligence/rules/*.local.md
+intelligence/agents/*.local.md
+intelligence/skills/*.local/
+```
+
+Sync renders a local artifact only into outputs Git ignores, and never into one it tracks: not `AGENTS.md`, not OpenCode's slash commands, not Copilot's output under `commit_output: true`. A clone without the file therefore renders the same committed files, and `intelligence sync --check` passes in CI. A local always-on rule reaches each tool through that tool's own always-on channel (see [Routing](#routing)), since `AGENTS.md` cannot carry it; OpenCode has none, and sync says so. `intelligence status --check` reports a missing pattern, and `intelligence init` restores it.
+
+A pattern never applies to a file Git already tracks, and a source outside the content directory has no pattern at all. `intelligence status --check` therefore names every file with a local name that Git tracks in a project-owned source: rename it to share it, or `git rm --cached` it to keep it on this machine.
+
+## Selecting adapters
+
+Every rule, agent and skill renders to every enabled adapter. Two frontmatter fields narrow that, for guidance that matters to one tool or should cost no other tool context:
+
+```yaml
+---
+targets: [claude, cursor]      # only these adapters; without it, every enabled one
+exclude_targets: [committed]   # remove these from that set
+---
+```
+
+Both take adapter ids — built-in or the project's own — and the group `committed`: every output path Git tracks, resolved per path from each adapter's contract. `AGENTS.md` always belongs to it, and so do OpenCode's slash commands and, under `commit_output: true`, Copilot's output; OpenCode's agents and the shared `.agents/skills/` do not. Write them in the list syntax `paths:` takes — a flow list `[a, b]` or a block list — and in `SKILL.md` for a skill. `targets: []` renders the artifact nowhere. Sync removes both fields from every generated copy.
+
+An id that names no adapter refuses the sync. An adapter that is not enabled is simply no target: enablement stays the manifest's decision. A local artifact excludes `committed` already, and one whose `targets` names a committed output — `agents`, `committed`, or an adapter all of whose output Git tracks — refuses the sync, because every other clone and CI render that output without it.
+
+Two paths are shared, not per tool, and a filter can withhold an artifact from a shared path but never from one of its readers. An artifact whose set contains `agents` goes into `AGENTS.md` and reaches every tool that reads it. A skill whose set contains any reader of `.agents/skills/` — Antigravity, Codex, Pi, OpenCode — lands there for all of them. Sync prints a `WARNING:` line when a shared path delivers an artifact to an enabled adapter outside its set, and when an adapter in its set can receive it through no channel. An artifact with neither field nor a `.local` name keeps the routing, and the warnings, it always had.
+
 ## Agent conventions
 
 ```yaml
@@ -246,9 +281,12 @@ Rule content in Markdown.
 |---|---|---|---|---|---|
 | Scoped | copied with `paths:` | `.mdc` with `globs:` | `.md` with `trigger: glob` and `globs:` | `.instructions.md` with `applyTo:` | listed in `AGENTS.md`; Pi also gets on-demand files and an extension |
 | Always-on | copied | omitted | omitted | omitted | inlined once into `AGENTS.md` |
+| Always-on, not in `AGENTS.md` | copied | `.mdc` with `alwaysApply: true` | `.md` with `trigger: always_on` | `.instructions.md` with `applyTo: "**"` | Codex: `AGENTS.override.md`; Pi: added to the system prompt by its extension; OpenCode: none |
 
 Cursor, Copilot, Codex, Pi, OpenCode and Antigravity consume `AGENTS.md`, so always-on rules are not duplicated in their tool-specific channels. Claude does not consume `AGENTS.md`, so it receives the full rule set. OpenCode and Codex have no generated path-scoped rule channel; OpenCode users may configure `instructions:` globs themselves.
 
+An always-on rule `AGENTS.md` does not carry — a local one, or one whose set leaves `agents` out (see [Selecting adapters](#selecting-adapters)) — reaches each tool in its set through that tool's own channel instead, the last row. Codex reads `AGENTS.override.md` instead of `AGENTS.md` in the same directory, so the file holds the whole `AGENTS.md` plus the rules only Codex receives; it is ignored, exists only while such a rule does, and one Intelligence did not generate is never touched. Antigravity's `trigger: always_on` belongs to the same undocumented key family as its `trigger: glob`. OpenCode reads instructions only from `AGENTS.md` or its committed `opencode.json`, so it can receive neither a local nor a tool-targeted always-on rule.
+
 Keep always-on rules small. Put narrow framework or component guidance behind `paths:` so unrelated tasks do not pay its context cost.
 
 ## Skill conventions
@@ -270,7 +308,7 @@ argument-hint: "<route-name>"
 4. Report the changed route and verification.
 ```
 
-Standard optional fields (`license`, `compatibility`, `metadata`, `allowed-tools`) and tool extensions pass through unchanged. A tool ignores fields it does not understand. `effort:` is the exception: sync renders it per tool, as [Effort mappings](#effort-mappings) describes.
+Standard optional fields (`license`, `compatibility`, `metadata`, `allowed-tools`) and tool extensions pass through unchanged. A tool ignores fields it does not understand. `effort:` is the exception: sync renders it per tool, as [Effort mappings](#effort-mappings) describes. `targets:` and `exclude_targets:` select the adapters that receive the skill and are removed from every copy ([Selecting adapters](#selecting-adapters)).
 
 `disable-model-invocation: true` makes a skill one only the owner starts, as a slash command: use it for a procedure that changes versions, the lock or generated outputs, where an agent selecting it unasked is the failure. Claude Code, Cursor and Copilot read the field itself; Codex does not, so sync writes `agents/openai.yaml` with `allow_implicit_invocation: false` beside the skill in `.agents/skills/`. Keep the source to the field. A skill that ships its own `agents/openai.yaml` keeps everything else in it: sync adds the policy when the file sets none, and refuses one that sets it otherwise or not as a plain `allow_implicit_invocation: false` directly under `policy:`.
 
@@ -311,6 +349,8 @@ skill-name/
 
 The engine copies the complete skill directory. Promote a helper outside the skill only when multiple skills share it.
 
+A symlink inside a skills source renders as the file or directory it points at when that stays inside the same source, so one source can alias a skill or share a resource between skills. A link that leaves its source, dangles or points at a directory enclosing it is left out with a `WARNING:` line; a skill whose directory or `SKILL.md` is such a link is left out entirely. Add a skill kept elsewhere as its own source or package instead of linking it in. Generated skill directories never contain symlinks.
+
 Size limits are backstops, not quotas:
 
 | Artifact | Hard cap | Response |
@@ -336,12 +376,12 @@ Every line enters a finite context budget. Prefer subtraction, consolidation and
 | Target | Rules | Skills | Agents |
 |---|---|---|---|
 | `agents` | Always-on inlined; scoped listed in `AGENTS.md` | Listed | Listed |
-| Antigravity | `AGENTS.md` plus scoped `.agents/rules/*.md` | `.agents/skills/` | `.agents/agents/*.md` |
+| Antigravity | `AGENTS.md` plus `.agents/rules/*.md` | `.agents/skills/` | `.agents/agents/*.md` |
 | Claude | `.claude/rules/` | `.claude/skills/` | `.claude/agents/` |
-| Cursor | scoped `.cursor/rules/*.mdc` | `.cursor/skills/` | `.cursor/agents/` |
-| Copilot | scoped `.github/instructions/*.instructions.md` | `.github/skills/` | `.github/agents/` |
-| Codex | `AGENTS.md` only | `.agents/skills/` | `.codex/agents/*.toml` |
-| Pi | `AGENTS.md` plus scoped `.pi/intelligence-sync/rules/` | `.agents/skills/` | `.pi/prompts/intelligence-agent-*.md` |
+| Cursor | `AGENTS.md` plus `.cursor/rules/*.mdc` | `.cursor/skills/` | `.cursor/agents/` |
+| Copilot | `AGENTS.md` plus `.github/instructions/*.instructions.md` | `.github/skills/` | `.github/agents/` |
+| Codex | `AGENTS.md`, or `AGENTS.override.md` while a rule needs it | `.agents/skills/` | `.codex/agents/*.toml` |
+| Pi | `AGENTS.md` plus scoped `.pi/intelligence-sync/rules/` and its extension | `.agents/skills/` | `.pi/prompts/intelligence-agent-*.md` |
 | OpenCode | `AGENTS.md` only | `.agents/skills/` plus slash commands | `.opencode/agents/*.md` |
 
 `AGENTS.md` is regenerated by the `agents` adapter. Its optional static header is `targets.agents.header` in `intelligence.yaml`; generated rule, agent and skill sections follow it. Commit `AGENTS.md` when it is the project's shared canonical context.
@@ -352,7 +392,12 @@ By default, commit the manifest, lock, project-owned content and `AGENTS.md`. Ig
 # CLI-managed package store
 .intelligence/
 
-# Local root instructions migrate into project rules; local preferences stay ignored
+# Local rules, agents and skills of the content directory stay on this machine
+intelligence/rules/*.local.md
+intelligence/agents/*.local.md
+intelligence/skills/*.local/
+
+# Root tool instructions migrate into project rules and stay ignored
 CLAUDE.md
 .cursorrules
 GEMINI.md
@@ -372,6 +417,7 @@ GEMINI.md
 .agents/rules/
 .agents/agents/
 .codex/agents/
+AGENTS.override.md
 
 # Generated Pi content
 .pi/intelligence-sync/
@@ -428,9 +474,10 @@ than inferring contents from Git status.
 move useful repository guidance from legacy root files such as `.cursorrules`
 and instruction-bearing `CLAUDE.md` out of their quarantined backup copies and
 into project-owned rules, then verify the generated tool output. Do not restore
-the original root monolith. Create a new root tool-specific file only when it
-contains genuinely local configuration that an adapter cannot represent; keep
-that exception gitignored rather than maintaining a second committed source.
+the original root monolith. Genuinely machine-local guidance becomes a local
+rule, agent or skill (see
+[Artifact names and local artifacts](#artifact-names-and-local-artifacts)), not
+a new root tool-specific file.
 
 Before the first render, `intelligence init` preserves existing AI prompt paths
 under `<content-dir>/_backup/`. Its `manifest.tsv` labels the snapshot
@@ -458,7 +505,7 @@ The permanent applied-schema key is the top-level scalar `schema_version` in `in
 The public lifecycle is deliberately compact:
 
 - `intelligence init [--preview|--apply]` is universal: it creates a new setup, aligns an existing Intelligence project, or plans/applies conversion of an eligible legacy Intelligence Sync project.
-- `intelligence sync [adapter] [--compact] [--force]` first aligns an existing Intelligence project with the installed CLI and restores every package the store lacks or holds at another commit, strictly from `intelligence.lock`. It skips rendering when local inputs and outputs match a previous successful run. Changes or missing outputs trigger rendering; `--force` always renders and refreshes the search for unconfigured source directories. An unchanged run replays the last full run's useful diagnostics. Compact mode shows context sizes, actionable warnings and final status on success, and all diagnostics on failure. In CI it refuses an alignment that would change tracked files and points to a local `intelligence init --apply` plus review/commit.
+- `intelligence sync [adapter] [--compact] [--force] [--check]` first aligns an existing Intelligence project with the installed CLI and restores every package the store lacks or holds at another commit, strictly from `intelligence.lock`. It skips rendering when local inputs and outputs match a previous successful run. Changes or missing outputs trigger rendering; `--force` always renders and refreshes the search for unconfigured source directories. An unchanged run replays the last full run's useful diagnostics. Compact mode shows context sizes, actionable warnings and final status on success, and all diagnostics on failure. In CI it refuses an alignment that would change tracked files and points to a local `intelligence init --apply` plus review/commit. `--check` changes no generated file: it prints one `IS_STATUS` line and exits 0 when generated files are up to date and 2 (`out-of-date`) when sync would change them or alignment is pending; it never applies alignment.
 - `intelligence update [@scope/name] [--preview|--apply]` is the only update surface. It prints the CLI/project/package plan; default mode prompts, `--preview` never writes, and `--apply` does not prompt. It never moves `ref:` pins.
 - `intelligence upgrade [--next] [--preview|--apply]` replaces the installed CLI with the newest version on its npm channel (`next` for a prerelease or with `--next`, otherwise `latest`) with the same modes. It touches no project, never downgrades, and refuses an installation that npm did not make.
 - `intelligence package add|remove|list|search` owns package inventory.
@@ -479,6 +526,7 @@ The engine emits one machine-readable line, `IS_STATUS=<code> [IS_DETAIL=...]`,
 | `migrated` | 0 | Initialization converted an older layout |
 | `error` | 1 | Generic failure |
 | `config-missing` | 2 | Required manifest is absent |
+| `out-of-date` | 2 | `sync --check` only: sync would change generated files, or alignment is pending. A check never reports `config-missing`, and turns any other failure that would end in 2 into 1 |
 | `ambiguous` | 3 | Conflicting state requiring agent/human judgment; reserved |
 | `ahead-of-engine` | 4 | Manifest schema is a newer major than the engine (a newer minor or patch warns and continues) |
 | `aborted-incomplete` | 5 | Staged replacement was incomplete; prior state remains |
@@ -493,6 +541,7 @@ Callers capture the real code with `command || rc=$?`. Do not use `if ! command;
 | `intelligence.yaml` | Manifest and schema contract | Tracked |
 | `intelligence.lock` | Resolved package state | Tracked |
 | `<content-dir>/{rules,agents,skills,adapters}/` | Project source of truth | Tracked |
+| `<content-dir>/{rules,agents}/*.local.md`, `<content-dir>/skills/*.local/` | Local artifacts, this clone only | Ignored |
 | `.intelligence/` | Restorable package store | Ignored |
 | `AGENTS.md` | Generated canonical project context | Normally tracked |
 | Tool output directories | Generated native content | Built-in adapter-owned paths ignored; shared settings tracked |

package/packages/sync/references/onboarding-migration.md

@@ -47,7 +47,7 @@ Migrate meaning, not tool syntax:
 
 | Existing format | Project-owned destination |
 |---|---|
-| Root `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, Copilot root instructions | Split verified guidance by topic into rules; keep local machine preferences in a gitignored root file only when no adapter representation exists |
+| Root `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, Copilot root instructions | Split verified guidance by topic into rules; move machine-local preferences into local rules (`<content-dir>/rules/<name>.local.md`), which Git ignores and sync keeps out of committed output |
 | `.claude/rules/*.md` | Rule; preserve valid `paths:` |
 | `.cursor/rules/*.mdc` | Rule; rename `globs:` to `paths:` and remove `alwaysApply:` |
 | Claude/Cursor/Copilot agents, Codex `.codex/agents/*.toml` | Agent; map native model/readonly/tool fields back to `tier:` and `access:`, and a native effort level (`effort:`, `model_reasoning_effort`) back to `effort:` |
@@ -64,9 +64,9 @@ Obtain approval per `CREATE`, `UPDATE`, `REMOVE`, or `KEEP` proposal. Apply
 project-owned source changes first, then run `intelligence sync` and
 `intelligence status --check`. Inspect the enabled targets to prove the
 migrated guidance arrived and verify quarantined old root instructions remain
-absent. Create a new root tool file only from a separately approved, genuinely
-machine-local subset that has no adapter representation; never restore the
-original instruction monolith.
+absent. A separately approved, genuinely machine-local subset becomes a local
+rule, `<content-dir>/rules/<name>.local.md`, not a new root tool file; never
+restore the original instruction monolith.
 
 For every removed or renamed path, search all tracked files with `git ls-files`
 and report remaining references with file and line number. Apply an unambiguous