@ainova-systems/intelligence 0.15.0 → 0.16.1

package/cli/commands/source.sh

@@ -0,0 +1,177 @@
+#!/bin/bash
+# intelligence source <add|remove|list> — the `sources:` block of the manifest.
+#
+# Sources are an ORDERED list of directories the engine renders, and the order
+# is the override rule: adapters copy in order, the last write wins. So the
+# command's real job is placement, and its default is the end of the section —
+# the project's own territory, where a directory the project added wins over
+# every installed package. `--before` / `--after` cover the other intent:
+# content that should behave like a package (a pack developed in the repository
+# that ships it) belongs after the store entries and before the project's.
+#
+# Installed package content is NOT managed here: `.intelligence/` entries are
+# written by `package add` and removed by `package remove`, and a hand-placed
+# entry under the store does not survive the next lifecycle alignment.
+set -euo pipefail
+source "$CLI_DIR/lib/cli-common.sh"
+
+USAGE="usage: intelligence source <command>
+  add <rules|agents|skills> <dir> [--first|--last|--before <entry>|--after <entry>]
+  remove <rules|agents|skills> <dir>
+  list"
+
+SECTIONS="rules agents skills"
+
+assert_source_section() {
+    case "${1:-}" in
+        rules|agents|skills) ;;
+        "") die "$USAGE" ;;
+        *) die "unknown source kind '$1' — expected rules, agents or skills" ;;
+    esac
+}
+
+# `normalize_source_dir` reduces `./x/`, `x/.` and `x/./y` to the one spelling
+# the manifest stores; it lives beside the classifier in cli-common so a typed
+# path and a manifest entry are judged as the same thing. Nothing else is
+# repaired — a source entry decides which artifact wins, so a path the user did
+# not type is the wrong kind of help.
+
+# assert_valid_source_dir <root> <dir> — refuse what the engine cannot report.
+# The shape checks are `source_entry_problem`, shared with `status --check` so
+# one definition covers both the entry about to be written and the one already
+# in the manifest; the store rule is this command's alone, because a
+# `.intelligence/` entry is legitimate when `package add` wrote it.
+assert_valid_source_dir() {
+    local root="$1" dir="$2" problem
+    [ -n "$dir" ] || die "$USAGE"
+    case "$dir" in
+        *\\*) die "invalid source '$dir' — manifest paths use '/': ${dir//\\//}" ;;
+        .intelligence|.intelligence/*)
+            die "'$dir' is inside the CLI-managed package store — install content with 'intelligence package add', and it is wired into sources automatically"
+            ;;
+    esac
+    problem="$(source_entry_problem "$root" "$dir")"
+    [ -z "$problem" ] || die "invalid source '$dir': it $problem"
+}
+
+# Print one section with its override direction and the state of each entry.
+# Position is the whole point of the block, so every mutation ends by showing
+# the order it produced rather than only naming what it wrote.
+print_section() {
+    local manifest="$1" root="$2" section="$3" entry n=0 note
+    echo "sources.$section (a later entry overrides an earlier one):"
+    while IFS= read -r entry; do
+        [ -n "$entry" ] || continue
+        n=$((n + 1))
+        note=""
+        case "$entry" in
+            .intelligence/*) note="  package" ;;
+        esac
+        [ -d "$root/$entry" ] || note="$note  MISSING"
+        printf '  %d. %s%s\n' "$n" "$entry" "$note"
+    done < <(sources_list_entries "$manifest" "$section")
+    [ "$n" -eq 0 ] && echo "  (none)"
+    return 0
+}
+
+action="${1:-}"
+[ -n "$action" ] || die "$USAGE"
+shift
+
+case "$action" in
+    add)
+        section="${1:-}"
+        dir="${2:-}"
+        assert_source_section "$section"
+        [ -n "$dir" ] || die "$USAGE"
+        shift 2
+        pos="last"
+        anchor=""
+        pos_given=0
+        while [ $# -gt 0 ]; do
+            case "$1" in
+                --first|--last)
+                    [ "$pos_given" -eq 0 ] || die "only one position may be given"
+                    pos="${1#--}"; pos_given=1; shift
+                    ;;
+                --before|--after)
+                    [ "$pos_given" -eq 0 ] || die "only one position may be given"
+                    [ -n "${2:-}" ] || die "$1 needs the entry to place this source next to"
+                    pos="${1#--}"; anchor="$(normalize_source_dir "$2")"; pos_given=1; shift 2
+                    ;;
+                *) die "$USAGE" ;;
+            esac
+        done
+
+        require_cli_project
+        dir="$(normalize_source_dir "$dir")"
+        assert_valid_source_dir "$IP_ROOT" "$dir"
+        [ "$anchor" != "$dir" ] || die "cannot place '$dir' relative to itself"
+        ensure_project_current "$IP_ROOT"
+        manifest="$IP_ROOT/intelligence.yaml"
+
+        if [ -n "$anchor" ] && ! sources_has_entry "$manifest" "$section" "$anchor"; then
+            echo "ERROR: sources.$section does not list '$anchor'." >&2
+            print_section "$manifest" "$IP_ROOT" "$section" >&2
+            exit 1
+        fi
+
+        if sources_has_entry "$manifest" "$section" "$dir"; then
+            if [ "$pos_given" -eq 0 ]; then
+                echo "already listed: sources.$section holds $dir"
+                print_section "$manifest" "$IP_ROOT" "$section"
+                exit 0
+            fi
+            sources_remove_entry "$manifest" "$section" "$dir"
+            sources_add_entry "$manifest" "$section" "$dir" "$pos" "$anchor"
+            echo "moved: $dir"
+        else
+            sources_add_entry "$manifest" "$section" "$dir" "$pos" "$anchor"
+            echo "added: $dir"
+        fi
+        if [ ! -d "$IP_ROOT/$dir" ]; then
+            echo "  WARN: $dir does not exist yet — sync skips a missing source and renders it once the directory appears." >&2
+        fi
+        print_section "$manifest" "$IP_ROOT" "$section"
+        echo "Run 'intelligence sync' to render it."
+        ;;
+    remove)
+        section="${1:-}"
+        dir="${2:-}"
+        assert_source_section "$section"
+        [ -n "$dir" ] || die "$USAGE"
+        [ $# -le 2 ] || die "$USAGE"
+        dir="$(normalize_source_dir "$dir")"
+        case "$dir" in
+            .intelligence|.intelligence/*)
+                die "'$dir' is installed package content — remove the package instead: intelligence package remove <@scope/name>"
+                ;;
+        esac
+
+        require_cli_project
+        ensure_project_current "$IP_ROOT"
+        manifest="$IP_ROOT/intelligence.yaml"
+
+        if ! sources_has_entry "$manifest" "$section" "$dir"; then
+            echo "not listed: sources.$section does not hold $dir"
+            print_section "$manifest" "$IP_ROOT" "$section"
+            exit 0
+        fi
+        sources_remove_entry "$manifest" "$section" "$dir"
+        echo "removed: $dir"
+        echo "  The directory is untouched; its artifacts leave the generated output at the next sync."
+        print_section "$manifest" "$IP_ROOT" "$section"
+        echo "Run 'intelligence sync' to rewrite the outputs."
+        ;;
+    list)
+        [ $# -eq 0 ] || die "$USAGE"
+        require_cli_project
+        manifest="$IP_ROOT/intelligence.yaml"
+        for section in $SECTIONS; do
+            print_section "$manifest" "$IP_ROOT" "$section"
+        done
+        ;;
+    *)
+        die "$USAGE"
+        ;;
+esac

package/cli/intelligence

@@ -55,6 +55,7 @@ Usage: intelligence <command> [args]
   upgrade [--next] [--preview|--apply]  Replace the installed CLI with the newest npm version
     --next                Follow the prerelease line instead of the stable one
   package <command>       add | remove | list | search
+  source <command>        add | remove | list — the sources: block (own directories)
   adapter <command>       list | create | enable | disable | remove
   status [--check]        Project state; --check runs deep consistency checks
   registry <list|add|remove>  Manage the trusted registry list (add <repo-url>)
@@ -89,6 +90,10 @@ if [ ! -f "$cmd_file" ]; then
             echo "ERROR: unknown command 'packages'. Use the singular command: intelligence package list" >&2
             exit 1
             ;;
+        sources)
+            echo "ERROR: unknown command 'sources'. Use the singular command: intelligence source list" >&2
+            exit 1
+            ;;
         registries)
             echo "ERROR: unknown command 'registries'. Use the singular command: intelligence registry list" >&2
             exit 1

package/cli/internal/check.sh

@@ -175,6 +175,13 @@ for section in rules agents skills; do
         case "$src" in
             git+*|@*) continue ;;
         esac
+        # A hand-edited entry the engine cannot render is worse than a missing
+        # one: it is skipped without a word and the sync still reports ok.
+        problem="$(source_entry_problem "$IP_ROOT" "$src")"
+        if [ -n "$problem" ]; then
+            warn "sources.$section '$src' $problem"
+            continue
+        fi
         if [ ! -d "$IP_ROOT/$src" ]; then
             case "$src" in
                 # Store content is restorable state: absent means un-installed.

package/cli/lib/cli-common.sh

@@ -156,6 +156,91 @@ require_cli_project() {
 
 # --- Manifest basics (engine-readable shapes) ----------------------------
 
+# normalize_source_dir_var <dir> — set IS_SOURCE_DIR to the spelling the
+# manifest stores: `.` and empty segments dropped, no trailing slash. A path
+# that reduces to nothing named the repository root, which is spelled `.` — so
+# the caller judges one shape instead of several.
+#
+# Rebuilt segment by segment rather than with `${dir//\/.\//\/}`: bash 3.2, which
+# is what macOS ships and CI runs, keeps the backslash of an escaped separator in
+# the REPLACEMENT and produced `intelligence\/rules`, while bash 5 consumed it.
+# shellcheck disable=SC2034
+normalize_source_dir_var() {
+    local dir="$1" out="" seg rest lead=""
+    # A leading slash is meaning, not an empty segment: dropping it would turn
+    # an absolute path into a relative one and hide it from the classifier.
+    case "$dir" in /*) lead="/" ;; esac
+    rest="$dir"
+    while [ -n "$rest" ]; do
+        seg="${rest%%/*}"
+        if [ "$seg" = "$rest" ]; then rest=""; else rest="${rest#*/}"; fi
+        case "$seg" in ""|".") continue ;; esac
+        out="${out:+$out/}$seg"
+    done
+    if [ -n "$lead" ]; then
+        IS_SOURCE_DIR="$lead$out"
+    else
+        IS_SOURCE_DIR="${out:-.}"
+    fi
+}
+
+normalize_source_dir() {
+    normalize_source_dir_var "$1"
+    printf '%s' "$IS_SOURCE_DIR"
+}
+
+# source_entry_problem <root> <entry> — one line naming why the engine cannot
+# render this `sources:` entry, or nothing when the entry is sound. Most cases
+# here are invisible at sync time: the engine resolves an entry as
+# `$REPO_ROOT/<entry>` and skips whatever is not a directory, so a bad entry is
+# a silent omission from a run that still reports ok. `source add` refuses one
+# before it is written; `status --check` reports one already in the manifest.
+source_entry_problem() {
+    local root="$1" entry="$2" seg rest norm
+    case "$entry" in
+        "") printf 'is empty'; return 0 ;;
+        *\\*) printf 'uses backslashes — manifest paths use "/"'; return 0 ;;
+        /*|[A-Za-z]:/*)
+            printf 'is an absolute path — the engine resolves every entry as $REPO_ROOT/<entry>, so it renders nothing'
+            return 0
+            ;;
+    esac
+    # The root is the loud failure rather than the silent one: it IS a
+    # directory, so the engine reads every top-level *.md in it — README,
+    # CHANGELOG, docs — as an artifact of this section.
+    normalize_source_dir_var "$entry"
+    norm="$IS_SOURCE_DIR"
+    if [ "$norm" = "." ]; then
+        printf 'is the repository root — every top-level *.md there would be read as an artifact of this section'
+        return 0
+    fi
+    rest="$norm"
+    while [ -n "$rest" ]; do
+        seg="${rest%%/*}"
+        if [ "$seg" = ".." ]; then
+            printf 'leaves the repository — its artifacts render, but with bare names instead of links in AGENTS.md'
+            return 0
+        fi
+        [ "$seg" = "$rest" ] && break
+        rest="${rest#*/}"
+    done
+    # The entry is stored as a double-quoted YAML scalar and read back by a
+    # parser that strips quotes and a trailing ` # comment`.
+    case "$entry" in
+        *[\"\'\#\$\`]*|*:*)
+            printf 'holds a character the manifest cannot carry verbatim — allowed: letters, digits, . _ - / @'
+            return 0
+            ;;
+    esac
+    # A symlink leaves the repository without a '..' anywhere in the path.
+    # repo_rel_dir compares by device+inode, so it answers for the real target.
+    if [ -d "$root/$entry" ] && [ -z "$(repo_rel_dir "$root" "$root/$entry")" ]; then
+        printf 'resolves outside the repository root'
+        return 0
+    fi
+    return 0
+}
+
 manifest_intelligence_dir() {
     local manifest="$1" v
     v="$(get_yaml_field "$manifest" "project" "intelligence_dir")"

package/cli/lib/gitignore.sh

@@ -1,12 +1,56 @@
 #!/bin/bash
 # Generated-output policy derived from each adapter's ownership contract.
 
+# The line that separates what this policy manages from what the project wrote
+# before Intelligence touched the file: everything the CLI appends lands after
+# it, so it is also the boundary of what the CLI may rewrite.
+IS_GITIGNORE_HEADER='# Intelligence generated state and tool output'
+
+# Line endings held in variables, never written as `$'\r'` at the point of use:
+# inside a command substitution bash does not expand that form, so the very same
+# expression stops stripping the CR depending on where it is called from.
+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.
+
+# ignore_file_eol_var <file> — set IS_IGNORE_EOL from the file's first line.
+ignore_file_eol_var() {
+    local file="$1" first=""
+    IS_IGNORE_EOL="$IS_LF"
+    [ -s "$file" ] || return 0
+    IFS= read -r first < "$file" || true
+    case "$first" in
+        *"$IS_CR") IS_IGNORE_EOL="$IS_CRLF" ;;
+    esac
+}
+
+# ignore_file_has_line <file> <line> — true when the file lists exactly this
+# line, with or without a trailing CR.
+ignore_file_has_line() {
+    local file="$1" line="$2"
+    [ -f "$file" ] || return 1
+    grep -Fqx -- "$line" "$file" 2>/dev/null && return 0
+    grep -Fqx -- "$line$IS_CR" "$file" 2>/dev/null
+}
+
+# ignore_file_append_line <file> <line> — append in the file's own ending.
+ignore_file_append_line() {
+    local file="$1" line="$2"
+    ignore_file_eol_var "$file"
+    printf '%s%s' "$line" "$IS_IGNORE_EOL" >> "$file"
+}
+
 gitignore_add_line() {
     local root="$1" line="$2" file="$1/.gitignore"
-    if [ -f "$file" ] && grep -Fqx -- "$line" "$file"; then
-        return 0
-    fi
-    printf '%s\n' "$line" >> "$file"
+    ignore_file_has_line "$file" "$line" && return 0
+    ignore_file_append_line "$file" "$line"
 }
 
 gitignore_path_is_ignored() {
@@ -21,10 +65,102 @@ gitignore_tail_is() {
     [ -f "$file" ] || return 1
     local want tail_lines
     want="$(printf '%s\n' "$@")"
-    tail_lines="$(tail -n "$#" -- "$file")"
+    # CR stripped for the comparison only — the chain is the same chain whether
+    # the file is LF or CRLF.
+    tail_lines="$(tail -n "$#" -- "$file" | tr -d '\r')"
     [ "$tail_lines" = "$want" ]
 }
 
+# gitignore_collapse_duplicates <root> <probe-path> <line…> — keep only the LAST
+# occurrence of each given line inside the region this policy owns (its header
+# to end of file).
+#
+# This removes residue, never meaning: Git applies the last matching rule, so
+# identical earlier copies of a line decide nothing. The copies exist because
+# the 0.12.0 repair appended the whole negation chain on every alignment — a
+# project carries one chain per run it made, and 0.12.1 only stopped the growth.
+#
+# Lines above the header predate Intelligence and are left untouched, including
+# a hand-written copy of a line this policy also writes. The probe path is
+# re-checked afterwards: a collapse that somehow changed what Git ignores is
+# rolled back rather than committed.
+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
+    [ -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
+    [ "$hdr" -ge 0 ] || return 0
+
+    # Where each managed line last occurs below the header. Indexed arrays and
+    # arithmetic `for` only — Bash 3.2 has no associative arrays.
+    for ((mi = 0; mi < ${#managed[@]}; mi++)); do
+        last_idx[mi]=-1
+        for ((i = hdr + 1; i < n; i++)); do
+            [ "${lines[i]%"$IS_CR"}" = "${managed[mi]}" ] && last_idx[mi]=$i
+        done
+    done
+
+    tmp="$file.cli.tmp"
+    {
+        for ((i = 0; i < n; i++)); do
+            keep=1
+            if [ "$i" -gt "$hdr" ]; then
+                key="${lines[i]%"$IS_CR"}"
+                for ((mi = 0; mi < ${#managed[@]}; mi++)); do
+                    if [ "$key" = "${managed[mi]}" ] && [ "$i" -ne "${last_idx[mi]}" ]; then
+                        keep=0
+                        break
+                    fi
+                done
+            fi
+            [ "$keep" -eq 1 ] || continue
+            if [ "$i" -eq $((n - 1)) ] && [ "$final_newline" -eq 0 ]; then
+                printf '%s' "${lines[i]}"
+            else
+                printf '%s\n' "${lines[i]}"
+            fi
+        done
+    } > "$tmp"
+    if [ ! -s "$tmp" ] || cmp -s "$tmp" "$file"; then
+        rm -f "$tmp"
+        return 0
+    fi
+
+    before=0
+    gitignore_path_is_ignored "$root" "$probe" || before=$?
+    backup="$file.cli.bak"
+    cp -- "$file" "$backup"
+    mv -- "$tmp" "$file"
+    after=0
+    gitignore_path_is_ignored "$root" "$probe" || after=$?
+    if [ "$after" != "$before" ]; then
+        mv -- "$backup" "$file"
+        return 0
+    fi
+    rm -f "$backup"
+}
+
 # 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
@@ -59,7 +195,7 @@ gitignore_add_effective_include() {
     gitignore_path_is_ignored "$root" "$value" || rc=$?
     case "$rc" in
         0) ;;
-        1|2) return 0 ;;
+        1|2) gitignore_collapse_duplicates "$root" "$value" "${negations[@]}"; return 0 ;;
         *) return "$rc" ;;
     esac
 
@@ -67,17 +203,25 @@ gitignore_add_effective_include() {
     # chain last. Already last means appending cannot help — leave it, and let
     # `status --check` report the re-inclusion this policy could not make
     # effective rather than growing the file forever.
-    gitignore_tail_is "$root/.gitignore" "${negations[@]}" && return 0
-    printf '%s\n' "${negations[@]}" >> "$root/.gitignore"
+    if ! gitignore_tail_is "$root/.gitignore" "${negations[@]}"; then
+        for line in "${negations[@]}"; do
+            ignore_file_append_line "$root/.gitignore" "$line"
+        done
+    fi
+    # Either way the chain now stands last, so any earlier copy of it is the
+    # residue an older CLI appended; collapsing runs on both paths so a project
+    # converges on one copy whether or not this run had to move anything.
+    gitignore_collapse_duplicates "$root" "$value" "${negations[@]}"
 }
 
 ensure_gitignore_header() {
     local root="$1" file="$1/.gitignore"
-    if [ ! -f "$file" ] || ! grep -Fqx '# Intelligence generated state and tool output' "$file"; then
+    if ! ignore_file_has_line "$file" "$IS_GITIGNORE_HEADER"; then
         if [ -f "$file" ] && [ -s "$file" ] && [ -n "$(tail -c 1 "$file" 2>/dev/null)" ]; then
-            printf '\n' >> "$file"
+            ignore_file_eol_var "$file"
+            printf '%s' "$IS_IGNORE_EOL" >> "$file"
         fi
-        printf '%s\n' '# Intelligence generated state and tool output' >> "$file"
+        ignore_file_append_line "$file" "$IS_GITIGNORE_HEADER"
     fi
 }
 
@@ -125,10 +269,8 @@ publisher_ignore_file_names() {
 
 publisher_ignore_add_line() {
     local file="$1" line="$2"
-    if grep -Fqx -- "$line" "$file" 2>/dev/null; then
-        return 0
-    fi
-    printf '%s\n' "$line" >> "$file"
+    ignore_file_has_line "$file" "$line" && return 0
+    ignore_file_append_line "$file" "$line"
     PUBLISH_IGNORE_FILE_CHANGED=1
 }
 
@@ -148,11 +290,12 @@ ensure_manifest_publisher_ignores() {
         file="$root/$rel"
         [ -f "$file" ] || continue
         PUBLISH_IGNORE_FILE_CHANGED=0
-        if ! grep -Fqx '# Intelligence development context and generated output' "$file" 2>/dev/null; then
+        if ! ignore_file_has_line "$file" '# Intelligence development context and generated output'; then
             if [ -s "$file" ] && [ -n "$(tail -c 1 "$file" 2>/dev/null)" ]; then
-                printf '\n' >> "$file"
+                ignore_file_eol_var "$file"
+                printf '%s' "$IS_IGNORE_EOL" >> "$file"
             fi
-            printf '%s\n' '# Intelligence development context and generated output' >> "$file"
+            ignore_file_append_line "$file" '# Intelligence development context and generated output'
             PUBLISH_IGNORE_FILE_CHANGED=1
         fi
         publisher_ignore_add_path "$file" '.intelligence'

package/cli/lib/manifest.sh

@@ -184,11 +184,14 @@ qmap_field() { _qmap_read field "$1" "$2" "$3" "$4"; }
 qmap_value() { _qmap_read value "$1" "$2" "$3"; }
 
 # _qmap_stage <file> <awk-program> [awk args…] — run an editing pass, verify
-# it produced output, commit.
+# it produced output, commit. An editor that cannot place its edit exits
+# non-zero; the staged file is dropped so a refused edit never reaches the
+# manifest half-applied.
 _qmap_stage() {
     local file="$1"; shift
-    local tmp="$file.cli.tmp"
-    awk "$@" "$file" > "$tmp"
+    local tmp="$file.cli.tmp" rc=0
+    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"; }
     mv "$tmp" "$file"
 }
@@ -399,44 +402,112 @@ registries_remove() {
         { print }
     '
 }
-# True (0) if <config> already lists <entry> under any sources section. Quoted
-# and bare spellings both count - a manifest may hold either.
-_mig_has_source() {
-    local config="$1" entry="$2"
-    [ -f "$config" ] || return 1
-    grep -Fq -- "\"$entry\"" "$config" || grep -Fq -- "- $entry" "$config"
+# --- sources: an ORDERED list of content directories ------------------------
+# Adapters copy sources in order and the last write wins, so position carries
+# 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.
+
+# sources_list_entries <file> <section> — entries of sources.<section>, one per
+# line, in manifest order.
+sources_list_entries() {
+    [ -f "$1" ] || return 0
+    read_yaml_list "$1" "$2"
 }
 
+# sources_has_entry <file> <section> <entry> — true (0) when that section lists
+# exactly this entry. Section-scoped and exact on purpose: one directory may
+# legitimately appear under two sections, and a substring test over the whole
+# file would silently refuse the second add — and would match a bare `- docs`
+# against a neighbouring `- docs/api`.
+sources_has_entry() {
+    local file="$1" section="$2" entry="$3" listed
+    [ -f "$file" ] || return 1
+    while IFS= read -r listed; do
+        [ "$listed" = "$entry" ] && return 0
+    done < <(sources_list_entries "$file" "$section")
+    return 1
+}
 
-# sources_add_entry_first <file> <section> <entry> — idempotent insert at the
-# TOP of sources.<section> (creating sources:/section as needed). Package
-# entries go through this so project-owned entries stay later in the list —
-# adapters copy sources in order and the last write wins, which is exactly
-# the documented "your file overrides the package's" behavior.
-sources_add_entry_first() {
-    local file="$1" section="$2" entry="$3"
-    _mig_has_source "$file" "$entry" && return 0
-    _qmap_stage "$file" -v section="$section" -v entry="$entry" '
+# sources_add_entry <file> <section> <entry> [position] [anchor]
+# Idempotent insert into sources.<section>, creating `sources:` and the section
+# as needed. Position is `last` (default), `first`, `before` or `after`; the
+# anchored forms take <anchor>, an entry the section already lists. The caller
+# validates the anchor, and an edit that cannot be placed exits 3 rather than
+# landing the entry somewhere else — a silently misplaced source changes which
+# artifact wins.
+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" '
         function line() { return "    - \"" entry "\"" }
+        function place() { print line(); done = 1 }
+        # Blank lines inside sources: are held back so an insert lands next to
+        # the entries it belongs with, not after the blank line that separates
+        # 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 "" }
+        function value(s,   v) {
+            v = s
+            sub(/^[ \t]*-[ \t]*/, "", v)
+            gsub(/["\x27]/, "", v)
+            sub(/[ \t]+#.*$/, "", v)
+            sub(/[ \t]+$/, "", v)
+            return v
+        }
+        BEGIN { anchored = (pos == "before" || pos == "after") }
         { sub(/\r$/, "") }
         /^sources:[ \t]*$/ { ins = 1; sourceseen = 1; print; next }
         ins && /^[^ #]/ {
-            if (!secseen && !done) { print "  " section ":"; print line(); done = 1 }
+            if (insec) { if (!done && pos == "last") place(); insec = 0 }
+            if (!secseen && !done && !anchored) { open_section(); secseen = 1 }
+            else flush_tail()
             ins = 0
         }
-        ins && $0 ~ "^  " section ":[ \t]*$" { secseen = 1; print; print line(); done = 1; next }
-        { print }
+        ins && !insec && $0 ~ "^  " section ":[ \t]*$" {
+            flush_tail(); secseen = 1; insec = 1; print
+            if (pos == "first") place()
+            next
+        }
+        ins && insec && /^  [A-Za-z_]/ {
+            if (!done && pos == "last") place()
+            insec = 0
+            flush_tail()
+        }
+        insec && /^[ \t]*-/ {
+            flush_tail()
+            v = value($0)
+            if (pos == "before" && v == anchor && !done) place()
+            print
+            if (pos == "after" && v == anchor && !done) place()
+            next
+        }
+        ins && /^[ \t]*$/ { tail[++ntail] = $0; next }
+        ins { flush_tail(); print; next }
+        { last = $0; print }
         END {
-            if (ins && !secseen && !done) { print "  " section ":"; print line(); done = 1 }
-            if (!sourceseen) {
-                print "sources:"
-                print "  " section ":"
-                print line()
+            if (insec && !done && pos == "last") place()
+            flush_tail()
+            if (!done && !anchored) {
+                if (ins && !secseen) { print "  " section ":"; place() }
+                else if (!sourceseen) {
+                    if (last != "") print ""
+                    print "sources:"; print "  " section ":"; place()
+                }
             }
+            if (!done) exit 3
         }
     '
 }
 
+# sources_add_entry_first <file> <section> <entry> — insert at the TOP of
+# sources.<section>. Package wiring uses it so project-owned entries stay later
+# in the list — adapters copy sources in order and the last write wins, which
+# is exactly the documented "your file overrides the package's" behavior.
+sources_add_entry_first() {
+    sources_add_entry "$1" "$2" "$3" first
+}
+
 # sources_remove_entry <file> <section> <entry> — remove `- "entry"` from
 # sources.<section>.
 sources_remove_entry() {

package/engine/ENGINE_SHA

@@ -1 +1 @@
-b12551947be83587f4f74e79c5a56765a18dd52f
+365ec21e2f2d4d9ef323ed9f1387b3c3c4bef845

package/engine/VERSION

@@ -1 +1 @@
-0.15.0
+0.16.1

package/engine/lib/common.sh

@@ -1335,7 +1335,15 @@ warn_unsynced() {
     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)
 
     if [ $warnings -gt 0 ]; then
-        echo "  Add these paths to sources: in ${config_file##*/}"
+        # Name the command that does it. A diagnostic that ends in "edit this
+        # file yourself" is the one step nobody repeats the same way twice —
+        # 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>"
+        else
+            echo "  Add these paths to sources: in ${config_file##*/}"
+        fi
     fi
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainova-systems/intelligence",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "Build, version and distribute AI agent intelligence across your organization — one CLI, versioned Intelligence Packages, and a sync engine for Claude Code, Cursor, Copilot, Codex, Pi and OpenCode.",
   "bin": {
     "intelligence": "bin/intelligence.js"

package/packages/sync/references/conventions.md

@@ -73,6 +73,8 @@ sources:
 
 Missing project-owned source directories are skipped, so a package-only project need not create empty `rules/`, `agents/` or `skills/` directories. Source order matters: later files with the same artifact name overwrite earlier ones. Package sources are wired before project sources so the project can override a package artifact deliberately.
 
+Project-owned entries are managed with `intelligence source add|remove|list` rather than by hand — it validates the path against the way the engine resolves it and prints the resulting order. `add` appends by default; `--before <entry>` / `--after <entry>` place content that should behave like a package ahead of the project's own directories.
+
 The CLI owns package and registry blocks:
 
 ```yaml

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

@@ -24,7 +24,10 @@ the same procedure. Updating the layer can create a new artifact.
    Prefer extending an existing owner, merging duplicates, or enforcing a
    convention mechanically. Resolve the writable directory from the manifest;
    create a pre-listed missing directory without changing the source list. Add a
-   source entry only when an accepted destination is outside the listed groups.
+   source entry only when an accepted destination is outside the listed groups,
+   and add it with `intelligence source add <rules|agents|skills> <dir>` rather
+   than by editing the manifest: the list is ordered, and its order decides which
+   artifact wins.
 
 3. Establish the evidence and artifact type. A constraint is a rule, a repeatable
    procedure is a skill, and a persona or expertise boundary is an agent. Verify