@ainova-systems/intelligence 0.19.0 → 0.20.0

package/engine/lib/contract.sh

@@ -84,6 +84,11 @@ IS_RC_AMBIGUOUS=3           # conflicting state; agent/human-only — bash never
 IS_RC_AHEAD=4               # project stamped newer than this engine understands
 IS_RC_ABORTED_INCOMPLETE=5  # staged state incomplete; the project was left untouched
 IS_RC_NEEDS_UPDATE=6        # pending schema changes (stamp < engine) — run `intelligence init --apply`
+# `intelligence sync --check` only: generated files differ from what sync would
+# leave, or alignment is pending (IS_STATUS=out-of-date). It shares 2 with
+# config-missing, which a check never reports: the CLI found the manifest, and
+# the check turns any other failure that ends in 2 into 1.
+IS_RC_OUT_OF_DATE=2
 
 # is_status <code-name> [detail] — emit one parseable line for the skill.
 is_status() {

package/engine/sync.sh

@@ -10,6 +10,8 @@
 #   IS_CONTENT_REL     the project's content dir, repo-relative
 #   IS_MODULE_REL      the installed sync package, repo-relative
 #   IS_PROTECTED_DIRS  dirs an adapter output may never overlap
+#   IS_SYNC_CHECK      optional: render, compare and restore, then write
+#                      `same` or `differs` to this file (`sync --check`)
 #
 # Usage: intelligence sync [target]
 
@@ -111,46 +113,43 @@ while IFS=$'\037' read -r section src state _dir alias holders; do
     echo "WARNING: sources.$section '$src' $IS_SOURCE_PROBLEM — skipped; 'intelligence status --check' reports it" >&2
 done <<< "${IS_YL_UNRESOLVED:-}"
 
+
+# Sources stay read-only for the whole run (validate_output_path refuses an
+# output inside one), so read_source_artifact_files enumerates each section
+# once, in this shell, and its later callers — the agents adapter, the shared
+# skill directory, the context report — replay it. Adapters that list sources
+# with in-shell globs spawn nothing and keep their own, locale-ordered listing.
+# The skills pass also settles every symlink in a skills source and warns once
+# about each it leaves out (decision 0017).
+# shellcheck disable=SC2034  # read by read_source_artifact_files in lib/common.sh
+IS_SOURCE_FILES_MEMO=1
+for section in rules agents skills; do
+    read_source_artifact_files "$REPO_ROOT" "$CONFIG_FILE" "$section"
+done
+
 # Lint frontmatter across all source files (rules, agents, skills).
 # Catches issues like unquoted colons that strict YAML consumers reject.
+# Skills are the rendered ones the pass above settled: SKILL.md behind a link
+# inside its source is linted, one that leaves its source is never read.
 LINT_FILES=()
-LINT_SKILL_DIRS=()
-for section in rules agents skills; do
+LINT_SKILLS=()
+[ "${#IS_SOURCE_FILES[@]}" -eq 0 ] || LINT_SKILLS=("${IS_SOURCE_FILES[@]}")
+for section in rules agents; do
     load_yaml_list "$CONFIG_FILE" "$section"
     while IFS= read -r src; do
         [ -z "$src" ] && continue
         src_dir="$REPO_ROOT/$src"
         [ -d "$src_dir" ] || continue
-        if [ "$section" = "skills" ]; then
-            LINT_SKILL_DIRS+=("$src_dir")
-        else
-            for f in "$src_dir"/*.md; do
-                [ -f "$f" ] && LINT_FILES+=("$f")
-            done
-        fi
+        for f in "$src_dir"/*.md; do
+            [ -f "$f" ] && LINT_FILES+=("$f")
+        done
     done <<< "$IS_YAML_LIST"
 done
-# One find for every skills source: it walks its start points in order.
-if [ "${#LINT_SKILL_DIRS[@]}" -gt 0 ]; then
-    while IFS= read -r f; do
-        [ -n "$f" ] && LINT_FILES+=("$f")
-    done < <(find "${LINT_SKILL_DIRS[@]}" -mindepth 2 -maxdepth 2 -name 'SKILL.md' 2>/dev/null)
-fi
+[ "${#LINT_SKILLS[@]}" -eq 0 ] || LINT_FILES+=("${LINT_SKILLS[@]}")
 if [ "${#LINT_FILES[@]}" -gt 0 ]; then
     lint_frontmatter_files "${LINT_FILES[@]}"
 fi
 
-# Sources stay read-only for the whole run (validate_output_path refuses an
-# output inside one), so read_source_artifact_files enumerates each section
-# once, in this shell, and its later callers — the agents adapter, the shared
-# skill directory, the context report — replay it. Adapters that list sources
-# with in-shell globs spawn nothing and keep their own, locale-ordered listing.
-# shellcheck disable=SC2034  # read by read_source_artifact_files in lib/common.sh
-IS_SOURCE_FILES_MEMO=1
-for section in rules agents skills; do
-    read_source_artifact_files "$REPO_ROOT" "$CONFIG_FILE" "$section"
-done
-
 # Adapters come from two places, discovered by filename (minus `.sh`,
 # `_template` excluded):
 #
@@ -211,6 +210,17 @@ SYNC_PARALLEL=1
 SYNC_BG_PIDS=()
 SYNC_COPY_INDEXES=()
 
+# An accepted output-root directory link is a write path, unlike a nested
+# generated asset link. Checks must retain the bytes behind that root too.
+snapshot_sync_entry() {
+    local src="$1" index="$2"
+    cp -a "$src" "$SYNC_TX_DIR/data/$index" || return $?
+    if [ -n "${IS_SYNC_CHECK:-}" ] && [ -L "$src" ] && [ -d "$src" ]; then
+        mkdir -p "$SYNC_TX_DIR/targets/$index" || return $?
+        cp -a "$src/." "$SYNC_TX_DIR/targets/$index" || return $?
+    fi
+}
+
 snapshot_sync_path() {
     local adapter_name="$1" rel="$2" src index present=0
     case "$SYNC_TX_SEEN_LIST" in
@@ -224,11 +234,11 @@ snapshot_sync_path() {
         # Copies of distinct paths into distinct slots: they can overlap, and
         # The snapshot wait before the render collects every status.
         if [ "$SYNC_PARALLEL" = 1 ]; then
-            cp -a "$src" "$SYNC_TX_DIR/data/$index" 2> "$SYNC_TX_DIR/copy.$index.err" &
+            snapshot_sync_entry "$src" "$index" 2> "$SYNC_TX_DIR/copy.$index.err" &
             SYNC_BG_PIDS+=("$!")
             SYNC_COPY_INDEXES+=("$index")
         else
-            cp -a "$src" "$SYNC_TX_DIR/data/$index"
+            snapshot_sync_entry "$src" "$index"
         fi
         present=1
     fi
@@ -274,6 +284,68 @@ wait_sync_jobs() {
     return "$first"
 }
 
+# Compare each entry without following links: copied relative and dangling
+# links describe their targets, not bytes at the snapshot's new location.
+compare_sync_entries() {
+    local snap="$1" live="$2" rc=0 target before
+    if [ -L "$snap" ]; then
+        [ -L "$live" ] || return 1
+        before="$(readlink "$snap")" || return 2
+        target="$(readlink "$live")" || return 2
+        # Source links inside the private copy refer to its root. Compare the
+        # generated target in the original project's coordinate system.
+        if [ -n "${IS_SYNC_CHECK_ROOT:-}" ] && [ -n "${IS_SYNC_CHECK:-}" ]; then
+            case "$before" in "$REPO_ROOT") before="$IS_SYNC_CHECK_ROOT" ;; "$REPO_ROOT"/*) before="$IS_SYNC_CHECK_ROOT/${before#"$REPO_ROOT/"}" ;; esac
+            case "$target" in "$REPO_ROOT") target="$IS_SYNC_CHECK_ROOT" ;; "$REPO_ROOT"/*) target="$IS_SYNC_CHECK_ROOT/${target#"$REPO_ROOT/"}" ;; esac
+        fi
+        [ "$before" = "$target" ] || return 1
+    elif [ -L "$live" ]; then
+        return 1
+    elif [ -f "$snap" ] && [ -f "$live" ]; then
+        cmp -s "$snap" "$live" || rc=$?
+        case "$rc" in 0) ;; 1) return 1 ;; *) return 2 ;; esac
+        if [ -x "$snap" ]; then [ -x "$live" ] || return 1; else [ ! -x "$live" ] || return 1; fi
+    elif [ -d "$snap" ] && [ -d "$live" ]; then
+        return 0
+    else
+        return 1
+    fi
+}
+
+compare_sync_snapshot() {
+    local index rel present live snap entry sub
+    while IFS=$'\t' read -r index rel present; do
+        [ -n "$rel" ] || continue
+        live="$REPO_ROOT/$rel"
+        snap="$SYNC_TX_DIR/data/$index"
+        if [ "$present" != 1 ]; then
+            if [ -e "$live" ] || [ -L "$live" ]; then return 1; fi
+            continue
+        fi
+        compare_sync_entries "$snap" "$live" || return $?
+        if [ -d "$SYNC_TX_DIR/targets/$index" ]; then
+            # validate_output_path permitted this physical directory inside
+            # the private project. Only its root is followed; descendants
+            # still use the entry-kind and literal-target comparison.
+            snap="$SYNC_TX_DIR/targets/$index"
+            live="$(cd "$live" && pwd -P)" || return 2
+        fi
+        [ ! -L "$snap" ] && [ -d "$snap" ] || continue
+        # NUL-delimited paths also preserve whitespace and newlines. find's
+        # default walk does not dereference links on GNU or BSD userland.
+        find "$snap" -print0 > "$SYNC_TX_DIR/snapshot.list" || return 2
+        find "$live" -print0 > "$SYNC_TX_DIR/live.list" || return 2
+        while IFS= read -r -d '' entry; do
+            sub="${entry#"$snap"}"
+            compare_sync_entries "$entry" "$live$sub" || return $?
+        done < "$SYNC_TX_DIR/snapshot.list"
+        while IFS= read -r -d '' entry; do
+            sub="${entry#"$live"}"
+            [ -e "$snap$sub" ] || [ -L "$snap$sub" ] || return 1
+        done < "$SYNC_TX_DIR/live.list"
+    done < "$SYNC_TX_INDEX"
+}
+
 finish_sync_transaction() {
     local rc=$?
     trap - EXIT INT TERM
@@ -625,6 +697,25 @@ if [ $synced -eq 0 ]; then
     exit 1
 fi
 
+# A check renders exactly like a sync, then compares every snapshotted path
+# with what the render left and restores the snapshot whatever the answer: it
+# never changes a file. The transaction stays active until the restore is
+# complete, so an interrupted restore is finished by the EXIT handler.
+if [ -n "${IS_SYNC_CHECK:-}" ]; then
+    check_rc=0
+    compare_sync_snapshot || check_rc=$?
+    case "$check_rc" in
+        0) check_verdict=same ;;
+        1) check_verdict=differs ;;
+        *)
+            echo "ERROR: sync --check could not compare the rendered output with its snapshot." >&2
+            exit 1
+            ;;
+    esac
+    restore_sync_snapshot
+    printf '%s\n' "$check_verdict" > "$IS_SYNC_CHECK"
+fi
+
 SYNC_TX_ACTIVE=0
 
 # After rendering, three read-only reports, in this order:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainova-systems/intelligence",
-  "version": "0.19.0",
+  "version": "0.20.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/adapters.md

@@ -178,6 +178,7 @@ Use the engine library instead of copying parsers or file-handling logic.
 | `copy_skill_bundle(src, dest)` | Copy `SKILL.md` and all resources safely, normalize Markdown, quote free-text frontmatter, and keep a valid `effort:` as written, as the shared skills tree does. |
 | `copy_skill_bundle_dirs(dest_root, src...)` | Batch form: copy every skill directory into `dest_root/<name>` with one copy and one finalize pass. |
 | `copy_skill_bundle_dirs_for(tool, dest_root, src...)` | The batch form for a tree one tool reads: `SKILL.md`'s `effort:` becomes that tool's level, or is removed when it has none. |
+| `skill_source_rendered(skill_dir)` | Whether sync renders a skill directory an adapter listed with its own glob; a skill left out for its symlinks fails it. |
 | `sync_open_skill_dirs(root, config, dest)` | Own and populate a shared Agent Skills directory such as `.agents/skills/`, deriving Codex's `agents/openai.yaml` for a skill with `disable-model-invocation: true`. |
 | `finalize_output_file(file)` | Expand layout tokens and normalize line endings; required for every emitted text file. |
 | `finalize_output_files(file...)` / `finalize_copy_files(dest, src...)` | Batch forms: finalize in place, or copy-and-finalize into a directory, in one process. |
@@ -212,6 +213,8 @@ If a new adapter relies on `AGENTS.md` for always-on rules, its target must requ
 
 Every successful sync prints an adapter-agnostic `CONTEXT:` summary with source byte totals and file counts. It separates always-on rules from custom context (scoped rules, agent prompts and skill entry points), then reports a numeric `agents-md` byte count and `generated`, `not-generated`, or `disabled` status; supporting skill assets are excluded until explicitly read. Adapter-specific hard limits and suppression controls stay inside the adapter that owns them.
 
+Print an adapter warning on stderr as one unindented line starting `WARNING:`. `sync --compact`, which `intelligence init` runs, keeps exactly those lines and drops indented progress, so a warning in any other form never reaches the reader.
+
 The Codex adapter checks its `project_doc_max_bytes` default (32 KiB). When generated `AGENTS.md` exceeds it, sync prints the byte count and a sufficient Codex setting. The warning says "may truncate" because a developer can already have a larger override. `targets.codex.warn_project_doc_limit` accepts `true` or omission for the default threshold, a positive byte count to match another effective limit, or `false` to disable the Intelligence warning. Both inline and block target forms work, and the field does not change Codex configuration. The warning remains visible in `sync --compact`.
 
 The Antigravity adapter checks the 12,000-character limit its documentation
@@ -237,7 +240,9 @@ Skills follow the [Agent Skills standard](https://agentskills.io). Copy each ski
 copy_skill_bundle "$source_skill_dir" "$output_dir/skills/$skill_name"
 ```
 
-Do not use plain `cp` for skill bundles. `copy_skill_bundle` preserves non-Markdown assets, avoids materializing symlink targets, normalizes Markdown, expands layout tokens and quotes `description` and `argument-hint` where strict YAML readers require strings. It renders `effort:` as the shared tree does; a tree only one tool reads uses `copy_skill_bundle_dirs_for <tool>`, so the copy carries that tool's level or no effort at all.
+Do not use plain `cp` for skill bundles. `copy_skill_bundle` preserves non-Markdown assets, normalizes Markdown, expands layout tokens and quotes `description` and `argument-hint` where strict YAML readers require strings. It renders `effort:` as the shared tree does; a tree only one tool reads uses `copy_skill_bundle_dirs_for <tool>`, so the copy carries that tool's level or no effort at all. It never writes a symlink; how a link in a skills source renders is defined in [conventions](conventions.md#skill-body-and-resources).
+
+An adapter that lists a skills source with its own glob checks each directory with `skill_source_rendered`. A skill whose directory or `SKILL.md` is a link leaving its source is left out of every output, and sync has already warned about it once.
 
 Antigravity, Codex, Pi and OpenCode share `.agents/skills/`. Any adapter writing that open-standard directory must call `sync_open_skill_dirs`; it is the single lifecycle owner for immediate skill subdirectories.
 

package/packages/sync/references/conventions.md

@@ -311,6 +311,8 @@ skill-name/
 
 The engine copies the complete skill directory. Promote a helper outside the skill only when multiple skills share it.
 
+A symlink inside a skills source renders as the file or directory it points at when that stays inside the same source, so one source can alias a skill or share a resource between skills. A link that leaves its source, dangles or points at a directory enclosing it is left out with a `WARNING:` line; a skill whose directory or `SKILL.md` is such a link is left out entirely. Add a skill kept elsewhere as its own source or package instead of linking it in. Generated skill directories never contain symlinks.
+
 Size limits are backstops, not quotas:
 
 | Artifact | Hard cap | Response |
@@ -458,7 +460,7 @@ The permanent applied-schema key is the top-level scalar `schema_version` in `in
 The public lifecycle is deliberately compact:
 
 - `intelligence init [--preview|--apply]` is universal: it creates a new setup, aligns an existing Intelligence project, or plans/applies conversion of an eligible legacy Intelligence Sync project.
-- `intelligence sync [adapter] [--compact] [--force]` first aligns an existing Intelligence project with the installed CLI and restores every package the store lacks or holds at another commit, strictly from `intelligence.lock`. It skips rendering when local inputs and outputs match a previous successful run. Changes or missing outputs trigger rendering; `--force` always renders and refreshes the search for unconfigured source directories. An unchanged run replays the last full run's useful diagnostics. Compact mode shows context sizes, actionable warnings and final status on success, and all diagnostics on failure. In CI it refuses an alignment that would change tracked files and points to a local `intelligence init --apply` plus review/commit.
+- `intelligence sync [adapter] [--compact] [--force] [--check]` first aligns an existing Intelligence project with the installed CLI and restores every package the store lacks or holds at another commit, strictly from `intelligence.lock`. It skips rendering when local inputs and outputs match a previous successful run. Changes or missing outputs trigger rendering; `--force` always renders and refreshes the search for unconfigured source directories. An unchanged run replays the last full run's useful diagnostics. Compact mode shows context sizes, actionable warnings and final status on success, and all diagnostics on failure. In CI it refuses an alignment that would change tracked files and points to a local `intelligence init --apply` plus review/commit. `--check` changes no generated file: it prints one `IS_STATUS` line and exits 0 when generated files are up to date and 2 (`out-of-date`) when sync would change them or alignment is pending; it never applies alignment.
 - `intelligence update [@scope/name] [--preview|--apply]` is the only update surface. It prints the CLI/project/package plan; default mode prompts, `--preview` never writes, and `--apply` does not prompt. It never moves `ref:` pins.
 - `intelligence upgrade [--next] [--preview|--apply]` replaces the installed CLI with the newest version on its npm channel (`next` for a prerelease or with `--next`, otherwise `latest`) with the same modes. It touches no project, never downgrades, and refuses an installation that npm did not make.
 - `intelligence package add|remove|list|search` owns package inventory.
@@ -479,6 +481,7 @@ The engine emits one machine-readable line, `IS_STATUS=<code> [IS_DETAIL=...]`,
 | `migrated` | 0 | Initialization converted an older layout |
 | `error` | 1 | Generic failure |
 | `config-missing` | 2 | Required manifest is absent |
+| `out-of-date` | 2 | `sync --check` only: sync would change generated files, or alignment is pending. A check never reports `config-missing`, and turns any other failure that would end in 2 into 1 |
 | `ambiguous` | 3 | Conflicting state requiring agent/human judgment; reserved |
 | `ahead-of-engine` | 4 | Manifest schema is a newer major than the engine (a newer minor or patch warns and continues) |
 | `aborted-incomplete` | 5 | Staged replacement was incomplete; prior state remains |