@ainova-systems/intelligence 0.11.0-rc.1 → 0.11.0-rc.10

package/engine/lib/contract.sh

@@ -0,0 +1,120 @@
+#!/bin/bash
+# shellcheck disable=SC2034  # IS_RC_*/IS_SCHEMA_VERSION_KEY are the public bash<->CLI contract, consumed by the scripts that source this lib
+# intelligence-sync: the version and status contract.
+# Source this file — never execute directly.
+#
+# Two things live here, and both are contracts other programs depend on:
+#   * the applied-schema stamp (`schema_version` in the manifest) with its
+#     read / write / compare helpers, and
+#   * the IS_STATUS / IS_RC_* codes every engine flow reports.
+#
+# Schema migrations themselves are NOT here: the CLI owns them behind
+# `intelligence init`, and a legacy Intelligence Sync project is brought forward
+# by its archived engine before `intelligence init` converts it.
+
+# The applied-schema version is a managed key in the manifest.
+#
+# INVARIANT: this key is a PERMANENT, format-stable, top-level scalar contract.
+# Anything else in the manifest may be reshaped; the name, location and shape of
+# this key never are - so any engine, however old or new, can always read "what
+# schema is this?" before parsing the rest.
+IS_SCHEMA_VERSION_KEY="schema_version"
+
+# read_schema_version <config_file> → applied version, or "" if absent.
+read_schema_version() {
+    local cf="$1"
+    [ -f "$cf" ] || return 0
+    awk -v k="$IS_SCHEMA_VERSION_KEY" '
+        { sub(/\r$/, "") }
+        $0 ~ "^" k ":" {
+            v = $0; sub(/^[^:]*:[[:space:]]*/, "", v)
+            gsub(/^["\047]|["\047][[:space:]]*$/, "", v)
+            sub(/[[:space:]]+$/, "", v)
+            print v; exit
+        }
+    ' "$cf"
+}
+
+# stamp_schema_version <config_file> <version> — idempotent, transactional upsert of
+# the contract key (replace in place if present, else append at top level).
+# No-op if config.yaml does not exist yet (pre-bootstrap).
+stamp_schema_version() {
+    local cf="$1" ver="$2"
+    [ -f "$cf" ] || return 0
+    local tmp="$cf.ver.tmp"
+    awk -v k="$IS_SCHEMA_VERSION_KEY" -v val="$ver" '
+        { sub(/\r$/, "") }
+        $0 ~ "^" k ":" { print k ": \"" val "\""; found=1; next }
+        { print }
+        END { if (!found) print k ": \"" val "\"" }
+    ' "$cf" > "$tmp" && mv "$tmp" "$cf"
+}
+
+# --- bash ↔ skill status contract -------------------------------------------
+# Bash is the deterministic, fail-closed core: it never guesses. Any state it
+# cannot resolve safely is reported as a machine-readable status line on
+# stdout plus a stable exit code, and the intelligence-update SKILL (the
+# intelligent layer) decides what to do. Codes are part of the public
+# contract — do not renumber.
+IS_RC_OK=0                  # success (synced / migrated / nothing to do)
+IS_RC_ERROR=1               # generic error
+IS_RC_CONFIG_MISSING=2      # no manifest found
+IS_RC_AMBIGUOUS=3           # conflicting state; agent/human-only — bash never emits this itself
+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`
+
+# is_status <code-name> [detail] — emit one parseable line for the skill.
+is_status() {
+    local code="$1" detail="${2:-}"
+    if [ -n "$detail" ]; then
+        echo "IS_STATUS=$code IS_DETAIL=$detail"
+    else
+        echo "IS_STATUS=$code"
+    fi
+}
+
+# Engine version = scripts/VERSION next to this lib (BASH_SOURCE works when
+# sourced). Empty if unreadable — callers treat empty as "no guard".
+engine_version() {
+    local vf
+    vf="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." 2>/dev/null && pwd)/VERSION"
+    [ -f "$vf" ] && tr -d ' \t\r\n' < "$vf"
+}
+
+# _ver_gt A B → true if semver A is strictly greater than B (numeric x.y.z;
+# any non-numeric suffix on a field is ignored). Missing fields = 0.
+# Pre-release/build metadata ordering is intentionally NOT handled — the
+# stamp only ever stores plain x.y.z, so this is sufficient.
+_ver_gt() {
+    local a="$1" b="$2" i ai bi
+    local -a A B
+    IFS=. read -r -a A <<< "$a"
+    IFS=. read -r -a B <<< "$b"
+    for i in 0 1 2; do
+        ai=$(printf '%s' "${A[$i]:-0}" | tr -cd '0-9'); ai=${ai:-0}
+        bi=$(printf '%s' "${B[$i]:-0}" | tr -cd '0-9'); bi=${bi:-0}
+        if [ "$((10#$ai))" -gt "$((10#$bi))" ]; then return 0; fi
+        if [ "$((10#$ai))" -lt "$((10#$bi))" ]; then return 1; fi
+    done
+    return 1
+}
+
+# check_version_compat <config_file> — refuse to operate on a project whose
+# config schema is stamped newer than this engine knows (a stale engine must
+# never rewrite/sync a newer schema). Emits status + returns IS_RC_AHEAD on
+# conflict, else 0.
+check_version_compat() {
+    local cf="$1" stamp eng
+    stamp="$(read_schema_version "$cf")"
+    [ -n "$stamp" ] || return 0
+    eng="$(engine_version)"
+    [ -n "$eng" ] || return 0
+    if _ver_gt "$stamp" "$eng"; then
+        is_status ahead-of-engine "stamp=$stamp engine=$eng"
+        echo "  ERROR: project stamped $stamp but this engine is $eng — refusing." >&2
+        echo "         Update the CLI first: npm i -g @ainova-systems/intelligence@latest" >&2
+        return "$IS_RC_AHEAD"
+    fi
+    return 0
+}

package/engine/sync.sh

@@ -0,0 +1,238 @@
+#!/bin/bash
+# intelligence-sync: the sync engine's entry point.
+#
+# The engine runs from outside the project (the CLI's install dir), so it never
+# searches the filesystem for one: the project arrives through the environment,
+# exported by `intelligence sync`.
+#
+#   CONFIG_FILE        the project's manifest (intelligence.yaml at the root)
+#   REPO_ROOT          the project root
+#   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
+#
+# Usage: intelligence sync [target]
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+source "$SCRIPT_DIR/lib/common.sh"
+source "$SCRIPT_DIR/lib/contract.sh"
+
+if [ -z "${CONFIG_FILE:-}" ] || [ ! -f "${CONFIG_FILE:-}" ]; then
+    is_status config-missing "CONFIG_FILE=${CONFIG_FILE:-}"
+    echo "ERROR: the engine needs CONFIG_FILE to point at an existing manifest." >&2
+    echo "       Run it through the CLI: intelligence sync" >&2
+    exit "$IS_RC_CONFIG_MISSING"
+fi
+
+# Schema version lives in the manifest (the frozen contract key).
+_cf="$CONFIG_FILE"
+
+# Stale engine vs project schema stamped NEWER (ahead-of-engine) → refuse.
+_vc_rc=0
+check_version_compat "$_cf" || _vc_rc=$?
+if [ "$_vc_rc" -ne 0 ]; then exit "$_vc_rc"; fi
+
+# Schema gap → refuse. sync is a PURE synchronizer: it never changes schemas,
+# so the CLI lifecycle preflight must align the project first. An ABSENT stamp
+# means the same thing — a manifest with no
+# `schema_version` must not silently sync past a schema change.
+_stamp="$(read_schema_version "$_cf")"
+_eng="$(engine_version)"
+if [ -z "$_stamp" ]; then
+    is_status needs-update "stamped= engine=$_eng (no schema_version)"
+    echo "ERROR: the manifest has no schema_version — schema un-applied." >&2
+    echo "       Run: intelligence init --apply" >&2
+    exit "$IS_RC_NEEDS_UPDATE"
+elif [ -n "$_eng" ] && _ver_gt "$_eng" "$_stamp"; then
+    is_status needs-update "stamped=$_stamp engine=$_eng"
+    echo "ERROR: project at $_stamp but engine is $_eng — pending schema changes." >&2
+    echo "       Run: intelligence init --apply" >&2
+    exit "$IS_RC_NEEDS_UPDATE"
+fi
+
+# Normalize REPO_ROOT and CONFIG_FILE to one `cd && pwd` spelling so
+# prefix-stripping in path comparisons works: Git Bash on Windows reaches the
+# same location through `D:/...` and `/d/...`, and the CLI (or the Node shim
+# behind it) may hand us either.
+REPO_ROOT_RAW="${REPO_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || dirname "$CONFIG_FILE")}"
+REPO_ROOT="$(cd "$REPO_ROOT_RAW" && pwd)"
+unset REPO_ROOT_RAW
+CONFIG_FILE="$(cd "$(dirname "$CONFIG_FILE")" && pwd)/$(basename "$CONFIG_FILE")"
+
+# Layout tokens for generated output (see finalize_output_file in common.sh).
+# Package-shipped rules/agents cannot hardcode the content dir's name — the
+# project chooses it — so they write `<content-dir>` / `<module>` and every adapter
+# expands them on the way out.
+IS_CONTENT_REL="${IS_CONTENT_REL:-intelligence}"
+# No vendor default: the CLI always exports the package path (derived from its
+# distribution data), so a bare invocation must say so rather than guess.
+if [ -z "${IS_MODULE_REL:-}" ]; then
+    echo "ERROR: the engine needs IS_MODULE_REL (exported by the intelligence CLI)." >&2
+    exit 1
+fi
+export IS_CONTENT_REL IS_MODULE_REL
+
+# Project-owned adapters live in the content dir: <content-dir>/adapters/.
+INTELLIGENCE_DIR="$REPO_ROOT/$IS_CONTENT_REL"
+
+TARGET_FILTER="${1:-}"
+
+echo "=== intelligence-sync ==="
+echo "  Config: $CONFIG_FILE"
+echo "  Root:   $REPO_ROOT"
+echo ""
+
+# Invariant: AGENTS.md is the canonical carrier of always-on rules for
+# Cursor / Copilot / Codex / Pi / opencode (their adapters skip always-on
+# rules to avoid duplication, since each tool reads AGENTS.md natively for
+# baseline project context). If those targets are enabled, `agents` must
+# also be enabled — otherwise always-on rules go nowhere for those tools.
+# Skip the check when the user requested a single target via $TARGET_FILTER:
+# they may be syncing only one IDE intentionally.
+if [ -z "$TARGET_FILTER" ]; then
+    agents_enabled=$(is_target_enabled "$CONFIG_FILE" "agents")
+    if [ "$agents_enabled" != "1" ]; then
+        # AGENTS.md-dependent adapters: any tool whose adapter skips always-on
+        # rule emission (because the tool reads AGENTS.md natively) must be
+        # listed here. Add new adapters to this list when they ship.
+        for tool in cursor copilot codex pi opencode; do
+            if [ "$(is_target_enabled "$CONFIG_FILE" "$tool")" = "1" ]; then
+                echo "ERROR: targets.$tool is enabled but targets.agents is not." >&2
+                echo "  $tool relies on AGENTS.md to deliver always-on rules — without it," >&2
+                echo "  always-on rules would be invisible to $tool." >&2
+                echo "  Either enable targets.agents in $CONFIG_FILE, or disable targets.$tool." >&2
+                exit 1
+            fi
+        done
+    fi
+fi
+
+# Lint frontmatter across all source files (rules, agents, skills).
+# Catches issues like unquoted colons that strict YAML consumers reject.
+for section in rules agents skills; do
+    while IFS= read -r src; do
+        [ -z "$src" ] && continue
+        src_dir="$(resolve_source_dir "$REPO_ROOT" "$src")"
+        [ -d "$src_dir" ] || continue
+        if [ "$section" = "skills" ]; then
+            while IFS= read -r f; do
+                [ -n "$f" ] && lint_frontmatter "$f"
+            done < <(find "$src_dir" -mindepth 2 -maxdepth 2 -name 'SKILL.md' 2>/dev/null)
+        else
+            for f in "$src_dir"/*.md; do
+                [ -f "$f" ] && lint_frontmatter "$f"
+            done
+        fi
+    done < <(read_yaml_list "$CONFIG_FILE" "$section")
+done
+
+# Adapters come from two places, discovered by filename (minus `.sh`,
+# `_template` excluded):
+#
+#   1. Built-in   — shipped inside the CLI, replaced with each CLI installation
+#   2. Project    — <content-dir>/adapters/, owned by the project and never touched
+#
+# A custom adapter therefore belongs in the content dir's `adapters/`; the
+# built-in directory lives inside the installed CLI and is not the project's to
+# edit. A project adapter whose name matches a built-in overrides it (an escape
+# hatch for patching a built-in without forking — announced, never silent).
+ADAPTERS=()
+ADAPTER_FILES=()
+
+register_adapter() {
+    local name="$1" file="$2"
+    local n=${#ADAPTERS[@]} i=0
+    while [ "$i" -lt "$n" ]; do
+        if [ "${ADAPTERS[$i]}" = "$name" ]; then
+            ADAPTER_FILES[$i]="$file"
+            echo "  NOTE: project adapter '$name' overrides the built-in one ($(basename "$INTELLIGENCE_DIR")/adapters/$(basename "$file"))"
+            return 0
+        fi
+        i=$((i + 1))
+    done
+    ADAPTERS+=("$name")
+    ADAPTER_FILES+=("$file")
+}
+
+for adapters_dir in "$SCRIPT_DIR/adapters" "$INTELLIGENCE_DIR/adapters"; do
+    [ -d "$adapters_dir" ] || continue
+    for adapter_file in "$adapters_dir"/*.sh; do
+        [ -f "$adapter_file" ] || continue
+        adapter_name="$(basename "$adapter_file" .sh)"
+        [ "$adapter_name" = "_template" ] && continue
+        register_adapter "$adapter_name" "$adapter_file"
+    done
+done
+
+synced=0
+adapter_count=${#ADAPTERS[@]}
+adapter_idx=0
+
+while [ "$adapter_idx" -lt "$adapter_count" ]; do
+    adapter="${ADAPTERS[$adapter_idx]}"
+    adapter_file="${ADAPTER_FILES[$adapter_idx]}"
+    adapter_idx=$((adapter_idx + 1))
+
+    # Skip if user requested specific target and this isn't it
+    if [ -n "$TARGET_FILTER" ] && [ "$adapter" != "$TARGET_FILTER" ]; then
+        continue
+    fi
+
+    # Check if target is enabled in config
+    enabled=$(is_target_enabled "$CONFIG_FILE" "$adapter")
+    if [ "$enabled" != "1" ]; then
+        if [ -n "$TARGET_FILTER" ]; then
+            echo "ERROR: Adapter '$TARGET_FILTER' is disabled in $CONFIG_FILE." >&2
+            echo "       Enable it first: intelligence adapter enable $TARGET_FILTER" >&2
+            exit 1
+        fi
+        continue
+    fi
+
+    # Get output directory
+    output=$(get_target_output "$CONFIG_FILE" "$adapter")
+    if [ -z "$output" ]; then
+        output=".$adapter"
+    fi
+    output_dir="$REPO_ROOT/$output"
+
+    # Refuse to run if the output would clobber content — `output: "."`,
+    # `output: "intelligence"`, or a `../` path that escapes the repo. Applies
+    # to EVERY adapter, `agents` included: dir-writing adapters `rm -rf` their
+    # output, and `agents` overwrites whatever single file it is handed. Both
+    # turn a bad config line into a destructive write.
+    validate_output_path "$REPO_ROOT" "$CONFIG_FILE" "$adapter" "$output_dir"
+
+    # Source adapter and run.
+    # shellcheck source=/dev/null
+    source "$adapter_file"
+    "sync_to_$adapter" "$REPO_ROOT" "$CONFIG_FILE" "$output_dir"
+    echo ""
+    synced=$((synced + 1))
+done
+
+if [ $synced -eq 0 ]; then
+    if [ -n "$TARGET_FILTER" ]; then
+        echo "ERROR: Adapter '$TARGET_FILTER' not found."
+        echo "Available: ${ADAPTERS[*]}"
+    else
+        echo "WARNING: No targets enabled in $CONFIG_FILE"
+    fi
+    exit 1
+fi
+
+# Warn about unsynced directories
+warn_unsynced "$REPO_ROOT" "$CONFIG_FILE"
+
+# Report model overrides that drift from intelligence-sync defaults
+# (helpful when defaults move forward — e.g., gpt-5.5 -> gpt-5.6).
+report_model_drift "$CONFIG_FILE"
+
+echo ""
+# sync.sh never changes project schemas (the CLI preflight owns that), so
+# success is always ok.
+is_status ok "synced=$synced"
+echo "=== Done: $synced target(s) synced ==="

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainova-systems/intelligence",
-  "version": "0.11.0-rc.1",
+  "version": "0.11.0-rc.10",
   "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"
@@ -9,7 +9,7 @@
     "bin",
     "cli",
     "engine",
-    "registry"
+    "packages"
   ],
   "engines": {
     "node": ">=18"
@@ -17,11 +17,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ainova-systems/intelligence-sync.git"
+    "url": "git+https://github.com/ainova-systems/intelligence.git"
   },
-  "homepage": "https://github.com/ainova-systems/intelligence-sync#readme",
+  "homepage": "https://github.com/ainova-systems/intelligence#readme",
   "bugs": {
-    "url": "https://github.com/ainova-systems/intelligence-sync/issues"
+    "url": "https://github.com/ainova-systems/intelligence/issues"
   },
   "keywords": [
     "ai",

package/{engine → packages/sync}/agents/intelligence-architect.md

@@ -9,12 +9,13 @@ skills:
   - intelligence-add-skill
   - intelligence-extract-skill
   - intelligence-review-skills
+  - intelligence-learn-from-repository
   - intelligence-learn-from-context
 ---
 
 # Intelligence architect
 
-Owns `<umbrella>/` itself: what the layer is made of, and what it is allowed to grow into. Not the project's code — the instructions that shape how everyone else writes it.
+Owns `<content-dir>/` itself: what the layer is made of, and what it is allowed to grow into. Not the project's code — the instructions that shape how everyone else writes it.
 
 ## Expertise
 
@@ -45,9 +46,10 @@ The per-artifact checks are procedure, so they live in the meta-skills rather th
 | `intelligence-add-rule` / `intelligence-add-agent` / `intelligence-add-skill` | author one artifact |
 | `intelligence-extract-skill` | turn an observed workflow into a skill |
 | `intelligence-review-skills` | audit the layer for duplication, drift, size, hardcoded paths |
+| `intelligence-learn-from-repository` | propose the initial project-owned layer from repository evidence |
 | `intelligence-learn-from-context` | fold a session's lessons back into the layer |
 | `intelligence-sync` | project the source to every tool channel |
-| `intelligence-update` | update or migrate the engine |
-| `intelligence-install-adapter` / `intelligence-uninstall-adapter` | turn a tool channel on or off |
+| `intelligence-update` | interpret and apply the CLI's unified update plan |
+| `intelligence-install-adapter` / `intelligence-uninstall-adapter` | research and manage a tool adapter |
 
 A change is done when the sync is green and the skill you invoked reports clean. Size is a separate judgement: the caps are ceilings, not quotas, and a short artifact is not a defect.

package/{engine → packages/sync}/agents/intelligence-operator.md

@@ -1,6 +1,6 @@
 ---
 name: intelligence-operator
-description: "Run the engine's mechanical flows - sync, update, adapter install and removal"
+description: "Interpret CLI plans and operate sync, update, and adapter flows"
 tier: standard
 access: full
 skills:
@@ -12,20 +12,17 @@ skills:
 
 # Intelligence operator
 
-Operates the engine: projects the source tree to every enabled tool channel, updates or migrates the
-engine, turns tool channels on and off. What the layer contains - which rules, agents and skills
+Operates the CLI: projects the source tree to every enabled tool channel, interprets and applies update
+plans, and manages adapters. What the layer contains - which rules, agents and skills
 exist and what they say - is `intelligence-architect`'s judgement; this agent runs the machinery
 that ships it.
 
 ## Expertise
 
-The bash-to-skill status contract (`docs/CONVENTIONS.md`, Migration & Module Contract). Every flow
-here is deterministic and fail-closed: `sync.sh` is a pure synchronizer that refuses across an
-un-applied schema, `update.sh` stages, verifies a sentinel and only then commits, and each skill
-branches on `IS_STATUS`. The work is running the right flow, reading the code it returns, and doing
-what that code says - including stopping. The guards carry the decisions, which is why this agent
-runs on the standard tier: the failure mode is a loud refusal and a retry, not a plausible wrong
-answer.
+The CLI and engine status contract. Mechanical flows are deterministic and
+fail-closed; the agent reads their result, selects the next supported command,
+checks changelog post-conditions, and stops on a refusal instead of recreating
+the operation in prose.
 
 ## Boundaries
 
@@ -35,7 +32,7 @@ answer.
 - **Operating is not authoring.** A change to what an artifact says - a rule body, an agent persona,
   a skill's steps - belongs to `intelligence-architect` and the authoring meta-skills. This agent
   ships what exists and never decides what should exist.
-- **A state the engine refuses to resolve goes to a human.** `ambiguous` and every other non-ok
+- **A state the CLI refuses to resolve goes to a human.** `ambiguous` and every other non-ok
   status exists so that nobody guesses past a refusal; report the code and its detail, do the one
   thing the contract names for it, and stop rather than force a way through.
 
@@ -45,5 +42,5 @@ answer.
 <sync-cmd>          # expect IS_STATUS=ok
 ```
 
-Done is the invoked skill reporting its own success criteria met: `IS_STATUS=ok` (`migrated` counts,
-for an update), per-target counts matching the sources, and no warning left unhandled.
+Done is the invoked skill reporting its own success criteria met: `IS_STATUS=ok`,
+per-target counts matching the sources, and no warning left unhandled.