@ainova-systems/intelligence 0.18.1 → 0.20.0

package/cli/lib/gitignore.sh

@@ -13,12 +13,13 @@ IS_CR=$'\r'
 IS_LF=$'\n'
 IS_CRLF=$'\r\n'
 
-# An ignore file checked out on Windows can hold CRLF, and a CR belongs to the
-# pattern Git matches — so these two helpers decide presence ignoring it, and
-# append in whatever ending the file already uses. Comparing with the CR
-# attached made every existing line look absent on Linux and macOS (where it is
-# part of the line, unlike under MSYS), so each alignment appended an LF copy of
-# a line that was already there and the file grew forever.
+# An ignore file checked out on Windows can hold CRLF. Git drops one trailing
+# CR from each line before matching, so `foo` and `foo<CR>` are the same rule:
+# these helpers decide presence ignoring that CR, and append in whatever ending
+# the file already uses. Comparing with the CR attached made every existing
+# line look absent on Linux and macOS (where it is part of the line, unlike
+# under MSYS), so each alignment appended an LF copy of a line that was already
+# there and the file grew forever.
 
 # ignore_file_eol_var <file> — set IS_IGNORE_EOL from the file's first line.
 ignore_file_eol_var() {
@@ -32,12 +33,19 @@ ignore_file_eol_var() {
 }
 
 # ignore_file_has_line <file> <line> — true when the file lists exactly this
-# line, with or without a trailing CR.
+# line, with or without a trailing CR. The one presence test for an ignore
+# file: the writer and `status --check` both ask it, so a line one appends is a
+# line the other reports present. Decided in bash, because an exact-line grep
+# answers per platform — MSYS grep never sees the CR, Linux and macOS grep keep
+# it as part of the line.
 ignore_file_has_line() {
-    local file="$1" line="$2"
+    local file="$1" line="$2" entry=""
     [ -f "$file" ] || return 1
-    grep -Fqx -- "$line" "$file" 2>/dev/null && return 0
-    grep -Fqx -- "$line$IS_CR" "$file" 2>/dev/null
+    while IFS= read -r entry || [ -n "$entry" ]; do
+        [ "${entry%"$IS_CR"}" = "$line" ] && return 0
+        entry=""
+    done < "$file"
+    return 1
 }
 
 # ignore_file_append_line <file> <line> — append in the file's own ending.
@@ -88,29 +96,17 @@ gitignore_collapse_duplicates() {
     local root="$1" probe="$2"; shift 2
     local file="$root/.gitignore" tmp backup before=0 after=0
     local -a lines=() managed=("$@") last_idx=()
-    local line key i mi n hdr=-1 keep final_newline=1
+    local key i mi n hdr keep final_newline
     [ -f "$file" ] || return 0
 
-    # Read and write the file's own bytes, without awk: on Windows it reads in
-    # text mode and would hand back every line stripped of its CR, rewriting a
-    # CRLF file as LF. A line's CR is significant to Git, and either way the
-    # lines this function does not remove must survive byte-for-byte.
-    line=""
-    while IFS= read -r line; do
-        lines[${#lines[@]}]="$line"
-        line=""
-    done < "$file"
-    # `read` returns 1 at EOF but still fills `line` when the file's last line
-    # carries no newline; preserve that ending instead of adding one.
-    if [ -n "$line" ]; then
-        lines[${#lines[@]}]="$line"
-        final_newline=0
-    fi
-    n=${#lines[@]}
-    for ((i = 0; i < n; i++)); do
-        if [ "${lines[i]%"$IS_CR"}" = "$IS_GITIGNORE_HEADER" ]; then hdr=$i; break; fi
-    done
+    gitignore_read_var "$file"
+    hdr=$IS_GI_HEADER
     [ "$hdr" -ge 0 ] || return 0
+    # A header was found, so the array is not empty — Bash 3.2 under `set -u`
+    # cannot expand an empty one.
+    lines=("${IS_GI_LINES[@]}")
+    final_newline=$IS_GI_FINAL_NEWLINE
+    n=${#lines[@]}
 
     # Where each managed line last occurs below the header. Indexed arrays and
     # arithmetic `for` only — Bash 3.2 has no associative arrays.
@@ -161,6 +157,97 @@ gitignore_collapse_duplicates() {
     rm -f "$backup"
 }
 
+# gitignore_read_var <file> — load the file's lines as stored, CRs included, into
+# IS_GI_LINES. IS_GI_HEADER is the index of this policy's header (-1 when the
+# file has none) and IS_GI_FINAL_NEWLINE is 0 when the last line ends without
+# one. Every writer that rewrites .gitignore line by line reads it here.
+#
+# `read`, never awk: on Windows awk reads in text mode and would hand back every
+# line stripped of its CR, rewriting a CRLF file as LF. The lines a writer does
+# not remove must survive byte-for-byte, whatever their ending.
+gitignore_read_var() {
+    local file="$1" line i
+    IS_GI_LINES=()
+    IS_GI_HEADER=-1
+    IS_GI_FINAL_NEWLINE=1
+    line=""
+    while IFS= read -r line; do
+        IS_GI_LINES[${#IS_GI_LINES[@]}]="$line"
+        line=""
+    done < "$file"
+    # `read` returns 1 at EOF but still fills `line` when the file's last line
+    # carries no newline; preserve that ending instead of adding one.
+    if [ -n "$line" ]; then
+        IS_GI_LINES[${#IS_GI_LINES[@]}]="$line"
+        IS_GI_FINAL_NEWLINE=0
+    fi
+    for ((i = 0; i < ${#IS_GI_LINES[@]}; i++)); do
+        if [ "${IS_GI_LINES[i]%"$IS_CR"}" = "$IS_GITIGNORE_HEADER" ]; then
+            IS_GI_HEADER=$i
+            break
+        fi
+    done
+}
+
+# gitignore_managed_has_line <root> <line> — true when the region this policy
+# owns (its header to end of file) lists the line, with or without a CR.
+gitignore_managed_has_line() {
+    local file="$1/.gitignore" want="$2" i
+    [ -f "$file" ] || return 1
+    gitignore_read_var "$file"
+    [ "$IS_GI_HEADER" -ge 0 ] || return 1
+    for ((i = IS_GI_HEADER + 1; i < ${#IS_GI_LINES[@]}; i++)); do
+        if [ "${IS_GI_LINES[i]%"$IS_CR"}" = "$want" ]; then
+            return 0
+        fi
+    done
+    return 1
+}
+
+# gitignore_remove_managed_lines <root> <line…> — take every copy of these lines
+# out of the region this policy owns. A contract names them with `unignore` when
+# the project's configuration keeps tracked what the default policy ignores
+# (targets.copilot.commit_output), so the ignore an earlier alignment wrote is
+# withdrawn by the writer that wrote it, not by a hand edit. Lines above the
+# header predate Intelligence and stay — a hand-written copy of the same
+# pattern included — and every kept line keeps its bytes and its own ending:
+# only the file's last line can lack a newline, and none is added to it.
+gitignore_remove_managed_lines() {
+    local root="$1"; shift
+    local file="$root/.gitignore" tmp key i mi n dropped=0
+    local -a remove=("$@") keep=()
+    [ "$#" -gt 0 ] && [ -f "$file" ] || return 0
+    gitignore_read_var "$file"
+    [ "$IS_GI_HEADER" -ge 0 ] || return 0
+    n=${#IS_GI_LINES[@]}
+    for ((i = 0; i < n; i++)); do
+        keep[i]=1
+        [ "$i" -gt "$IS_GI_HEADER" ] || continue
+        key="${IS_GI_LINES[i]%"$IS_CR"}"
+        for ((mi = 0; mi < ${#remove[@]}; mi++)); do
+            if [ "$key" = "${remove[mi]}" ]; then
+                keep[i]=0
+                dropped=1
+                break
+            fi
+        done
+    done
+    [ "$dropped" -eq 1 ] || return 0
+
+    tmp="$file.cli.tmp"
+    {
+        for ((i = 0; i < n; i++)); do
+            [ "${keep[i]}" -eq 1 ] || continue
+            if [ "$i" -eq $((n - 1)) ] && [ "$IS_GI_FINAL_NEWLINE" -eq 0 ]; then
+                printf '%s' "${IS_GI_LINES[i]}"
+            else
+                printf '%s\n' "${IS_GI_LINES[i]}"
+            fi
+        done
+    } > "$tmp"
+    mv -- "$tmp" "$file"
+}
+
 # Git cannot re-include a child of an excluded directory, so an include needs an
 # explicit negation for every parent. A negation only wins when it comes after
 # the rule excluding the parent, and the only repair an append can make is to
@@ -233,18 +320,25 @@ ensure_base_gitignore() {
 
 ensure_target_gitignore() {
     local root="$1" manifest="$2" target="$3" content_dir output kind value records
+    local -a unignored=()
     ensure_gitignore_header "$root"
     content_dir="$(manifest_intelligence_dir "$manifest")"
     output="$(get_target_output "$manifest" "$target")"
     [ -n "$output" ] || output="$(default_target_output "$target")"
-    records="$(adapter_records_for "$root" "$content_dir" "$target" "$output")" \
+    records="$(adapter_records_for "$root" "$content_dir" "$target" "$output" "$manifest")" \
         || die "adapter '$target' has an invalid ownership contract"
     while IFS=$'\t' read -r kind value; do
         case "$kind" in
-            ignore)  gitignore_add_line "$root" "$value" ;;
-            include) gitignore_add_effective_include "$root" "$value" ;;
+            ignore)   gitignore_add_line "$root" "$value" ;;
+            include)  gitignore_add_effective_include "$root" "$value" ;;
+            unignore) unignored+=("$value") ;;
         esac
     done <<< "$records"
+    # One rewrite for all of them; Bash 3.2 cannot expand an empty array under
+    # `set -u`, hence the count guard.
+    if [ "${#unignored[@]}" -gt 0 ]; then
+        gitignore_remove_managed_lines "$root" "${unignored[@]}"
+    fi
 }
 
 ensure_manifest_gitignore() {
@@ -331,7 +425,7 @@ managed_gitignore_patterns() {
         [ "$(is_target_enabled "$manifest" "$target")" = "1" ] || continue
         output="$(get_target_output "$manifest" "$target")"
         [ -n "$output" ] || output="$(default_target_output "$target")"
-        records="$(adapter_records_for "$root" "$content_dir" "$target" "$output")" \
+        records="$(adapter_records_for "$root" "$content_dir" "$target" "$output" "$manifest")" \
             || return 1
         while IFS=$'\t' read -r kind value; do
             case "$kind" in

package/cli/lib/lockfile.sh

@@ -13,6 +13,12 @@ LOCK_SEP=$'\x1f'
 # lock_validate <lock> [--metadata|--restore] [manifest] — read-only preflight. A subshell
 # contains the fail-fast input guards so status can report a failed verdict too.
 lock_validate() (
+    lock_validate_checks "$@"
+)
+
+# lock_validate_checks — lock_validate without its subshell, for a caller that
+# already runs it in one (a capturing `$(...)`): the guards exit through `die`.
+lock_validate_checks() {
     local lock="$1" mode="${2---metadata}" manifest="${3:-}" count=0
     local kind name requested url path resolved sha line rows current
     local -x CLI_INPUT_CONTEXT=""
@@ -23,7 +29,8 @@ lock_validate() (
     esac
     # The same tokenizer supplies ordinary lock rows and strict metadata. Buffer
     # before consumption: a failed parser must never yield a partial package set.
-    rows="$(_qmap_read lock "$lock" packages '' '' "$LOCKFILE_VERSION")" || return $?
+    _qmap_read_var lock "$lock" packages '' '' "$LOCKFILE_VERSION" || return $?
+    rows="$IS_QMAP_OUT"
     bundled_engine_version_var
     current="$IS_BUNDLED_ENGINE_VERSION"
     while IFS="$LOCK_SEP" read -r kind name requested url path resolved sha line; do
@@ -66,10 +73,12 @@ lock_validate() (
         [[ "$sha" =~ ^[0-9a-f]{40}$ || "$sha" =~ ^[0-9a-f]{64}$ ]] \
             || die "locked restore: $name has a missing or invalid commit SHA — restore a valid intelligence.lock"
     done <<< "$rows"
-    if [ "$count" -eq 0 ] && [ -n "$manifest" ] && [ -n "$(qmap_keys "$manifest" packages)" ]; then
-        die "$lock: packages is empty but the manifest declares packages — restore their recorded identities"
+    if [ "$count" -eq 0 ] && [ -n "$manifest" ]; then
+        _qmap_read_var keys "$manifest" packages
+        [ -z "$IS_QMAP_OUT" ] \
+            || die "$lock: packages is empty but the manifest declares packages — restore their recorded identities"
     fi
-)
+}
 
 # top_scalar <file> <key> — one top-level scalar through the shared tokenizer.
 top_scalar() {
@@ -86,6 +95,7 @@ lock_to_tsv() {
 lock_write_from_tsv() {
     local lock="$1" tsv="$2"
     local tmp="$lock.cli.tmp"
+    qmap_memo_reset
     {
         echo "# Generated by the intelligence CLI. Do not edit."
         echo "lockfile_version: $LOCKFILE_VERSION"

package/cli/lib/manifest.sh

@@ -2,9 +2,10 @@
 # The CLI-owned YAML shapes: quoted-key maps (`packages:`, `registries:` in
 # the manifest, `packages:` in the lock and in registry indexes).
 #
-# The engine deliberately never reads these blocks, and its readers cannot
-# hold `@scope/name` keys — so this is the CLI's single, deliberate parser,
-# scoped to exactly one shape:
+# The engine reads none of these blocks beyond the names and aliases in
+# `packages:`, which resolve package references in `sources:`
+# (engine/lib/common.sh), and its list readers cannot hold `@scope/name` keys —
+# so this is the CLI's single, deliberate parser, scoped to exactly one shape:
 #
 #   block:
 #     "@scope/name":            # 2-space indent, key always quoted
@@ -155,10 +156,20 @@ target_set_enabled() {
     '
 }
 
+_QMAP_AWK="${BASH_SOURCE[0]%/*}/qmap.awk"
+
 # _qmap_read <mode> <file> <block> [key] [field] [expected-lock-version]
 # All scalar reads and strict lock records share one tokenizer. Environment
 # transport preserves literal backslashes that awk -v would interpret again.
 _qmap_read() {
+    if _qmap_memo_find "$@"; then
+        _qmap_memo_replay
+        return
+    fi
+    _qmap_read_file "$@"
+}
+
+_qmap_read_file() {
     local mode="$1" file="$2"
     if [ ! -f "$file" ] || [ ! -r "$file" ]; then
         case "$mode" in
@@ -168,7 +179,140 @@ _qmap_read() {
     fi
     QMAP_MODE="$mode" QMAP_FILE="$file" QMAP_BLOCK="${3:-}" \
         QMAP_KEY="${4:-}" QMAP_FIELD="${5:-}" QMAP_EXPECTED_VERSION="${6:-}" \
-        LC_ALL=C awk -f "${BASH_SOURCE[0]%/*}/qmap.awk" < "$file"
+        LC_ALL=C awk -f "$_QMAP_AWK" < "$file"
+}
+
+# _qmap_read_var <mode> <file> <block> [key] [field] [expected-lock-version]
+# — _qmap_read into IS_QMAP_OUT, as `$(_qmap_read ...)` would capture it, and
+# with its status. A preloaded answer costs no process: on Git Bash every
+# `$(...)` forks, which is what made a lifecycle preflight take half a second.
+# shellcheck disable=SC2034  # IS_QMAP_OUT is the return channel
+_qmap_read_var() {
+    if _qmap_memo_find "$@"; then
+        IS_QMAP_OUT="${QMAP_MEMO_OUTS[$IS_QMAP_MEMO_AT]}"
+        while [[ "$IS_QMAP_OUT" == *$'\n' ]]; do IS_QMAP_OUT="${IS_QMAP_OUT%$'\n'}"; done
+        if [ "${QMAP_MEMO_RCS[$IS_QMAP_MEMO_AT]}" -ne 0 ]; then
+            printf '%s' "${QMAP_MEMO_OUTS[$IS_QMAP_MEMO_AT]}" >&2
+            IS_QMAP_OUT=""
+        fi
+        return "${QMAP_MEMO_RCS[$IS_QMAP_MEMO_AT]}"
+    fi
+    IS_QMAP_OUT="$(_qmap_read_file "$@")"
+}
+
+# --- Reads answered once per process ------------------------------------
+# qmap_preload runs one awk over several requests and remembers each answer —
+# output or strict error, and status — under the exact request it answers.
+# Only a command that holds the project lock may preload, and anything that
+# writes a qmap document forgets every answer (qmap_memo_reset): a remembered
+# read must never outlive the bytes it was read from.
+QMAP_MEMO_KEYS=()
+QMAP_MEMO_RCS=()
+QMAP_MEMO_OUTS=()
+
+qmap_memo_reset() {
+    QMAP_MEMO_KEYS=()
+    QMAP_MEMO_RCS=()
+    QMAP_MEMO_OUTS=()
+    if declare -F manifest_view_reset >/dev/null; then manifest_view_reset; fi
+}
+
+# _qmap_memo_find <request...> — set IS_QMAP_MEMO_AT to the remembered answer.
+_qmap_memo_find() {
+    local request="${1:-}"$'\037'"${2:-}"$'\037'"${3:-}"$'\037'"${4:-}"$'\037'"${5:-}"$'\037'"${6:-}" i=0
+    while [ "$i" -lt "${#QMAP_MEMO_KEYS[@]}" ]; do
+        if [ "${QMAP_MEMO_KEYS[$i]}" = "$request" ]; then
+            IS_QMAP_MEMO_AT="$i"
+            return 0
+        fi
+        i=$((i + 1))
+    done
+    return 1
+}
+
+# Print a remembered answer exactly as the awk reader printed it.
+_qmap_memo_replay() {
+    if [ "${QMAP_MEMO_RCS[$IS_QMAP_MEMO_AT]}" -ne 0 ]; then
+        printf '%s' "${QMAP_MEMO_OUTS[$IS_QMAP_MEMO_AT]}" >&2
+        return "${QMAP_MEMO_RCS[$IS_QMAP_MEMO_AT]}"
+    fi
+    printf '%s' "${QMAP_MEMO_OUTS[$IS_QMAP_MEMO_AT]}"
+}
+
+# qmap_preload <request>... — each request is one string of _qmap_read's six
+# arguments, unit-separated. Requests for absent or empty documents are left
+# to the ordinary reader, which reports them exactly as before. A preload that
+# cannot run leaves nothing remembered; reads then take the ordinary path.
+# A caller that wants the awk pass to overlap other work uses the three steps
+# itself: qmap_preload_plan, qmap_preload_run (prints), qmap_preload_store.
+qmap_preload() {
+    local out
+    qmap_preload_plan "$@" || return 0
+    out="$(qmap_preload_run)" || return 0
+    qmap_preload_store "$out"
+}
+
+# qmap_preload_plan <request>... — QMAP_PLAN_REQUESTS, _FILES and _JOBS for the
+# requests one awk pass can answer; returns 1 when there are none.
+qmap_preload_plan() {
+    local request saved_ifs="$IFS"
+    local -a fields=()
+    QMAP_PLAN_REQUESTS=() QMAP_PLAN_FILES=() QMAP_PLAN_JOBS=""
+    for request in "$@"; do
+        IFS=$'\037'
+        set -f
+        # shellcheck disable=SC2206  # splitting on the unit separator is the point
+        fields=($request)
+        set +f
+        IFS="$saved_ifs"
+        case "${fields[1]:-}" in /*) ;; *) continue ;; esac
+        [ -f "${fields[1]}" ] && [ -r "${fields[1]}" ] && [ -s "${fields[1]}" ] || continue
+        QMAP_PLAN_FILES+=("${fields[1]}")
+        QMAP_PLAN_REQUESTS+=("$request")
+        QMAP_PLAN_JOBS="$QMAP_PLAN_JOBS${fields[0]:-}"$'\037'"${fields[2]:-}"$'\037'"${fields[3]:-}"$'\037'"${fields[4]:-}"$'\037'"${fields[5]:-}"$'\n'
+    done
+    [ "${#QMAP_PLAN_FILES[@]}" -gt 0 ]
+}
+
+# qmap_preload_run — the planned pass; a trailing `end` proves it completed.
+qmap_preload_run() {
+    QMAP_JOBS="${QMAP_PLAN_JOBS%$'\n'}" LC_ALL=C awk -f "$_QMAP_AWK" "${QMAP_PLAN_FILES[@]}" && echo end
+}
+
+# qmap_preload_store <output> — remember every planned answer, or nothing when
+# the output is not exactly one complete answer per request.
+qmap_preload_store() {
+    local header line status count raw i=0 saved_ifs="$IFS"
+    local -a lines=() rcs=() outs=()
+    IFS=$'\n'
+    set -f
+    # shellcheck disable=SC2206  # no line is empty: rows carry a ">" prefix
+    lines=($1)
+    set +f
+    IFS="$saved_ifs"
+    while [ "$i" -lt "${#lines[@]}" ]; do
+        header="${lines[i]}"
+        i=$((i + 1))
+        if [ "$header" = end ]; then
+            [ "$i" -eq "${#lines[@]}" ] && [ "${#rcs[@]}" -eq "${#QMAP_PLAN_REQUESTS[@]}" ] || return 0
+            QMAP_MEMO_KEYS+=("${QMAP_PLAN_REQUESTS[@]}")
+            QMAP_MEMO_RCS+=("${rcs[@]}")
+            QMAP_MEMO_OUTS+=("${outs[@]}")
+            return 0
+        fi
+        case "$header" in $'\036'[01]' '[0-9]*) ;; *) return 0 ;; esac
+        status="${header:1:1}" count="${header#* }"
+        raw=""
+        while [ "$count" -gt 0 ]; do
+            line="${lines[i]-}"
+            case "$line" in '>'*) ;; *) return 0 ;; esac
+            raw="$raw${line#>}"$'\n'
+            i=$((i + 1))
+            count=$((count - 1))
+        done
+        rcs+=("$status")
+        outs+=("$raw")
+    done
 }
 
 # qmap_validate_document <file> <block> — structural validation only.
@@ -190,6 +334,7 @@ qmap_value() { _qmap_read value "$1" "$2" "$3"; }
 _qmap_stage() {
     local file="$1"; shift
     local tmp="$file.cli.tmp" rc=0
+    qmap_memo_reset
     awk "$@" "$file" > "$tmp" || rc=$?
     [ "$rc" -eq 0 ] || { rm -f "$tmp"; die "internal: manifest edit refused (awk exit $rc) for $file"; }
     [ -s "$tmp" ] || { rm -f "$tmp"; die "internal: manifest edit produced an empty file for $file"; }
@@ -407,12 +552,14 @@ registries_remove() {
 # meaning: a later entry overrides a same-named artifact from an earlier one.
 # Reading goes through the engine's own list parser, so the CLI sees exactly
 # what the engine will render instead of a second reading of the same file.
+# The editors read it raw — a package reference as written, which is what they
+# compare and rewrite — and read_source_entries says what each one renders.
 
-# sources_list_entries <file> <section> — entries of sources.<section>, one per
-# line, in manifest order.
+# sources_list_entries <file> <section> — entries of sources.<section> as
+# written, one per line, in manifest order.
 sources_list_entries() {
     [ -f "$1" ] || return 0
-    read_yaml_list "$1" "$2"
+    read_yaml_list_raw "$1" "$2"
 }
 
 # sources_has_entry <file> <section> <entry> — true (0) when that section lists
@@ -439,7 +586,7 @@ sources_has_entry() {
 sources_add_entry() {
     local file="$1" section="$2" entry="$3" pos="${4:-last}" anchor="${5:-}"
     sources_has_entry "$file" "$section" "$entry" && return 0
-    _qmap_stage "$file" -v section="$section" -v entry="$entry" -v pos="$pos" -v anchor="$anchor" '
+    _qmap_stage "$file" -v section="$section" -v entry="$entry" -v pos="$pos" -v anchor="$anchor" "$IS_YAML_ITEM_AWK"'
         function line() { return "    - \"" entry "\"" }
         function place() { print line(); done = 1 }
         # Blank lines inside sources: are held back so an insert lands next to
@@ -447,13 +594,11 @@ sources_add_entry() {
         # one section from the next.
         function flush_tail(   i) { for (i = 1; i <= ntail; i++) print tail[i]; blanks = ntail; ntail = 0 }
         function open_section() { flush_tail(); print "  " section ":"; place(); if (blanks) print "" }
+        # The entry as the engine reads it (yaml_item, engine/lib/common.sh).
         function value(s,   v) {
             v = s
-            sub(/^[ \t]*-[ \t]*/, "", v)
-            gsub(/["\x27]/, "", v)
-            sub(/[ \t]+#.*$/, "", v)
-            sub(/[ \t]+$/, "", v)
-            return v
+            sub(/^[ \t]*-/, "", v)
+            return yaml_item(v)
         }
         BEGIN { anchored = (pos == "before" || pos == "after") }
         { sub(/\r$/, "") }
@@ -509,24 +654,173 @@ sources_add_entry_first() {
 }
 
 # sources_remove_entry <file> <section> <entry> — remove `- "entry"` from
-# sources.<section>.
+# sources.<section>, matching each item as the engine reads it (yaml_item).
 sources_remove_entry() {
     local file="$1" section="$2" entry="$3"
     [ -f "$file" ] || return 0
-    _qmap_stage "$file" -v section="$section" -v entry="$entry" '
+    _qmap_stage "$file" -v section="$section" -v entry="$entry" "$IS_YAML_ITEM_AWK"'
         { sub(/\r$/, "") }
         /^sources:[ \t]*$/ { ins = 1; print; next }
         ins && /^[^ #]/ { ins = 0; insec = 0 }
         ins && $0 ~ "^  " section ":[ \t]*$" { insec = 1; print; next }
         ins && /^  [A-Za-z_]/ { insec = 0 }
-        insec {
+        insec && /^[ \t]*-/ {
             line = $0
-            sub(/^[ \t]*-[ \t]*/, "", line)
-            gsub(/["\x27]/, "", line)
-            sub(/[ \t]+#.*$/, "", line)
-            sub(/[ \t]+$/, "", line)
-            if (line == entry) next
+            sub(/^[ \t]*-/, "", line)
+            if (yaml_item(line) == entry) next
         }
         { print }
     '
 }
+
+# --- package references and aliases ------------------------------------------
+# `sources:` may name a package's directory by its store path, by the package's
+# full name or by the alias its `packages:` entry declares (decision 0019). The
+# engine's list parser (IS_PKG_REF_AWK in engine/lib/common.sh) is the only
+# definition of those spellings; everything below reads through it, so the CLI
+# never judges an entry differently from the way the engine renders it. The CLI
+# itself only ever writes store paths, and writes an alias only through
+# `package add --alias` and `package alias`.
+
+# assert_valid_alias <alias> — refuse an alias the engine would never resolve.
+assert_valid_alias() {
+    pkg_alias_valid "$1" \
+        || die "invalid alias '$1' — expected $IS_PKG_ALIAS_RULE"
+}
+
+# package_alias_of <file> <@scope/name> — the alias that package declares, when it
+# is well formed; nothing otherwise (an invalid one resolves nothing).
+package_alias_of() {
+    local name alias verdict
+    while IFS=$'\037' read -r name alias verdict; do
+        [ "$name" = "$2" ] || continue
+        [ "$verdict" = invalid ] || printf '%s' "$alias"
+        return 0
+    done < <(read_package_aliases "$1")
+}
+
+# assert_alias_free <file> <@scope/name> <alias> — refuse an alias another package
+# already declares: one alias names exactly one package.
+assert_alias_free() {
+    local file="$1" self="$2" want="$3" name alias verdict
+    while IFS=$'\037' read -r name alias verdict; do
+        [ "$name" != "$self" ] && [ "$alias" = "$want" ] || continue
+        die "alias '$want' already names $name — one alias names one package; choose another"
+    done < <(read_package_aliases "$file")
+}
+
+# sources_alias_users <file> <alias> — every sources entry spelled <alias>:<dir>,
+# one `sources.<section> '<entry>'` line each.
+sources_alias_users() {
+    local file="$1" alias="$2" section entry
+    for section in rules agents skills; do
+        while IFS= read -r entry; do
+            case "$entry" in
+                "$alias":*) printf "sources.%s '%s'\n" "$section" "$entry" ;;
+            esac
+        done < <(sources_list_entries "$file" "$section")
+    done
+}
+
+# assert_alias_unused <file> <@scope/name> <alias> <remove|replace> — refuse to
+# take away an alias `sources:` still spells entries with: they would stop
+# resolving, and the package's content would leave the outputs in silence.
+assert_alias_unused() {
+    local file="$1" name="$2" alias="$3" verb="$4" users
+    users="$(sources_alias_users "$file" "$alias")"
+    [ -n "$users" ] || return 0
+    echo "ERROR: cannot $verb alias '$alias' of $name — sources: still uses it:" >&2
+    printf '%s\n' "$users" | sed 's/^/  /' >&2
+    echo "  Spell those entries $name/<dir> instead, then $verb the alias." >&2
+    exit 1
+}
+
+# sources_classify_entry <file> <entry> — `<state>\037<directory>` for an entry
+# that is not in the manifest (yet): what the engine would render it as against
+# the packages the manifest declares. States are pkr_parse's.
+sources_classify_entry() {
+    local file="$1"
+    [ -f "$file" ] || file=/dev/null
+    IS_PKR_CANDIDATE="$2" awk "$IS_PKG_REF_AWK"'
+        { sub(/\r$/, ""); pkr_collect($0) }
+        END { dir = pkr_expand(ENVIRON["IS_PKR_CANDIDATE"]); print PKR_STATE "\037" dir }
+    ' "$file"
+}
+
+# sources_find_entry <file> <section> <entry> — print the entry of
+# sources.<section>, as written, that names the same directory as <entry> in any
+# spelling; fail when the section names it nowhere. An entry that renders
+# nothing matches only itself.
+sources_find_entry() {
+    local file="$1" section="$2" entry="$3" want _state raw _st dir _rest
+    [ -f "$file" ] || return 1
+    IFS=$'\037' read -r _state want <<< "$(sources_classify_entry "$file" "$entry")"
+    while IFS=$'\037' read -r raw _st dir _rest; do
+        if [ "$raw" = "$entry" ] || { [ -n "$want" ] && [ "$dir" = "$want" ]; }; then
+            printf '%s' "$raw"
+            return 0
+        fi
+    done < <(read_source_entries "$file" "$section")
+    return 1
+}
+
+# package_source_listed <file> <section> <store-dir> — true when sources.<section>
+# already names <store-dir>, in whichever spelling.
+package_source_listed() {
+    local _raw _st dir _rest
+    [ -f "$1" ] || return 1
+    while IFS=$'\037' read -r _raw _st dir _rest; do
+        [ "$dir" = "$3" ] && return 0
+    done < <(read_source_entries "$1" "$2")
+    return 1
+}
+
+# sources_remove_package <file> <@scope/name> [section...] — drop the package's
+# entries from sources:, in every spelling. With sections, only the entry of
+# sources.<section> that names the package's own <section> directory goes;
+# without, every rules/agents/skills entry naming a directory inside the
+# package. The references resolve through `packages:`, so call it while the
+# package and its alias are still declared. Every other line survives byte for
+# byte, and an unchanged file is not rewritten.
+sources_remove_package() {
+    local file="$1" name="$2" tmp rc=0
+    shift 2
+    [ -f "$file" ] || return 0
+    tmp="$file.cli.tmp"
+    # A write to a qmap document forgets every remembered read, as _qmap_stage does.
+    qmap_memo_reset
+    awk -v name="$name" -v only=" $* " "$IS_PKG_REF_AWK$IS_YAML_ITEM_AWK"'
+        BEGIN { store = ".intelligence/packages/" name }
+        FNR == 1 { pass++ }
+        pass == 1 { sub(/\r$/, ""); pkr_collect($0); next }
+        { sub(/\r$/, "") }
+        /^sources:[ \t]*$/ { ins = 1; print; next }
+        ins && /^[^ #]/ { ins = 0; sec = "" }
+        ins && /^  [A-Za-z_]/ {
+            sec = $0
+            sub(/^  /, "", sec)
+            sub(/:.*$/, "", sec)
+            if (sec != "rules" && sec != "agents" && sec != "skills") sec = ""
+            print
+            next
+        }
+        ins && sec != "" && /^[ \t]*-/ {
+            v = $0
+            sub(/^[ \t]*-/, "", v)
+            dir = pkr_expand(yaml_item(v))
+            if (only == "  ") drop = dir == store || index(dir, store "/") == 1
+            else drop = index(only, " " sec " ") && dir == store "/" sec
+            if (drop) { changed = 1; next }
+        }
+        { print }
+        END { exit (changed ? 0 : 10) }
+    ' "$file" "$file" > "$tmp" || rc=$?
+    case "$rc" in
+        0)
+            [ -s "$tmp" ] || { rm -f "$tmp"; die "internal: sources edit produced an empty file for $file"; }
+            mv "$tmp" "$file"
+            ;;
+        10) rm -f "$tmp" ;;
+        *) rm -f "$tmp"; die "internal: sources edit refused (awk exit $rc) for $file" ;;
+    esac
+}