@ainova-systems/intelligence 0.23.0 → 0.25.0

package/cli/internal/check.sh

@@ -8,6 +8,74 @@ warn() { echo "  ✗ $*"; problems=$((problems + 1)); }
 note() { echo "  ! $*"; }
 ok()   { echo "  ✓ $*"; }
 
+# claude_md_excluded <path> <settings>... - whether an entry of
+# claudeMdExcludes in one of the settings files matches <path>. Claude Code
+# matches those globs against absolute paths; this reads `**`, `*` and `?` and
+# takes every other character literally. A Windows path is tried in both the
+# Git Bash spelling and the drive spelling (`/d/x`, `D:/x`).
+claude_md_excluded() {
+    local f alt=""
+    if command -v cygpath >/dev/null 2>&1; then alt="$(cygpath -m "$1")"; fi
+    for f in "${@:2}"; do
+        [ -f "$f" ] || continue
+        CMX_PATH="$1" CMX_ALT="$alt" awk '
+            function glob_re(g,   i, c, out) {
+                out = "^"
+                for (i = 1; i <= length(g); i++) {
+                    c = substr(g, i, 1)
+                    if (c == "*" && substr(g, i + 1, 1) == "*") {
+                        i++
+                        if (substr(g, i + 1, 1) == "/") { i++; out = out "(.*/)?" }
+                        else out = out ".*"
+                    }
+                    else if (c == "*") out = out "[^/]*"
+                    else if (c == "?") out = out "[^/]"
+                    else if (index("\\^$.|+()[]{}", c)) out = out "\\" c
+                    else out = out c
+                }
+                return out "$"
+            }
+            { buf = buf $0 "\n" }
+            END {
+                p = index(buf, "\"claudeMdExcludes\"")
+                if (!p) exit 1
+                s = substr(buf, p + 18)
+                if (!sub(/^[ \t\r\n]*:[ \t\r\n]*\[/, "", s)) exit 1
+                while (1) {
+                    sub(/^[ \t\r\n,]*/, "", s)
+                    if (substr(s, 1, 1) != "\"") exit 1
+                    v = ""
+                    for (i = 2; i <= length(s); i++) {
+                        c = substr(s, i, 1)
+                        if (c == "\\") { i++; v = v substr(s, i, 1); continue }
+                        if (c == "\"") break
+                        v = v c
+                    }
+                    s = substr(s, i + 1)
+                    re = glob_re(v)
+                    if (ENVIRON["CMX_PATH"] ~ re) exit 0
+                    if (ENVIRON["CMX_ALT"] != "" && ENVIRON["CMX_ALT"] ~ re) exit 0
+                }
+            }
+        ' "$f" && return 0
+    done
+    return 1
+}
+
+# claude_md_above <dir> - whether <dir> or a directory above it holds a
+# CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md, any of which keeps Claude
+# Code from reading AGENTS.md. The user's own ~/.claude/CLAUDE.md does not.
+claude_md_above() {
+    local d="$1" up
+    while :; do
+        [ ! -e "$d/CLAUDE.md" ] && [ ! -e "$d/CLAUDE.local.md" ] || return 0
+        if [ -e "$d/.claude/CLAUDE.md" ] && ! [ "$d" -ef "${HOME:-}" ]; then return 0; fi
+        up="${d%/*}"
+        [ -n "$d" ] && [ "$up" != "$d" ] || return 1
+        d="$up"
+    done
+}
+
 echo "environment:"
 command -v git >/dev/null 2>&1 && ok "git $(git --version | awk '{print $3}')" || warn "git not found"
 command -v awk >/dev/null 2>&1 && ok "awk present" || warn "awk not found"
@@ -144,6 +212,7 @@ content_dir="$(manifest_intelligence_dir "$manifest")"
 # Ownership across enabled adapters: two adapters claiming one owned path prune
 # each other silently, and sync reports success for both.
 adapter_claims_reset
+claude_out="" agents_out="" disabled_owned=""
 while IFS= read -r target; do
     [ -n "$target" ] || continue
     output="$(get_target_output "$manifest" "$target")"
@@ -161,6 +230,14 @@ while IFS= read -r target; do
     if [ "$(is_target_enabled "$manifest" "$target")" = "1" ]; then
         adapter_claims_add_records "$target" "$records" \
             || warn "$IS_ADAPTER_CLAIM_CONFLICT"
+        case "$target" in
+            claude) claude_out="$output" ;;
+            agents) agents_out="$output" ;;
+        esac
+    else
+        while IFS=$'\t' read -r kind value; do
+            [ "$kind" != owned ] || disabled_owned+="$target"$'\t'"$value"$'\n'
+        done <<< "$records"
     fi
     while IFS=$'\t' read -r kind value; do
         if [ "$kind" = "requires" ] \
@@ -204,6 +281,52 @@ while IFS= read -r target; do
     ok "adapter $target contract v1"
 done < <(target_names "$manifest")
 
+# Disabling an adapter keeps its output for a cleanup the owner approves. An
+# owned path an enabled adapter also claims is that adapter's output now. The
+# empty line the here-string ends with reports the last adapter.
+left_target="" left_paths=""
+while IFS=$'\t' read -r target value; do
+    if [ "$target" != "$left_target" ] && [ -n "$left_paths" ]; then
+        note "adapter '$left_target' is disabled, and its output is still here: ${left_paths#, }. The intelligence-manage-adapters skill reviews it and removes what you approve"
+        left_paths=""
+    fi
+    left_target="$target"
+    [ -n "$target" ] || continue
+    [ -e "$IP_ROOT/$value" ] || [ -L "$IP_ROOT/$value" ] || continue
+    adapter_contract_rel_path "$value"
+    claimed=0
+    while IFS=$'\t' read -r _ _ path; do
+        [ -n "$path" ] || continue
+        case "$IS_ADAPTER_REL_PATH/" in "$path"/*) claimed=1 ;; esac
+        case "$path/" in "$IS_ADAPTER_REL_PATH"/*) claimed=1 ;; esac
+    done <<< "$IS_ADAPTER_CLAIMS"
+    [ "$claimed" = 1 ] || left_paths="$left_paths, $IS_ADAPTER_REL_PATH"
+done <<< "$disabled_owned"
+
+# Claude Code 2.1.277 and later reads AGENTS.md as project instructions when no
+# CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in the project or above
+# it, and keeps loading .claude/rules/ beside it (code.claude.com/docs/en/memory).
+# With both targets enabled every always-on rule then loads twice. The contract
+# preserves settings.json, so the exclude is the owner's to add.
+if [ -n "$claude_out" ] && [ -n "$agents_out" ]; then
+    agents_output_path_var "$agents_out"
+    adapter_contract_rel_path "$IS_AGENTS_OUTPUT_PATH"
+    agents_md="$IS_ADAPTER_REL_PATH"
+    adapter_contract_rel_path "$claude_out"
+    claude_out="$IS_ADAPTER_REL_PATH"
+    case "/$agents_md" in
+        */.agents/*) ;;
+        */AGENTS.md)
+            if ! claude_md_above "$IP_ROOT" && [ ! -e "$IP_ROOT/$claude_out/CLAUDE.md" ] \
+                && ! claude_md_excluded "$IP_ROOT/$agents_md" \
+                    "$IP_ROOT/$claude_out/settings.json" "$IP_ROOT/$claude_out/settings.local.json"; then
+                note "Claude Code 2.1.277 and later reads $agents_md when there is no CLAUDE.md, $claude_out/CLAUDE.md or CLAUDE.local.md, so the always-on rules load twice: from $claude_out/rules/ and from $agents_md. Sync never edits settings; put this key in $claude_out/settings.json:"
+                printf '      { "claudeMdExcludes": ["**/%s"] }\n' "$agents_md"
+            fi
+            ;;
+    esac
+fi
+
 # A local rule, agent or skill is one these patterns name (decision 0021): the
 # engine keeps it out of every committed output, and without the pattern Git
 # would still offer to commit the file itself.

package/engine/ENGINE_SHA

@@ -1 +1 @@
-79201cedae74ec96e67c3aa94e267f6b1e226c23
+faf0b3ae4ad1b07f08463caf9a332c1eb3a6dcc9

package/engine/VERSION

@@ -1 +1 @@
-0.23.0
+0.25.0

package/engine/adapters/agents.sh

@@ -34,6 +34,17 @@ agents_md_module_rel() {
     printf '%s' "${IS_MODULE_REL:-.intelligence/packages/@ainova-systems/sync}"
 }
 
+# agents_md_link_var <repo_root> <path>: the link target AGENTS.md gives an
+# artifact in IS_REPO_REL, "" for its bare name. The package store is ignored,
+# so a link into .intelligence/ is dead in every clone before a sync and on the
+# forge: store content is listed by name, like content outside the root.
+agents_md_link_var() {
+    repo_rel_link_var "$1" "$2"
+    case "$IS_REPO_REL" in
+        .intelligence/*) IS_REPO_REL="" ;;
+    esac
+}
+
 # Append the static header block from config.yaml (or a fallback).
 agents_md_append_header() {
     local output="$1"
@@ -73,7 +84,7 @@ agents_md_append_agents_table() {
         while IFS=$'\x1f' read -r path tier access desc; do
             name="${names[i]}"
             i=$((i + 1))
-            repo_rel_link_var "$repo_root" "$path"
+            agents_md_link_var "$repo_root" "$path"
             if [ -n "$IS_REPO_REL" ]; then
                 rows+="| [$name]($IS_REPO_REL) | ${tier:--} | ${access:--} | ${desc:--} |"$'\n'
             else
@@ -118,7 +129,7 @@ agents_md_append_skills_table() {
         while IFS=$'\x1f' read -r path desc; do
             name="${names[i]}"
             i=$((i + 1))
-            repo_rel_link_var "$repo_root" "$path"
+            agents_md_link_var "$repo_root" "$path"
             if [ -n "$IS_REPO_REL" ]; then
                 rows+="| [$name]($IS_REPO_REL) | ${desc:--} |"$'\n'
             else
@@ -162,7 +173,7 @@ agents_md_append_rules_list() {
         else
             global_rule_files+=("$path")
         fi
-        repo_rel_link_var "$repo_root" "$path"
+        agents_md_link_var "$repo_root" "$path"
         if [ -n "$IS_REPO_REL" ]; then
             lines+="- [$name]($IS_REPO_REL) ($scope)"$'\n'
         else

package/engine/adapters/codex.sh

@@ -3,8 +3,7 @@
 # Transforms source prompts to Codex format.
 #
 # Codex reads AGENTS.md natively for project context — the `agents` adapter
-# inlines always-on rules into AGENTS.md, so this adapter only emits skills
-# and subagent definitions.
+# inlines shared always-on rules into AGENTS.md.
 #
 # Rules: an always-on rule AGENTS.md does not carry — a local one, or one whose
 #   targets leave `agents` out — goes into AGENTS.override.md beside it
@@ -12,6 +11,8 @@
 #   directory, so it holds the whole AGENTS.md plus those rules. The contract
 #   ignores it, and it exists only while such a rule does; one Intelligence did
 #   not generate is never touched, and refuses a render that needs the path.
+#   Scoped rules get compact pattern-to-source links in that same override.
+#   This is on-demand reading guidance, not a native glob-triggered loader.
 #
 # Skills: copy skill directories in full to .agents/skills/{name}/ (Codex
 #   reads from $REPO_ROOT/.agents/skills exclusively per official docs)
@@ -43,49 +44,79 @@ adapter_contract_codex() {
 CODEX_OVERRIDE_MARKER="<!-- Generated by intelligence-sync. Do not edit manually. -->"
 
 # sync_codex_override <repo_root> <config_file> — write AGENTS.override.md
-# while an always-on rule AGENTS.md does not carry is for Codex, and remove a
-# generated one otherwise.
+# while Codex needs extra always-on rules or scoped-rule routing, and remove
+# a generated one otherwise.
 sync_codex_override() {
     local repo_root="$1" config_file="$2" override="$1/AGENTS.override.md" first="" agents_file i
-    local -a files=() names=()
+    local -a files=() names=() scoped=() scoped_names=()
     source_artifacts_var "$repo_root" "$config_file" rules codex "AGENTS.override.md"
     for ((i = 0; i < ${#IS_SOURCE_FILES[@]}; i++)); do
-        [ "${IS_SOURCE_SCOPED[i]}" = 0 ] && [ "${IS_SOURCE_IN_AGENTS[i]}" = 0 ] || continue
-        files+=("${IS_SOURCE_FILES[i]}")
+        if [ "${IS_SOURCE_SCOPED[i]}" = 1 ]; then
+            scoped+=("${IS_SOURCE_FILES[i]}")
+            scoped_names+=("${IS_SOURCE_NAMES[i]}")
+        elif [ "${IS_SOURCE_IN_AGENTS[i]}" = 0 ]; then
+            files+=("${IS_SOURCE_FILES[i]}")
+        else
+            continue
+        fi
         names+=("${IS_SOURCE_NAMES[i]}")
     done
     if [ -f "$override" ]; then
         IFS= read -r first < "$override" || true
         if [ "${first%$'\r'}" != "$CODEX_OVERRIDE_MARKER" ]; then
-            [ "${#files[@]}" -gt 0 ] || return 0
-            echo "ERROR: AGENTS.override.md was not generated by intelligence-sync, but ${names[*]} need it: always-on rules for Codex that AGENTS.md does not carry go there. Move its guidance into a rule, remove it, then sync." >&2
+            [ "${#names[@]}" -gt 0 ] || return 0
+            echo "ERROR: AGENTS.override.md was not generated by intelligence-sync, but ${names[*]} need it: additional Codex rules and scoped-rule routing go there. Move its guidance into a rule, remove it, then sync." >&2
             return 1
         fi
     fi
-    if [ "${#files[@]}" -eq 0 ]; then
+    if [ "${#names[@]}" -eq 0 ]; then
         rm -f "$override"
         return 0
     fi
     target_output_var "$config_file" "agents"
     agents_output_path_var "${IS_TGT_OUTPUT:-.agents}"
     agents_file="$repo_root/$IS_AGENTS_OUTPUT_PATH"
+    local routes="" rows path patterns link
+    if [ "${#scoped[@]}" -gt 0 ]; then
+        rows="$(frontmatter_index 'paths[]' "${scoped[@]}")" || return 1
+        i=0
+        while IFS=$'\x1f' read -r path patterns; do
+            repo_rel_link_var "$repo_root" "$path"
+            # The override is ignored: external sources may use their real path.
+            link="${IS_REPO_REL:-$path}"
+            routes+="- \`${patterns:-[]}\` → [${scoped_names[i]}](<$link>)"$'\n'
+            i=$((i + 1))
+        done <<< "$rows"
+    fi
+    # Only the Codex section is finalized: AGENTS.md already is, and a second
+    # pass would expand the tokens its rules escaped.
+    local section=""
     {
-        if [ -f "$agents_file" ]; then
-            cat "$agents_file"
-        else
-            printf '%s\n\n' "$CODEX_OVERRIDE_MARKER"
-        fi
         echo "---"
         echo ""
         echo "## Codex Project Context"
         echo ""
-        echo "<!-- Always-on rules AGENTS.md does not carry. Codex reads this file instead of AGENTS.md. -->"
+        echo "<!-- Codex reads this file instead of AGENTS.md. -->"
         echo ""
-        emit_rule_bodies "${files[@]}"
+        if [ -n "$routes" ]; then
+            echo "Before working on files matching these repo-relative patterns, read and follow the linked rules. Apply each only within its scope."
+            echo ""
+            printf '%s\n' "$routes"
+        fi
+        [ "${#files[@]}" -eq 0 ] || emit_rule_bodies "${files[@]}"
     } > "$override"
     finalize_output_file "$override"
+    IFS= read -r -d '' section < "$override" || true
+    {
+        if [ -f "$agents_file" ]; then
+            cat "$agents_file"
+        else
+            printf '%s\n\n' "$CODEX_OVERRIDE_MARKER"
+        fi
+        printf '%s' "$section"
+    } > "$override"
     for ((i = 0; i < ${#names[@]}; i++)); do
-        echo "  rule: ${names[i]} (always-on, AGENTS.override.md)"
+        echo "  rule: ${names[i]} (AGENTS.override.md)"
     done
     echo "  -> AGENTS.override.md"
 }

package/engine/adapters/pi.sh

@@ -39,8 +39,9 @@ adapter_contract_pi() {
 
 # Fork-free TS string escape: sets IS_PI_TS_ESCAPED.
 pi_ts_escape_var() {
-    local s="$1"
-    s="${s//\\/\\\\}"
+    local s
+    token_keep_var "$1"
+    s="${IS_TOKEN_KEPT//\\/\\\\}"
     s="${s//\"/\\\"}"
     s="${s//$'\r'/}"
     s="${s//$'\n'/ }"
@@ -109,7 +110,7 @@ pi_rule_body_rows() {
         /^---$/ && !past_fm { in_fm = !in_fm; if (!in_fm) past_fm = 1; next }
         !past_fm { next }
         {
-            line = is_repl($0, "\\", "\\\\")
+            line = is_repl(fin_keep($0), "\\", "\\\\")
             line = is_repl(line, "\"", "\\\"")
             line = is_repl(line, "\t", "\\t")
             B[++n] = line

package/engine/lib/common.sh

@@ -23,6 +23,9 @@ normalize_file_to_lf() {
 #   <content-dir> -> the repo-relative project content dir (e.g. `Intelligence`)
 #   <module>      -> the repo-relative sync package store path
 #
+# A backslash in front keeps a token literal, and the source lint warns about a
+# token in a project source that reads as ordinary text (_IS_AWK_LINT).
+#
 # Values come from IS_CONTENT_REL / IS_MODULE_REL, which the CLI derives from
 # the detected layout (never hardcoded) and exports before any adapter runs.
 # Expansion happens in EVERY generated file, frontmatter and body alike, so a
@@ -50,11 +53,24 @@ IS_AWK_LIB='
         }
         return out s
     }
+    # A backslash keeps a token as written: `\<module>` renders as `<module>`.
+    # The escaped token waits on a control character while the others expand.
+    # A writer that doubles backslashes for YAML or TOML calls fin_keep (or
+    # token_keep_var) first: once escaped, `\\<module>` no longer reads as one.
+    function fin_keep(s) {
+        if (!index(s, "\\<")) return s
+        s = is_repl(s, "\\<sync-cmd>", "\034sync-cmd>")
+        s = is_repl(s, "\\<manifest>", "\034manifest>")
+        s = is_repl(s, "\\<module>", "\034module>")
+        return is_repl(s, "\\<content-dir>", "\034content-dir>")
+    }
     function fin_line(s) {
+        s = fin_keep(s)
         s = is_repl(s, "<sync-cmd>", FIN_SC)
         s = is_repl(s, "<manifest>", FIN_MF)
         s = is_repl(s, "<module>", FIN_MOD)
         s = is_repl(s, "<content-dir>", FIN_CONTENT)
+        if (index(s, "\034")) s = is_repl(s, "\034", "<")
         return s
     }
     function fm_value_strip(val,   n, first, last) {
@@ -217,7 +233,9 @@ source_name_map_var() {
 # unit separator — never present in frontmatter values). Value semantics are
 # get_frontmatter_value's exactly: first frontmatter block only, first key
 # occurrence wins, first-colon split, symmetric quote strip. The special key
-# `paths#` yields the has_paths count instead of a value. A file without
+# `paths#` yields the has_paths count; `paths[]` folds the first paths list
+# into one display value, preserving YAML quotes and inline list syntax.
+# A file without
 # frontmatter (or an empty file) still gets a row, with empty values.
 frontmatter_index() {
     local keys="$1"
@@ -235,7 +253,7 @@ frontmatter_index() {
             store()
             cur = FILENAME
             for (ri = 1; ri <= nk; ri++) { V[ri] = (K[ri] == "paths#") ? 0 : ""; delete SEEN[ri] }
-            in_fm = 0; fm_done = 0
+            in_fm = 0; fm_done = 0; paths_list = 0
         }
         { sub(/\r$/, "") }
         FNR == 1 && $0 == "---" { in_fm = 1; next }
@@ -243,12 +261,29 @@ frontmatter_index() {
         in_fm && !fm_done && $0 == "---" { fm_done = 1; next }
         fm_done || !in_fm { next }
         {
+            if (paths_list && /^[[:space:]]*#/) next
+            if (paths_list && (/^[[:space:]]+/ || /^-[[:space:]]+/ || /^\]/)) {
+                item = $0
+                sub(/^[[:space:]]*/, "", item)
+                sub(/^-[[:space:]]+/, "", item)
+                if (item != "" && item !~ /^#/) {
+                    for (ki = 1; ki <= nk; ki++)
+                        if (K[ki] == "paths[]") V[ki] = V[ki] (V[ki] == "" ? "" : " ") item
+                }
+                next
+            }
+            if ($0 !~ /^[[:space:]]*$/) paths_list = 0
             idx = index($0, ":")
             if (idx == 0) next
             k = substr($0, 1, idx - 1)
             for (ki = 1; ki <= nk; ki++) {
                 if (K[ki] == "paths#") {
                     if (k == "paths") V[ki]++
+                } else if (K[ki] == "paths[]" && k == "paths" && !(ki in SEEN)) {
+                    SEEN[ki] = 1
+                    V[ki] = substr($0, idx + 1)
+                    sub(/^[[:space:]]+/, "", V[ki])
+                    paths_list = 1
                 } else if (k == K[ki] && !(ki in SEEN)) {
                     SEEN[ki] = 1
                     V[ki] = fm_value_strip(substr($0, idx + 1))
@@ -269,12 +304,28 @@ frontmatter_index() {
     ' "$@"
 }
 
+# token_keep_var <s> — fin_keep for the shell escapers below, whose output
+# fin_line finalizes later: an escaped layout token gives up its backslash
+# before they double backslashes. Sets IS_TOKEN_KEPT.
+token_keep_var() {
+    local s="$1" fs=$'\034' t
+    case "$s" in
+        *'\<'*)
+            for t in sync-cmd manifest module content-dir; do
+                s="${s//\\<$t>/$fs$t>}"
+            done
+            ;;
+    esac
+    IS_TOKEN_KEPT="$s"
+}
+
 # Escape a string for safe interpolation into a TOML basic string ("..").
 # Backslash and double-quote are escaped; control chars stripped.
 # Fork-free form: sets IS_TOML_ESCAPED; the printing form wraps it.
 toml_escape_var() {
-    local s="$1"
-    s="${s//\\/\\\\}"
+    local s
+    token_keep_var "$1"
+    s="${IS_TOKEN_KEPT//\\/\\\\}"
     s="${s//\"/\\\"}"
     # Strip any literal newline / carriage return — TOML basic strings
     # do not allow them; multi-line content belongs in `"""..."""`.
@@ -291,8 +342,9 @@ toml_escape() {
 # Escape a string for safe interpolation into a YAML double-quoted scalar.
 # Fork-free form: sets IS_YAML_ESCAPED; the printing form wraps it.
 yaml_dq_escape_var() {
-    local s="$1"
-    s="${s//\\/\\\\}"
+    local s
+    token_keep_var "$1"
+    s="${IS_TOKEN_KEPT//\\/\\\\}"
     s="${s//\"/\\\"}"
     s="${s//$'\n'/ }"
     s="${s//$'\r'/}"
@@ -450,7 +502,7 @@ emit_wrapped_bodies() {
             else if (!past_fm) next
             line = $0
             if (ESC[cur] == "toml") {
-                line = is_repl(line, "\\", "\\\\")
+                line = is_repl(fin_keep(line), "\\", "\\\\")
                 line = is_repl(line, "\"\"\"", "\"\"\\\"")
             }
             body[++body_n] = line
@@ -495,13 +547,15 @@ emit_rule_bodies() {
 # When wrapping an unquoted value, literal `\` and `"` inside it are escaped
 # (`\\`, `\"`) so an inner quote — e.g. `Use as a quick "what do we have" view`
 # — cannot prematurely terminate the generated double-quoted scalar. Values the
-# author already wrapped (in `"` or `'`) pass through untouched.
+# author already wrapped (in `"` or `'`) pass through untouched. An escaped
+# layout token is resolved first (fin_keep), so <dst> still needs
+# finalize_output_file, as every emitted file does.
 #
 # Usage: copy_md_with_quoted_frontmatter "src.md" "dst.md"
 copy_md_with_quoted_frontmatter() {
     local src="$1"
     local dst="$2"
-    awk '
+    awk "$IS_AWK_LIB"'
         function yamlq(s,    out, i, c) {
             out = ""
             for (i = 1; i <= length(s); i++) {
@@ -531,7 +585,7 @@ copy_md_with_quoted_frontmatter() {
             first = substr(val, 1, 1)
             last = substr(val, length(val), 1)
             if ((first == "\"" && last == "\"") || (first == "\047" && last == "\047")) { print; next }
-            print key ": \"" yamlq(val) "\""
+            print key ": \"" yamlq(fin_keep(val)) "\""
             next
         }
         state == "after" { print }
@@ -813,7 +867,7 @@ _skill_bundles_flush() {
                             first = substr(val, 1, 1)
                             last = substr(val, length(val), 1)
                             if (!((first == "\"" && last == "\"") || (first == "\047" && last == "\047"))) {
-                                $0 = key ": \"" yamlq(val) "\""
+                                $0 = key ": \"" yamlq(fin_keep(val)) "\""
                             }
                         }
                     }
@@ -1070,9 +1124,41 @@ _IS_AWK_LINT='
                 LEVEL[LV[li]] = 1
                 allowed = allowed (li > 1 ? ", " : "") LV[li]
             }
+            tok_root = ENVIRON["IS_TOK_ROOT"]
+            split("<content-dir> <module> <manifest> <sync-cmd>", TOK, " ")
+            TOKV[1] = FIN_CONTENT; TOKV[2] = FIN_MOD; TOKV[3] = FIN_MF; TOKV[4] = FIN_SC
+        }
+        # A layout token that cannot mean what it renders as: joined to a word
+        # or a path around it, or an XML element closed on the same line. A
+        # module-name placeholder `<module>_update_N` rendered as the package
+        # path. Packages use tokens by design, so only project sources (under
+        # the root, outside its package store) are read, and an escaped token
+        # (`\<module>`) is literal.
+        function tok_check(l,   k, t, n, at, p, b, a) {
+            for (k = 1; k <= 4; k++) {
+                t = TOK[k]; n = length(t); at = 0
+                while ((p = index(substr(l, at + 1), t)) > 0) {
+                    at += p
+                    b = (at > 1) ? substr(l, at - 1, 1) : ""
+                    a = substr(l, at + n, 2)
+                    at += n - 1
+                    if (b == "\\") continue
+                    if (b ~ /[[:alnum:]_]/ || b == "/" || a ~ /^([[:alnum:]_-]|[.][[:alnum:]_])/ \
+                        || index(l, "</" substr(t, 2))) {
+                        printf "WARNING: %s:%d %s is part of the text around it, but sync renders this layout token as %s; write \\%s to keep it as written\n", \
+                            substr(FILENAME, length(tok_root) + 2), FNR, t, TOKV[k], t > "/dev/stderr"
+                        break
+                    }
+                }
+            }
+        }
+        FNR == 1 {
+            in_fm = 0; done = 0; effort_seen = 0
+            tok_own = tok_root != "" && index(FILENAME, tok_root "/") == 1 \
+                && index(FILENAME, tok_root "/.intelligence/") != 1
         }
-        FNR == 1 { in_fm = 0; done = 0; effort_seen = 0 }
         { sub(/\r$/, "") }
+        tok_own && index($0, ">") { tok_check($0) }
         done { next }
         FNR == 1 && $0 != "---" { done = 1; next }
         FNR == 1 { in_fm = 1; next }
@@ -2423,7 +2509,7 @@ source_catalog_build() {
         # One pass reads what routing needs from every source's frontmatter
         # and, for the engine, lints it. Captured, not streamed: a short answer
         # must stop the run, not route the files it lost as always-on.
-        rows="$(source_frontmatter_scan "$lint" "${files[@]}")" || {
+        rows="$(source_frontmatter_scan "${lint:+$repo_root}" "${files[@]}")" || {
             echo "ERROR: cannot read the frontmatter of the sources — refusing to render a partial list." >&2
             exit 1
         }
@@ -2447,20 +2533,22 @@ source_catalog_build() {
     [ "${IS_SOURCE_FILES_MEMO:-0}" != 1 ] || IS_CAT_KEY="$key"
 }
 
-# source_frontmatter_scan <lint> <file>... — one row per file in argument
+# source_frontmatter_scan <lint-root> <file>... - one row per file in argument
 # order, \x1f-separated: the path; its `paths:` line count, read with
 # frontmatter_index's `paths#` semantics; then for `targets:` and for
 # `exclude_targets:` whether it is set and its ids, space-separated. Both take
 # the list syntax `paths:` takes — a block list or a flow list `[a, b]`, items
 # optionally quoted — and a bare value is a one-item list. The first
 # occurrence of a key wins, and a key with no value at all is not set
-# (`targets: []` is: it is the empty list). With <lint> = lint the same pass
-# runs lint_frontmatter_files over every file, its warnings on stderr.
+# (`targets: []` is: it is the empty list). With <lint-root>, the repository
+# root, the same pass runs lint_frontmatter_files over every file and the
+# layout-token check over the project's own; warnings go to stderr.
 source_frontmatter_scan() {
-    local do_lint=0
-    [ "$1" != lint ] || do_lint=1
+    local do_lint=0 root="$1"
+    [ -z "$root" ] || do_lint=1
     shift
-    awk -v levels="$IS_EFFORT_LEVELS" -v do_lint="$do_lint" "$IS_AWK_LIB"'
+    is_fin_awk_vars
+    IS_TOK_ROOT="$root" awk -v levels="$IS_EFFORT_LEVELS" -v do_lint="$do_lint" "${IS_FIN_V[@]}" "$IS_AWK_LIB"'
         BEGIN { SX_US = sprintf("%c", 31) }
         function sx_items(s, k,   parts, m, j, v, q) {
             m = split(s, parts, ",")
@@ -2767,7 +2855,7 @@ source_catalog_check_local() {
 # A project adapter's channels are its own business: it has one.
 builtin_has_channel() {
     case "$1:$2" in
-        opencode:always|opencode:scoped|codex:scoped) return 1 ;;
+        opencode:always|opencode:scoped) return 1 ;;
     esac
     return 0
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainova-systems/intelligence",
-  "version": "0.23.0",
+  "version": "0.25.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

@@ -42,7 +42,7 @@ To stop syncing a target:
 intelligence adapter disable mytool
 ```
 
-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.
+Disabling changes only target state. Generated output is deliberately kept so disabling is reversible; the adapter contract identifies its paths for review, and `intelligence status --check` names the owned paths still on disk and the `intelligence-manage-adapters` skill that removes 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.
 
 ## Required interface
 
@@ -187,7 +187,7 @@ Use the engine library instead of copying parsers or file-handling logic.
 | `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. |
 | `get_frontmatter_value(key, file)` | Read a scalar from the first frontmatter block. |
-| `frontmatter_index(keys, file...)` | Read several frontmatter scalars for many files in one pass (`\x1f`-separated rows; special key `paths#` counts `paths:` lines). |
+| `frontmatter_index(keys, file...)` | Read several frontmatter scalars for many files in one pass (`\x1f`-separated rows; `paths#` counts `paths:` lines, `paths[]` folds a paths list for display). |
 | `has_frontmatter(file)` / `has_paths(file)` | Inspect source shape. |
 | `strip_frontmatter(file)` | Emit the body without its first frontmatter block. |
 | `get_model(config, tool, tier)` | Resolve a `frontier`, `heavy`, `standard` or `light` model, including manifest overrides. |
@@ -218,16 +218,18 @@ Intelligence routes always-on rules once through `AGENTS.md` for tools that cons
 
 | Built-in | Always-on rules | Always-on, not in `AGENTS.md` | Scoped rules |
 |---|---|---|---|
-| `agents` | Inline in `AGENTS.md` | — | List with links |
+| `agents` | Inline in `AGENTS.md` | None | List with links; package and out-of-tree content by name |
 | `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 |
+| `codex` | Omit; reads `AGENTS.md` | `AGENTS.override.md`: all of `AGENTS.md` plus these rules | Compact patterns and source links in `AGENTS.override.md`; read on demand |
 | `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.
+Codex reads `AGENTS.override.md` instead of `AGENTS.md` in the same directory, so the Codex adapter writes the whole rendered `AGENTS.md`, a compact scoped-rule index, and any additional always-on rules into that override. It exists while either kind needs it. 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.
+
+The scoped index pairs source `paths:` patterns with source links and asks Codex to read matching rules before working on files. Local and targeted rules follow the same source filtering as other output. This is model-followed guidance, not a native glob matcher; it creates no nested `AGENTS.md` files and leaves other tools' instruction channels unchanged. Checked 2026-10-23 against OpenAI's [instruction discovery documentation](https://learn.chatgpt.com/docs/agent-configuration/agents-md): startup discovery walks from the project root to the working directory, and an override replaces the base file in the same directory. Restart Codex after syncing updated instructions.
 
 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.
 
@@ -303,7 +305,7 @@ Content shipped in `@ainova-systems/sync` cannot assume the project's content-di
 | `<manifest>` | `intelligence.yaml` |
 | `<sync-cmd>` | `intelligence sync` |
 
-Call `finalize_output_file` on every text file after transformation. It expands the tokens literally and converts CRLF to LF. A generated file containing an unexpanded token is an adapter bug.
+Call `finalize_output_file` on every text file after transformation. It expands the tokens literally, keeps a token escaped with a backslash as written ([Layout tokens](conventions.md#layout-tokens)), and converts CRLF to LF. A generated file containing an unexpanded token is an adapter bug.
 
 `copy_skill_bundle` already finalizes Markdown within a skill; do not run a second custom token pass.
 

package/packages/sync/references/conventions.md

@@ -142,6 +142,8 @@ Expansion applies to frontmatter and bodies. Thus `paths: ["<content-dir>/**"]`
 
 Project-authored artifacts normally use their known project paths directly. Tokens are useful only when the same artifact must work under different content-directory or package-store locations.
 
+The four tokens are reserved in every source, so a placeholder that means something else, such as a module name, needs a backslash: `\<module>` renders as `<module>`. Sync prints a `WARNING:` line with the file and line when a project source holds a token joined to the text around it (`<module>_update_N`, `modules/<module>.md`) or used as an XML element closed on the same line (`<manifest></manifest>`).
+
 ## Naming
 
 Rule filenames, agent names and skill names share a domain prefix such as `backend-`, `frontend-`, `devops-`, `core-`, `tests-`, a project codename or a monorepo component. Pick the domain from repository structure and reuse it.
@@ -251,7 +253,7 @@ Skills take the same field. `.claude/skills/` receives Claude's level, the share
 
 ### Access mappings
 
-`access: full` inherits ordinary tool permissions. `access: readonly` is transformed into the target's native restriction: for example Claude receives read/search/bash tools with writes disallowed, Cursor receives `readonly: true`, and Codex receives a read-only sandbox.
+`access: full` inherits ordinary tool permissions. `access: readonly` is transformed into the target's native restriction, and the targets differ on commands. Claude keeps `Bash` beside its read and search tools, with `Write` and `Edit` disallowed. Cursor receives `readonly: true`, which its documentation says blocks edits and state-changing shell commands. Copilot, OpenCode and Antigravity receive read and search tools only, and Pi receives the restriction as an instruction. Codex receives `sandbox_mode = "read-only"`, which its [subagent documentation](https://learn.chatgpt.com/docs/agent-configuration/subagents) says a custom agent file cannot set, so a Codex agent runs in the parent session's sandbox.
 
 Use only `full` or `readonly` in source agents. Tool-specific permission syntax belongs in adapters.
 
@@ -279,13 +281,13 @@ Rule content in Markdown.
 
 | Source rule | Claude | Cursor | Antigravity | Copilot | Codex / Pi / OpenCode / `AGENTS.md` |
 |---|---|---|---|---|---|
-| 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 |
+| Scoped | copied with `paths:` | `.mdc` with `globs:` | `.md` with `trigger: glob` and `globs:` | `.instructions.md` with `applyTo:` | listed in `AGENTS.md`; Codex gets routing in its override; Pi 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.
+Cursor, Copilot, Codex, Pi, OpenCode and Antigravity consume `AGENTS.md`, so always-on rules are not duplicated in their tool-specific channels. Claude receives the full rule set in `.claude/rules/`. Claude Code 2.1.277 and later also reads `AGENTS.md` when no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` exists in the working directory or above it ([memory docs](https://code.claude.com/docs/en/memory#agents-md)), so the always-on rules load twice until `.claude/settings.json` carries `"claudeMdExcludes": ["**/AGENTS.md"]`. Sync never edits that file; `intelligence status --check` prints the entry when it is missing. Codex's override lists scoped patterns and source links with an instruction to read matching rules on demand; this depends on the model following the instruction, not native glob-triggered loading. OpenCode users may configure `instructions:` globs themselves. See [adapter routing](adapters.md#rules) for delivery details.
 
-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.
+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 scoped routing and additional always-on rules; it is ignored, exists while either needs it, 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.
 
@@ -308,9 +310,15 @@ 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. `targets:` and `exclude_targets:` select the adapters that receive the skill and are removed from every copy ([Selecting adapters](#selecting-adapters)).
+Standard optional fields (`license`, `compatibility`, `metadata`, `allowed-tools`) and tool extensions pass through unchanged. `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 a person starts, as a slash command. The flag hides the procedure, not the act: Claude Code keeps the skill's description out of the model's context, so a request in words such as "commit this" never reaches the skill and is carried out without its checks. Keep the flag for a skill that starts a named person's decision, such as approving a plan, moving versions or changing adapters; the person typing the command after seeing what it acts on is the yes, so the skill does not ask again. A skill with side effects stays model-invocable, and its description names the requests that should reach it.
+
+Claude Code, Cursor, Copilot, OpenCode and Pi 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:`.
 
-`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:`.
+`context: fork`, `agent`, `background` and `model` are Claude Code fields, and sync copies them unchanged. A forked skill runs as a subagent of the `agent` type that receives the skill as its prompt, sees none of the conversation and has no `AskUserQuestion` tool. In an interactive session it runs in the background by default, so the caller's turn goes on before the result arrives, and a skill whose result its caller needs in the same turn sets `background: false` ([skills](https://code.claude.com/docs/en/skills#run-skills-in-a-subagent), [subagents](https://code.claude.com/docs/en/sub-agents#available-tools)). Without `context: fork`, `agent` selects nothing, and `model` switches the session's model for the rest of the turn, which then re-reads the whole conversation without the prompt cache ([prompt caching](https://code.claude.com/docs/en/prompt-caching#switching-models)). Of the other targets, only Copilot in VS Code documents `context: fork`, as experimental, and none documents `agent`, `background` or `model` for a skill (checked 2026-11-07).
+
+Fork a skill whose inputs are files and arguments, that asks nothing on the way, and whose work is heavy reading, auditing or judging: the caller's context stays small and the work gets an independent reader. Keep a skill inline, with no `agent`, when its input is the conversation or its job is a dialogue or an approval with the person. A forked skill never asks. When it reaches a decision that belongs to the person, it stops before the write and ends its result with the decision, the options and its recommendation, so the caller asks.
 
 These limits reject a skill instead of degrading it:
 
@@ -351,14 +359,15 @@ The engine copies the complete skill directory. Promote a helper outside the ski
 
 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:
+Size limits are backstops, not quotas. They count words, because a paragraph written as one long line passes any line cap:
 
-| Artifact | Hard cap | Response |
+| Artifact | Budget | Response |
 |---|---|---|
-| `SKILL.md` body | 1000 lines | Move detail to `references/` |
-| Reference file | 500 lines | Add a contents list past 300; split if still oversized |
-| Rule | 500 lines | Split by scope or move examples behind a skill reference |
-| Agent | 200 lines | Move procedures and constraints into skills/rules |
+| `SKILL.md` | 1,500 words | Move detail to `references/` |
+| Reference file | 3,000 words | Add a contents list past 1,500; split if still oversized |
+| Rule | 2,000 words | Split by scope or move examples behind a skill reference |
+| Agent | 500 words | Move procedures and constraints into skills/rules |
+| Paragraph, list item or table row | 150 words | Split it into the thoughts it holds |
 
 ## Writing discipline
 
@@ -448,6 +457,8 @@ targets:
 
 `AGENTS.md` stays committed by default: it is the tool-neutral fallback every tool reads, and a fresh clone has it only when it is committed, before anyone has synced.
 
+Claude Code loads project skills from the checkout a session starts in, and from 2.1.277 a Git worktree without its own `.claude/skills`, such as one not yet synced, gets the main checkout's ([skills docs](https://code.claude.com/docs/en/skills#load-skills-in-monorepos-and-subdirectories)), so a task in a worktree runs in a session started there after `intelligence sync` there.
+
 Git tracking and release packaging are separate policies. When a project
 already has `.vscodeignore`, `.npmignore`, or `.dockerignore`, the CLI appends a
 small idempotent block excluding the package store, `intelligence.yaml`,

package/packages/sync/rules/intelligence-authoring.md

@@ -21,7 +21,7 @@ Three ways to shorten, in order of what they are worth:
 2. **Delete what the code already says.** A rule restating what a reader can see in the file is noise, and noise trains people to skim the lines that are not.
 3. **Cut the words, keep the reason.** Prose can shrink; the *why* cannot — an instruction without its reason does not survive contact with a judgement call.
 
-**Never solve a problem by adding an artifact when moving one, or removing one, would do.** A new rule is the most expensive answer available, and it is the one that feels cheapest to write.
+**Never solve a problem by adding an artifact when moving one, or removing one, would do.** A new rule is the most expensive answer available, and it is the one that feels cheapest to write. The same holds inside an artifact: a fix restates the outcome once, and a clause added for each edge case or review finding is itself the defect.
 
 ## Source of truth
 
@@ -60,7 +60,7 @@ The mistakes that actually happen, in order of frequency:
 
 ### Invariants
 
-- **Never state behaviour of a tool or engine you have not verified in its documentation or source.** An unverified claim about tooling is worse than a gap: nothing in the repository contradicts it, so it silently reshapes every decision downstream. Verified means a page you can cite - for how rules load, the Claude Code docs *Memory → Organize rules with `.claude/rules/`* and *Subagents → What loads at startup*.
+- **Never state behaviour of a tool or engine you have not verified in its documentation or source.** An unverified claim about tooling is worse than a gap: nothing in the repository contradicts it, so it silently reshapes every decision downstream. Verified means a page you can cite - for how rules load, the Claude Code [memory](https://code.claude.com/docs/en/memory#organize-rules-with-claude/rules/) and [subagent startup](https://code.claude.com/docs/en/sub-agents#what-loads-at-startup) docs.
 - **Never write a current defect into a rule as if it were the design.** Known breakage belongs in one place that says so. Every other rule describes the project *as it is meant to work* — a workaround documented as procedure becomes permanent.
 - **Never link from one always-on rule to another.** Always-on rules are inlined verbatim into `AGENTS.md`, and the path-scoped channels carry only scoped rules, so a relative link is dead in at least one output. Name the rule instead; it loads on its own.
 
@@ -68,7 +68,7 @@ The mistakes that actually happen, in order of frequency:
 
 An agent is **thin**: who it is, where it stops, how it verifies. Nothing else.
 
-- **Do not list rules for an agent to read.** They load on their own — Claude Code loads `.claude/rules/` into every custom subagent's startup context, and Cursor, Copilot, Codex, Pi, OpenCode and Antigravity receive always-on rules inlined in `AGENTS.md`. Naming a rule is fine; copying it is duplication that drifts.
+- **Do not list rules for an agent to read.** They load on their own: a Claude Code subagent starts with the project's instruction files, `.claude/rules/` included, unless it is the built-in Explore or Plan agent or its definition sets `omitClaudeMd`, and Cursor, Copilot, Codex, Pi, OpenCode and Antigravity receive always-on rules inlined in `AGENTS.md`. A step handed to an agent that starts without them names the rules it depends on in the delegation message. Naming a rule is fine; copying it is duplication that drifts.
 - **Point at a rule, do not restate it.** Wanting to copy a rule into an agent means the rule is in the wrong place — move it.
 - **Do carry** what is genuinely the agent's own: its boundaries ("if the app will not start, stop — do not hand-write the output"), its verification commands, its definition of done.
 
@@ -95,15 +95,16 @@ Two verbs are told apart by what already exists. **`add-` puts one new member in
 
 ## Size — the backstop, not the goal
 
-The goal is subtraction, above. These are only the line past which something is definitely wrong.
+The goal is subtraction, above. These are only the line past which something is definitely wrong. They count words, because a line cap never sees a paragraph written as one long line.
 
-| Type | Hard cap |
+| Type | Budget |
 |---|---|
-| Rule | 500 lines |
-| Agent | 200 lines |
-| `SKILL.md` | 1000 lines |
+| Rule | 2,000 words |
+| Agent | 500 words |
+| `SKILL.md` | 1,500 words |
+| Paragraph, list item or table row | 150 words |
 
-**Ceilings, not quotas.** An artifact that says everything it needs to is finished, not underweight — nothing here is a reason to pad. Over the cap means the artifact is doing two jobs, or the detail belongs in `references/<topic>.md` with a pointer from the body.
+**Ceilings, not quotas.** An artifact that says everything it needs to is finished, not underweight; nothing here is a reason to pad. Over the budget means the artifact is doing two jobs, or the detail belongs in `references/<topic>.md` with a pointer from the body, and a paragraph over it holds several thoughts to split.
 
 `description` fields compete for one shared budget across the whole registry: a long one pushes another artifact out of reach. Four to eight words when the name is unambiguous; longer only when a sibling does something similar and needs distinguishing. (The tools reject a `description` over 1024 characters outright — but that is a wall to stay far away from, not a target.)
 

package/packages/sync/skills/intelligence-learn-from-repository/SKILL.md

@@ -104,10 +104,13 @@ explains itself well.
     back. Completion requires
     `IS_STATUS=ok`, a clean final check, and no `onboarding is pending` header
     after accepted migration.
-11. Report what was created, updated, removed, or deliberately kept. Remind the
-    user to commit source, manifest, lock and `AGENTS.md` changes, plus Copilot's
-    `.github/` output only when `targets.copilot.commit_output` is `true`. Keep or
-    remove the initial backup only by separate user approval.
+11. Report what was created, updated, removed, or deliberately kept. A
+    `status --check` note that names a tool settings change is the owner's step:
+    show it with the exact JSON it prints and leave the settings file to the
+    owner. Remind the user to commit source, manifest, lock and `AGENTS.md`
+    changes, plus Copilot's `.github/` output only when
+    `targets.copilot.commit_output` is `true`. Keep or remove the initial backup
+    only by separate user approval.
 
 ## Later learning
 

package/packages/sync/skills/intelligence-learn-from-session/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: intelligence-learn-from-session
 description: "Capture session lessons and workflows in project context"
-agent: intelligence-architect
+argument-hint: "[lesson, or a folder of lesson records]"
 ---
 
 # Learn from a session
@@ -9,6 +9,8 @@ agent: intelligence-architect
 Capture a durable preference, working pattern, recurring friction, or successful
 workflow from a session in an established Intelligence project. This skill owns
 identifying and generalizing the lesson; `intelligence-update-context` owns writing it.
+A lesson is saved only through that skill, as a source every clone and tool reads,
+never in a tool's own memory.
 
 ## Verify readiness
 
@@ -23,7 +25,10 @@ identifying and generalizing the lesson; `intelligence-update-context` owns writ
 
 2. Identify the lesson from the conversation or explicit user input. For a
    workflow, list the actual steps performed, user decisions, branches, failure
-   recovery, and verification. Retain the sequence that worked.
+   recovery, and verification. Retain the sequence that worked. Given a folder
+   of lesson records, read every record against the current sources: report a
+   record the sources already satisfy as applied and drop it, and carry the rest
+   forward as lessons.
 3. Generalize the evidence by removing instance-specific filenames, dates, and
    phrasing. Keep the reason needed to apply the lesson to the next task. Prefer
    a positive instruction such as "Default to one recommendation" for "Stop
@@ -33,18 +38,26 @@ identifying and generalizing the lesson; `intelligence-update-context` owns writ
 4. Inspect configured sources for an existing owner. A preference or constraint
    belongs in a rule, path-specific context in a scoped rule, an observed
    repeatable procedure in a skill, and a persona or expertise boundary in an
-   agent. Prefer extending an existing artifact over adding a sibling.
-5. Present each proposal with its action (`CREATE`, `UPDATE`, or `ARCHIVE`),
-   source path, concrete draft, and one-line reason. This phase is read-only;
-   only user-accepted lessons become persistent instructions. Reuse approval
-   already given for the exact proposal.
+   agent. Prefer extending an existing artifact over adding a sibling. A lesson
+   about installed package content or the CLI itself is fixed upstream, never in
+   the installed copy: draft an issue for the package's source repository, which
+   `intelligence.lock` records, or for Intelligence. The draft holds only safe
+   facts: versions from `intelligence version`, what was done, the expected and
+   the actual behavior, and nothing confidential or specific to the project.
+5. Present each proposal with its action (`CREATE`, `UPDATE`, `ARCHIVE`, or
+   `UPSTREAM` for an issue draft), source path or repository, concrete draft, and
+   one-line reason. This phase is read-only; only user-accepted lessons become
+   persistent instructions. Reuse approval already given for the exact proposal.
 
 ## Apply and verify
 
 6. Pass accepted proposals and their session evidence to
    `/intelligence-update-context`. It handles artifact-specific authoring,
-   references, a single batch sync, and the final status check.
+   references, a single batch sync, and the final status check. An accepted
+   `UPSTREAM` draft goes into the report; filing it is a separate request the
+   person makes.
 7. Compare the resulting source changes with the accepted lesson. For a workflow,
    verify that its decisions, working steps, recovery, and proof of completion
    remain executable without this conversation. Report the saved lesson, its
-   owner, and verification; a session-specific transcript is not completion.
+   owner, and verification, the records dropped as applied, and each upstream
+   draft with its state; a session-specific transcript is not completion.

package/packages/sync/skills/intelligence-manage-adapters/SKILL.md

@@ -2,7 +2,6 @@
 name: intelligence-manage-adapters
 description: "Enable, disable, or remove adapters and assess generated-output cleanup"
 argument-hint: "<enable|disable|remove> <adapter-name>"
-agent: intelligence-operator
 disable-model-invocation: true
 ---
 
@@ -42,5 +41,6 @@ scaffolding, and sync. Adapter implementation follows the public adapter guide.
 5. Verify with `intelligence adapter list` and `intelligence status --check`:
    requested target state is correct, retained files are intact, and only approved
    adapter-owned output was deleted. Report state, output paths, and any remaining
-   implementation or cleanup work. Preserve CLI refusals instead of recreating
-   lifecycle mechanics manually.
+   implementation or cleanup work, with each settings change a check note names
+   as the owner's step and its exact JSON. Preserve CLI refusals instead of
+   recreating lifecycle mechanics manually.

package/packages/sync/skills/intelligence-review-context/SKILL.md

@@ -3,33 +3,37 @@ name: intelligence-review-context
 description: "Audit rules, agents, and skills and propose behavior-preserving reductions"
 argument-hint: "[rules|agents|skills|all] [compact]"
 agent: intelligence-architect
+context: fork
+background: false
 ---
 
 # Review project context
 
-Audit the intelligence layer and propose improvements. Review and compaction
-analysis are read-only: do not sync or edit while inspecting. Accepted changes
-go through `intelligence-update-context`; this skill owns their review criteria.
+Audit the intelligence layer and return proposals. Work from the arguments and
+the files alone and ask nothing: in Claude Code this skill runs as a subagent that
+sees none of the conversation. Review and compaction analysis are read-only, so
+never sync or edit. Accepted changes go through `intelligence-update-context`;
+this skill owns their review criteria.
 
 ## Audit
 
 1. Read `<manifest>` and enumerate its configured rule, agent, and skill sources.
    Read the `intelligence-authoring` rule and
    `<module>/references/conventions.md`. Review project-owned sources; an installed
-   package finding — an entry naming a package's directory, however spelled —
+   package finding, an entry naming a package's directory however spelled,
    belongs upstream. In a package's own repository, review its
    authoritative source tree. Do not audit generated output prose. Its byte count
    is the metadata-only exception.
 2. Record source line and byte counts, and git history when available: first
    addition, last edit, and edit count. Find incoming references before proposing
    an archive. Resolve the shared agents output from the manifest and measure its
-   bytes, or reuse a fresh `CONTEXT:` summary. Mark missing or stale measurements;
-   do not regenerate output during analysis.
+   bytes. Mark missing or stale measurements; do not regenerate output during
+   analysis.
 3. Read and apply [references/audit-checks.md](references/audit-checks.md). Reuse
    these generic checks in any project-specific audit. Check subtraction before
    proposing a split or rewrite: remove an unnecessary artifact, merge overlapping
    owners, or replace prose with an existing deterministic gate where possible.
-4. When the user asks to compact context, or the audit proposes a merge, move,
+4. When the arguments ask to compact context, or the audit proposes a merge, move,
    deletion, scoping change, or size reduction, read
    [references/compaction.md](references/compaction.md) and its principles. Build
    the behavior ledger and draft the structural reduction before wording changes.
@@ -39,17 +43,17 @@ go through `intelligence-update-context`; this skill owns their review criteria.
    3: description or naming polish). Compaction items also show the authoritative
    owner, behavior preserved, estimated byte savings, and any change to meaning,
    scope, or loading. Surface unverified reasons without silently rewriting them.
+   A finding about what an artifact says is a wrong or missing outcome, a
+   contradiction, or a stale reference; an edge case its outcome already covers
+   is no finding.
 
-## Accepted changes
+## Hand the decision back
 
-6. The user accepts items individually; a batch acceptance may cover named items.
-   Pass accepted proposals to `/intelligence-update-context`, with the behavior
-   ledger and additional checks. Reuse existing approval for those exact changes.
-   If fresh rendered measurements are needed, capture them only after apply is
-   authorized and before editing; record `<sync-cmd> --compact` output and require
-   `IS_STATUS=ok`. The authoring skill performs the final batch sync and status check.
-7. Verify each accepted finding against the resulting sources. For reductions,
-   complete the ledger comparison, measurements, and behavioral evaluation in
-   the compaction reference. Report each artifact as pass, fixed (what), or
-   flagged (for whom), plus unresolved proposals. A read-only review ends with
-   the evidenced punch-list; an apply run ends only after its checks complete.
+6. End the result with the decision that belongs to the person: which numbered
+   items to accept, one by one or as a named batch, with the items you recommend
+   and the reason for each. Accepted items go to `/intelligence-update-context`
+   with their drafts. For compaction items, include what that skill needs to
+   verify them: the behavior ledger, the baseline counts with any missing
+   rendered measurement marked, and the steps under *Verify the accepted result*
+   in the compaction reference, copied into the result. The review is complete
+   when this evidenced punch-list is returned.

package/packages/sync/skills/intelligence-review-context/references/audit-checks.md

@@ -6,7 +6,8 @@ Apply these checks to the source groups resolved by the review skill.
 |---|---|---|
 | **Duplicate content** | Two artifacts cover overlapping scope, or their descriptions share trigger phrases | `MERGE` — present both, propose one |
 | **Misplaced content** | A checklist or procedure in an agent body; a convention in an agent; a workflow in a rule; expertise in a skill (the *Pick the right artifact* table in `intelligence-authoring`) | `MOVE` — a move, not a rewrite: both files change together |
-| **Over the cap** | `SKILL.md` over 1000 lines, rule over 500, agent over 200 | `SPLIT` — two artifacts, or move detail into `references/<topic>.md` |
+| **Over the budget** | `SKILL.md` over 1,500 words, rule over 2,000, agent over 500, skill reference over 3,000, or a paragraph, list item or table row over 150 (`R7`) | `SPLIT` - two artifacts, detail into `references/<topic>.md`, or a long paragraph into the thoughts it holds |
+| **Rule repeats a gate** | A rule sentence restating what a script, test or sync already checks or refuses | `DELETE` - the gate holds the decision; a second copy in prose drifts from it and costs context in every session |
 | **Shared instruction budget** | The measured shared agents output, or `agents-md` in sync's `CONTEXT:` summary, is over 32 KiB (32,768 bytes) | `COMPACT` — this is Intelligence's recommended maximum, not an adapter rejection threshold; use the compaction procedure in `intelligence-review-context` to reduce the owning sources without teaching terse output |
 | **Rule links to a rule** | A markdown link from one rule to another (`R1`) | `UNLINK` — name the rule instead: always-on rules are inlined into `AGENTS.md` and the scoped channels carry only scoped rules, so the link is dead in at least one output |
 | **Machine facts in a rule** | OS, shell, editor or a local absolute path (`R2`) | `MOVE` — these belong in a local rule, `<content-dir>/rules/<name>.local.md`, which Git ignores and sync keeps out of committed output; a rule is committed and read by everyone, including whoever is on another platform |
@@ -14,7 +15,7 @@ Apply these checks to the source groups resolved by the review skill.
 | **Skill with no verification** | Nothing at the end proves the procedure worked (`R4`) | `FLAG` — a procedure that proves nothing is a note, or just the work: give it a verification, or delete it |
 | **Pressure marker** | A heading or section named CRITICAL / MANDATORY / HARD RULE / READ FIRST, or a density of `MUST` / `NEVER` / `ALWAYS` with no reason beside it (`R5`) | `REWRITE` - plain heading, one reason per constraint; when several instructions are each marked critical the marker stops carrying information, so keep emphasis for the one instruction demonstrably under-weighted without it |
 | **History narrative** | A PR number, incident id, commit SHA, date or "this session" inside a rule body (`R6`) | `REWRITE` - keep the causal sentence, drop the archaeology; a rule's authority is the behaviour it prescribes, and git history keeps the date |
-| **Reserved prefix** | A project artifact named `intelligence-*` | `RENAME` — the prefix belongs to the sync package and collides in generated output |
+| **Name collision** | A project artifact named `intelligence-*` or like an installed package artifact it does not mean to override, or a skill named like a built-in command or bundled skill of an enabled tool ([Claude Code commands](https://code.claude.com/docs/en/commands)) | `RENAME` - the project artifact renders in the package's place, and a Claude Code skill replaces the command of its name but not that command's aliases, so one request runs different procedures depending on the name typed |
 | **Naming** | A skill that is not `<domain>-<verb>-<noun>`, or a domain invented rather than reused | `RENAME` — or introduce the new domain deliberately |
 | **Stale** | No edits in 6+ months and nothing cross-references it | `ARCHIVE` — move to `<content-dir>/_archive/` |
 | **Negative-framed judgement call** | "Never do X" where a positive default fits, outside safety / security / output-format | `REWRITE` — state the default; reserve NEVER for true must-nots |
@@ -23,6 +24,7 @@ Apply these checks to the source groups resolved by the review skill.
 | **Weak / duplicate description** | Identical to a sibling, or too vague to choose between them | `DIFFERENTIATE` — add the distinguishing trigger |
 | **Description over budget** | Over ~250 characters (the shared registry budget); over **1024** the tools reject the artifact outright | `TRIM` — keep the distinguishing trigger, drop the rest |
 | **Missing frontmatter field** | `name` or `description` absent | `PATCH` — add it |
+| **Dead skill field** | `agent:` in a `SKILL.md` without `context: fork` (`R8`) | `PATCH` - delete `agent:`, which selects nothing without the fork, or fork the skill when the authoring conventions say it should |
 | **Orphan rule** | Nothing points at it and nothing loads it | `FLAG` — intentional, or dead? |
 
 Detection commands, portable on purpose — no `\b` and no `-P`, so the same command works in Git Bash on Windows, on macOS (BSD grep) and on Linux. Run each over the source directories resolved in step 2, never over generated output:
@@ -51,6 +53,28 @@ grep -rcE '(MUST|NEVER|ALWAYS)' <rule-dirs> <agent-dirs> <skill-dirs> | grep -vE
 # R6 - history narrative in a rule body: PR numbers, incident ids, dates, "this session", commit SHAs
 grep -rniE -e '(#|PR )[0-9]{3,}' -e '[0-9]{4}-[0-9]{2}-[0-9]{2}' -e 'this session|origin session' \
   -e '`[0-9a-f]{7,40}`' <rule-dirs>
+
+# R7 - words per file, then the longest paragraph; a list item or table row is its own paragraph
+find <rule-dirs> <agent-dirs> <skill-dirs> -name '*.md' | while IFS= read -r f; do
+  awk -v f="$f" 'BEGIN { fence = sprintf("%c%c%c", 96, 96, 96) }
+    NR == 1 && /^---[ \t\r]*$/ { fm = 1; next }
+    fm { if (/^---[ \t\r]*$/) fm = 0; next }
+    { w += NF }
+    index($1, fence) == 1 { code = !code; p = 0; next }
+    code || NF == 0 { p = 0; next }
+    /^[ \t]*(#|[-*] |[0-9]+\. |\|)/ { p = 0 }
+    { p += NF; if (p > max) max = p }
+    END { printf "%6d %4d %s\n", w, max, f }' "$f"
+done | sort -rn
+
+# R8 - a skill's agent: without context: fork, read from the frontmatter only
+find <skill-dirs> -name SKILL.md | while IFS= read -r f; do
+  awk -v f="$f" 'NR == 1 && /^---[ \t\r]*$/ { fm = 1; next }
+    fm && /^---[ \t\r]*$/ { exit }
+    fm && /^agent:/ { a = 1 }
+    fm && /^context:[ \t]*"?fork/ { c = 1 }
+    END { if (a && !c) print f }' "$f"
+done
 ```
 
 `R4` is a coarse net, not a verdict: a skill that merely *mentions* a verification command anywhere passes it. Read the final step of every skill regardless — the question is whether something at the end **proves the work landed**, not whether the word appears. So are `R5` and `R6`: a `NEVER` that carries its reason and a date inside a frontmatter template are both legitimate hits, and the row's action applies only where the marker or the id is doing no work.

package/packages/sync/skills/intelligence-review-context/references/compaction.md

@@ -35,12 +35,14 @@ product requirement.
 
 Proposals use `DELETE`, `MERGE`, `SCOPE`, `MOVE`, `REFERENCE`, or `REWRITE` and name
 the owner, semantic contract, estimated savings, and any changed behavior or load
-timing. Keep unapproved passages byte-for-byte; the review skill routes only
-accepted proposals to the shared authoring procedure.
+timing. Keep unapproved passages byte-for-byte; only accepted proposals reach
+the shared authoring procedure, which runs the steps below.
 
 ## Verify the accepted result
 
-1. Compare the ledger with the diff. Each original behavior exists once in its
+1. Before editing, when the baseline marks a rendered measurement missing, record
+   `<sync-cmd> --compact` output and require `IS_STATUS=ok`. After editing,
+   compare the ledger with the diff. Each original behavior exists once in its
    authoritative owner, was deliberately removed with approval, or is enforced by
    the named deterministic mechanism. Check for dead links, unconditional reference
    loads, conflicting instructions, and unintended scope expansion.
@@ -54,4 +56,4 @@ accepted proposals to the shared authoring procedure.
    and an ordinary explanation that reveals clipped language. Report explicitly
    when this evaluation is unavailable: fewer bytes prove size, not quality.
 4. Report artifacts changed, behavior checks, measurements, and remaining owner
-   decisions. Return these results to the review skill's final report.
+   decisions in the authoring skill's final report.

package/packages/sync/skills/intelligence-sync/SKILL.md

@@ -3,6 +3,7 @@ name: intelligence-sync
 description: "Sync intelligence to enabled adapters"
 agent: intelligence-operator
 context: fork
+background: false
 ---
 
 # Sync intelligence
@@ -19,13 +20,12 @@ context: fork
    `IS_STATUS=needs-update` (exit 6) means the project needs a migration only
    `intelligence update` applies; report that, and never edit the manifest or
    lock by hand to get past it. A frozen restore refusal means the
-   manifest and lock disagree or the locked commit cannot be verified/restored—report it without
-   hand-copying package content.
-4. On a probable Intelligence defect, first ask whether to collect a sanitized
-   issue draft; collect nothing before approval and never use telemetry. Include
-   only approved CLI/version, expected/actual behavior, and safe error details—
-   no confidential or project-specific data. Show the draft and obtain separate
-   approval before filing. If declined, ask whether the opt-out is for this
-   session, a user/gitignored dev-project profile, or a shared team policy; save
-   it only with separate approval. Put team policy in a project-owned rule, and
-   never invent a profile path or infer the intended scope.
+   manifest and lock disagree or the locked commit cannot be verified or restored;
+   report it without hand-copying package content.
+4. On a probable Intelligence defect, end the result with a block headed
+   `Probable Intelligence defect` that holds only safe facts: the CLI and engine
+   versions from `intelligence version`, the command, the expected and the actual
+   behavior, and error text with nothing confidential or specific to the project.
+   Follow it with an issue draft built from those facts alone. The result is the
+   only place they go: send and file nothing, and use no telemetry. Filing the
+   draft is a separate request the person makes.

package/packages/sync/skills/intelligence-update-context/SKILL.md

@@ -2,7 +2,6 @@
 name: intelligence-update-context
 description: "Create, revise, or remove project rules, agents, and skills"
 argument-hint: "[rule|agent|skill] [request or accepted proposals]"
-agent: intelligence-architect
 ---
 
 # Update project context
@@ -74,3 +73,6 @@ the same procedure. Updating the layer can create a new artifact.
 9. Report the created, updated, removed, or archived artifacts and their checks.
    Return control to the originating workflow for its additional semantic,
    compaction, migration, or packaging verification; those checks remain required.
+   Review proposals carry their verification steps instead, because the review
+   has already returned: run each at the point it names, before or after editing,
+   and report the results here.

package/packages/sync/skills/intelligence-update-context/references/skills.md

@@ -22,15 +22,16 @@
 name: <domain>-<verb>-<noun>
 description: "What the skill does and when to use it"
 argument-hint: "Expected arguments"
-agent: <existing-agent>
 ---
 ```
 
 Omit optional fields that do not apply. Add `effort:` only when the procedure
 needs a reasoning effort other than the session's, using the scale in the
-authoring conventions' effort mappings. Add the skill to its matching agent's
+authoring conventions' effort mappings. Add `context: fork` with `agent:` only
+for a skill the authoring conventions say to fork, and `background: false` when
+its caller needs the result in the same turn. Add the skill to its matching agent's
 `skills:` list when that agent is project-owned; propose an upstream change for
 a package-owned agent instead of editing the installed copy. Verify bindings,
 relative resource links, executable steps, and final success criteria. Apply the
-1000-line skill limit and other budgets from the authoring conventions, then
-return to the shared sync and verification steps.
+word budgets from the authoring conventions, then return to the shared sync and
+verification steps.

package/packages/sync/skills/intelligence-upgrade/SKILL.md

@@ -2,7 +2,6 @@
 name: intelligence-upgrade
 description: "Upgrade Intelligence and installed packages with migration checks"
 argument-hint: "[@scope/name]"
-agent: intelligence-operator
 disable-model-invocation: true
 ---