@ainova-systems/intelligence 0.18.0 → 0.19.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.
@@ -460,11 +461,17 @@ 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_bundles_flush open
 }
 
 # copy_skill_bundle_dirs <dest_root> <src_dir>... — batch form: ONE cp -R
@@ -473,8 +480,14 @@ copy_skill_bundle() {
 # bundles. A later source with the same skill name overwrites file-by-file in
 # order, exactly like the sequential per-bundle copies did.
 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 -a srcs=()
@@ -488,7 +501,7 @@ copy_skill_bundle_dirs() {
         dest="$dest_root/${src##*/}"
         _skill_bundle_note "$dest"
     done
-    _skill_bundles_flush
+    _skill_bundles_flush "$effort_tool"
 }
 
 _skill_bundles_reset() {
@@ -531,6 +544,7 @@ _skill_bundle_note() {
     esac
 }
 
+# _skill_bundles_flush <effort-tool>
 _skill_bundles_flush() {
     [ "${#_SB_DESTS[@]}" -gt 0 ] || return 0
     local -a mds=()
@@ -540,18 +554,27 @@ _skill_bundles_flush() {
     done < <(find "${_SB_DESTS[@]}" -type f -name '*.md')
     _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 +595,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 +690,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
 
@@ -677,12 +707,23 @@ sync_open_skill_dirs() {
 # `agents/openai.yaml` beside SKILL.md. Source skills stay tool-neutral: the
 # policy file is derived here, in the open-standard tree Codex reads, so every
 # adapter sharing that tree writes the same bytes. A skill that ships its own
-# `agents/openai.yaml` keeps it — that is the author configuring Codex directly.
+# `agents/openai.yaml` keeps the rest of it: the output copy gains the policy
+# 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.
 open_skill_invocation_policies() {
-    local output_dir="$1" path flag rows
-    local -a skill_mds=() policy_dirs=() 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
-        [ -f "$path" ] && [ ! -L "$path" ] && skill_mds+=("$path")
+        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
     done
     [ "${#skill_mds[@]}" -gt 0 ] || return 0
     # Captured, not streamed: a reader cut short must fail the render rather
@@ -693,13 +734,32 @@ open_skill_invocation_policies() {
     }
     while IFS=$'\x1f' read -r path flag; do
         [ "$flag" = "true" ] || continue
-        path="${path%/SKILL.md}/agents"
-        # A symlinked `agents` would carry the write outside the output tree.
-        [ -L "$path" ] && continue
-        [ -e "$path/openai.yaml" ] || [ -L "$path/openai.yaml" ] && 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
+        fi
         policy_dirs+=("$path")
         policies+=("$path/openai.yaml")
     done <<< "$rows"
+    if [ "${#authored[@]}" -gt 0 ]; then
+        refusals="$(enforce_authored_invocation_policies "${authored[@]}")" || {
+            echo "ERROR: could not read or rewrite agents/openai.yaml under $output_dir" >&2
+            return 1
+        }
+        if [ -n "$refusals" ]; then
+            while IFS=$'\t' read -r path flag; do
+                path="${path%/agents/openai.yaml}"
+                echo "ERROR: ${path##*/} sets disable-model-invocation: true, but its agents/openai.yaml $flag — make them agree, or Codex can still select the skill" >&2
+            done <<< "$refusals"
+            return 1
+        fi
+    fi
     [ "${#policies[@]}" -gt 0 ] || return 0
     mkdir -p "${policy_dirs[@]}"
     for path in "${policies[@]}"; do
@@ -709,20 +769,128 @@ open_skill_invocation_policies() {
     finalize_output_files "${policies[@]}"
 }
 
+# enforce_authored_invocation_policies <openai.yaml>... — one awk pass over
+# author-owned Codex files of skills that set `disable-model-invocation: true`.
+# A file already setting `policy.allow_implicit_invocation: false` is left
+# alone; one without that key gains it, inside an existing `policy:` block or
+# as a new block, every other line kept. Only the plain boolean on a direct
+# child of `policy:` counts — the key Codex reads. A file that sets it
+# otherwise, or whose `policy:` sync cannot read or extend safely, is printed
+# as `<file>\t<reason>` and left untouched for the caller to refuse.
+enforce_authored_invocation_policies() {
+    awk '
+        function reset() {
+            file = ""; n = 0; haspol = 0; inpol = 0; polline = 0
+            inline = ""; child = ""; val = ""; hasval = 0; bad = ""
+        }
+        # A one-line policy counts only as a flat flow mapping of plain
+        # scalars holding the key itself; a quoted or nested value is not read.
+        function inline_ok(s,   body, parts, k, i, p) {
+            if (s !~ /^\{.*\}$/) return 0
+            body = substr(s, 2, length(s) - 2)
+            if (body ~ /[{}"\047]/ || index(body, "[") || index(body, "]")) return 0
+            k = split(body, parts, ",")
+            for (i = 1; i <= k; i++) {
+                p = parts[i]
+                gsub(/^[[:space:]]+|[[:space:]]+$/, "", p)
+                if (p ~ /^allow_implicit_invocation[[:space:]]*:[[:space:]]*false$/) return 1
+            }
+            return 0
+        }
+        function finish(   i, ind) {
+            if (file == "") return
+            if (bad == "" && inline != "" && !inline_ok(inline))
+                bad = "has policy: " inline ", which does not plainly set allow_implicit_invocation: false"
+            if (bad == "" && hasval && val != "false")
+                bad = "sets policy.allow_implicit_invocation: " (val == "" ? "null" : val)
+            if (bad != "") { printf "%s\t%s\n", file, bad; reset(); return }
+            if (inline != "" || hasval) { reset(); return }
+            ind = (child != "") ? child : "  "
+            for (i = 1; i <= n; i++) {
+                print L[i] > file
+                if (haspol && i == polline) print ind "allow_implicit_invocation: false" > file
+            }
+            if (!haspol) {
+                print "policy:" > file
+                print "  allow_implicit_invocation: false" > file
+            }
+            close(file)
+            reset()
+        }
+        BEGIN { reset() }
+        FNR == 1 { finish(); file = FILENAME }
+        { sub(/\r$/, ""); L[++n] = $0 }
+        /^["\047]?policy["\047]?[[:space:]]*:/ {
+            if (haspol) bad = "has more than one policy: key"
+            haspol = 1; polline = n; inpol = 1
+            rest = $0
+            sub(/^[^:]*:[[:space:]]*/, "", rest)
+            sub(/[[:space:]]+#.*$/, "", rest)
+            sub(/^#.*$/, "", rest)
+            sub(/[[:space:]]+$/, "", rest)
+            if (rest != "") { inline = rest; inpol = 0 }
+            next
+        }
+        inpol && /^[^[:space:]#]/ { inpol = 0 }
+        # The first indented line fixes the depth of the direct children of
+        # policy:, and a deeper line belongs to another key, not the one Codex
+        # reads.
+        inpol && /^[[:space:]]+[^[:space:]#]/ {
+            match($0, /^[[:space:]]+/)
+            cur = substr($0, 1, RLENGTH)
+            if (child == "") {
+                child = cur
+                if ($0 ~ /^[[:space:]]+-([[:space:]]|$)/) bad = "has a policy: that is not a mapping"
+            } else if (length(cur) < length(child)) {
+                bad = "has a policy: block indented inconsistently"
+            }
+            if (cur == child && $0 ~ /^[[:space:]]+["\047]?allow_implicit_invocation["\047]?[[:space:]]*:/) {
+                v = $0
+                sub(/^[^:]*:[[:space:]]*/, "", v)
+                sub(/[[:space:]]+#.*$/, "", v)
+                sub(/^#.*$/, "", v)
+                sub(/[[:space:]]+$/, "", v)
+                hasval = 1; val = v
+            }
+        }
+        END { finish() }
+    ' "$@"
+}
+
 # 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.
 # 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"
         }
@@ -876,8 +1044,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" ;;
@@ -1010,7 +1178,11 @@ load_model_tiers() {
 }
 
 # resolve_model_var <tier> — set IS_MODEL from the tiers load_model_tiers
-# resolved. An empty tier resolves to heavy, like get_model's default.
+# resolved. An empty tier resolves to heavy, like get_model's default. A tier
+# 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 (decision 0016).
 # shellcheck disable=SC2034  # IS_MODEL is the return channel read by adapters
 resolve_model_var() {
     case "$1" in
@@ -1018,7 +1190,17 @@ resolve_model_var() {
         heavy|"") IS_MODEL="$IS_MODEL_HEAVY" ;;
         standard) IS_MODEL="$IS_MODEL_STANDARD" ;;
         light)    IS_MODEL="$IS_MODEL_LIGHT" ;;
-        *)        IS_MODEL="$(get_model "$IS_MODEL_CFG" "$IS_MODEL_IDE" "$1")" ;;
+        *)
+            IS_MODEL="$(get_model "$IS_MODEL_CFG" "$IS_MODEL_IDE" "$1")"
+            [ -n "$IS_MODEL" ] && return 0
+            case "${IS_MODEL_WARNED:-|}" in
+                *"|$IS_MODEL_IDE:$1|"*) ;;
+                *)
+                    IS_MODEL_WARNED="${IS_MODEL_WARNED:-|}$IS_MODEL_IDE:$1|"
+                    echo "WARNING: no $IS_MODEL_IDE model for tier '$1' — agents with it get an empty model; use frontier, heavy, standard or light, or set models.$IS_MODEL_IDE.$1" >&2
+                    ;;
+            esac
+            ;;
     esac
 }
 
@@ -1110,6 +1292,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
@@ -1655,9 +1895,213 @@ 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
@@ -1681,27 +2125,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
@@ -1733,7 +2217,10 @@ load_yaml_list() {
 
 # 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.
+# 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
@@ -1743,9 +2230,9 @@ load_yaml_lists() {
             *) return 1 ;;
         esac
     done
-    out="$(awk -v sections="$*" '
+    out="$(awk -v sections="$*" "$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]
@@ -1754,19 +2241,26 @@ 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))
                 }
             }
         }
+        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
+            }
+        }
     ' "$file")"
     for s in "$@"; do
         j=""
@@ -1779,6 +2273,12 @@ load_yaml_lists() {
         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