@ainova-systems/intelligence 0.11.4 → 0.11.5

package/cli/commands/sync.sh

@@ -57,9 +57,10 @@ if [ "$compact" -eq 0 ]; then
     exit $?
 fi
 
-# Compact mode is intentionally quiet only on success. Buffering the complete
-# combined stream means a failure still returns every diagnostic emitted by
-# lifecycle preflight, locked restore or the engine, together with its real rc.
+# Compact mode keeps actionable one-line warnings on success. Buffering the
+# complete combined stream means a failure still returns every diagnostic
+# emitted by lifecycle preflight, locked restore or the engine, together with
+# its real rc.
 compact_output="$(mktemp -t intelligence-sync-XXXXXX)"
 trap 'rm -f "$compact_output"' EXIT
 rc=0
@@ -76,5 +77,6 @@ if [ -z "$status_line" ] || [ -z "$done_line" ]; then
     echo "ERROR: sync succeeded without its final status contract" >&2
     exit 1
 fi
+grep -E '^(WARNING:|CONTEXT:)' "$compact_output" || true
 echo "$status_line"
 echo "$done_line"

package/cli/intelligence

@@ -47,7 +47,7 @@ Usage: intelligence <command> [args]
     --targets a,b --dir name --bare --no-sync   New-project options
     --force               Accept a dirty worktree during legacy project conversion
   sync [adapter] [--compact]  Restore locked content, then render enabled adapters
-    --compact            On success show only final status; on failure show diagnostics
+    --compact            On success show context, warnings and final status; on failure show diagnostics
   update [@scope/name]    Show an update plan; ask before applying it
     --preview             Show the plan without asking or writing
     --apply               Apply the plan without asking

package/engine/ENGINE_SHA

@@ -1 +1 @@
-a8e3accf49ce60d8e0b04f04bc68ef6f813f2a2e
+bd688bcdb5443d808a72ed4e63805a65255a7d02

package/engine/VERSION

@@ -1 +1 @@
-0.11.4
+0.11.5

package/engine/adapters/agents.sh

@@ -58,22 +58,11 @@ agents_md_append_agents_table() {
     local rows=""
     local count=0
 
-    local src f
+    local f
     local -a files=()
-    load_yaml_list "$config_file" "agents"
-    local list="$IS_YAML_LIST"
-    while IFS= read -r src; do
-        [ -z "$src" ] && continue
-        local dir="$repo_root/$src"
-        [ -d "$dir" ] || continue
-        # Byte-order (LC_ALL=C) sort so generated output is identical across
-        # platforms — bash glob order follows LC_COLLATE, which differs between
-        # Linux CI (UTF-8, ignores `-`) and Git Bash (C, byte order).
-        while IFS= read -r f; do
-            [ -f "$f" ] || continue
-            files+=("$f")
-        done < <(find "$dir" -maxdepth 1 -type f -name '*.md' -print | LC_ALL=C sort)
-    done <<< "$list"
+    while IFS= read -r f; do
+        [ -n "$f" ] && files+=("$f")
+    done < <(source_artifact_files "$repo_root" "$config_file" "agents")
 
     if [ "${#files[@]}" -gt 0 ]; then
         local path tier access desc name
@@ -112,24 +101,11 @@ agents_md_append_skills_table() {
     local rows=""
     local count=0
 
-    local src skill_dir dirname
+    local f dirname
     local -a skill_files=()
-    load_yaml_list "$config_file" "skills"
-    local list="$IS_YAML_LIST"
-    while IFS= read -r src; do
-        [ -z "$src" ] && continue
-        local dir="$repo_root/$src"
-        [ -d "$dir" ] || continue
-        # Byte-order (LC_ALL=C) sort so generated output is identical across
-        # platforms — see the note in agents_md_append_agents_table.
-        while IFS= read -r skill_dir; do
-            [ -d "$skill_dir" ] || continue
-            dirname="${skill_dir##*/}"
-            case "$dirname" in _*) continue ;; esac
-            [ -f "${skill_dir%/}/SKILL.md" ] || continue
-            skill_files+=("${skill_dir%/}/SKILL.md")
-        done < <(find "$dir" -mindepth 1 -maxdepth 1 -type d -print | LC_ALL=C sort)
-    done <<< "$list"
+    while IFS= read -r f; do
+        [ -n "$f" ] && skill_files+=("$f")
+    done < <(source_artifact_files "$repo_root" "$config_file" "skills")
 
     if [ "${#skill_files[@]}" -gt 0 ]; then
         local path desc
@@ -169,22 +145,11 @@ agents_md_append_rules_list() {
     local count=0
     local global_rule_files=()
 
-    local src f
+    local f
     local -a files=()
-    load_yaml_list "$config_file" "rules"
-    local list="$IS_YAML_LIST"
-    while IFS= read -r src; do
-        [ -z "$src" ] && continue
-        local dir="$repo_root/$src"
-        [ -d "$dir" ] || continue
-        # Byte-order (LC_ALL=C) sort so generated output — and the inline order
-        # of always-on rules below — is identical across platforms. See the
-        # note in agents_md_append_agents_table.
-        while IFS= read -r f; do
-            [ -f "$f" ] || continue
-            files+=("$f")
-        done < <(find "$dir" -maxdepth 1 -type f -name '*.md' -print | LC_ALL=C sort)
-    done <<< "$list"
+    while IFS= read -r f; do
+        [ -n "$f" ] && files+=("$f")
+    done < <(source_artifact_files "$repo_root" "$config_file" "rules")
 
     if [ "${#files[@]}" -gt 0 ]; then
         local path hp name scope
@@ -251,10 +216,8 @@ agents_md_append_rules_list() {
 
 # Main entry point for AGENTS.md adapter
 adapter_contract_agents() {
-    local output="$1"
-    if [[ "$output" == */ ]] || [[ "$output" != *.md ]]; then
-        output="${output%/}/AGENTS.md"
-    fi
+    local output
+    output="$(agents_output_path "$1")"
     adapter_contract_version 1
     adapter_contract_owned "$output"
     adapter_contract_legacy "AGENTS.md"
@@ -271,10 +234,8 @@ sync_to_agents() {
     # If it looks like a directory lexically (trailing slash or no .md
     # extension), append the default filename. The ownership contract uses the
     # same rule, so filesystem state cannot make its write-set ambiguous.
-    local output_file="$output_dir"
-    if [[ "$output_file" == */ ]] || [[ "$output_file" != *.md ]]; then
-        output_file="${output_file%/}/AGENTS.md"
-    fi
+    local output_file
+    output_file="$(agents_output_path "$output_dir")"
 
     mkdir -p "$(dirname "$output_file")"
 

package/engine/adapters/codex.sh

@@ -26,6 +26,44 @@ adapter_contract_codex() {
     adapter_contract_ignore "$output/agents/"
 }
 
+# Codex-specific guard for its documented project-instruction byte budget.
+# A personal/project Codex config may already raise the actual limit, so the
+# manifest exposes one warning setting: false disables it, while a positive
+# byte count matches an effective limit the adapter cannot discover itself.
+codex_warn_project_doc_size() {
+    local repo_root="$1"
+    local config_file="$2"
+    local warning_setting warning_limit=32768
+    warning_setting="$(get_target_field "$config_file" "codex" "warn_project_doc_limit")"
+    case "$warning_setting" in
+        ''|true) ;;
+        false) return 0 ;;
+        *[!0-9]*|0|0*)
+            echo "ERROR: targets.codex.warn_project_doc_limit must be true, false, or a positive byte count without leading zeros." >&2
+            return 1
+            ;;
+        *) warning_limit="$warning_setting" ;;
+    esac
+
+    target_output_var "$config_file" "agents"
+    local output
+    output="$(agents_output_path "${IS_TGT_OUTPUT:-.agents}")"
+
+    local output_file="$repo_root/$output"
+    [ -f "$output_file" ] || return 0
+
+    local bytes
+    bytes="$(context_files_bytes "$output_file")"
+    [ "$bytes" -gt "$warning_limit" ] || return 0
+
+    local recommended="$warning_limit"
+    while [ "$recommended" -lt "$bytes" ]; do
+        recommended=$((recommended * 2))
+    done
+
+    echo "WARNING: Codex may truncate $output: $bytes bytes exceeds the $warning_limit-byte Intelligence warning threshold; set project_doc_max_bytes = $recommended in Codex config.toml and restart Codex, reduce/split the instructions, set targets.codex.warn_project_doc_limit to the effective byte limit, or set it to false to disable this warning."
+}
+
 # Sync skills to Codex format (.agents/skills/{name}/SKILL.md)
 sync_codex_skills() {
     local repo_root="$1"
@@ -117,4 +155,6 @@ sync_to_codex() {
     rm -rf "$agents_dir"
     mkdir -p "$agents_dir"
     sync_codex_agents "$repo_root" "$config_file" "$agents_dir"
+
+    codex_warn_project_doc_size "$repo_root" "$config_file"
 }

package/engine/lib/common.sh

@@ -641,23 +641,16 @@ sync_open_skill_dirs() {
     fi
     mkdir -p "$output_dir"
 
-    local count=0 log="" d skill_name src list
+    local count=0 log="" d skill_file skill_name
     local -a skill_dirs=()
-    load_yaml_list "$config_file" "skills"
-    list="$IS_YAML_LIST"
-    while IFS= read -r src; do
-        [ -z "$src" ] && continue
-        local dir="$repo_root/$src"
-        [ -d "$dir" ] || continue
-        for d in "$dir"/*/; do
-            [ -d "$d" ] || continue
-            skill_name="${d%/}"; skill_name="${skill_name##*/}"
-            [ -f "$d/SKILL.md" ] || continue
-            skill_dirs+=("$d")
-            count=$((count + 1))
-            log+="  skill: $skill_name"$'\n'
-        done
-    done <<< "$list"
+    while IFS= read -r skill_file; do
+        [ -n "$skill_file" ] || continue
+        d="${skill_file%/SKILL.md}"
+        skill_name="${d##*/}"
+        skill_dirs+=("$d/")
+        count=$((count + 1))
+        log+="  skill: $skill_name"$'\n'
+    done < <(source_artifact_files "$repo_root" "$config_file" "skills")
     # copy_skill_bundle_dirs owns the frontmatter-quoting pass, so every
     # target gets it — not just this open-standard dir.
     if [ "$count" -gt 0 ]; then
@@ -1335,6 +1328,109 @@ warn_unsynced() {
     fi
 }
 
+# Enumerate one manifest source kind using the same depth and ordering
+# everywhere. Source-list order is significant; entries inside each directory
+# use byte-order sorting for cross-platform determinism.
+source_artifact_files() {
+    local repo_root="$1"
+    local config_file="$2"
+    local section="$3"
+    local src f dir
+
+    load_yaml_list "$config_file" "$section"
+    while IFS= read -r src; do
+        [ -n "$src" ] || continue
+        dir="$repo_root/$src"
+        [ -d "$dir" ] || continue
+        case "$section" in
+            rules|agents)
+                find "$dir" -maxdepth 1 -type f -name '*.md' -print | LC_ALL=C sort
+                ;;
+            skills)
+                while IFS= read -r f; do
+                    [ -n "$f" ] || continue
+                    [ -f "$f/SKILL.md" ] && printf '%s\n' "$f/SKILL.md"
+                done < <(find "$dir" -mindepth 1 -maxdepth 1 -type d -print | LC_ALL=C sort)
+                ;;
+        esac
+    done <<< "$IS_YAML_LIST"
+}
+
+# Apply the agents adapter's lexical output rule without consulting filesystem
+# state. An omitted output uses the generic adapter default directory.
+agents_output_path() {
+    local output="${1:-.agents}"
+    if [[ "$output" == */ ]] || [[ "$output" != *.md ]]; then
+        output="${output%/}/AGENTS.md"
+    fi
+    printf '%s\n' "$output"
+}
+
+# Report source prompt pressure independently of adapter formats. "Always-on"
+# means rules without paths; "custom" means scoped rules, agent prompts and
+# skill entry points. Supporting skill assets are excluded because tools load
+# them only when a skill explicitly reads them. When the shared agents target
+# exists, also report its rendered size; policy for any tool-specific limit
+# stays in that tool's adapter.
+context_files_bytes() {
+    if [ "$#" -eq 0 ]; then
+        echo 0
+        return 0
+    fi
+    LC_ALL=C wc -c "$@" | awk 'END { print $1 + 0 }'
+}
+
+report_context_source_sizes() {
+    local repo_root="$1"
+    local config_file="$2"
+    local f path has_paths
+    local -a rule_files=() always_on_rules=() scoped_rules=() agent_files=() skill_files=()
+
+    while IFS= read -r f; do
+        [ -n "$f" ] && rule_files+=("$f")
+    done < <(source_artifact_files "$repo_root" "$config_file" "rules")
+    if [ "${#rule_files[@]}" -gt 0 ]; then
+        while IFS=$'\x1f' read -r path has_paths; do
+            [ -n "$path" ] || continue
+            if [ "$has_paths" = "0" ]; then
+                always_on_rules+=("$path")
+            else
+                scoped_rules+=("$path")
+            fi
+        done < <(frontmatter_index "paths#" "${rule_files[@]}")
+    fi
+
+    while IFS= read -r f; do
+        [ -n "$f" ] && agent_files+=("$f")
+    done < <(source_artifact_files "$repo_root" "$config_file" "agents")
+
+    while IFS= read -r f; do
+        [ -n "$f" ] && skill_files+=("$f")
+    done < <(source_artifact_files "$repo_root" "$config_file" "skills")
+
+    local always_bytes custom_bytes agents_output agents_bytes=0 agents_status="disabled"
+    always_bytes="$(context_files_bytes "${always_on_rules[@]+"${always_on_rules[@]}"}")"
+    custom_bytes="$(context_files_bytes \
+        "${scoped_rules[@]+"${scoped_rules[@]}"}" \
+        "${agent_files[@]+"${agent_files[@]}"}" \
+        "${skill_files[@]+"${skill_files[@]}"}")"
+    target_enabled_var "$config_file" "agents"
+    if [ "$IS_TGT_ENABLED" = "1" ]; then
+        agents_status="not-generated"
+        target_output_var "$config_file" "agents"
+        agents_output="$(agents_output_path "${IS_TGT_OUTPUT:-.agents}")"
+        if [ -f "$repo_root/$agents_output" ]; then
+            agents_bytes="$(context_files_bytes "$repo_root/$agents_output")"
+            agents_status="generated"
+        fi
+    fi
+
+    printf 'CONTEXT: always-on=%s bytes (%s rules); custom=%s bytes (%s scoped rules, %s agents, %s skills); agents-md=%s bytes; agents-md-status=%s\n' \
+        "$always_bytes" "${#always_on_rules[@]}" "$custom_bytes" \
+        "${#scoped_rules[@]}" "${#agent_files[@]}" "${#skill_files[@]}" \
+        "$agents_bytes" "$agents_status"
+}
+
 # --- Config Parsing ---
 
 # Read a simple list from config.yaml
@@ -1415,9 +1511,9 @@ load_yaml_list() {
 
 # load_targets_cache <file> — parse the whole targets: section once into the
 # global IS_TGT_TSV (one `name<TAB>enabled<TAB>output` row per target),
-# replicating is_target_enabled and get_target_output semantics: inline and
-# block forms, first occurrence wins, `enabled` defaults to 0 when the block
-# ends without one and to empty at end of file. The engine warms this once;
+# matching is_target_enabled and get_target_output semantics: inline and block
+# forms, first occurrence wins, `enabled` defaults to 0 when the block ends
+# without one and to empty at end of file. The engine warms this once;
 # both readers consult it before spawning awk.
 load_targets_cache() {
     local file="$1"
@@ -1433,20 +1529,9 @@ load_targets_cache() {
         }
         { sub(/\r$/, "") }
         /^targets:[[:space:]]*$/ { in_targets = 1; next }
-        /^[a-zA-Z]/ { in_targets = 0 }
-        # The per-target readers scanned forward for the FIRST line containing
-        # `enabled:` / `output:` after the target header, checking it before
-        # the block-end test — so a sibling header line could donate its own
-        # inline values to a block that lacked them. These two rules run
-        # before the header rule below to keep that reading.
-        name != "" && enabled == "" && /enabled:/ {
-            enabled = ($0 ~ /true/) ? 1 : 0
-        }
-        name != "" && output == "" && /output:/ {
-            val = $0
-            sub(/.*output:[[:space:]]*["\047]?/, "", val)
-            sub(/["\047]?[[:space:]]*}?$/, "", val)
-            output = val
+        /^[a-zA-Z]/ {
+            if (in_targets) flush_target(0)
+            in_targets = 0
         }
         in_targets && $0 ~ /^  [a-zA-Z0-9_-]+:/ {
             flush_target(1)
@@ -1465,7 +1550,15 @@ load_targets_cache() {
             }
             next
         }
-        name != "" && /^  [a-zA-Z]/ { flush_target(1) }
+        name != "" && enabled == "" && /^    enabled:/ {
+            enabled = ($0 ~ /true/) ? 1 : 0
+        }
+        name != "" && output == "" && /^    output:/ {
+            val = $0
+            sub(/.*output:[[:space:]]*["\047]?/, "", val)
+            sub(/["\047]?[[:space:]]*}?$/, "", val)
+            output = val
+        }
         END { flush_target(0) }
     ' "$file")"
     IS_TGT_FILE="$file"
@@ -1530,6 +1623,7 @@ is_target_enabled() {
 
         # Enter/leave the targets: section
         /^targets:[[:space:]]*$/ { in_targets = 1; next }
+        in_target && /^[a-zA-Z]/ { exit }
         /^[a-zA-Z]/ { in_targets = 0 }
 
         in_targets && $0 ~ "^  " target ":" {
@@ -1537,11 +1631,11 @@ is_target_enabled() {
             if ($0 ~ /enabled:[[:space:]]*false/) { print 0; exit }
             in_target = 1; next
         }
-        in_target && /enabled:/ {
+        in_target && /^  [a-zA-Z0-9_-]+:/ { print 0; exit }
+        in_target && /^    enabled:/ {
             if ($0 ~ /true/) { print 1 } else { print 0 }
             exit
         }
-        in_target && /^  [a-zA-Z]/ { print 0; exit }
     ' "$file"
 }
 
@@ -1556,6 +1650,7 @@ get_target_field() {
     awk -v target="$target" -v field="$field" '
         { sub(/\r$/, "") }
         /^targets:[[:space:]]*$/ { in_targets = 1; next }
+        in_target && /^[a-zA-Z]/ { exit }
         /^[a-zA-Z]/ { in_targets = 0 }
 
         in_targets && $0 ~ "^  " target ":" {
@@ -1601,6 +1696,7 @@ get_target_output() {
         { sub(/\r$/, "") }
 
         /^targets:[[:space:]]*$/ { in_targets = 1; next }
+        in_target && /^[a-zA-Z]/ { exit }
         /^[a-zA-Z]/ { in_targets = 0 }
 
         in_targets && $0 ~ "^  " target ":" {
@@ -1616,14 +1712,14 @@ get_target_output() {
             }
             in_target = 1; next
         }
-        in_target && /output:/ {
+        in_target && /^  [a-zA-Z0-9_-]+:/ { exit }
+        in_target && /^    output:/ {
             val = $0
             sub(/.*output:[[:space:]]*["\047]?/, "", val)
             sub(/["\047]?[[:space:]]*}?$/, "", val)
             print val
             exit
         }
-        in_target && /^  [a-zA-Z]/ { exit }
     ' "$file"
 }
 

package/engine/sync.sh

@@ -311,6 +311,9 @@ trap - EXIT INT TERM
 # Warn about unsynced directories
 warn_unsynced "$REPO_ROOT" "$CONFIG_FILE"
 
+# Report adapter-agnostic source context pressure on every successful sync.
+report_context_source_sizes "$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"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainova-systems/intelligence",
-  "version": "0.11.4",
+  "version": "0.11.5",
   "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/agents/intelligence-architect.md

@@ -8,6 +8,7 @@ skills:
   - intelligence-add-agent
   - intelligence-add-skill
   - intelligence-extract-skill
+  - intelligence-compact-context
   - intelligence-review-skills
   - intelligence-learn-from-repository
   - intelligence-learn-from-context
@@ -45,6 +46,7 @@ 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-compact-context` | reduce context without changing behavior or teaching terse output |
 | `intelligence-review-skills` | audit the layer for duplication, drift, size, hardcoded paths |
 | `intelligence-learn-from-repository` | recover and complete first-time repository onboarding |
 | `intelligence-learn-from-context` | fold one later session lesson into an established layer |

package/packages/sync/references/adapters.md

@@ -172,6 +172,10 @@ Intelligence routes always-on rules once through `AGENTS.md` for tools that cons
 
 If a new adapter relies on `AGENTS.md` for always-on rules, its target must require `agents`. Add that invariant to `engine/sync.sh` when contributing the adapter upstream.
 
+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.
+
+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`.
+
 ### Skills
 
 Skills follow the [Agent Skills standard](https://agentskills.io). Copy each skill directory as a complete bundle—not only `SKILL.md`—because its body may reference `references/`, `scripts/` or `assets/` beside it.

package/packages/sync/references/conventions.md

@@ -385,7 +385,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]` first aligns an existing Intelligence project with the installed CLI, restores a missing store strictly from `intelligence.lock`, then renders. Compact mode shows only 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]` first aligns an existing Intelligence project with the installed CLI, restores a missing store strictly from `intelligence.lock`, then renders. 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 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 package add|remove|list|search` owns package inventory.
 - `intelligence adapter list|create|enable|disable|remove` owns adapter inventory and target state.

package/packages/sync/rules/intelligence-authoring.md

@@ -60,7 +60,7 @@ The mistakes that actually happen, in order of frequency:
 
 ### Invariants
 
-- **Never state behaviour of a tool or engine you have not verified in its documentation or source.** This invariant exists because the claim *"Claude Code does not auto-load `.claude/rules/`"* was once written into this layer as fact. It is false — rules without `paths:` load at launch, path-scoped ones activate on matching files, and custom subagents inherit both (Claude Code docs: *Memory → Organize rules with `.claude/rules/`*, and *Subagents → What loads at startup*). An unverified claim about tooling is worse than a gap: nothing in the repository contradicts it, so it silently reshapes every decision downstream.
+- **Never state behaviour of a tool or engine you have not verified in its documentation or source.** An unverified claim about tooling is worse than a gap: nothing in the repository contradicts it, so it silently reshapes every decision downstream. Verified means a page you can cite - for how rules load, the Claude Code docs *Memory → Organize rules with `.claude/rules/`* and *Subagents → What loads at startup*.
 - **Never write a current defect into a rule as if it were the design.** Known breakage belongs in one place that says so. Every other rule describes the project *as it is meant to work* — a workaround documented as procedure becomes permanent.
 - **Never link from one always-on rule to another.** Always-on rules are inlined verbatim into `AGENTS.md`, and the path-scoped channels carry only scoped rules, so a relative link is dead in at least one output. Name the rule instead; it loads on its own.
 

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

@@ -0,0 +1,118 @@
+---
+name: intelligence-compact-context
+description: "Reduce rules, agents, and skills without changing behavior or teaching terse output"
+argument-hint: "[target: rules|agents|skills|all]"
+agent: intelligence-architect
+---
+
+# Compact intelligence context
+
+Reduce persistent and on-demand prompt cost by changing structure before wording.
+The result must preserve the layer's behavioral contract and ordinary, complete
+language; a smaller file is not a success if agents become terse, vague, or less
+reliable.
+
+## Analyze
+
+1. Resolve `<manifest>`, `<content-dir>`, and `<module>`. Enumerate the source
+   directories declared under `sources.rules`, `sources.agents`, and
+   `sources.skills`; skip installed package sources and generated adapter output.
+
+2. Read `<module>/references/conventions.md`, the `intelligence-authoring` rule,
+   and [references/principles.md](references/principles.md). The reference
+   explains which forms of indirection save context and which merely move text.
+
+3. Run `<sync-cmd> --compact` and save the `CONTEXT:` line as the baseline,
+   including its rendered `agents-md` byte count. Record individual source-file
+   byte and line counts for the requested target.
+
+4. Invoke `intelligence-review-skills` for the same target. Reuse its findings
+   for duplication, misplaced content, scope, stale artifacts, pressure markers,
+   history narrative, and description budget; do not reproduce its audit.
+
+5. Build a semantic ledger before drafting edits. For every candidate passage,
+   record:
+
+   - the behavior, constraint, procedure, or expertise it carries;
+   - its one authoritative owner;
+   - when it must load;
+   - the reason or example needed to apply it correctly;
+   - the repository evidence or external documentation that supports it.
+
+   Two passages are duplicates only when those meanings match. Similar wording
+   with different scope, priority, or failure behavior is not duplication.
+
+## Draft the compaction
+
+6. Apply structural reductions in this order:
+
+   1. Replace an instruction with a deterministic gate or command when the
+      repository already enforces it.
+   2. Delete generic knowledge and facts the agent can read directly from the
+      repository, unless a non-obvious interpretation is the instruction.
+   3. Keep one owner for duplicated guidance and remove the copies. A skill may
+      invoke another skill by name; an agent may list a skill; neither restates
+      the called artifact.
+   4. Add `paths:` to rules that matter only in part of the repository.
+   5. Move multi-step procedures from rules or agents into skills, and move
+      reusable constraints or expertise to the artifact type that owns them.
+   6. Move optional skill detail into skill-local `references/` and state the
+      exact condition that requires each file. Do not use an always-loaded
+      import or an unconditional read step and call that compaction.
+   7. Tighten prose only after the preceding reductions are exhausted.
+
+7. Preserve language quality while tightening prose:
+
+   - Use complete grammatical sentences and ordinary project vocabulary.
+   - Preserve the reason when it guides judgment, and keep one minimal example
+     when the rule would otherwise be ambiguous.
+   - Preserve triggers, boundaries, ordering, failure behavior, verification,
+     and output contracts exactly.
+   - Shorten descriptions by retaining the unique trigger that distinguishes a
+     sibling; never reduce them to vague labels.
+   - Do not add instructions telling agents to be terse, abbreviated, clipped,
+     or concise unless that response style is an explicit product requirement.
+   - Do not turn prose into fragments, dense acronyms, slash-separated phrases,
+     or unexplained labels. Compression targets redundancy, not grammar.
+
+8. Treat references according to load behavior:
+
+   - A conditional skill reference saves startup context.
+   - An always-loaded import improves organization but does not save context.
+   - A plain link is navigation, not guaranteed instruction loading; never hide
+     a critical constraint behind one.
+   - An always-on rule that is too large normally needs deletion, scoping, a
+     gate, or conversion of its procedure into a skill—not a reference index.
+
+## Approval and apply
+
+9. Present a proposal grouped as `DELETE`, `MERGE`, `SCOPE`, `MOVE`,
+   `REFERENCE`, or `REWRITE`. For each item show the owner, semantic contract,
+   estimated bytes saved, and any behavior that could change. Ask for approval
+   before changing meaning, ownership, scope, or load timing.
+
+10. Apply only accepted items to project-owned sources. Preserve unapproved
+    passages byte-for-byte and never edit generated output or installed package
+    sources locally.
+
+## Verify
+
+11. Compare the semantic ledger with the diff. Every original behavior must be
+    present once in its authoritative owner, deliberately removed with approval,
+    or enforced by the named deterministic mechanism. Check that no move created
+    a dead link, unconditional reference load, conflicting instruction, or
+    broader scope.
+
+12. Run `<sync-cmd> --compact`, require `IS_STATUS=ok`, then run
+    `intelligence status --check`. Compare the new `CONTEXT:` line and per-file
+    counts with the baseline.
+
+13. Exercise three representative prompts when the environment supports agent
+    evaluation: one direct case governed by a compacted instruction, one adjacent
+    judgment case that needs its reason, and one ordinary explanation that would
+    reveal clipped language. If behavioral evaluation is unavailable, report
+    that explicitly; a smaller byte count proves size reduction, not quality.
+
+14. Report bytes and percentage saved for always-on and custom context, the
+    before-and-after `agents-md` size, the artifacts changed, the semantic
+    checks performed, and any remaining item that needs an owner decision.

package/packages/sync/skills/intelligence-compact-context/references/principles.md

@@ -0,0 +1,58 @@
+# Context compaction principles
+
+Use these principles to decide what to remove, relocate, or keep. They summarize
+current primary guidance; they do not replace repository evidence or an
+artifact's semantic ledger.
+
+## What consistently improves instruction context
+
+- Keep persistent instructions specific, focused, and grounded in behavior the
+  agent would otherwise miss. Current vendor guidance consistently recommends
+  removing unclear or conflicting instructions because they reduce adherence.
+- Scope narrow guidance so it loads only for matching work. Anthropic, GitHub,
+  and Cursor all recommend path-specific rules instead of making framework or
+  component guidance repository-wide.
+- Prefer one authoritative statement. Duplicate instructions spend context;
+  slightly different copies can also become a conflict whose winner is
+  unpredictable.
+- Keep what is non-obvious: project conventions, pitfalls, rationale, failure
+  behavior, and evidence-backed exceptions. Remove generic tutorials and facts
+  the agent can obtain directly from code or configuration.
+- Use progressive disclosure for skills. Keep the executable core in
+  `SKILL.md`; move optional detail to a nearby reference and name the exact
+  condition under which the agent reads it.
+- Test changes on representative work. Instruction quality is behavioral, so a
+  byte reduction alone cannot prove that meaning or adherence survived.
+
+## References are not automatically compression
+
+Indirection saves context only when the target is not loaded until it is needed.
+Anthropic explicitly notes that `@path` imports still enter startup context. A
+plain Markdown link has the opposite risk: some tools will not load it at all.
+
+Use a reference when all three conditions hold:
+
+1. the parent artifact remains actionable without the detail;
+2. the parent gives a precise condition for reading the reference; and
+3. every adapter that needs the detail copies or can resolve the reference.
+
+This works naturally for skill-local `references/`. It is usually the wrong fix
+for an always-on rule: scope the rule, convert its procedure to a skill, enforce
+it mechanically, or delete redundant material instead.
+
+## Preserve natural language
+
+Compaction changes the information architecture, not the desired voice of the
+agent. Keep complete sentences, clear headings, reasons that support judgment,
+and one concrete example where it prevents ambiguity. Do not achieve a smaller
+file by instructing the agent to answer tersely or by rewriting the source into
+telegraphic fragments. Persistent instructions shape behavior as well as task
+decisions, so clipped source language is a quality risk rather than a valid
+optimization.
+
+## Primary sources
+
+- [Claude Code memory documentation](https://code.claude.com/docs/en/memory) — specific instructions, path scoping, conflict removal, and why imports do not reduce startup context.
+- [Agent Skills best practices](https://agentskills.io/skill-creation/best-practices) — omit generic knowledge, keep coherent units, and use conditional progressive disclosure.
+- [GitHub Copilot custom-instruction guidance](https://docs.github.com/en/copilot/tutorials/customize-code-review) — short, focused instructions, path-specific files, concrete examples, and iteration.
+- [Cursor rules documentation](https://docs.cursor.com/context/rules) — focused, actionable, scoped rules and composable rule files.

package/packages/sync/skills/intelligence-review-skills/SKILL.md

@@ -19,23 +19,26 @@ The name uses "skills" as shorthand for all AI artifacts (rules, agents, and ski
 
 3. **Skip installed package sources.** Sources under `<module>/` (`<module>/rules`, `<module>/agents`, `<module>/skills/intelligence-*`) are package-owned and restored by CLI lifecycle operations, so a local "fix" is not durable. Never propose a project-local edit to them. If one is wrong, make an upstream proposal instead.
 
-4. **Never read or edit generated output** (`.claude/`, `.cursor/`, `.github/`, `.codex/`, `.agents/`, `.pi/`, `.opencode/`, `AGENTS.md`). Sync owns those entirely; the finding always belongs to the source.
+4. **Never read or edit generated output** (`.claude/`, `.cursor/`, `.github/`, `.codex/`, `.agents/`, `.pi/`, `.opencode/`, `AGENTS.md`). Sync owns those entirely; the finding always belongs to the source. Reading its byte count from sync's `CONTEXT:` summary or a byte-count command is the metadata-only exception—do not open the output to audit its prose.
 
 ## Steps
 
 5. **Pull git history** (when available) for each artifact — last edit, edit count, first-add date. A stale candidate has no recent edits *and* nothing cross-referencing it.
 
-6. **Run the detection checks.** Judgement decides; the checks only make a finding evidence rather than an impression.
+6. **Run the detection checks.** Resolve the shared agents target output from `<manifest>` and measure only its byte count; use the `agents-md` value when a fresh `CONTEXT:` summary is already available. Apply the shared instruction budget below, but do not run sync during this read-only audit. Judgement decides; the checks only make a finding evidence rather than an impression.
 
    | Check | What it is | Proposed action |
    |---|---|---|
    | **Duplicate content** | Two artifacts cover overlapping scope, or their descriptions share trigger phrases | `MERGE` — present both, propose one |
    | **Misplaced content** | A checklist or procedure in an agent body; a convention in an agent; a workflow in a rule; expertise in a skill (the *Pick the right artifact* table in `intelligence-authoring`) | `MOVE` — a move, not a rewrite: both files change together |
    | **Over the cap** | `SKILL.md` over 1000 lines, rule over 500, agent over 200 | `SPLIT` — two artifacts, or move detail into `references/<topic>.md` |
+   | **Shared instruction budget** | The measured shared agents output, or `agents-md` in sync's `CONTEXT:` summary, is over 32 KiB (32,768 bytes) | `COMPACT` — this is Intelligence's recommended maximum, not an adapter rejection threshold; use `intelligence-compact-context` to reduce the owning sources without teaching terse output |
    | **Rule links to a rule** | A markdown link from one rule to another (`R1`) | `UNLINK` — name the rule instead: always-on rules are inlined into `AGENTS.md` and the scoped channels carry only scoped rules, so the link is dead in at least one output |
    | **Machine facts in a rule** | OS, shell, editor or a local absolute path (`R2`) | `MOVE` — these belong in a personal, gitignored `CLAUDE.md`; a rule is committed and read by everyone, including whoever is on another platform |
    | **Literal path or command in a skill** | A path *outside the skill's own folder* baked into a procedure (`R3`) | `PARAMETERIZE` — a skill is *executed*, so a literal path breaks the moment the layout moves; resolve it from a rule or from `<manifest>`. **Exempt:** the skill's own bundle (`references/`, `scripts/`, `assets/` — content is co-located with its skill by default); rules and agents (describing the repository is their job); an example inside an output-format block; the resolution step itself |
    | **Skill with no verification** | Nothing at the end proves the procedure worked (`R4`) | `FLAG` — a procedure that proves nothing is a note, or just the work: give it a verification, or delete it |
+   | **Pressure marker** | A heading or section named CRITICAL / MANDATORY / HARD RULE / READ FIRST, or a density of `MUST` / `NEVER` / `ALWAYS` with no reason beside it (`R5`) | `REWRITE` - plain heading, one reason per constraint; when several instructions are each marked critical the marker stops carrying information, so keep emphasis for the one instruction demonstrably under-weighted without it |
+   | **History narrative** | A PR number, incident id, commit SHA, date or "this session" inside a rule body (`R6`) | `REWRITE` - keep the causal sentence, drop the archaeology; a rule's authority is the behaviour it prescribes, and git history keeps the date |
    | **Reserved prefix** | A project artifact named `intelligence-*` | `RENAME` — the prefix belongs to the sync package and collides in generated output |
    | **Naming** | A skill that is not `<domain>-<verb>-<noun>`, or a domain invented rather than reused | `RENAME` — or introduce the new domain deliberately |
    | **Stale** | No edits in 6+ months and nothing cross-references it | `ARCHIVE` — move to `<content-dir>/_archive/` |
@@ -50,6 +53,9 @@ The name uses "skills" as shorthand for all AI artifacts (rules, agents, and ski
    Detection commands, portable on purpose — no `\b` and no `-P`, so the same command works in Git Bash on Windows, on macOS (BSD grep) and on Linux. Run each over the source directories resolved in step 2, never over generated output:
 
    ```sh
+   # Shared instruction budget — resolve this output path from <manifest>
+   wc -c "<agents-output>"
+
    # R1 — a markdown link from one rule to another
    grep -rnE '\]\([^)]*\.md\)' <rule-dirs>
 
@@ -62,9 +68,17 @@ The name uses "skills" as shorthand for all AI artifacts (rules, agents, and ski
 
    # R4 — skills whose body never mentions verifying anything (-L lists files with NO match)
    grep -riLE --include=SKILL.md 'verif|expect|assert|check|test|IS_STATUS' <skill-dirs>
+
+   # R5 - pressure markers: a heading or label named for urgency, then absolute-language density per file
+   grep -rnE '^#+ .*(CRITICAL|MANDATORY|HARD RULE|READ FIRST)|\((CRITICAL|MANDATORY|HARD RULE)\)' <rule-dirs> <agent-dirs> <skill-dirs>
+   grep -rcE '(MUST|NEVER|ALWAYS)' <rule-dirs> <agent-dirs> <skill-dirs> | grep -vE ':0$'
+
+   # R6 - history narrative in a rule body: PR numbers, incident ids, dates, "this session", commit SHAs
+   grep -rniE -e '(#|PR )[0-9]{3,}' -e '[0-9]{4}-[0-9]{2}-[0-9]{2}' -e 'this session|origin session' \
+     -e '`[0-9a-f]{7,40}`' <rule-dirs>
    ```
 
-   `R4` is a coarse net, not a verdict: a skill that merely *mentions* a verification command anywhere passes it. Read the final step of every skill regardless — the question is whether something at the end **proves the work landed**, not whether the word appears.
+   `R4` is a coarse net, not a verdict: a skill that merely *mentions* a verification command anywhere passes it. Read the final step of every skill regardless — the question is whether something at the end **proves the work landed**, not whether the word appears. So are `R5` and `R6`: a `NEVER` that carries its reason and a date inside a frontmatter template are both legitimate hits, and the row's action applies only where the marker or the id is doing no work.
 
 7. **Ask subtraction first.** Before proposing any `SPLIT`, `REWRITE` or `PATCH`, ask whether the artifact should exist at all, whether two should become one, and whether the rule could be replaced by a gate the model cannot skip. A deletion is a better outcome than a tidy-up, and the punch-list should say so when it is true.
 
@@ -84,3 +98,4 @@ The user accepts items individually; bulk-accept for low-impact tweaks is fine.
 
 - `intelligence-learn-from-context` — single-session lesson capture; this skill delegates accepted edits to its Phase B
 - `intelligence-extract-skill` — when the audit surfaces a workflow that should become a skill
+- `intelligence-compact-context` — approval-gated structural compaction when the shared instruction budget or source size needs reduction