@ainova-systems/intelligence 0.19.0 → 0.21.0

package/engine/lib/common.sh

@@ -71,6 +71,46 @@ IS_AWK_LIB='
         return val
     }
     function base_name(p,   q, m) { m = split(p, q, "/"); return q[m] }
+    # The name a source renders under (decision 0021) comes from the source
+    # catalog, which hands a batch its `<path> US <name>` lines through
+    # ENVIRON["IS_NAME_MAP"]. A path the map does not hold keeps its own name.
+    BEGIN {
+        is_nm_n = split(ENVIRON["IS_NAME_MAP"], is_nm_rows, "\n")
+        for (is_nm_i = 1; is_nm_i <= is_nm_n; is_nm_i++) {
+            is_nm_p = index(is_nm_rows[is_nm_i], sprintf("%c", 31))
+            if (is_nm_p > 0) ART_NAME[substr(is_nm_rows[is_nm_i], 1, is_nm_p - 1)] = substr(is_nm_rows[is_nm_i], is_nm_p + 1)
+        }
+    }
+    # art_file(path, ext) — the output file name: the catalog name plus <ext>,
+    # or the source file name itself.
+    function art_file(p, ext) { return (p in ART_NAME) ? ART_NAME[p] ext : base_name(p) }
+    # art_name(path) — the catalog name, or the file name without `.md`.
+    function art_name(p,   b) {
+        if (p in ART_NAME) return ART_NAME[p]
+        b = base_name(p); sub(/\.md$/, "", b); return b
+    }
+    # tgt_drop(line) — whether a frontmatter line belongs to `targets:` or
+    # `exclude_targets:` (decision 0021), which select adapters and are
+    # removed from every rendered copy. Call tgt_reset() at the start of each
+    # file and tgt_drop() for each of its frontmatter lines in order: a block
+    # list, or a flow list spanning lines, goes with its key.
+    function tgt_reset() { tgt_cont = "" }
+    function tgt_drop(s,   v) {
+        if (tgt_cont == "block") {
+            if (s ~ /^[ \t]/ || s == "") return 1
+            tgt_cont = ""
+        } else if (tgt_cont == "flow") {
+            if (index(s, "]")) tgt_cont = ""
+            return 1
+        }
+        if (s !~ /^(targets|exclude_targets):/) return 0
+        v = substr(s, index(s, ":") + 1)
+        sub(/[ \t]+#.*$/, "", v)
+        gsub(/^[ \t]+|[ \t]+$/, "", v)
+        if (v == "") tgt_cont = "block"
+        else if (substr(v, 1, 1) == "[" && !index(v, "]")) tgt_cont = "flow"
+        return 1
+    }
 '
 
 # is_fin_awk_vars — fill the global IS_FIN_V array with the -v bindings the
@@ -119,23 +159,58 @@ finalize_output_file() {
 finalize_copy_files() {
     local dst="$1"
     shift
+    finalize_copy_named "$dst" "" "$@"
+}
+
+# finalize_copy_named <dst_dir> <name-map> <src>... — finalize_copy_files with
+# each source written as <dst_dir>/<name>.md when <name-map> holds it: the
+# rendered names source_artifacts_var leaves in IS_SOURCE_NAME_MAP, so
+# `.draft.md` and `me.local.md` land as `draft.md` and `me.md`.
+finalize_copy_named() {
+    local dst="$1" map="$2" f
+    shift 2
     [ "$#" -gt 0 ] || return 0
-    local f
     # awk never reads a record from an empty source, so pre-create those to
     # keep the old cp behavior of producing an empty output file.
     for f in "$@"; do
-        [ -s "$f" ] || : > "$dst/${f##*/}"
+        [ -s "$f" ] && continue
+        if source_name_map_var "$map" "$f"; then
+            : > "$dst/$IS_MAPPED_NAME.md"
+        else
+            : > "$dst/${f##*/}"
+        fi
     done
     is_fin_awk_vars
-    awk "${IS_FIN_V[@]}" -v dst="$dst" "$IS_AWK_LIB"'
+    IS_NAME_MAP="$map" awk "${IS_FIN_V[@]}" -v dst="$dst" "$IS_AWK_LIB"'
         FNR == 1 {
             if (out_file != "") close(out_file)
-            out_file = dst "/" base_name(FILENAME)
+            out_file = dst "/" art_file(FILENAME, ".md")
+            tgt_reset()
         }
-        { sub(/\r$/, ""); print fin_line($0) > out_file }
+        { sub(/\r$/, "") }
+        FNR == 1 { cp_fm = ($0 == "---") }
+        FNR > 1 && cp_fm == 1 {
+            if ($0 == "---") cp_fm = 2
+            else if (tgt_drop($0)) next
+        }
+        { print fin_line($0) > out_file }
     ' "$@"
 }
 
+# source_name_map_var <name-map> <path> — set IS_MAPPED_NAME to the name the
+# map gives <path>; return 1 when it gives none. A map is "\n" followed by one
+# `<path> US <name>` line per source.
+source_name_map_var() {
+    local rest
+    IS_MAPPED_NAME=""
+    case "$1" in
+        *$'\n'"$2"$'\x1f'*) ;;
+        *) return 1 ;;
+    esac
+    rest="${1#*$'\n'"$2"$'\x1f'}"
+    IS_MAPPED_NAME="${rest%%$'\n'*}"
+}
+
 # frontmatter_index <keys-csv> <file>...
 # One awk pass over many files; prints one row per file, in argument order:
 # the path, then one value per requested key, all separated by \x1f (ASCII
@@ -394,6 +469,22 @@ emit_wrapped_bodies() {
     ' "${srcs[@]}"
 }
 
+# emit_rule_bodies <file>... — every rule's body without its frontmatter, in
+# one awk, a blank line after each: how AGENTS.md inlines always-on rules, and
+# how Codex's AGENTS.override.md adds the ones AGENTS.md does not carry.
+emit_rule_bodies() {
+    [ "$#" -gt 0 ] || return 0
+    awk '
+        FNR == 1 { if (NR != 1) print ""; in_fm = 0; past_fm = 0 }
+        { sub(/\r$/, "") }
+        /^---$/ {
+            if (!past_fm) { in_fm = !in_fm; if (!in_fm) { past_fm = 1 }; next }
+        }
+        past_fm || !in_fm { print }
+        END { print "" }
+    ' "$@"
+}
+
 # Copy a markdown file with frontmatter, ensuring free-text string fields are
 # wrapped in double quotes. Used by adapters that feed strict-YAML consumers
 # (Codex CLI rejects unquoted colons / booleans). Idempotent — already-quoted
@@ -452,8 +543,11 @@ copy_md_with_quoted_frontmatter() {
 # ship support files beside SKILL.md, and SKILL.md bodies point at them by
 # relative path, so dropping them breaks the skill at runtime). Markdown is
 # normalized to LF; every other file is copied byte-for-byte so potentially
-# binary assets survive. `cp -R` copies symlinks as symlinks (POSIX), so a
-# link inside a source skill never leaks host file content into the output.
+# binary assets survive. A symlink never reaches the output: the plan
+# skill_source_inventory made turns a link inside its source into the regular
+# file or directory it points at and leaves any other out, and the flush
+# removes a link no plan covered (a copy from outside every skills source), so
+# no host file outside the source is ever copied in (decision 0017).
 #
 # SKILL.md frontmatter is quoted for EVERY consumer, not only the strict-YAML
 # ones. `argument-hint: [pr-number]` is a YAML *flow sequence*, so an unquoted
@@ -470,7 +564,7 @@ copy_md_with_quoted_frontmatter() {
 # Usage: copy_skill_bundle "src/skill/dir" "dest/skill/dir"
 copy_skill_bundle() {
     _skill_bundles_reset
-    _skill_bundle_stage "$1" "$2"
+    _skill_bundle_stage "$1" "$2" || return 1
     _skill_bundles_flush open
 }
 
@@ -478,7 +572,8 @@ copy_skill_bundle() {
 # copies every source skill directory into <dest_root>/<skill-name>, then one
 # awk pass quotes and finalizes every bundled markdown file across all
 # bundles. A later source with the same skill name overwrites file-by-file in
-# order, exactly like the sequential per-bundle copies did.
+# order, exactly like the sequential per-bundle copies did. A skill with links
+# to resolve is copied from its materialized stage, in the same order.
 copy_skill_bundle_dirs() {
     copy_skill_bundle_dirs_for open "$@"
 }
@@ -488,18 +583,59 @@ copy_skill_bundle_dirs() {
 copy_skill_bundle_dirs_for() {
     local effort_tool="$1" dest_root="$2"
     shift 2
+    copy_skill_bundle_dirs_named "$effort_tool" "$dest_root" "" "$@"
+}
+
+# copy_skill_bundle_dirs_named <tool> <dest_root> <name-map> <src_dir>... — the
+# batch form with each skill copied to <dest_root>/<name> when <name-map> holds
+# its directory: the rendered names source_artifacts_var leaves in
+# IS_SOURCE_NAME_MAP, so `deploy.local/` lands as `deploy/` and still matches
+# its own `name: deploy`. Only a skill whose name differs from its directory
+# costs a copy of its own.
+copy_skill_bundle_dirs_named() {
+    local effort_tool="$1" dest_root="$2" map="$3"
+    shift 3
     [ "$#" -gt 0 ] || return 0
-    local src dest
-    local -a srcs=()
+    local src from name dest i linked=0 renamed=0
+    local -a srcs=() names=()
     for src in "$@"; do
-        srcs+=("${src%/}")
+        src="${src%/}"
+        srcs+=("$src")
+        name="${src##*/}"
+        if source_name_map_var "$map" "$src" && [ "$IS_MAPPED_NAME" != "$name" ]; then
+            name="$IS_MAPPED_NAME"
+            renamed=1
+        fi
+        names+=("$name")
+        ! _ski_planned "$src" || linked=1
     done
     mkdir -p "$dest_root"
-    cp -R "${srcs[@]}" "$dest_root/"
+    if [ "$linked" = 0 ] && [ "$renamed" = 0 ]; then
+        cp -R "${srcs[@]}" "$dest_root/"
+    else
+        for ((i = 0; i < ${#srcs[@]}; i++)); do
+            src="${srcs[i]}"
+            from="$src"
+            if _ski_planned "$src"; then
+                _skill_bundle_materialize "$src" || return 1
+                from="$IS_SKI_STAGED"
+            fi
+            dest="$dest_root/${names[i]}"
+            if [ "${names[i]}" = "${src##*/}" ]; then
+                cp -R "$from" "$dest_root/" || return 1
+            elif [ -e "$dest" ]; then
+                # A second skill of one name merges file by file, as the
+                # batch copy of same-named directories does.
+                cp -R "$from/." "$dest/" || return 1
+            else
+                cp -R "$from" "$dest" || return 1
+            fi
+            [ "$from" = "$src" ] || rm -rf "${IS_SKI_STAGED%/*}"
+        done
+    fi
     _skill_bundles_reset
-    for src in "${srcs[@]}"; do
-        dest="$dest_root/${src##*/}"
-        _skill_bundle_note "$dest"
+    for name in "${names[@]}"; do
+        _skill_bundle_note "$dest_root/$name"
     done
     _skill_bundles_flush "$effort_tool"
 }
@@ -513,24 +649,63 @@ _skill_bundles_reset() {
 _skill_bundle_stage() {
     local src="${1%/}" dest="$2"
     mkdir -p "$dest"
-    cp -R "$src/." "$dest/"
+    if _ski_planned "$src"; then
+        _skill_bundle_materialize "$src" || return 1
+        cp -R "$IS_SKI_STAGED/." "$dest/" || return 1
+        rm -rf "${IS_SKI_STAGED%/*}"
+    else
+        cp -R "$src/." "$dest/"
+    fi
     _skill_bundle_note "$dest"
 }
 
+# _skill_bundle_materialize <skill_dir> — copy a skill whose plan holds links
+# into a fresh stage and apply the plan there, parents first: each planned link
+# is replaced by a copy of the file or directory it resolves to inside its
+# source, or removed. Sets IS_SKI_STAGED to <stage>/<name>; the caller copies
+# it on and removes the stage. Spawns per link, never per file — a source
+# without links never comes here.
+_skill_bundle_materialize() {
+    local src="$1" key stage out rec rel act phys first=1
+    _ski_key_var "$src"
+    key="$_SKI_KEY"
+    stage="$(mktemp -d -t intelligence-skill-XXXXXX)" || return 1
+    out="$stage/${key##*/}"
+    while IFS= read -r rec; do
+        case "$rec" in
+            "$key$IS_SKI_US"*) ;;
+            *) continue ;;
+        esac
+        rec="${rec#"$key$IS_SKI_US"}"
+        rel="${rec%%"$IS_SKI_US"*}"
+        rec="${rec#*"$IS_SKI_US"}"
+        act="${rec%%"$IS_SKI_US"*}"
+        phys="${rec#*"$IS_SKI_US"}"
+        if [ "$first" = 1 ]; then
+            first=0
+            if [ -z "$rel" ]; then
+                # The skill directory itself is the link.
+                mkdir "$out" && cp -R "$phys/." "$out/" || return 1
+                continue
+            fi
+            cp -R "$src" "$stage/" || return 1
+        fi
+        # The copy holds the link itself here; `rm -f` never follows it and
+        # refuses a directory, so a plan that no longer matches stops the run.
+        rm -f "$out/$rel" || return 1
+        case "$act" in
+            f) cp "$phys" "$out/$rel" || return 1 ;;
+            d) mkdir "$out/$rel" && cp -R "$phys/." "$out/$rel/" || return 1 ;;
+        esac
+    done <<< "$IS_SKI_PLAN"
+    IS_SKI_STAGED="$out"
+}
+
 # Record a staged bundle for the flush pass: mark its SKILL.md for
 # frontmatter quoting and deduplicate the destination.
 _skill_bundle_note() {
     local dest="$1"
-    # A symlinked SKILL.md is left exactly as `cp -R` produced it — a
-    # symlink. `[ -f ]` follows links, so quoting it would read the link's
-    # TARGET and write that content into a real file, turning
-    # `skills/x/SKILL.md -> /etc/…` into a copy of a host file inside the
-    # output. That is the leak the symlink-preserving copy exists to
-    # prevent, so skip the rewrite and say so (the same reason
-    # `find -type f` in the flush never matches a symlink).
-    if [ -L "$dest/SKILL.md" ]; then
-        echo "  WARN: ${dest##*/}/SKILL.md is a symlink — emitted as-is (frontmatter not quoted, tokens not expanded)" >&2
-    elif [ -f "$dest/SKILL.md" ]; then
+    if [ -f "$dest/SKILL.md" ]; then
         _SB_QUOTE_LIST="$_SB_QUOTE_LIST$dest/SKILL.md"$'\n'
     fi
     # The same skill name from a later source overwrites the earlier copy;
@@ -547,11 +722,25 @@ _skill_bundle_note() {
 # _skill_bundles_flush <effort-tool>
 _skill_bundles_flush() {
     [ "${#_SB_DESTS[@]}" -gt 0 ] || return 0
-    local -a mds=()
-    local f quote_list="$_SB_QUOTE_LIST"
+    local -a mds=() links=()
+    local f listing quote_list="$_SB_QUOTE_LIST"
+    # Captured, not streamed: a listing cut short could leave a link behind.
+    listing="$(find "${_SB_DESTS[@]}" \( -type l -o -type f -name '*.md' \) -print)" || {
+        echo "ERROR: could not list the skill copies under ${_SB_DESTS[0]%/*}" >&2
+        return 1
+    }
     while IFS= read -r f; do
-        [ -n "$f" ] && mds+=("$f")
-    done < <(find "${_SB_DESTS[@]}" -type f -name '*.md')
+        [ -n "$f" ] || continue
+        if [ -L "$f" ]; then links+=("$f"); else mds+=("$f"); fi
+    done <<< "$listing"
+    # A link only a copy from outside every skills source can bring: no plan
+    # resolved it, so it is not followed but removed.
+    if [ "${#links[@]}" -gt 0 ]; then
+        rm -f "${links[@]}" || return 1
+        for f in "${links[@]}"; do
+            echo "WARNING: ${f#"${REPO_ROOT:-}"/} was copied as a symlink from outside every skills source — removed; generated output never holds one" >&2
+        done
+    fi
     _skill_bundles_reset
     [ "${#mds[@]}" -gt 0 ] || return 0
     effort_map_var "$1"
@@ -596,12 +785,14 @@ _skill_bundles_flush() {
             out_file = FILENAME; line_n = 0
             state = (FILENAME in QUOTE) ? "before" : ""
             effort_seen = 0
+            tgt_reset()
         }
         { sub(/\r$/, "") }
         state == "before" {
             if (FNR == 1 && $0 == "---") state = "in_fm"
             else state = "after"
         }
+        state == "in_fm" && FNR > 1 && $0 != "---" && tgt_drop($0) { next }
         state == "in_fm" && FNR > 1 && substr($0, 1, 7) == "effort:" {
             if (effort_seen++) next
             val = fm_value_strip(substr($0, 8))
@@ -671,26 +862,27 @@ sync_open_skill_dirs() {
     fi
     mkdir -p "$output_dir"
 
-    local count=0 log="" d skill_file skill_name
+    local count=0 log="" i rel
     local -a skill_dirs=()
-    read_source_artifact_files "$repo_root" "$config_file" "skills"
+    # Every tool that reads this directory reads all of it, so a skill lands
+    # here when it is for any of them (decision 0021). The engine names the
+    # enabled readers from their contracts.
+    normalize_path_var "$output_dir"
+    rel="${IS_NORM_PATH#"$repo_root"/}"
+    source_artifacts_var "$repo_root" "$config_file" skills \
+        "${IS_OPEN_SKILLS_READERS-antigravity codex opencode pi}" "$rel/{}"
     # Guard on the count, then expand quoted: Bash 3.2 (macOS) errors on an
     # empty array under `set -u`, and quoting keeps a path with a space or a
     # glob character intact.
-    if [ "${#IS_SOURCE_FILES[@]}" -gt 0 ]; then
-        for skill_file in "${IS_SOURCE_FILES[@]}"; do
-            [ -n "$skill_file" ] || continue
-            d="${skill_file%/SKILL.md}"
-            skill_name="${d##*/}"
-            skill_dirs+=("$d/")
-            count=$((count + 1))
-            log+="  skill: $skill_name"$'\n'
-        done
-    fi
+    for ((i = 0; i < ${#IS_SOURCE_FILES[@]}; i++)); do
+        skill_dirs+=("${IS_SOURCE_FILES[i]%/SKILL.md}/")
+        count=$((count + 1))
+        log+="  skill: ${IS_SOURCE_NAMES[i]}"$'\n'
+    done
     # copy_skill_bundle_dirs owns the frontmatter-quoting pass, so every
     # target gets it — not just this open-standard dir.
     if [ "$count" -gt 0 ]; then
-        copy_skill_bundle_dirs_for open "$output_dir" "${skill_dirs[@]}"
+        copy_skill_bundle_dirs_named open "$output_dir" "$IS_SOURCE_NAME_MAP" "${skill_dirs[@]}"
         open_skill_invocation_policies "$output_dir" || return 1
     fi
 
@@ -711,19 +903,15 @@ sync_open_skill_dirs() {
 # when the author's file sets none, and a file whose policy says otherwise, or
 # that sync cannot read as saying it, refuses the render — an owner-only skill
 # Codex can still select is the exact failure the field exists to prevent, so
-# it never passes as a success.
+# it never passes as a success. The tree holds no symlink — copy_skill_bundle_dirs
+# renders a link inside its source as a regular file and leaves any other out —
+# so a skill whose SKILL.md or agents/openai.yaml is a link in its source is
+# read and enforced like any other.
 open_skill_invocation_policies() {
     local output_dir="$1" path dir flag rows refusals
     local -a skill_mds=() policy_dirs=() policies=() authored=()
     for path in "$output_dir"/*/SKILL.md; do
-        dir="${path%/SKILL.md}"
-        # A link is emitted as-is (see _skill_bundle_note): reading through it
-        # or writing beside it would reach outside the output tree.
-        if [ -L "$dir" ] || [ -L "$path" ]; then
-            echo "  WARN: ${dir##*/}/SKILL.md is reached through a symlink — Codex gets no invocation policy derived for it" >&2
-        elif [ -f "$path" ]; then
-            skill_mds+=("$path")
-        fi
+        [ ! -f "$path" ] || skill_mds+=("$path")
     done
     [ "${#skill_mds[@]}" -gt 0 ] || return 0
     # Captured, not streamed: a reader cut short must fail the render rather
@@ -736,10 +924,6 @@ open_skill_invocation_policies() {
         [ "$flag" = "true" ] || continue
         dir="${path%/SKILL.md}"
         path="$dir/agents"
-        if [ -L "$path" ] || [ -L "$path/openai.yaml" ]; then
-            echo "  WARN: ${dir##*/}/agents/openai.yaml is a symlink — left as-is, its invocation policy is not enforced" >&2
-            continue
-        fi
         if [ -s "$path/openai.yaml" ]; then
             authored+=("$path/openai.yaml")
             continue
@@ -860,6 +1044,8 @@ enforce_authored_invocation_policies() {
 # Lint YAML frontmatter for common pitfalls (unquoted colons, leading tabs).
 # Print warnings to stderr; do not fail. Strict consumers (Codex CLI) reject
 # these files with cryptic messages — catching them in sync gives better DX.
+# Each finding is a `WARNING:` line: the author has to edit the source, so
+# `sync --compact` (the first sync `init` runs) must keep it.
 # Batched: one awk process lints every file passed.
 # The engine lints every source once, so this is also where an `effort:` off
 # IS_EFFORT_LEVELS is reported — read with frontmatter_index's semantics,
@@ -870,7 +1056,13 @@ enforce_authored_invocation_policies() {
 # Usage: lint_frontmatter_files "a.md" "b.md" ...
 lint_frontmatter_files() {
     [ "$#" -gt 0 ] || return 0
-    awk -v levels="$IS_EFFORT_LEVELS" "$IS_AWK_LIB"'
+    awk -v levels="$IS_EFFORT_LEVELS" "$IS_AWK_LIB$_IS_AWK_LINT" "$@"
+}
+
+# The lint rules, shared with source_frontmatter_scan, which runs them in the
+# same pass that reads routing fields. Every rule may end with `next`, so a
+# program that joins them puts its own rules first.
+_IS_AWK_LINT='
         BEGIN {
             nl = split(levels, LV, " ")
             allowed = ""
@@ -892,7 +1084,7 @@ lint_frontmatter_files() {
             }
         }
         in_fm && /^\t/ {
-            printf "  WARN: %s:%d leading tab in frontmatter (use spaces)\n", FILENAME, FNR > "/dev/stderr"
+            printf "WARNING: %s:%d leading tab in frontmatter (use spaces)\n", FILENAME, FNR > "/dev/stderr"
         }
         in_fm && /^[a-zA-Z0-9_-]+:[[:space:]]+[^"\047|>[{]/ {
             value_start = index($0, ":") + 1
@@ -900,10 +1092,10 @@ lint_frontmatter_files() {
             sub(/^[[:space:]]+/, "", value)
             if (value ~ /:[[:space:]]/ || value ~ /:$/) {
                 col = index(value, ":") + value_start
-                printf "  WARN: %s:%d unquoted colon in value at column %d — wrap value in quotes\n", FILENAME, FNR, col > "/dev/stderr"
+                printf "WARNING: %s:%d unquoted colon in value at column %d — wrap value in quotes\n", FILENAME, FNR, col > "/dev/stderr"
             }
             if (value ~ /"/) {
-                printf "  WARN: %s:%d literal double quote in unquoted value — wrap value in single quotes or escape as \\\" so strict-YAML targets accept it\n", FILENAME, FNR > "/dev/stderr"
+                printf "WARNING: %s:%d literal double quote in unquoted value — wrap value in single quotes or escape as \\\" so strict-YAML targets accept it\n", FILENAME, FNR > "/dev/stderr"
             }
         }
         # Field-length limits. Both Claude Code and the Agent Skills standard
@@ -922,11 +1114,10 @@ lint_frontmatter_files() {
             }
             limit = (key == "name") ? 64 : 1024
             if (length(val) > limit) {
-                printf "  WARN: %s:%d %s is %d chars — over the %d-char limit; the skill/agent will be REJECTED at load time\n", FILENAME, FNR, key, length(val), limit > "/dev/stderr"
+                printf "WARNING: %s:%d %s is %d chars — over the %d-char limit; the skill/agent will be REJECTED at load time\n", FILENAME, FNR, key, length(val), limit > "/dev/stderr"
             }
         }
-    ' "$@"
-}
+'
 
 # lint_frontmatter <file> — single-file form for project adapters.
 lint_frontmatter() {
@@ -1561,7 +1752,8 @@ warn_unsynced() {
         load_yaml_list "$config_file" "$section"
         while IFS= read -r src; do
             [ -z "$src" ] && continue
-            all_sources+=("$src")
+            normalize_path_var "$repo_root/$src"
+            all_sources+=("${IS_NORM_PATH#"$repo_root/"}")
         done <<< "$IS_YAML_LIST"
     done
 
@@ -1655,11 +1847,7 @@ warn_unsynced() {
         done
 
         if [ "$matched" = false ]; then
-            if [ $warnings -eq 0 ]; then
-                echo ""
-                echo "=== WARNING: Unsynced directories ==="
-            fi
-            echo "  NOT SYNCED: $rel_dir"
+            echo "WARNING: NOT SYNCED: $rel_dir" >&2
             warnings=$((warnings + 1))
         fi
     done < <(find "$repo_root" \( -name ".git" -o -name "node_modules" -o -name "vendor" -o -name "dist" -o -name ".claude" -o -name ".cursor" -o -name ".github" -o -name ".codex" -o -name ".agents" -o -name ".intelligence" \) -prune -o -type d \( -name "rules" -o -name "agents" -o -name "skills" -o -name "Rules" -o -name "Agents" -o -name "Skills" \) -print 2>/dev/null)
@@ -1670,10 +1858,367 @@ warn_unsynced() {
         # and hand-placing an entry in an ordered list decides which artifact
         # wins. The engine may also run without the CLI around it.
         if [ "${IS_CLI:-0}" = "1" ]; then
-            echo "  Wire one in: intelligence source add <rules|agents|skills> <path>"
+            echo "WARNING: Wire one in: intelligence source add <rules|agents|skills> <path>" >&2
         else
-            echo "  Add these paths to sources: in ${config_file##*/}"
+            echo "WARNING: Add these paths to sources: in ${config_file##*/}" >&2
+        fi
+    fi
+}
+
+# --- Skill sources and the symlinks inside them (decision 0017) ---
+#
+# A symlink in a skills source renders as the regular file or directory it
+# resolves to while that stays inside the same source, and is left out with a
+# WARNING: line when it resolves outside it, nowhere, or to a directory that
+# encloses it. Generated output never holds a link, and nothing is ever copied
+# from outside the source (decision 0006). Every consumer takes that decision
+# from here, once per run: the skill list read_source_artifact_files returns,
+# which the source catalog reads, the membership skill_source_rendered
+# answers, and the plan copy_skill_bundle_dirs applies to its copy. A skill
+# rendered from a link is an ordinary skill from then on — quoting, token
+# expansion, the effort rendering and the Codex invocation policy all run on
+# the output copy.
+#
+# skill_source_inventory <repo_root> <config_file> fills, in the caller's
+# shell and fail-closed like read_source_artifact_files:
+#   IS_SKI_LIST  <source>/<skill>/SKILL.md of every rendered skill, one a line,
+#                sources in manifest order, names in byte order;
+#   IS_SKI_KEYS  "\n<source>/<skill>\n…", the same skills as a membership set;
+#   IS_SKI_PLAN  "\n" + one record a line for every link in a rendered skill,
+#                parents first: <source>/<skill> US <path in the skill copy>
+#                US f|d|x US <physical target>. f and d materialize the file or
+#                directory at that path, x leaves the link out; an empty path
+#                is the skill directory itself.
+# The resolution spawns processes only for a source that holds a link, and
+# then per source and per link-chain hop, never per file.
+IS_SKI_US=$'\x1f'
+
+skill_source_inventory() {
+    local repo_root="$1" config_file="$2" memo_key src dir listing
+    memo_key="$repo_root"$'\n'"$config_file"
+    if [ "${IS_SOURCE_FILES_MEMO:-0}" = 1 ] && [ "${IS_SKI_KEY:-}" = "$memo_key" ]; then
+        return 0
+    fi
+    IS_SKI_KEY=""
+    IS_SKI_LIST=""
+    IS_SKI_KEYS=$'\n'
+    IS_SKI_PLAN=$'\n'
+    load_yaml_list "$config_file" "skills"
+    while IFS= read -r src; do
+        [ -n "$src" ] || continue
+        dir="$repo_root/$src"
+        while [ "${dir%/}" != "$dir" ]; do dir="${dir%/}"; done
+        [ -d "$dir" ] || continue
+        # Every directory and link at any depth: the top level holds the
+        # skills, and a link anywhere below one is part of its bundle. -H
+        # lists a source that is itself a link through it, as a glob does.
+        # Command substitution, so find or sort failing stops the run here
+        # instead of yielding a short list.
+        listing="$(find -H "$dir" -mindepth 1 \( -type d -o -type l \) -print | LC_ALL=C sort)" || {
+            echo "ERROR: cannot enumerate skills under '$dir' — refusing to render a partial list." >&2
+            exit 1
+        }
+        [ -n "$listing" ] || continue
+        _ski_source "$repo_root" "$dir" "$listing"
+    done <<< "$IS_YAML_LIST"
+    [ "${IS_SOURCE_FILES_MEMO:-0}" != 1 ] || IS_SKI_KEY="$memo_key"
+}
+
+# skill_source_rendered <skill_dir> — the inventory renders this skill. No
+# built-in adapter calls it: they read skills through source_artifacts_var
+# (decision 0021). It stays for a project adapter written against earlier
+# releases that still lists a skills source with its own glob — that adapter
+# keeps skipping skills sync leaves out, but not local or targeted ones.
+skill_source_rendered() {
+    _ski_key_var "$1"
+    case "${IS_SKI_KEYS:-}" in
+        *$'\n'"$_SKI_KEY"$'\n'*) return 0 ;;
+    esac
+    return 1
+}
+
+# _ski_key_var <skill_dir> — the key a skill is listed and planned under, its
+# source and name joined by one slash however the caller spelled a trailing
+# slash on either.
+_ski_key_var() {
+    local path="$1" parent
+    while [ "${path%/}" != "$path" ]; do path="${path%/}"; done
+    parent="${path%/*}"
+    while [ -n "$parent" ] && [ "${parent%/}" != "$parent" ]; do parent="${parent%/}"; done
+    _SKI_KEY="$parent/${path##*/}"
+}
+
+# _ski_planned <skill_dir> — the skill has links the copy has to resolve.
+_ski_planned() {
+    _ski_key_var "$1"
+    case "${IS_SKI_PLAN:-}" in
+        *$'\n'"$_SKI_KEY$IS_SKI_US"*) return 0 ;;
+    esac
+    return 1
+}
+
+# _ski_source <repo_root> <source_dir> <listing> — inventory one skills source.
+_ski_source() {
+    local repo_root="$1" f rel
+    local -a tops=() links=()
+    _SKI_DIR="$2"
+    _SKI_ROOT_REL="${2#"$repo_root"/}"
+    _SKI_REPO="$repo_root"
+    while IFS= read -r f; do
+        [ -n "$f" ] || continue
+        rel="${f#"$_SKI_DIR"/}"
+        case "$rel" in
+            */*) [ ! -L "$f" ] || links+=("$f") ;;
+            *)
+                tops+=("$f")
+                [ ! -L "$f" ] || links+=("$f")
+                ;;
+        esac
+    done <<< "$3"
+    _SKI_LREL=(); _SKI_LSTAT=(); _SKI_LKIND=(); _SKI_LTREL=(); _SKI_LPHYS=()
+    [ "${#links[@]}" -eq 0 ] || _ski_classify_links "${links[@]}"
+    for f in "${tops[@]+"${tops[@]}"}"; do
+        _ski_skill "${f##*/}"
+    done
+}
+
+# _ski_classify_links <link>... — resolve every link of the current source and
+# record where it leads: ok (inside the source), outside, dangling, or other
+# (neither a file nor a directory). A link that cannot be resolved stops the
+# run, like any enumeration that cannot answer.
+_ski_classify_links() {
+    local out root_phys rec kind phys i=0 link
+    local -a recs=()
+    out="$(_ski_physical "$_SKI_DIR" "$@")" || {
+        echo "ERROR: cannot resolve the symlinks under '$_SKI_DIR' — refusing to render a partial list." >&2
+        exit 1
+    }
+    while IFS= read -r rec; do recs+=("$rec"); done <<< "$out"
+    if [ "${#recs[@]}" -ne $(($# + 1)) ]; then
+        echo "ERROR: cannot resolve the symlinks under '$_SKI_DIR' — refusing to render a partial list." >&2
+        exit 1
+    fi
+    root_phys="${recs[0]%/}"
+    for link in "$@"; do
+        rec="${recs[i + 1]}"
+        kind="${rec%%"$IS_SKI_US"*}"
+        phys="${rec#*"$IS_SKI_US"}"
+        _SKI_LREL[i]="${link#"$_SKI_DIR"/}"
+        _SKI_LKIND[i]="$kind"
+        _SKI_LPHYS[i]="$phys"
+        _SKI_LTREL[i]=""
+        case "$kind" in
+            d|f)
+                case "$phys" in
+                    "$root_phys"/*) _SKI_LSTAT[i]=ok; _SKI_LTREL[i]="${phys#"$root_phys"/}" ;;
+                    "${root_phys:-/}") _SKI_LSTAT[i]=ok ;;
+                    *) _SKI_LSTAT[i]=outside ;;
+                esac
+                ;;
+            o) _SKI_LSTAT[i]=other ;;
+            *) _SKI_LSTAT[i]=dangling ;;
+        esac
+        i=$((i + 1))
+    done
+}
+
+# _ski_physical <source_dir> <link>... — print the source's physical path,
+# then one "<kind> US <physical target>" line per link: d (directory), f
+# (regular file), o (anything else) or x (dangling, or a link loop). Runs in a
+# subshell so it can change directory: `cd -P` resolves a directory, and a
+# file's chain is read with one readlink per hop for all links at once (no
+# readlink -f on macOS).
+_ski_physical() (
+    local dir="$1" link target targets i k n hops=0 parent
+    local -a kind=() cur=() phys=() pend=() next=() paths=()
+    shift
+    n=$#
+    cd -P -- "$dir" 2>/dev/null || exit 1
+    printf '%s\n' "$PWD"
+    i=0
+    for link in "$@"; do
+        kind[i]=x; phys[i]=""; cur[i]="$link"
+        if [ -d "$link" ]; then
+            cd -P -- "$link" 2>/dev/null || exit 1
+            kind[i]=d; phys[i]="$PWD"
+        elif [ -f "$link" ]; then
+            kind[i]=f; pend+=("$i")
+        elif [ -e "$link" ]; then
+            kind[i]=o
+        fi
+        i=$((i + 1))
+    done
+    while [ "${#pend[@]}" -gt 0 ]; do
+        hops=$((hops + 1))
+        [ "$hops" -le 40 ] || exit 1
+        paths=()
+        for i in "${pend[@]}"; do paths+=("${cur[i]}"); done
+        targets="$(readlink "${paths[@]}")" || exit 1
+        next=(); k=0
+        while IFS= read -r target; do
+            # More lines than links: a target held a newline.
+            [ "$k" -lt "${#pend[@]}" ] || exit 1
+            i="${pend[k]}"
+            case "$target" in
+                /*) cur[i]="$target" ;;
+                *) cur[i]="${cur[i]%/*}/$target" ;;
+            esac
+            [ ! -L "${cur[i]}" ] || next+=("$i")
+            k=$((k + 1))
+        done <<< "$targets"
+        [ "$k" -eq "${#pend[@]}" ] || exit 1
+        pend=("${next[@]+"${next[@]}"}")
+    done
+    for ((i = 0; i < n; i++)); do
+        if [ "${kind[i]}" = f ]; then
+            parent="${cur[i]%/*}"
+            cd -P -- "${parent:-/}" 2>/dev/null || exit 1
+            phys[i]="${PWD%/}/${cur[i]##*/}"
         fi
+        printf '%s%s%s\n' "${kind[i]}" "$IS_SKI_US" "${phys[i]}"
+    done
+)
+
+# _ski_link_var <path in source> — set _SKI_K to the index of the link at that
+# path, or -1.
+_ski_link_var() {
+    local k=0
+    _SKI_K=-1
+    while [ "$k" -lt "${#_SKI_LREL[@]}" ]; do
+        if [ "${_SKI_LREL[k]}" = "$1" ]; then
+            _SKI_K="$k"
+            return 0
+        fi
+        k=$((k + 1))
+    done
+}
+
+# _ski_loops <target> <open> — materializing the directory at <target> would
+# copy one of the <open> paths (newline-separated) being materialized, the
+# link itself included, so it would never end.
+_ski_loops() {
+    local target="$1" open
+    [ -n "$target" ] || return 0
+    while IFS= read -r open; do
+        case "$open" in "$target"|"$target"/*) return 0 ;; esac
+    done <<< "$2"
+    return 1
+}
+
+# _ski_skill <name> — decide one top-level entry of the current source: a
+# rendered skill (with its plan and warnings), a skill left out, or no skill.
+_ski_skill() {
+    local name="$1" key content open="" state rel link reason nl=$'\n'
+    key="$_SKI_DIR/$name"
+    _SKI_ENTRIES="$nl"
+    _SKI_DROPS=""
+    _ski_link_var "$name"
+    if [ "$_SKI_K" -ge 0 ]; then
+        # The skill directory is itself a link. A test through one that
+        # leaves the source only stats it; nothing is read from outside.
+        case "${_SKI_LSTAT[_SKI_K]}:${_SKI_LKIND[_SKI_K]}" in
+            ok:d) ;;
+            outside:d)
+                _ski_warn "$name" "" "$name" outside
+                return 0
+                ;;
+            dangling:*)
+                _ski_warn "$name" "" "$name" dangling
+                return 0
+                ;;
+            *) return 0 ;;
+        esac
+        content="${_SKI_LTREL[_SKI_K]}"
+        if _ski_loops "$content" ""; then
+            [ ! -f "$_SKI_DIR/$name/SKILL.md" ] || _ski_warn "$name" "" "$name" loop
+            return 0
+        fi
+        _SKI_ENTRIES="$_SKI_ENTRIES$key$IS_SKI_US${IS_SKI_US}d$IS_SKI_US${_SKI_LPHYS[_SKI_K]}$nl"
+        open="$nl"
+    else
+        content="$name"
+    fi
+    _ski_expand "$key" "$content" "" "$open"
+    # A skill is a directory whose SKILL.md renders as a regular file.
+    case "$_SKI_ENTRIES" in
+        *"$nl$key${IS_SKI_US}SKILL.md${IS_SKI_US}f$IS_SKI_US"*) state=ok ;;
+        *"$nl$key${IS_SKI_US}SKILL.md${IS_SKI_US}x$IS_SKI_US"*) state=dropped ;;
+        *"$nl$key${IS_SKI_US}SKILL.md$IS_SKI_US"*) state=none ;;
+        *)
+            state=none
+            [ ! -f "$_SKI_DIR/$content/SKILL.md" ] || state=ok
+            ;;
+    esac
+    case "$state" in
+        none) return 0 ;;
+        dropped)
+            while IFS="$IS_SKI_US" read -r rel link reason; do
+                [ "$rel" != "SKILL.md" ] || _ski_warn "$name" "" "$link" "$reason"
+            done <<< "$_SKI_DROPS"
+            return 0
+            ;;
+    esac
+    IS_SKI_LIST="$IS_SKI_LIST$_SKI_DIR/$name/SKILL.md$nl"
+    IS_SKI_KEYS="$IS_SKI_KEYS$key$nl"
+    IS_SKI_PLAN="$IS_SKI_PLAN${_SKI_ENTRIES#"$nl"}"
+    while IFS="$IS_SKI_US" read -r rel link reason; do
+        [ -z "$rel" ] || _ski_warn "$name" "$rel" "$link" "$reason"
+    done <<< "$_SKI_DROPS"
+}
+
+# _ski_expand <key> <content> <prefix> <open> — plan every link inside the
+# source directory <content> as it lands at <prefix> in the skill copy,
+# recursing into each directory a link materializes. <open> holds the
+# locations of the links already being materialized, for _ski_loops.
+_ski_expand() {
+    local key="$1" content="$2" prefix="$3" open="$4" k=0 rel out location
+    while [ "$k" -lt "${#_SKI_LREL[@]}" ]; do
+        rel="${_SKI_LREL[k]}"
+        case "$rel" in
+            "$content"/*) ;;
+            *) k=$((k + 1)); continue ;;
+        esac
+        out="${prefix:+$prefix/}${rel#"$content"/}"
+        case "${_SKI_LSTAT[k]}:${_SKI_LKIND[k]}" in
+            ok:f)
+                _SKI_ENTRIES="$_SKI_ENTRIES$key$IS_SKI_US$out${IS_SKI_US}f$IS_SKI_US${_SKI_LPHYS[k]}"$'\n'
+                ;;
+            ok:d)
+                location="${rel%/*}"
+                if _ski_loops "${_SKI_LTREL[k]}" "$open$location"; then
+                    _ski_drop "$key" "$out" "$rel" loop
+                else
+                    _SKI_ENTRIES="$_SKI_ENTRIES$key$IS_SKI_US$out${IS_SKI_US}d$IS_SKI_US${_SKI_LPHYS[k]}"$'\n'
+                    _ski_expand "$key" "${_SKI_LTREL[k]}" "$out" "$open$location"$'\n'
+                fi
+                ;;
+            *) _ski_drop "$key" "$out" "$rel" "${_SKI_LSTAT[k]}" ;;
+        esac
+        k=$((k + 1))
+    done
+}
+
+# _ski_drop <key> <path in copy> <path in source> <reason> — leave a link out.
+_ski_drop() {
+    _SKI_ENTRIES="$_SKI_ENTRIES$1$IS_SKI_US$2${IS_SKI_US}x$IS_SKI_US"$'\n'
+    _SKI_DROPS="$_SKI_DROPS$2$IS_SKI_US$3$IS_SKI_US$4"$'\n'
+}
+
+# _ski_warn <skill> <path in copy> <path in source> <reason> — one WARNING:
+# line naming the skill and the link by its own path. An empty <path in copy>
+# means the whole skill is left out.
+_ski_warn() {
+    local link="$_SKI_ROOT_REL/$3" what
+    case "$4" in
+        outside) what="is a symlink that resolves outside $_SKI_ROOT_REL" ;;
+        dangling) what="is a dangling symlink" ;;
+        loop) what="is a symlink to a directory that encloses it" ;;
+        *) what="is a symlink to neither a file nor a directory" ;;
+    esac
+    if [ -n "$2" ]; then
+        echo "WARNING: skill '$1' renders without $2: $link $what" >&2
+    else
+        echo "WARNING: skill '$1' is left out of every output: $link $what" >&2
     fi
 }
 
@@ -1696,6 +2241,9 @@ warn_unsynced() {
 # replay that answer. Only the engine sets it: a sync never writes into a
 # source (validate_output_path refuses), so each caller would otherwise re-run
 # the same find and sort for every source directory.
+#
+# Skills come from skill_source_inventory, which also decides what a symlink
+# inside a skills source renders as.
 read_source_artifact_files() {
     local repo_root="$1"
     local config_file="$2"
@@ -1703,8 +2251,15 @@ read_source_artifact_files() {
     local src f dir listing memo_key="" key_var="" list_var="" joined=""
 
     IS_SOURCE_FILES=()
+    if [ "$section" = "skills" ]; then
+        skill_source_inventory "$repo_root" "$config_file"
+        while IFS= read -r f; do
+            [ -n "$f" ] && IS_SOURCE_FILES+=("$f")
+        done <<< "$IS_SKI_LIST"
+        return 0
+    fi
     case "${IS_SOURCE_FILES_MEMO:-0}:$section" in
-        1:rules|1:agents|1:skills)
+        1:rules|1:agents)
             key_var="IS_SF_${section}_KEY"
             list_var="IS_SF_${section}_LIST"
             memo_key="$repo_root"$'\n'"$config_file"
@@ -1724,15 +2279,11 @@ read_source_artifact_files() {
         [ -d "$dir" ] || continue
         # Command substitution, so the pipeline's status is the assignment's:
         # `find` or `sort` failing aborts here instead of yielding a short list.
+        # A link to a regular file is one too, read where it points, as the
+        # adapters' globs always read it; a dangling one is no artifact.
         case "$section" in
             rules|agents)
-                listing="$(find "$dir" -maxdepth 1 -type f -name '*.md' -print | LC_ALL=C sort)" || {
-                    echo "ERROR: cannot enumerate $section under '$dir' — refusing to render a partial list." >&2
-                    exit 1
-                }
-                ;;
-            skills)
-                listing="$(find "$dir" -mindepth 1 -maxdepth 1 -type d -print | LC_ALL=C sort)" || {
+                listing="$(find "$dir" -maxdepth 1 -name '*.md' \( -type f -o -type l \) -print | LC_ALL=C sort)" || {
                     echo "ERROR: cannot enumerate $section under '$dir' — refusing to render a partial list." >&2
                     exit 1
                 }
@@ -1743,11 +2294,7 @@ read_source_artifact_files() {
         # A here-string redirect keeps this loop in the current shell, so the
         # array it fills survives and any failure inside it is this shell's.
         while IFS= read -r f; do
-            [ -n "$f" ] || continue
-            if [ "$section" = "skills" ]; then
-                [ -f "$f/SKILL.md" ] || continue
-                f="$f/SKILL.md"
-            fi
+            [ -f "$f" ] || continue
             IS_SOURCE_FILES+=("$f")
             joined="$joined$f"$'\n'
         done <<< "$listing"
@@ -1758,6 +2305,556 @@ read_source_artifact_files() {
     fi
 }
 
+# --- The source catalog (decision 0021) --------------------------------------
+#
+# Every renderer — AGENTS.md, every built-in adapter, the adapter template —
+# reads sources through source_artifacts_var, so one place decides what an
+# artifact is called, which artifact of a name renders, and where it may go:
+#
+#   name      the entry without a leading `.`, `.md` and a trailing `.local`:
+#             `.environment.local.md` is the rule `environment`, `.draft.md`
+#             the rule `draft`, the skill directory `deploy.local/` the skill
+#             `deploy`. A leading dot means nothing.
+#   local     a rule or agent named `*.local.md`, a skill directory named
+#             `*.local` — exactly the patterns `init` writes to .gitignore, so
+#             Git and the engine never disagree. A local artifact never renders
+#             into an output Git tracks (`committed`).
+#   override  across sources the later artifact of a name renders. Two of one
+#             name in one directory, or a local and a non-local one anywhere,
+#             refuse the sync: either would change what committed output holds
+#             depending on which file a clone has.
+#   targets   `targets:` lists the adapters an artifact is for, every enabled
+#             one without it; `exclude_targets:` removes adapters from that
+#             set. Both take adapter ids and the group `committed` — every
+#             output path Git tracks — and a local artifact excludes
+#             `committed` implicitly.
+#
+# source_catalog_build fills, in the caller's shell and fail-closed like the
+# listing it reads, one row per source entry in listing order:
+#   IS_CAT_SEC IS_CAT_PATH IS_CAT_NAME IS_CAT_LOCAL IS_CAT_WIN IS_CAT_SCOPED
+#   IS_CAT_HAS_T IS_CAT_T IS_CAT_HAS_X IS_CAT_X
+# (section; the file, or a skill's SKILL.md; the rendered name; 1 when local;
+# 1 when no later source overrides it; 1 for a rule with `paths:`; whether
+# `targets:` / `exclude_targets:` are set, and their ids, space-separated),
+# IS_CAT_N, and IS_CAT_NEED_COMMITTED, 1 when rendering has to know which
+# outputs Git tracks. With IS_SOURCE_FILES_MEMO=1 a second call replays the
+# first.
+
+# source_artifact_name_var <section> <entry> — IS_ART_NAME and IS_ART_LOCAL for
+# one file (rules, agents) or skill directory (skills) name.
+source_artifact_name_var() {
+    local n="$2"
+    IS_ART_LOCAL=0
+    case "$1:$n" in
+        skills:*.local|rules:*.local.md|agents:*.local.md) IS_ART_LOCAL=1 ;;
+    esac
+    n="${n#.}"
+    [ "$1" = skills ] || n="${n%.md}"
+    case "$n" in *.local) n="${n%.local}" ;; esac
+    IS_ART_NAME="$n"
+}
+
+# shellcheck disable=SC2034  # IS_CAT_NEED_COMMITTED is read by engine/sync.sh
+source_catalog_build() {
+    local repo_root="$1" config_file="$2" lint="${3:-}" key section f entry dir name
+    local seen=$'\n' errors="" i n=0 prev rest rows path scoped kind has_t t has_x x
+    local -a files=()
+    key="$repo_root"$'\n'"$config_file"
+    if [ "${IS_SOURCE_FILES_MEMO:-0}" = 1 ] && [ "${IS_CAT_KEY:-}" = "$key" ]; then
+        return 0
+    fi
+    IS_CAT_KEY=""
+    IS_CAT_SEC=(); IS_CAT_PATH=(); IS_CAT_NAME=(); IS_CAT_LOCAL=()
+    IS_CAT_WIN=(); IS_CAT_SCOPED=()
+    IS_CAT_HAS_T=(); IS_CAT_T=(); IS_CAT_HAS_X=(); IS_CAT_X=()
+    IS_CAT_NEED_COMMITTED=0
+    for section in rules agents skills; do
+        read_source_artifact_files "$repo_root" "$config_file" "$section"
+        for f in "${IS_SOURCE_FILES[@]+"${IS_SOURCE_FILES[@]}"}"; do
+            if [ "$section" = skills ]; then
+                dir="${f%/SKILL.md}"
+                entry="${dir##*/}"
+                dir="${dir%/*}"
+                kind="skill"
+            else
+                entry="${f##*/}"
+                dir="${f%/*}"
+                kind="${section%s}"
+            fi
+            source_artifact_name_var "$section" "$entry"
+            name="$IS_ART_NAME"
+            IS_CAT_SEC[n]="$section"
+            IS_CAT_PATH[n]="$f"
+            IS_CAT_NAME[n]="$name"
+            IS_CAT_LOCAL[n]="$IS_ART_LOCAL"
+            IS_CAT_WIN[n]=1
+            IS_CAT_SCOPED[n]=0
+            IS_CAT_HAS_T[n]=0; IS_CAT_T[n]=""; IS_CAT_HAS_X[n]=0; IS_CAT_X[n]=""
+            [ "$IS_ART_LOCAL" = 0 ] || IS_CAT_NEED_COMMITTED=1
+            case "$seen" in
+                *$'\n'"$section/$name"$'\t'*)
+                    rest="${seen##*$'\n'"$section/$name"$'\t'}"
+                    prev="${rest%%$'\n'*}"
+                    rest="${IS_CAT_PATH[prev]}"
+                    [ "$section" != skills ] || rest="${rest%/SKILL.md}"
+                    if [ "${IS_CAT_PATH[prev]}" = "$f" ]; then
+                        # One directory listed twice: the same artifact.
+                        IS_CAT_WIN[prev]=0
+                    elif [ "${rest%/*}" = "$dir" ]; then
+                        errors+="ERROR: ${IS_CAT_PATH[prev]#"$repo_root"/} and ${f#"$repo_root"/} are both the $kind '$name' in one directory — rename or remove one"$'\n'
+                    elif [ "${IS_CAT_LOCAL[prev]}" != "$IS_ART_LOCAL" ]; then
+                        errors+="ERROR: ${IS_CAT_PATH[prev]#"$repo_root"/} and ${f#"$repo_root"/} are both the $kind '$name', one local and one not — a local artifact cannot override or yield to a committed one; rename one"$'\n'
+                    else
+                        IS_CAT_WIN[prev]=0
+                    fi
+                    ;;
+            esac
+            seen="$seen$section/$name"$'\t'"$n"$'\n'
+            files+=("$f")
+            n=$((n + 1))
+        done
+    done
+    IS_CAT_N="$n"
+    if [ -n "$errors" ]; then
+        printf '%s' "$errors" >&2
+        exit 1
+    fi
+    if [ "$n" -gt 0 ]; then
+        # 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[@]}")" || {
+            echo "ERROR: cannot read the frontmatter of the sources — refusing to render a partial list." >&2
+            exit 1
+        }
+        i=0
+        while IFS=$'\x1f' read -r path scoped has_t t has_x x; do
+            [ "$i" -lt "$n" ] && [ "$path" = "${IS_CAT_PATH[i]}" ] || {
+                echo "ERROR: cannot read the frontmatter of the sources — refusing to render a partial list." >&2
+                exit 1
+            }
+            [ "${IS_CAT_SEC[i]}" != rules ] || [ "$scoped" = 0 ] || IS_CAT_SCOPED[i]=1
+            IS_CAT_HAS_T[i]="$has_t"; IS_CAT_T[i]="$t"
+            IS_CAT_HAS_X[i]="$has_x"; IS_CAT_X[i]="$x"
+            case " $t $x " in *" committed "*) IS_CAT_NEED_COMMITTED=1 ;; esac
+            i=$((i + 1))
+        done <<< "$rows"
+        if [ "$i" -ne "$n" ]; then
+            echo "ERROR: cannot read the frontmatter of the sources — refusing to render a partial list." >&2
+            exit 1
+        fi
+    fi
+    [ "${IS_SOURCE_FILES_MEMO:-0}" != 1 ] || IS_CAT_KEY="$key"
+}
+
+# source_frontmatter_scan <lint> <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.
+source_frontmatter_scan() {
+    local do_lint=0
+    [ "$1" != lint ] || do_lint=1
+    shift
+    awk -v levels="$IS_EFFORT_LEVELS" -v do_lint="$do_lint" "$IS_AWK_LIB"'
+        BEGIN { SX_US = sprintf("%c", 31) }
+        function sx_items(s, k,   parts, m, j, v, q) {
+            m = split(s, parts, ",")
+            for (j = 1; j <= m; j++) {
+                v = parts[j]
+                gsub(/^[ \t]+|[ \t]+$/, "", v)
+                q = substr(v, 1, 1)
+                if (length(v) >= 2 && (q == "\"" || q == "\047") && substr(v, length(v), 1) == q)
+                    v = substr(v, 2, length(v) - 2)
+                if (v == "") continue
+                sx_v[k] = (sx_v[k] == "") ? v : sx_v[k] " " v
+                sx_n[k]++
+            }
+        }
+        # The end of a block list: one without an item is a key with no value.
+        function sx_close() {
+            if (sx_mode == "block" && sx_n[sx_list] == 0) sx_has[sx_list] = 0
+            sx_list = ""; sx_mode = ""
+        }
+        function sx_line(l,   c, k, v) {
+            if (sx_mode == "flow") {
+                c = index(l, "]")
+                if (c) { sx_items(substr(l, 1, c - 1), sx_list); sx_list = ""; sx_mode = "" }
+                else sx_items(l, sx_list)
+                return
+            }
+            if (sx_mode == "block") {
+                if (l ~ /^[ \t]+-/) {
+                    v = l
+                    sub(/^[ \t]+-[ \t]*/, "", v)
+                    sub(/[ \t]+#.*$/, "", v)
+                    sx_items(v, sx_list)
+                    return
+                }
+                if (l ~ /^[ \t]*$/ || l ~ /^[ \t]+#/) return
+                sx_close()
+            }
+            c = index(l, ":")
+            if (!c) return
+            k = substr(l, 1, c - 1)
+            if (k == "paths") { sx_paths++; return }
+            if ((k != "targets" && k != "exclude_targets") || sx_seen[k]) return
+            sx_seen[k] = 1; sx_has[k] = 1
+            v = substr(l, c + 1)
+            sub(/[ \t]+#.*$/, "", v)
+            gsub(/^[ \t]+|[ \t]+$/, "", v)
+            if (v == "") { sx_list = k; sx_mode = "block"; return }
+            if (substr(v, 1, 1) == "[") {
+                v = substr(v, 2)
+                c = index(v, "]")
+                if (c) sx_items(substr(v, 1, c - 1), k)
+                else { sx_items(v, k); sx_list = k; sx_mode = "flow" }
+                return
+            }
+            sx_items(v, k)
+        }
+        function sx_store() {
+            if (sx_cur == "") return
+            sx_close()
+            SXR[sx_cur] = sx_cur SX_US sx_paths SX_US sx_has["targets"] SX_US sx_v["targets"] \
+                SX_US sx_has["exclude_targets"] SX_US sx_v["exclude_targets"]
+        }
+        FNR == 1 {
+            sx_store()
+            sx_cur = FILENAME; sx_paths = 0; sx_fm = 0; sx_list = ""; sx_mode = ""
+            sx_seen["targets"] = 0; sx_has["targets"] = 0; sx_v["targets"] = ""; sx_n["targets"] = 0
+            sx_seen["exclude_targets"] = 0; sx_has["exclude_targets"] = 0
+            sx_v["exclude_targets"] = ""; sx_n["exclude_targets"] = 0
+        }
+        {
+            sx_l = $0
+            sub(/\r$/, "", sx_l)
+            if (FNR == 1) sx_fm = (sx_l == "---")
+            else if (sx_fm == 1) {
+                if (sx_l == "---") { sx_close(); sx_fm = 2 }
+                else sx_line(sx_l)
+            }
+        }
+        END {
+            sx_store()
+            for (sx_i = 1; sx_i < ARGC; sx_i++)
+                print (ARGV[sx_i] in SXR) ? SXR[ARGV[sx_i]] : ARGV[sx_i] SX_US 0 SX_US 0 SX_US SX_US 0 SX_US
+        }
+        !do_lint { next }
+    '"$_IS_AWK_LINT" "$@"
+}
+
+# The source catalog's committed check needs every enabled adapter's Git
+# policy, which only the engine reads (sync.sh: IS_COMMIT_POLICY, one
+# `adapter TAB kind TAB pattern` line per ignore and include record, and
+# IS_COMMIT_POLICY_SET=1). It reads it only when IS_CAT_NEED_COMMITTED says a
+# render depends on it, so a project without local artifacts never pays for
+# the manifest read the Copilot contract makes (decision 0020).
+#
+# output_committed <adapter> <repo-relative path> — true when Git tracks that
+# output: no `ignore` record of the adapter's contract covers it, or an
+# `include` record takes it back. AGENTS.md always belongs here.
+output_committed() {
+    local adapter="$1" path="$2" a kind pat ignored=0 included=0
+    [ "$adapter" != agents ] || return 0
+    if [ "${IS_COMMIT_POLICY_SET:-0}" != 1 ]; then
+        echo "ERROR: rendering a local artifact needs the Git policy of every enabled adapter; run it through the engine: intelligence sync" >&2
+        exit 1
+    fi
+    while IFS=$'\t' read -r a kind pat; do
+        [ "$a" = "$adapter" ] || continue
+        case "$kind" in
+            ignore) [ "$ignored" = 1 ] || ! policy_pattern_covers "$pat" "$path" || ignored=1 ;;
+            include) [ "$included" = 1 ] || ! policy_pattern_covers "$pat" "$path" || included=1 ;;
+        esac
+    done <<< "$IS_COMMIT_POLICY"
+    [ "$ignored" = 1 ] && [ "$included" = 0 ] && return 1
+    return 0
+}
+
+# policy_pattern_covers <ignore-pattern> <path> — whether a contract's ignore
+# or include pattern covers a repo-relative path or one of its parents: a
+# trailing `/` names a directory, `*` and `?` match as Git's do inside one.
+policy_pattern_covers() {
+    local pat="${1#./}" path="$2"
+    pat="${pat#/}"
+    case "$pat" in
+        */)
+            pat="${pat%/}"
+            case "$path" in "$pat"|"$pat"/*) return 0 ;; esac
+            return 1
+            ;;
+    esac
+    # shellcheck disable=SC2254  # the pattern is a glob on purpose
+    case "$path" in
+        $pat|$pat/*) return 0 ;;
+    esac
+    return 1
+}
+
+# _cat_member <index> <adapter> <repo-relative output path> — whether the
+# catalog row renders into that adapter's output at that path: its targets
+# name the adapter, or `committed` while Git tracks the path, or it has none;
+# its exclusions name neither; and a local row never reaches a tracked path.
+_cat_member() {
+    local i="$1" a="$2" path="$3"
+    if [ "${IS_CAT_HAS_T[i]}" = 1 ]; then
+        case " ${IS_CAT_T[i]} " in
+            *" $a "*) ;;
+            *" committed "*) output_committed "$a" "$path" || return 1 ;;
+            *) return 1 ;;
+        esac
+    fi
+    if [ "${IS_CAT_HAS_X[i]}" = 1 ]; then
+        case " ${IS_CAT_X[i]} " in *" $a "*) return 1 ;; esac
+        case " ${IS_CAT_X[i]} " in
+            *" committed "*) ! output_committed "$a" "$path" || return 1 ;;
+        esac
+    fi
+    if [ "${IS_CAT_LOCAL[i]}" = 1 ]; then
+        ! output_committed "$a" "$path" || return 1
+    fi
+    return 0
+}
+
+# _cat_routed <index> — the row selects its adapters: a local artifact, or one
+# with `targets:` or `exclude_targets:`. Every other row renders everywhere,
+# with no question asked.
+_cat_routed() {
+    [ "${IS_CAT_LOCAL[$1]}" = 1 ] || [ "${IS_CAT_HAS_T[$1]}" = 1 ] || [ "${IS_CAT_HAS_X[$1]}" = 1 ]
+}
+
+# source_artifacts_var <repo_root> <config> <section> <adapters> <output>
+# — the artifacts of a section that render for one of <adapters> (space-
+# separated ids) into <output>, a repo-relative path in which `{}` stands for
+# the artifact's name (`.claude/rules/{}.md`, `.agents/skills/{}`). Fills, in
+# catalog order — sources in manifest order, entries in byte order:
+#   IS_SOURCE_FILES      the source file, or a skill's SKILL.md
+#   IS_SOURCE_NAMES      the rendered name
+#   IS_SOURCE_SCOPED     1 for a rule with `paths:`
+#   IS_SOURCE_IN_AGENTS  1 when AGENTS.md carries the artifact too
+#   IS_SOURCE_NAME_MAP   the name map finalize_copy_named and
+#                        copy_skill_bundle_dirs_named take (a skill keyed by
+#                        its directory)
+source_artifacts_var() {
+    local repo_root="$1" config_file="$2" section="$3" adapters="$4" output="$5"
+    local i a pre post path member key ph='{}'
+    source_catalog_build "$repo_root" "$config_file"
+    IS_SOURCE_FILES=(); IS_SOURCE_NAMES=(); IS_SOURCE_SCOPED=(); IS_SOURCE_IN_AGENTS=()
+    IS_SOURCE_NAME_MAP=$'\n'
+    case "$output" in
+        *"$ph"*) pre="${output%%"$ph"*}"; post="${output#*"$ph"}" ;;
+        *) pre="$output"; post="" ;;
+    esac
+    for ((i = 0; i < IS_CAT_N; i++)); do
+        [ "${IS_CAT_SEC[i]}" = "$section" ] && [ "${IS_CAT_WIN[i]}" = 1 ] || continue
+        if _cat_routed "$i"; then
+            case "$output" in *"$ph"*) path="$pre${IS_CAT_NAME[i]}$post" ;; *) path="$output" ;; esac
+            member=0
+            for a in $adapters; do
+                if _cat_member "$i" "$a" "$path"; then member=1; break; fi
+            done
+            [ "$member" = 1 ] || continue
+            # AGENTS.md is always committed, so its path decides nothing.
+            if _cat_member "$i" agents AGENTS.md; then
+                IS_SOURCE_IN_AGENTS+=(1)
+            else
+                IS_SOURCE_IN_AGENTS+=(0)
+            fi
+        else
+            IS_SOURCE_IN_AGENTS+=(1)
+        fi
+        IS_SOURCE_FILES+=("${IS_CAT_PATH[i]}")
+        IS_SOURCE_NAMES+=("${IS_CAT_NAME[i]}")
+        IS_SOURCE_SCOPED+=("${IS_CAT_SCOPED[i]}")
+        key="${IS_CAT_PATH[i]}"
+        [ "$section" != skills ] || key="${key%/SKILL.md}"
+        IS_SOURCE_NAME_MAP="$IS_SOURCE_NAME_MAP$key"$'\x1f'"${IS_CAT_NAME[i]}"$'\n'
+    done
+}
+
+# The checks below run in the engine, after preflight read every enabled
+# contract: IS_ENABLED_ADAPTERS and IS_AGENTS_READERS (the enabled adapters,
+# and those that require `agents` and so read AGENTS.md), IS_OPEN_SKILLS_READERS
+# and IS_ADAPTER_CLAIMS (every enabled adapter's owned and managed paths).
+
+# source_catalog_check_ids <repo_root> <known adapter ids> — refuse a
+# `targets:` or `exclude_targets:` id that is neither an adapter, built-in or
+# the project's, nor `committed`. Every finding is printed before the refusal.
+source_catalog_check_ids() {
+    local repo_root="$1" known=" $2 committed " i id field ids bad=0
+    local -a list=()
+    for ((i = 0; i < IS_CAT_N; i++)); do
+        [ "${IS_CAT_WIN[i]}" = 1 ] || continue
+        for field in targets exclude_targets; do
+            if [ "$field" = targets ]; then
+                [ "${IS_CAT_HAS_T[i]}" = 1 ] || continue
+                ids="${IS_CAT_T[i]}"
+            else
+                [ "${IS_CAT_HAS_X[i]}" = 1 ] || continue
+                ids="${IS_CAT_X[i]}"
+            fi
+            read -r -a list <<< "$ids"
+            for id in "${list[@]+"${list[@]}"}"; do
+                case "$known" in *" $id "*) continue ;; esac
+                echo "ERROR: ${IS_CAT_PATH[i]#"$repo_root"/}: $field names '$id', which is no adapter — use one of: ${2// /, }, or the group committed" >&2
+                bad=1
+            done
+        done
+    done
+    return "$bad"
+}
+
+# _adapter_paths_var <adapter> — IS_AP_PATHS, the adapter's owned and managed
+# paths as preflight registered them.
+_adapter_paths_var() {
+    local a kind p
+    IS_AP_PATHS=()
+    while IFS=$'\t' read -r a kind p; do
+        if [ "$a" = "$1" ] && [ -n "$p" ]; then IS_AP_PATHS+=("$p"); fi
+    done <<< "${IS_ADAPTER_CLAIMS:-}"
+}
+
+# _cat_adapter_member <index> <adapter> — the row renders into any output of
+# the adapter: its set of adapters, read per path.
+_cat_adapter_member() {
+    local p
+    _adapter_paths_var "$2"
+    for p in "${IS_AP_PATHS[@]+"${IS_AP_PATHS[@]}"}"; do
+        if _cat_member "$1" "$2" "$p"; then return 0; fi
+    done
+    return 1
+}
+
+# source_catalog_check_local <repo_root> — refuse a local artifact whose
+# targets name a committed output: `committed` itself, `agents`, or an enabled
+# adapter all of whose paths Git tracks. The source exists in no other clone
+# and not in CI, which render that output without it.
+source_catalog_check_local() {
+    local repo_root="$1" i id p tracked bad=0
+    local -a list=()
+    for ((i = 0; i < IS_CAT_N; i++)); do
+        [ "${IS_CAT_WIN[i]}" = 1 ] && [ "${IS_CAT_LOCAL[i]}" = 1 ] && [ "${IS_CAT_HAS_T[i]}" = 1 ] || continue
+        read -r -a list <<< "${IS_CAT_T[i]}"
+        for id in "${list[@]+"${list[@]}"}"; do
+            tracked=0
+            case "$id" in
+                committed|agents) tracked=1 ;;
+                *)
+                    case " ${IS_ENABLED_ADAPTERS:-} " in *" $id "*) ;; *) continue ;; esac
+                    _adapter_paths_var "$id"
+                    [ "${#IS_AP_PATHS[@]}" -gt 0 ] || continue
+                    tracked=1
+                    for p in "${IS_AP_PATHS[@]}"; do
+                        if ! output_committed "$id" "$p"; then tracked=0; break; fi
+                    done
+                    ;;
+            esac
+            [ "$tracked" = 1 ] || continue
+            echo "ERROR: ${IS_CAT_PATH[i]#"$repo_root"/} is local, but its targets name $id, whose output Git tracks — a local artifact exists in no other clone, so it renders only into ignored output" >&2
+            bad=1
+        done
+    done
+    return "$bad"
+}
+
+# builtin_has_channel <adapter> <always|scoped|agent|skill> — whether a built-in
+# adapter has a channel of its own for that kind of artifact, AGENTS.md aside.
+# 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 ;;
+    esac
+    return 0
+}
+
+# source_catalog_warn <repo_root> — the WARNING: lines for an artifact that
+# selects its adapters (decision 0021): a shared path — AGENTS.md, or
+# .agents/skills/ — that delivers it to an enabled adapter outside its set, and
+# an adapter in its set that no channel reaches. An artifact with neither field
+# nor a `.local` name keeps the routing every sync had, and no new warning.
+source_catalog_warn() {
+    local repo_root="$1" i a rel kind in_agents outside unreach landed what
+    for ((i = 0; i < IS_CAT_N; i++)); do
+        [ "${IS_CAT_WIN[i]}" = 1 ] || continue
+        _cat_routed "$i" || continue
+        rel="${IS_CAT_PATH[i]#"$repo_root"/}"
+        case "${IS_CAT_SEC[i]}" in
+            rules) kind=always; [ "${IS_CAT_SCOPED[i]}" = 0 ] || kind=scoped ;;
+            agents) kind=agent ;;
+            *) kind=skill; rel="${rel%/SKILL.md}/" ;;
+        esac
+        in_agents=0
+        case " ${IS_ENABLED_ADAPTERS:-} " in
+            *" agents "*) if _cat_member "$i" agents AGENTS.md; then in_agents=1; fi ;;
+        esac
+        if [ "$in_agents" = 1 ]; then
+            outside=""
+            for a in ${IS_AGENTS_READERS:-}; do
+                _cat_adapter_member "$i" "$a" || outside="$outside${outside:+, }$a"
+            done
+            if [ -n "$outside" ]; then
+                echo "WARNING: $rel still reaches $outside through AGENTS.md, which they read, although its targets leave them out" >&2
+            fi
+        fi
+        if [ "$kind" = skill ]; then
+            landed=0
+            outside=""
+            for a in ${IS_OPEN_SKILLS_READERS:-}; do
+                if _cat_member "$i" "$a" ".agents/skills/${IS_CAT_NAME[i]}"; then
+                    landed=1
+                else
+                    outside="$outside${outside:+, }$a"
+                fi
+            done
+            if [ "$landed" = 1 ] && [ -n "$outside" ]; then
+                echo "WARNING: $rel still reaches $outside through .agents/skills/, which they read too, although its targets leave them out" >&2
+            fi
+        fi
+        unreach=""
+        for a in ${IS_ENABLED_ADAPTERS:-}; do
+            [ "$a" != agents ] || continue
+            _cat_adapter_member "$i" "$a" || continue
+            if [ "$in_agents" = 1 ]; then
+                case " ${IS_AGENTS_READERS:-} " in *" $a "*) continue ;; esac
+            fi
+            builtin_has_channel "$a" "$kind" || unreach="$unreach${unreach:+, }$a"
+        done
+        if [ -n "$unreach" ]; then
+            what="an always-on rule"
+            [ "$kind" != scoped ] || what="a scoped rule"
+            echo "WARNING: $rel cannot reach $unreach: no channel there carries $what outside AGENTS.md" >&2
+        fi
+    done
+}
+
+# output_rel_var <repo_root> <absolute output path> — IS_OUTPUT_REL, the
+# output's repo-relative path spelled as contracts and source_artifacts_var
+# spell it.
+# shellcheck disable=SC2034  # IS_OUTPUT_REL is the return channel read by adapters
+output_rel_var() {
+    normalize_path_var "$2"
+    IS_OUTPUT_REL="${IS_NORM_PATH#"$1"/}"
+}
+
+# source_catalog_winners_var <repo_root> <config> <section> — every artifact of
+# a section that renders anywhere, whatever its outputs: IS_SOURCE_FILES and
+# IS_SOURCE_SCOPED, for the adapter-agnostic context report.
+source_catalog_winners_var() {
+    local i
+    source_catalog_build "$1" "$2"
+    IS_SOURCE_FILES=(); IS_SOURCE_SCOPED=()
+    for ((i = 0; i < IS_CAT_N; i++)); do
+        [ "${IS_CAT_SEC[i]}" = "$3" ] && [ "${IS_CAT_WIN[i]}" = 1 ] || continue
+        IS_SOURCE_FILES+=("${IS_CAT_PATH[i]}")
+        IS_SOURCE_SCOPED+=("${IS_CAT_SCOPED[i]}")
+    done
+}
+
 # Apply the agents adapter's lexical output rule without consulting filesystem
 # state. An omitted output uses the generic adapter default directory.
 agents_output_path_var() {
@@ -1827,26 +2924,23 @@ context_files_bytes() {
 report_context_source_sizes() {
     local repo_root="$1"
     local config_file="$2"
-    local f path has_paths
-    local -a rule_files=() always_on_rules=() scoped_rules=() agent_files=() skill_files=()
-
-    read_source_artifact_files "$repo_root" "$config_file" "rules"
-    [ "${#IS_SOURCE_FILES[@]}" -eq 0 ] || rule_files=("${IS_SOURCE_FILES[@]}")
-    if [ "${#rule_files[@]}" -gt 0 ]; then
-        while IFS=$'\x1f' read -r path has_paths; do
-            [ -n "$path" ] || continue
-            if [ "$has_paths" = "0" ]; then
-                always_on_rules+=("$path")
-            else
-                scoped_rules+=("$path")
-            fi
-        done < <(frontmatter_index "paths#" "${rule_files[@]}")
-    fi
+    local i
+    local -a always_on_rules=() scoped_rules=() agent_files=() skill_files=()
+
+    # What renders anywhere: an artifact a later source overrides is no context.
+    source_catalog_winners_var "$repo_root" "$config_file" "rules"
+    for ((i = 0; i < ${#IS_SOURCE_FILES[@]}; i++)); do
+        if [ "${IS_SOURCE_SCOPED[i]}" = 0 ]; then
+            always_on_rules+=("${IS_SOURCE_FILES[i]}")
+        else
+            scoped_rules+=("${IS_SOURCE_FILES[i]}")
+        fi
+    done
 
-    read_source_artifact_files "$repo_root" "$config_file" "agents"
+    source_catalog_winners_var "$repo_root" "$config_file" "agents"
     [ "${#IS_SOURCE_FILES[@]}" -eq 0 ] || agent_files=("${IS_SOURCE_FILES[@]}")
 
-    read_source_artifact_files "$repo_root" "$config_file" "skills"
+    source_catalog_winners_var "$repo_root" "$config_file" "skills"
     [ "${#IS_SOURCE_FILES[@]}" -eq 0 ] || skill_files=("${IS_SOURCE_FILES[@]}")
 
     local always_bytes=0 custom_bytes=0 agents_output agents_bytes=0 agents_status="disabled"
@@ -2106,8 +3200,9 @@ IS_YAML_LIST_AWK='
 # Consults the load_yaml_list cache first: sync reads the same sections from
 # the same manifest dozens of times, and each awk spawn costs tens of
 # milliseconds on Windows. The cache is only ever populated by
-# load_yaml_list, which the engine calls for a manifest it never mutates, so
-# a CLI process that edits the manifest keeps reading the file directly.
+# load_yaml_list and load_yaml_lists. The engine never mutates its manifest;
+# CLI writers invalidate it through qmap_memo_reset; load_yaml_lists and the
+# project preloader also populate it.
 read_yaml_list() {
     local file="$1"
     local section="$2"
@@ -2215,22 +3310,17 @@ load_yaml_list() {
     esac
 }
 
-# load_yaml_lists <file> <section>... — warm the load_yaml_list cache for several
-# sections in one manifest pass. Each section runs read_yaml_list's own state
-# machine and its reference expansion, so every cached value is what
-# load_yaml_list would have stored. The same pass leaves the references that
-# resolve to nothing in IS_YL_UNRESOLVED, one read_source_entries-shaped line
-# each with the section in front, for the WARNING: lines `sync` prints.
-load_yaml_lists() {
-    local file="$1" out line s v j
-    shift
-    for s in "$@"; do
-        case "$s" in
-            rules|agents|skills|ignore|submodules) ;;
-            *) return 1 ;;
-        esac
-    done
-    out="$(awk -v sections="$*" "$IS_PKG_REF_AWK$IS_YAML_ITEM_AWK"'
+# The manifest readers below share their awk programs, so the combined pass in
+# load_manifest_view reads each shape exactly as its single-purpose reader does.
+# Rule order matters when they are joined: the targets program ends its rules
+# with `next`, so it runs last and never hides a line from the others.
+#
+# The lists program carries the package-reference parser with it: it sees every
+# line, so `packages:` is collected wherever it stands, and each source list is
+# expanded exactly as read_yaml_list expands it. A reference that resolves to
+# nothing comes out as a `!` row, which _yaml_lists_store keeps in
+# IS_YL_UNRESOLVED.
+_IS_AWK_LISTS="$IS_PKG_REF_AWK$IS_YAML_ITEM_AWK"'
         BEGIN { n = split(sections, want, " ") }
         { sub(/\r$/, ""); pkr_collect($0) }
         {
@@ -2261,42 +3351,33 @@ load_yaml_lists() {
                 else print "!\037" s "\037" val "\037" PKR_STATE "\037" dir "\037" PKR_ALIAS "\037" PKR_HOLDERS
             }
         }
-    ' "$file")"
-    for s in "$@"; do
-        j=""
-        while IFS= read -r line; do
-            [ "${line%%$'\037'*}" = "$s" ] || continue
-            v="${line#*$'\037'}"
-            j="$j$v"$'\n'
-        done <<< "$out"
-        while [[ "$j" == *$'\n' ]]; do j="${j%$'\n'}"; done
-        printf -v "IS_YL_${s}_FILE" '%s' "$file"
-        printf -v "IS_YL_${s}_VAL" '%s' "$j"
-    done
-    IS_YL_UNRESOLVED=""
-    while IFS= read -r line; do
-        case "$line" in
-            "!"$'\037'*) IS_YL_UNRESOLVED="$IS_YL_UNRESOLVED${line#"!"$'\037'}"$'\n' ;;
-        esac
-    done <<< "$out"
-}
+'
 
-# load_targets_cache <file> — parse the whole targets: section once into the
-# global IS_TGT_TSV (one `name<TAB>enabled<TAB>output` row per target),
-# matching is_target_enabled and get_target_output semantics: inline and block
-# forms, first occurrence wins, `enabled` defaults to 0 when the block ends
-# without one and to empty at end of file. The engine warms this once;
-# both readers consult it before spawning awk.
-load_targets_cache() {
-    local file="$1"
-    if [ "${IS_TGT_FILE:-}" = "$file" ]; then
-        return 0
-    fi
-    IS_TGT_TSV="$(awk '
+# get_yaml_field: the first `  fkey:` inside the first `fsection:` block. A
+# top-level key closes the block; ftag prefixes the printed value.
+_IS_AWK_FIELD='
+        { sub(/\r$/, "") }
+        !fdone {
+            if ($0 ~ "^" fsection ":") fin = 1
+            else if (fin && /^[a-zA-Z]/) fdone = 1
+            else if (fin && $0 ~ "^  " fkey ":") {
+                fval = $0
+                sub(/.*:[[:space:]]*["\047]?/, "", fval)
+                sub(/["\047]?[[:space:]]*$/, "", fval)
+                ffound = 1
+                fdone = 1
+            }
+        }
+        END { if (ffound) print ftag fval }
+'
+
+# load_targets_cache: one `name<TAB>enabled<TAB>output` row per target, each
+# prefixed with ttag.
+_IS_AWK_TARGETS='
         function flush_target(at_sibling) {
             if (name == "") return
             if (enabled == "" && at_sibling) enabled = 0
-            printf "%s\t%s\t%s\n", name, enabled, output
+            printf "%s%s\t%s\t%s\n", ttag, name, enabled, output
             name = ""
         }
         { sub(/\r$/, "") }
@@ -2332,10 +3413,147 @@ load_targets_cache() {
             output = val
         }
         END { flush_target(0) }
-    ' "$file")"
+'
+
+# _yaml_lists_store <file> <awk-output> <section>... — fill the load_yaml_list
+# cache for each section from `<section><US><value>` rows, and IS_YL_UNRESOLVED
+# from the `!` rows: one read_source_entries-shaped line each, the section in
+# front.
+_yaml_lists_store() {
+    local file="$1" out="$2" line v s k saved_ifs="$IFS"
+    local -a lines=() names=() vals=()
+    shift 2
+    names=("$@")
+    IFS=$'\n'
+    set -f
+    # shellcheck disable=SC2206  # rows are `<section><US><value>`, never empty
+    lines=($out)
+    set +f
+    IFS="$saved_ifs"
+    IS_YL_UNRESOLVED=""
+    # One pass over the rows in this shell: reading a here-string again per
+    # section costs a system call per byte on Git Bash.
+    for line in "${lines[@]+"${lines[@]}"}"; do
+        s="${line%%$'\037'*}"
+        v="${line#*$'\037'}"
+        if [ "$s" = "!" ]; then
+            IS_YL_UNRESOLVED="$IS_YL_UNRESOLVED$v"$'\n'
+            continue
+        fi
+        for ((k = 0; k < ${#names[@]}; k++)); do
+            [ "${names[k]}" = "$s" ] || continue
+            vals[k]="${vals[k]-}$v"$'\n'
+        done
+    done
+    for ((k = 0; k < ${#names[@]}; k++)); do
+        v="${vals[k]-}"
+        while [[ "$v" == *$'\n' ]]; do v="${v%$'\n'}"; done
+        printf -v "IS_YL_${names[k]}_FILE" '%s' "$file"
+        printf -v "IS_YL_${names[k]}_VAL" '%s' "$v"
+    done
+}
+
+# load_yaml_lists <file> <section>... — warm the load_yaml_list cache for several
+# sections in one manifest pass. Each section runs read_yaml_list's own state
+# machine and its reference expansion, so every cached value is what
+# load_yaml_list would have stored. The same pass leaves the references that
+# resolve to nothing in IS_YL_UNRESOLVED, one read_source_entries-shaped line
+# each with the section in front, for the WARNING: lines `sync` prints.
+load_yaml_lists() {
+    local file="$1" out s
+    shift
+    for s in "$@"; do
+        case "$s" in
+            rules|agents|skills|ignore|submodules) ;;
+            *) return 1 ;;
+        esac
+    done
+    out="$(awk -v sections="$*" "$_IS_AWK_LISTS" "$file")"
+    _yaml_lists_store "$file" "$out" "$@"
+}
+
+# load_targets_cache <file> — parse the whole targets: section once into the
+# global IS_TGT_TSV (one `name<TAB>enabled<TAB>output` row per target),
+# matching is_target_enabled and get_target_output semantics: inline and block
+# forms, first occurrence wins, `enabled` defaults to 0 when the block ends
+# without one and to empty at end of file. The engine warms this once;
+# both readers consult it before spawning awk.
+load_targets_cache() {
+    local file="$1"
+    if [ "${IS_TGT_FILE:-}" = "$file" ]; then
+        return 0
+    fi
+    IS_TGT_TSV="$(awk "$_IS_AWK_TARGETS" "$file")"
+    IS_TGT_FILE="$file"
+}
+
+# load_manifest_view <file> <field-section> <field-key> <section>... — one
+# awk pass for what the CLI's preflight reads of a manifest: the
+# load_yaml_lists cache for each <section>, the targets cache, and the one
+# get_yaml_field answer that get_yaml_field_var then returns without a process.
+# Each reader's program is the one it runs alone, so the answers cannot differ.
+# A caller that overlaps the pass with other work runs manifest_view_run (it
+# prints) and hands the output to manifest_view_store itself.
+load_manifest_view() {
+    local out
+    out="$(manifest_view_run "$@")" || return 1
+    manifest_view_store "$out" "$@"
+}
+
+manifest_view_run() {
+    local file="$1" fsection="$2" fkey="$3" s
+    shift 3
+    for s in "$@"; do
+        case "$s" in
+            rules|agents|skills|ignore|submodules) ;;
+            *) return 1 ;;
+        esac
+    done
+    awk -v sections="$*" -v fsection="$fsection" -v fkey="$fkey" \
+        -v ftag=$'\036F' -v ttag=$'\036T' \
+        "$_IS_AWK_LISTS$_IS_AWK_FIELD$_IS_AWK_TARGETS" "$file"
+}
+
+# manifest_view_store <output> <file> <field-section> <field-key> <section>...
+manifest_view_store() {
+    local out="$1" file="$2" fsection="$3" fkey="$4" line lists="" targets="" field="" found=0
+    local saved_ifs="$IFS"
+    local -a lines=()
+    shift 4
+    IFS=$'\n'
+    set -f
+    # shellcheck disable=SC2206  # every row is tagged or `<section><US>`, never empty
+    lines=($out)
+    set +f
+    IFS="$saved_ifs"
+    for line in "${lines[@]+"${lines[@]}"}"; do
+        case "$line" in
+            $'\036T'*) targets="$targets${line#??}"$'\n' ;;
+            $'\036F'*) field="${line#??}"; found=1 ;;
+            *) lists="$lists$line"$'\n' ;;
+        esac
+    done
+    while [[ "$targets" == *$'\n' ]]; do targets="${targets%$'\n'}"; done
+    _yaml_lists_store "$file" "$lists" "$@"
+    IS_TGT_TSV="$targets"
     IS_TGT_FILE="$file"
+    IS_YF_KEY="$file"$'\037'"$fsection"$'\037'"$fkey"
+    IS_YF_VALUE="$field"
+    IS_YF_FOUND="$found"
+}
+
+# manifest_view_reset — forget every manifest answer cached in this shell. A
+# process that has the manifest rewritten (by a child it ran) calls it before
+# reading again.
+manifest_view_reset() {
+    local s
+    for s in rules agents skills ignore submodules; do
+        unset "IS_YL_${s}_FILE" "IS_YL_${s}_VAL"
+    done
+    unset IS_TGT_FILE IS_TGT_TSV IS_YF_KEY IS_YF_VALUE IS_YF_FOUND IS_YL_UNRESOLVED
 }
 
+
 # _targets_cache_row <target> — scan the cached TSV; sets IS_TGT_ROW_ENABLED /
 # IS_TGT_ROW_OUTPUT. Returns 1 when the target has no row (reader falls back
 # to empty, same as the awk scan finding nothing).
@@ -2557,18 +3775,23 @@ get_yaml_field() {
     local file="$1"
     local section="$2"
     local key="$3"
-    awk -v section="$section" -v key="$key" '
-        { sub(/\r$/, "") }
-        $0 ~ "^" section ":" { in_section = 1; next }
-        in_section && /^[a-zA-Z]/ { exit }
-        in_section && $0 ~ "^  " key ":" {
-            val = $0
-            sub(/.*:[[:space:]]*["\047]?/, "", val)
-            sub(/["\047]?[[:space:]]*$/, "", val)
-            print val
-            exit
-        }
-    ' "$file"
+    if [ "${IS_YF_KEY:-}" = "$file"$'\037'"$section"$'\037'"$key" ]; then
+        [ "$IS_YF_FOUND" != 1 ] || printf '%s\n' "$IS_YF_VALUE"
+        return 0
+    fi
+    awk -v fsection="$section" -v fkey="$key" "$_IS_AWK_FIELD" "$file"
+}
+
+# get_yaml_field_var <file> <section> <key> — get_yaml_field into
+# IS_YAML_FIELD, without a process when load_manifest_view read it.
+# shellcheck disable=SC2034  # IS_YAML_FIELD is the return channel
+get_yaml_field_var() {
+    if [ "${IS_YF_KEY:-}" = "$1"$'\037'"$2"$'\037'"$3" ]; then
+        IS_YAML_FIELD=""
+        [ "$IS_YF_FOUND" != 1 ] || IS_YAML_FIELD="$IS_YF_VALUE"
+        return 0
+    fi
+    IS_YAML_FIELD="$(get_yaml_field "$@")"
 }
 
 # Get project name from config.yaml (project.name)