@ainova-systems/intelligence 0.18.1 → 0.20.0

package/engine/lib/common.sh

@@ -293,9 +293,10 @@ repo_rel_dir() {
     done
 }
 
-# Resolve a single source token to an absolute local directory. Every token is
-# a repo-relative path: the CLI resolves, fetches and pins packages, so by the
-# time the engine runs a package is just a directory under the store.
+# Resolve a single source entry to an absolute local directory. Every entry is
+# a repo-relative path by the time it gets here: the CLI resolves, fetches and
+# pins packages, so a package is just a directory under the store, and the list
+# parser has already expanded a package reference to that directory.
 # ALWAYS returns 0 (echoes nothing on failure) so `set -e` callers using
 # `dir="$(resolve_source_dir ...)"` never abort; the caller's existing
 # `[ -d "$dir" ] || continue` guard then skips an unresolved source.
@@ -451,8 +452,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
@@ -460,35 +464,62 @@ copy_md_with_quoted_frontmatter() {
 # "argument-hint must be a string" — the skill silently disappears from the
 # picker. Quoting is idempotent: an already-quoted value passes through
 # untouched.
+#
+# The same pass renders SKILL.md's `effort:` for the tool that reads the copy
+# (map_effort_var): the first `effort:` line becomes the tool's level, and is
+# dropped — with every later one — when the tool has no level for it. The
+# plain forms render for the shared `open` tree, which keeps a neutral level as
+# written and drops only an empty or off-scale one.
 # Usage: copy_skill_bundle "src/skill/dir" "dest/skill/dir"
 copy_skill_bundle() {
     _skill_bundles_reset
-    _skill_bundle_stage "$1" "$2"
-    _skill_bundles_flush
+    _skill_bundle_stage "$1" "$2" || return 1
+    _skill_bundles_flush open
 }
 
 # copy_skill_bundle_dirs <dest_root> <src_dir>... — batch form: ONE cp -R
 # 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() {
-    local dest_root="$1"
-    shift
+    copy_skill_bundle_dirs_for open "$@"
+}
+
+# copy_skill_bundle_dirs_for <tool> <dest_root> <src_dir>... — the batch form
+# for a tree one tool reads, rendering `effort:` for that tool.
+copy_skill_bundle_dirs_for() {
+    local effort_tool="$1" dest_root="$2"
+    shift 2
     [ "$#" -gt 0 ] || return 0
-    local src dest
+    local src dest linked=0
     local -a srcs=()
     for src in "$@"; do
-        srcs+=("${src%/}")
+        src="${src%/}"
+        srcs+=("$src")
+        ! _ski_planned "$src" || linked=1
     done
     mkdir -p "$dest_root"
-    cp -R "${srcs[@]}" "$dest_root/"
+    if [ "$linked" = 0 ]; then
+        cp -R "${srcs[@]}" "$dest_root/"
+    else
+        for src in "${srcs[@]}"; do
+            if _ski_planned "$src"; then
+                _skill_bundle_materialize "$src" || return 1
+                cp -R "$IS_SKI_STAGED" "$dest_root/" || return 1
+                rm -rf "${IS_SKI_STAGED%/*}"
+            else
+                cp -R "$src" "$dest_root/" || return 1
+            fi
+        done
+    fi
     _skill_bundles_reset
     for src in "${srcs[@]}"; do
         dest="$dest_root/${src##*/}"
         _skill_bundle_note "$dest"
     done
-    _skill_bundles_flush
+    _skill_bundles_flush "$effort_tool"
 }
 
 _skill_bundles_reset() {
@@ -500,24 +531,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;
@@ -531,27 +601,51 @@ _skill_bundle_note() {
     esac
 }
 
+# _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"
     # One awk: quote free-text frontmatter fields in each top-level SKILL.md
     # (strict-YAML consumers reject unquoted colons; `argument-hint:
     # [pr-number]` would otherwise arrive as a YAML flow sequence and the
-    # skill silently vanishes from the picker) and expand layout tokens in
-    # every bundled markdown file. Quoting is idempotent — already-quoted
-    # values pass through untouched. The quote list travels through the
-    # environment, like emit_wrapped_bodies specs.
+    # skill silently vanishes from the picker), render its `effort:` for the
+    # tool, and expand layout tokens in every bundled markdown file. Quoting is
+    # idempotent — already-quoted values pass through untouched. The quote list
+    # and the effort map travel through the environment, like
+    # emit_wrapped_bodies specs. The effort key is matched exactly as
+    # frontmatter_index reads it, so the line rewritten is the one the
+    # lint judged.
     is_fin_awk_vars
-    IS_QUOTE_LIST="$quote_list" awk "${IS_FIN_V[@]}" "$IS_AWK_LIB"'
+    IS_QUOTE_LIST="$quote_list" IS_EFFORT_MAP="$IS_EFFORT_MAP" awk "${IS_FIN_V[@]}" "$IS_AWK_LIB"'
         BEGIN {
             qn = split(ENVIRON["IS_QUOTE_LIST"], QL, "\n")
             for (qi = 1; qi <= qn; qi++) if (QL[qi] != "") QUOTE[QL[qi]] = 1
+            en = split(ENVIRON["IS_EFFORT_MAP"], EL, "\n")
+            for (ei = 1; ei <= en; ei++) {
+                eq = index(EL[ei], "=")
+                if (eq > 0) EFFORT[substr(EL[ei], 1, eq - 1)] = substr(EL[ei], eq + 1)
+            }
         }
         function yamlq(s,    out, i, c) {
             out = ""
@@ -572,12 +666,19 @@ _skill_bundles_flush() {
             flush_file()
             out_file = FILENAME; line_n = 0
             state = (FILENAME in QUOTE) ? "before" : ""
+            effort_seen = 0
         }
         { sub(/\r$/, "") }
         state == "before" {
             if (FNR == 1 && $0 == "---") state = "in_fm"
             else state = "after"
         }
+        state == "in_fm" && FNR > 1 && substr($0, 1, 7) == "effort:" {
+            if (effort_seen++) next
+            val = fm_value_strip(substr($0, 8))
+            if (!(val in EFFORT)) next
+            if (EFFORT[val] != val) $0 = "effort: " EFFORT[val]
+        }
         state == "in_fm" && FNR > 1 {
             if ($0 == "---") state = "after"
             else {
@@ -660,7 +761,7 @@ sync_open_skill_dirs() {
     # 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 "$output_dir" "${skill_dirs[@]}"
+        copy_skill_bundle_dirs_for open "$output_dir" "${skill_dirs[@]}"
         open_skill_invocation_policies "$output_dir" || return 1
     fi
 
@@ -681,19 +782,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
@@ -706,10 +803,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
@@ -830,19 +923,41 @@ 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,
+# first occurrence only. Adapters render it as absent and say nothing, so the
+# warning names the source exactly once however many tools render it. Unlike
+# the lint notes it is an unindented `WARNING:` line, because `sync --compact`
+# (and so `init`) keeps only those (decision 0015).
 # Usage: lint_frontmatter_files "a.md" "b.md" ...
 lint_frontmatter_files() {
     [ "$#" -gt 0 ] || return 0
-    awk '
-        FNR == 1 { in_fm = 0; done = 0 }
+    awk -v levels="$IS_EFFORT_LEVELS" "$IS_AWK_LIB"'
+        BEGIN {
+            nl = split(levels, LV, " ")
+            allowed = ""
+            for (li = 1; li <= nl; li++) {
+                LEVEL[LV[li]] = 1
+                allowed = allowed (li > 1 ? ", " : "") LV[li]
+            }
+        }
+        FNR == 1 { in_fm = 0; done = 0; effort_seen = 0 }
         { sub(/\r$/, "") }
         done { next }
         FNR == 1 && $0 != "---" { done = 1; next }
         FNR == 1 { in_fm = 1; next }
         in_fm && $0 == "---" { done = 1; next }
+        in_fm && substr($0, 1, 7) == "effort:" && !effort_seen++ {
+            effort = fm_value_strip(substr($0, 8))
+            if (effort != "" && !(effort in LEVEL)) {
+                printf "WARNING: %s:%d effort \"%s\" is not one of %s — ignored, so no tool receives an effort from this file\n", FILENAME, FNR, effort, allowed > "/dev/stderr"
+            }
+        }
         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
@@ -850,10 +965,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
@@ -872,7 +987,7 @@ 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"
             }
         }
     ' "$@"
@@ -994,8 +1109,8 @@ get_model_default_var() {
         cursor:heavy)     IS_MODEL_DEFAULT="inherit" ;;
         cursor:standard)  IS_MODEL_DEFAULT="inherit" ;;
         cursor:light)     IS_MODEL_DEFAULT="inherit" ;;
-        # GPT-6 has no mid model, so frontier and heavy share Astra; Codex
-        # separates them by reasoning effort instead.
+        # GPT-6 has no mid model, so frontier and heavy share Astra and render
+        # identically; reasoning effort comes from `effort:`, never the tier.
         copilot:frontier) IS_MODEL_DEFAULT="gpt-6-astra" ;;
         copilot:heavy)    IS_MODEL_DEFAULT="gpt-6-astra" ;;
         copilot:standard) IS_MODEL_DEFAULT="gpt-6.1-sol" ;;
@@ -1132,7 +1247,7 @@ load_model_tiers() {
 # the tool has no default for and the manifest overrides nowhere — a typo, as a
 # rule — still renders an empty model, but never silently: the run warns once
 # per tool and tier, unindented on purpose because `sync --compact` keeps only
-# `WARNING:` lines.
+# `WARNING:` lines (decision 0016).
 # shellcheck disable=SC2034  # IS_MODEL is the return channel read by adapters
 resolve_model_var() {
     case "$1" in
@@ -1242,6 +1357,64 @@ map_access_to_claude_disallowed() {
     echo "$IS_CLAUDE_DISALLOWED"
 }
 
+# --- Effort Mapping ---
+
+# `effort:` is the tool-neutral reasoning effort an agent or skill asks for,
+# lowest first (decision 0015). It is independent of `tier`, which selects the
+# model only. A value off this scale — matched exactly, case included — is an
+# absent effort: lint_frontmatter_files warns about it and no tool receives
+# one, because a typo in another source's package must not block a sync.
+IS_EFFORT_LEVELS="low medium high xhigh max ultra"
+
+# effort_levels_var <tool> — set IS_EFFORT_TOOL_LEVELS to the levels the tool's
+# native effort field accepts, in scale order; empty for a tool without one.
+# `open` is the shared Agent Skills tree (.agents/skills/), which keeps the
+# neutral value for the tools that read it.
+effort_levels_var() {
+    case "$1" in
+        claude)     IS_EFFORT_TOOL_LEVELS="low medium high xhigh max" ;;
+        codex|open) IS_EFFORT_TOOL_LEVELS="$IS_EFFORT_LEVELS" ;;
+        # Copilot, Cursor, OpenCode, Antigravity and Pi have no per-agent
+        # effort field: the tool's own setting applies.
+        *)          IS_EFFORT_TOOL_LEVELS="" ;;
+    esac
+}
+
+# map_effort_var <tool> <effort> — set IS_EFFORT to the level the tool receives:
+# the same level, or the nearest lower one the tool has (`ultra` is `max` for
+# Claude Code). Empty when the effort is absent or off the scale, or the tool
+# has no field. Which levels a particular model supports is the tool's call: a
+# manifest may override the model, and the tools fall back on their own.
+map_effort_var() {
+    local level best=""
+    IS_EFFORT=""
+    effort_levels_var "$1"
+    for level in $IS_EFFORT_LEVELS; do
+        case " $IS_EFFORT_TOOL_LEVELS " in *" $level "*) best="$level" ;; esac
+        if [ "$level" = "${2-}" ]; then
+            IS_EFFORT="$best"
+            return 0
+        fi
+    done
+}
+
+map_effort() {
+    map_effort_var "$1" "$2"
+    echo "$IS_EFFORT"
+}
+
+# effort_map_var <tool> — set IS_EFFORT_MAP to one `<neutral>=<native>` line per
+# level the tool maps, so a batched awk pass rewrites `effort:` in place with
+# map_effort_var's answers instead of a second copy of the mapping.
+effort_map_var() {
+    local level map=""
+    for level in $IS_EFFORT_LEVELS; do
+        map_effort_var "$1" "$level"
+        [ -z "$IS_EFFORT" ] || map+="$level=$IS_EFFORT"$'\n'
+    done
+    IS_EFFORT_MAP="$map"
+}
+
 # --- Validation ---
 
 # Lexically canonicalize a path: collapse `//`, `.` and `..` by pure string
@@ -1453,7 +1626,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
 
@@ -1547,11 +1721,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)
@@ -1562,10 +1732,363 @@ 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,
+# the membership the glob-listing adapters check (skill_source_rendered), 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. For
+# adapters that list a skills source with their own glob.
+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
 }
 
@@ -1588,6 +2111,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"
@@ -1595,8 +2121,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"
@@ -1623,12 +2156,6 @@ read_source_artifact_files() {
                     exit 1
                 }
                 ;;
-            skills)
-                listing="$(find "$dir" -mindepth 1 -maxdepth 1 -type d -print | LC_ALL=C sort)" || {
-                    echo "ERROR: cannot enumerate $section under '$dir' — refusing to render a partial list." >&2
-                    exit 1
-                }
-                ;;
             *) continue ;;
         esac
         [ -n "$listing" ] || continue
@@ -1636,10 +2163,6 @@ read_source_artifact_files() {
         # 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
             IS_SOURCE_FILES+=("$f")
             joined="$joined$f"$'\n'
         done <<< "$listing"
@@ -1787,15 +2310,220 @@ report_context_source_sizes() {
 
 # --- Config Parsing ---
 
+# --- Package references in sources -------------------------------------------
+# A `sources:` entry names a directory inside an installed package in one of
+# three spellings (decision 0019):
+#
+#   .intelligence/packages/@scope/name/<dir>  the store path: an ordinary
+#                                             repository path, as the CLI writes it
+#   @scope/name/<dir>                         by full name: a reference only while
+#                                             `packages:` declares @scope/name,
+#                                             otherwise an ordinary path as before
+#   <alias>:<dir>                             by the alias that package's
+#                                             `packages:` entry declares
+#
+# A reference renders exactly as the store path it stands for. The list parser
+# below expands it inside the awk pass that already reads the manifest; that
+# pass is the one point every reader goes through — adapters, the engine's own
+# loops and the CLI — so expansion costs no process, and the CLI sees exactly
+# what the engine renders (decision 0009). A reference that resolves to nothing
+# is left out of the list, so no reader can render it as a path: `sync` names it
+# in a WARNING: line and `status --check` reports it.
+#
+# An alias is two or more of A-Z a-z 0-9 . _ - and starts with a letter or digit:
+# no `/`, `:` or `@`, no whitespace or quotes, and never one letter that reads
+# like a drive. It is a lookup key, never part of a path. <dir> is one or more
+# `/`-separated segments, none of them empty, `.` or `..`, without a backslash,
+# so a reference never leaves its package.
+#
+# These functions are the only definition. The CLI's editors (lib/manifest.sh),
+# `source`, `package alias` and `status --check` load this same string:
+#
+#   pkr_collect(line)   feed every manifest line; records the names `packages:`
+#                       declares and the alias each one states
+#   pkr_parse(entry)    classify one entry: path, ok, unknown (an alias no
+#                       package declares), ambiguous (an alias several declare)
+#                       or invalid (a reference whose <dir> is malformed); sets
+#                       PKR_NAME, PKR_DIR, PKR_ALIAS and, when ambiguous,
+#                       PKR_HOLDERS
+#   pkr_expand(entry)   the directory the entry renders as, "" when it renders
+#                       nothing; leaves the state in PKR_STATE
+#   pkr_alias_ok(a)     whether <a> is a well-formed alias
+IS_PKG_REF_AWK='
+    function pkr_seg_ok(s) { return s != "" && s != "." && s != ".." }
+    # The CLI refuses any other package name (assert_valid_pkg_name): a name
+    # becomes a store path, so one that is not a plain @scope/name is never
+    # declared.
+    function pkr_name_ok(name,   p) {
+        if (name !~ /^@[@A-Za-z0-9._-]*\/[@A-Za-z0-9._-]*$/) return 0
+        p = index(name, "/")
+        return pkr_seg_ok(substr(name, 2, p - 2)) && pkr_seg_ok(substr(name, p + 1))
+    }
+    # Enumerated, not a range: a range follows the locale in some awks.
+    function pkr_alias_ok(a,   i, c) {
+        if (length(a) < 2) return 0
+        for (i = 1; i <= length(a); i++) {
+            c = substr(a, i, 1)
+            if (index("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789", c)) continue
+            if (i > 1 && index("._-", c)) continue
+            return 0
+        }
+        return 1
+    }
+    function pkr_dir_ok(dir,   n, i, seg) {
+        if (dir == "" || index(dir, "\\")) return 0
+        n = split(dir, seg, "/")
+        for (i = 1; i <= n; i++) if (!pkr_seg_ok(seg[i])) return 0
+        return 1
+    }
+    # The quoted keys of the top-level packages: block and their alias fields,
+    # read the way lib/qmap.awk reads what the CLI writes: a duplicated key is
+    # one package, and the first alias a package states is the one it has.
+    function pkr_collect(line,   s, q, v) {
+        if (line ~ /^packages:[ \t]*$/) { pkr_in = 1; pkr_cur = ""; return }
+        if (!pkr_in || line ~ /^[ \t]*(#.*)?$/) return
+        if (line ~ /^[^ \t]/) { pkr_in = 0; pkr_cur = ""; return }
+        if (substr(line, 1, 3) == "  \"") {
+            pkr_cur = ""
+            s = substr(line, 4)
+            q = index(s, "\"")
+            if (q < 2) return
+            v = substr(s, 1, q - 1)
+            if (!pkr_name_ok(v)) return
+            if (!(v in pkr_seen)) { pkr_seen[v] = 1; PKR_NAMES[++PKR_N] = v }
+            pkr_cur = v
+            return
+        }
+        if (substr(line, 1, 4) != "    ") { pkr_cur = ""; return }
+        if (pkr_cur == "" || (pkr_cur in PKR_ALIAS_RAW) || substr(line, 5, 6) != "alias:") return
+        v = substr(line, 11)
+        sub(/^[ \t]+/, "", v)
+        if (substr(v, 1, 1) == "\"") {
+            v = substr(v, 2)
+            q = index(v, "\"")
+            if (q == 0) return
+            v = substr(v, 1, q - 1)
+        } else {
+            sub(/[ \t]+#.*$/, "", v)
+            sub(/[ \t]+$/, "", v)
+        }
+        PKR_ALIAS_RAW[pkr_cur] = v
+        if (!pkr_alias_ok(v)) return
+        pkr_holders[v] = (v in pkr_holders) ? pkr_holders[v] ", " pkr_cur : pkr_cur
+        pkr_count[v]++
+        pkr_alias[v] = pkr_cur
+    }
+    function pkr_parse(entry,   c, p, i, rest, name) {
+        PKR_NAME = ""; PKR_DIR = ""; PKR_ALIAS = ""; PKR_HOLDERS = ""
+        if (substr(entry, 1, 1) == "@") {
+            p = index(entry, "/")
+            if (p == 0) return "path"
+            rest = substr(entry, p + 1)
+            i = index(rest, "/")
+            name = i ? substr(entry, 1, p + i - 1) : entry
+            if (!(name in pkr_seen)) return "path"
+            PKR_NAME = name
+            PKR_DIR = i ? substr(rest, i + 1) : ""
+            return pkr_dir_ok(PKR_DIR) ? "ok" : "invalid"
+        }
+        c = index(entry, ":")
+        if (c == 0 || !pkr_alias_ok(substr(entry, 1, c - 1))) return "path"
+        PKR_ALIAS = substr(entry, 1, c - 1)
+        PKR_DIR = substr(entry, c + 1)
+        if (!pkr_dir_ok(PKR_DIR)) return "invalid"
+        if (!(PKR_ALIAS in pkr_count)) return "unknown"
+        if (pkr_count[PKR_ALIAS] > 1) { PKR_HOLDERS = pkr_holders[PKR_ALIAS]; return "ambiguous" }
+        PKR_NAME = pkr_alias[PKR_ALIAS]
+        return "ok"
+    }
+    function pkr_expand(entry) {
+        PKR_STATE = pkr_parse(entry)
+        if (PKR_STATE == "path") return entry
+        if (PKR_STATE == "ok") return ".intelligence/packages/" PKR_NAME "/" PKR_DIR
+        return ""
+    }
+'
+
+# The value of one block-sequence item in the manifest — the only reading of a
+# list entry. Every list reader below and the CLI's `sources:` editors
+# (lib/manifest.sh) load this string, so an entry the engine renders and the
+# entry an editor compares are the same text (decision 0009, point 7).
+#
+#   yaml_item(text)   <text> is what follows the item's `-`. Returns the value:
+#                     whitespace around it and a trailing `# comment` dropped,
+#                     then every quote removed, as the readers always did. A
+#                     comment starts at a `#` that follows whitespace outside
+#                     quotes; inside a quoted scalar a `#` is part of the value,
+#                     and so is one with no whitespace before it (`a#b`).
+IS_YAML_ITEM_AWK='
+    function yaml_item(s,   q, e, rest) {
+        sub(/^[ \t]+/, "", s)
+        q = substr(s, 1, 1)
+        rest = s
+        s = ""
+        if (q == "\"" || q == "\047") {
+            e = index(substr(rest, 2), q)
+            if (e == 0) { s = rest; rest = "" }
+            else { s = substr(rest, 1, e + 1); rest = substr(rest, e + 2) }
+        }
+        if (s == "" && substr(rest, 1, 1) == "#") rest = ""
+        else if (match(rest, /[ \t]#/)) rest = substr(rest, 1, RSTART - 1)
+        s = s rest
+        sub(/[ \t]+$/, "", s)
+        gsub(/["\047]/, "", s)
+        return s
+    }
+'
+
+# The manifest list reader. `mode` selects what it prints for each entry:
+#   expand    the entry as the engine renders it: a reference becomes its store
+#             path, one that resolves to nothing is left out
+#   raw       the entry as written — what an editor compares and rewrites
+#   classify  raw, pkr_parse state, expansion, alias and the packages sharing
+#             it, separated by \037 — what `status --check` and `source` judge
+# Only rules, agents and skills hold sources; every other list reads raw.
+# Entries are held until the end of the file because `packages:` may follow
+# `sources:`.
+IS_YAML_LIST_AWK='
+    { sub(/\r$/, ""); pkr_collect($0) }
+    /^[a-z]/ { current_section = ""; depth = 0 }
+    /^  [a-z]/ { current_section = ""; depth = 0 }
+    $0 ~ "^" section ":" { current_section = section; depth = 0; next }
+    $0 ~ "^  " section ":" { current_section = section; depth = 2; next }
+    current_section == section && depth == 0 && /^  - / {
+        vals[++nv] = yaml_item(substr($0, 5))
+    }
+    current_section == section && depth == 2 && /^    - / {
+        vals[++nv] = yaml_item(substr($0, 7))
+    }
+    END {
+        sources = section == "rules" || section == "agents" || section == "skills"
+        n = nv + 0
+        for (i = 1; i <= n; i++) {
+            val = vals[i]
+            if (!sources || mode == "raw") { print val; continue }
+            dir = pkr_expand(val)
+            if (mode == "classify") print val "\037" PKR_STATE "\037" dir "\037" PKR_ALIAS "\037" PKR_HOLDERS
+            else if (PKR_STATE == "path" || PKR_STATE == "ok") print dir
+        }
+    }
+'
+
 # Read a simple list from config.yaml
 # Format: key:\n  - "value1"\n  - "value2"
-# Usage: readarray -t arr < <(read_yaml_list "config.yaml" "rules")
+# Usage: while IFS= read -r src; do ...; done < <(read_yaml_list "intelligence.yaml" "rules")
+#
+# A source list arrives with its package references expanded to store paths —
+# the spelling every renderer resolves as $REPO_ROOT/<entry> — and without the
+# ones that resolve to nothing. Editors that rewrite the manifest read it with
+# read_yaml_list_raw instead.
 #
 # 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"
@@ -1813,27 +2541,67 @@ read_yaml_list() {
             fi
             ;;
     esac
-    awk -v section="$section" '
-        {
-            sub(/\r$/, "")
-        }
-        /^[a-z]/ { current_section = ""; depth = 0 }
-        /^  [a-z]/ { current_section = ""; depth = 0 }
-        $0 ~ "^" section ":" { current_section = section; depth = 0; next }
-        $0 ~ "^  " section ":" { current_section = section; depth = 2; next }
-        current_section == section && depth == 0 && /^  - / {
-            val = $0
-            sub(/^  - /, "", val)
-            gsub(/["\047]/, "", val)
-            print val
-        }
-        current_section == section && depth == 2 && /^    - / {
-            val = $0
-            sub(/^    - /, "", val)
-            gsub(/["\047]/, "", val)
-            print val
+    awk -v section="$section" -v mode=expand "$IS_PKG_REF_AWK$IS_YAML_ITEM_AWK$IS_YAML_LIST_AWK" "$file"
+}
+
+# read_yaml_list_raw <file> <section> — the entries exactly as written,
+# references included and never cached. The CLI's sources editors compare and
+# rewrite these, so an entry is matched as the user spelled it.
+read_yaml_list_raw() {
+    awk -v section="$2" -v mode=raw "$IS_PKG_REF_AWK$IS_YAML_ITEM_AWK$IS_YAML_LIST_AWK" "$1"
+}
+
+# read_source_entries <file> <section> — one \037-separated line per entry: as
+# written, its pkr_parse state (path, ok, unknown, ambiguous or invalid), the
+# directory it renders as ("" for none), the alias it names and, when several
+# packages declare that alias, their names. One pass of the parser the engine
+# renders through, so a verdict can never disagree with the render.
+read_source_entries() {
+    awk -v section="$2" -v mode=classify "$IS_PKG_REF_AWK$IS_YAML_ITEM_AWK$IS_YAML_LIST_AWK" "$1"
+}
+
+# read_package_aliases <file> — one \037-separated line per declared package that
+# states an alias: its name, the alias, and ok, ambiguous (another package states
+# it too) or invalid (not a well-formed alias, so it resolves nothing). An
+# invalid alias is manifest input that may hold anything, so its field is empty.
+read_package_aliases() {
+    [ -f "$1" ] || return 0
+    awk "$IS_PKG_REF_AWK"'
+        { sub(/\r$/, ""); pkr_collect($0) }
+        END {
+            for (i = 1; i <= PKR_N; i++) {
+                name = PKR_NAMES[i]
+                if (!(name in PKR_ALIAS_RAW)) continue
+                a = PKR_ALIAS_RAW[name]
+                if (!pkr_alias_ok(a)) { print name "\037\037invalid"; continue }
+                print name "\037" a "\037" (pkr_count[a] > 1 ? "ambiguous" : "ok")
+            }
         }
-    ' "$file"
+    ' "$1"
+}
+
+# What pkr_alias_ok accepts, in the words every message that refuses an alias
+# uses.
+# shellcheck disable=SC2034
+IS_PKG_ALIAS_RULE="two or more of A-Z a-z 0-9 . _ -, starting with a letter or digit"
+
+# pkg_alias_valid <alias> — true when <alias> is well formed (pkr_alias_ok). The
+# value travels through the environment: `awk -v` would interpret backslashes.
+pkg_alias_valid() {
+    IS_PKR_CANDIDATE="$1" awk "$IS_PKG_REF_AWK"'BEGIN { exit !pkr_alias_ok(ENVIRON["IS_PKR_CANDIDATE"]) }'
+}
+
+# source_reference_problem_var <state> <alias> <holders> — set IS_SOURCE_PROBLEM
+# to why a reference in that state renders nothing, "" for path and ok. The one
+# wording of `sync`'s WARNING: line and of `status --check`.
+# shellcheck disable=SC2034
+source_reference_problem_var() {
+    case "$1" in
+        unknown) IS_SOURCE_PROBLEM="names alias '$2', which no package in packages: declares" ;;
+        ambiguous) IS_SOURCE_PROBLEM="names alias '$2', which several packages declare ($3) — an alias names one package" ;;
+        invalid) IS_SOURCE_PROBLEM="names no directory inside its package — the part after the package must be one or more '/'-separated segments, none empty, '.' or '..'" ;;
+        *) IS_SOURCE_PROBLEM="" ;;
+    esac
 }
 
 # load_yaml_list <file> <section> — fill the global IS_YAML_LIST with the
@@ -1863,21 +2631,19 @@ 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, so every cached value is what load_yaml_list would have stored.
-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="$*" '
+# 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$/, "") }
+        { sub(/\r$/, ""); pkr_collect($0) }
         {
             for (k = 1; k <= n; k++) {
                 s = want[k]
@@ -1886,49 +2652,53 @@ load_yaml_lists() {
                 if ($0 ~ "^" s ":") { cur[k] = s; dep[k] = 0; continue }
                 if ($0 ~ "^  " s ":") { cur[k] = s; dep[k] = 2; continue }
                 if (cur[k] == s && dep[k] == 0 && /^  - /) {
-                    val = $0
-                    sub(/^  - /, "", val)
-                    gsub(/["\047]/, "", val)
-                    print s "\037" val
+                    got_s[++ng] = s
+                    got_v[ng] = yaml_item(substr($0, 5))
                 }
                 if (cur[k] == s && dep[k] == 2 && /^    - /) {
-                    val = $0
-                    sub(/^    - /, "", val)
-                    gsub(/["\047]/, "", val)
-                    print s "\037" val
+                    got_s[++ng] = s
+                    got_v[ng] = yaml_item(substr($0, 7))
                 }
             }
         }
-    ' "$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
-}
+        END {
+            m = ng + 0
+            for (i = 1; i <= m; i++) {
+                s = got_s[i]
+                val = got_v[i]
+                if (s != "rules" && s != "agents" && s != "skills") { print s "\037" val; continue }
+                dir = pkr_expand(val)
+                if (PKR_STATE == "path" || PKR_STATE == "ok") print s "\037" dir
+                else print "!\037" s "\037" val "\037" PKR_STATE "\037" dir "\037" PKR_ALIAS "\037" PKR_HOLDERS
+            }
+        }
+'
 
-# 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$/, "") }
@@ -1964,10 +2734,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).
@@ -2189,18 +3096,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)