@ainova-systems/intelligence 0.15.0 → 0.16.0

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/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
+179b1e89ade2ac7d833750458de1babe0c7a6d90

package/engine/VERSION

@@ -1 +1 @@
-0.15.0
+0.16.0

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.0",
   "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