@ainova-systems/intelligence 0.21.0 → 0.22.0

package/cli/commands/sync.sh

@@ -106,6 +106,10 @@ run_check() {
             die "no intelligence project found here - run 'intelligence init'"
             ;;
     esac
+    # A check marks the lock it holds, so a sync started meanwhile waits for
+    # it instead of refusing (sync-lock.sh).
+    # shellcheck disable=SC2034  # read by sync-lock.sh when the lock is taken
+    SYNC_LOCK_KIND=check
     hold_project
     project_preflight "$IP_ROOT" || return $?
     if project_needs_upgrade "$IP_ROOT"; then
@@ -144,6 +148,11 @@ fi
 compact_output="$(mktemp -t intelligence-sync-XXXXXX)"
 trap 'rm -f "$compact_output"' EXIT
 rc=0
+# The one line that must not wait for the buffer: a wait for a check holding
+# the lock can last minutes (sync-lock.sh). Descriptor 9 keeps the real stderr.
+exec 9>&2
+# shellcheck disable=SC2034  # read by sync-lock.sh while the lock is taken
+IS_LOCK_NOTICE_FD=9
 (run_sync) > "$compact_output" 2>&1 || rc=$?
 if [ "$rc" -ne 0 ]; then
     cat "$compact_output" >&2

package/cli/lib/sync-lock.sh

@@ -12,9 +12,25 @@
 # join instead of refusing, and a holder that died can be told from one whose
 # writers still run. Taking over a dead holder's lock happens under a second
 # lock, so two runs that judged the same lock stale cannot both take it.
+#
+# `sync --check` holds the lock too, because it may restore the package store
+# and compares a copy of the live outputs. It writes nothing a person keeps, so
+# a holder that is a check marks its lock with a `kind` file, and a writing
+# command that finds such a holder waits for it instead of refusing (decision
+# 0022): a status check that runs every few minutes must never make the
+# person's own sync fail. A check never waits in line — it refuses any holder
+# at once — so it is never queued behind a writer; one that arrives as a lock is
+# released can still take it first, and the waiting writer's bound then starts
+# again for that check. A writing holder is refused at once, as before.
 
 SYNC_LOCK_HELD=""
 SYNC_LOCK_TOKEN=""
+# What this process takes the lock for: "check" for `sync --check`, empty for
+# every writer. Set before the lock is taken.
+SYNC_LOCK_KIND=""
+# How long a writer waits for each check that holds the lock, in seconds. Kept
+# in the environment only so the lock suite can exercise the bound quickly.
+SYNC_LOCK_CHECK_WAIT="${INTELLIGENCE_SYNC_LOCK_CHECK_WAIT:-300}"
 
 sync_lock_now() {
     if [ -n "${EPOCHSECONDS:-}" ]; then
@@ -47,6 +63,9 @@ sync_lock_pgid() {
 }
 
 sync_lock_write_owner() {
+    # The kind goes first, before anything that costs time: whoever can read
+    # the owner can read the kind too.
+    [ -z "$SYNC_LOCK_KIND" ] || printf '%s\n' "$SYNC_LOCK_KIND" > "$1/kind"
     sync_lock_now
     sync_lock_pgid
     SYNC_LOCK_TOKEN="$$.$IS_NOW.$RANDOM$RANDOM"
@@ -88,31 +107,89 @@ sync_lock_is_stale() {
     [ -d "$1" ] && [ -n "$(find "$1" -maxdepth 0 -mmin +1 2>/dev/null)" ]
 }
 
-# sync_lock_acquire <root> — take <root>/.intelligence/sync.lock or refuse.
+# sync_lock_held_by_check <lock> — true when the holder marked its lock as a
+# `sync --check`. A lock without the mark is a writer's, or an older CLI's.
+sync_lock_held_by_check() {
+    local kind=""
+    # The group silences the redirection too: a kind released between the
+    # test and the read must not print a stray error a caller would show.
+    [ -f "$1/kind" ] && { IFS= read -r kind < "$1/kind"; } 2>/dev/null
+    [ "$kind" = check ]
+}
+
+# sync_lock_acquire <root> — take <root>/.intelligence/sync.lock, or refuse.
+# A writer waits for each check that holds it for up to SYNC_LOCK_CHECK_WAIT
+# seconds; a check refuses at once.
 sync_lock_acquire() {
-    local root="$1" lock="$1/.intelligence/sync.lock" took=0 age=""
+    local root="$1" lock="$1/.intelligence/sync.lock" took age="" started="$SECONDS" told=0 ownerless=""
+    local holder="" seen
     # A process start costs tens of milliseconds on Git Bash: skip the usual case.
     [ -d "$root/.intelligence" ] || mkdir -p "$root/.intelligence" || die "cannot create $root/.intelligence"
-    if mkdir "$lock" 2>/dev/null; then
-        took=1
-    elif mkdir "$lock.takeover" 2>/dev/null; then
-        # Judge again under the takeover lock: another run may have taken
-        # it over since this one looked.
-        if sync_lock_is_stale "$lock"; then
-            rm -rf "$lock"
-            mkdir "$lock" 2>/dev/null && took=1
+    while :; do
+        took=0
+        if mkdir "$lock" 2>/dev/null; then
+            took=1
+        elif sync_lock_is_stale "$lock" && mkdir "$lock.takeover" 2>/dev/null; then
+            # The takeover lock is taken only for a lock that already looks
+            # stale: a command waiting for a live check must never hold it,
+            # since one interrupted mid-wait would leave it behind for good.
+            # Judge again under it: another run may have taken the lock over
+            # since this one looked.
+            if sync_lock_is_stale "$lock"; then
+                rm -rf "$lock"
+                mkdir "$lock" 2>/dev/null && took=1
+            fi
+            rmdir "$lock.takeover"
+        elif [ -d "$lock.takeover" ] && [ -n "$(find "$lock.takeover" -maxdepth 0 -mmin +1 2>/dev/null)" ]; then
+            # A takeover runs for milliseconds. Removing an abandoned one is itself
+            # a check-then-delete race, so it is left to a person.
+            die "a takeover of $lock was abandoned; if no intelligence command is running in this project, remove $lock.takeover"
         fi
-        rmdir "$lock.takeover"
-    elif [ -n "$(find "$lock.takeover" -maxdepth 0 -mmin +1 2>/dev/null)" ]; then
-        # A takeover runs for milliseconds. Removing an abandoned one is itself
-        # a check-then-delete race, so it is left to a person.
-        die "a takeover of $lock was abandoned; if no intelligence command is running in this project, remove $lock.takeover"
-    fi
-    if [ "$took" = 1 ]; then
-        sync_lock_write_owner "$lock" || { rm -rf "$lock"; die "cannot write $lock/owner"; }
-        SYNC_LOCK_HELD="$lock"
-        return 0
-    fi
+        if [ "$took" = 1 ]; then
+            sync_lock_write_owner "$lock" || { rm -rf "$lock"; die "cannot write $lock/owner"; }
+            SYNC_LOCK_HELD="$lock"
+            return 0
+        fi
+        if [ "$SYNC_LOCK_KIND" != check ] && sync_lock_held_by_check "$lock"; then
+            # A later ownerless moment belongs to another holder's start or
+            # release, and gets its own few seconds.
+            ownerless=""
+            # The bound is per check: one that took the lock while this
+            # command waited starts its own count.
+            if sync_lock_read_owner "$lock"; then
+                seen="$IS_LOCK_PID $IS_LOCK_SINCE $IS_LOCK_TOKEN"
+                if [ "$seen" != "$holder" ]; then
+                    holder="$seen"
+                    started="$SECONDS"
+                fi
+            fi
+            [ $((SECONDS - started)) -lt "$SYNC_LOCK_CHECK_WAIT" ] || break
+            if [ "$told" = 0 ]; then
+                # A caller that buffers this command's output (sync --compact)
+                # names a descriptor for the terminal, so a wait of minutes
+                # is never silent.
+                # Not one `>&"${fd:-2}"`: the group's 2>/dev/null, which keeps
+                # a closed descriptor quiet, would swallow the default too.
+                if [ -n "${IS_LOCK_NOTICE_FD:-}" ]; then
+                    { echo "waiting for intelligence sync --check to release $lock" >&"$IS_LOCK_NOTICE_FD"; } 2>/dev/null \
+                        || echo "waiting for intelligence sync --check to release $lock" >&2
+                else
+                    echo "waiting for intelligence sync --check to release $lock" >&2
+                fi
+                told=1
+            fi
+        elif ! sync_lock_read_owner "$lock"; then
+            # No owner: a holder between its mkdir and its owner file, or one
+            # being released. Both last moments, so look again for a few
+            # seconds from the first sight before calling it a run that is
+            # still starting.
+            [ -n "$ownerless" ] || ownerless="$SECONDS"
+            [ $((SECONDS - ownerless)) -lt 3 ] || break
+        else
+            break
+        fi
+        sleep 1
+    done
     if sync_lock_read_owner "$lock"; then
         sync_lock_now
         case "$IS_LOCK_SINCE" in ''|*[!0-9]*) ;; *) age=", for $((IS_NOW - IS_LOCK_SINCE))s" ;; esac
@@ -147,6 +224,11 @@ project_lock_hold() {
 sync_lock_release() {
     [ -n "$SYNC_LOCK_HELD" ] || return 0
     if sync_lock_read_owner "$SYNC_LOCK_HELD" && [ "$IS_LOCK_TOKEN" = "$SYNC_LOCK_TOKEN" ]; then
+        # A check's owner goes first: `rm -rf` alone could expose a moment with
+        # the owner still there and the kind gone, and a command waiting for
+        # the check would be refused in it. Without the owner, a waiter sees a
+        # check or a lock still starting, and waits either way.
+        [ ! -f "$SYNC_LOCK_HELD/kind" ] || rm -f "$SYNC_LOCK_HELD/owner"
         rm -rf "$SYNC_LOCK_HELD"
     fi
     SYNC_LOCK_HELD=""

package/engine/ENGINE_SHA

@@ -1 +1 @@
-af0a0fdbc3f505e4f063ae516c9243c92db6e376
+ee05b0f09bc74b1914e04c067cce1e87a75bd18a

package/engine/VERSION

@@ -1 +1 @@
-0.21.0
+0.22.0

package/engine/adapters/claude-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "intelligence",
+  "version": "__INTELLIGENCE_VERSION__",
+  "description": "Shows this project's Intelligence sync status above the prompt and runs intelligence sync from Claude Code",
+  "author": { "name": "Ainova Systems" }
+}

package/engine/adapters/claude-plugin/README.md

@@ -0,0 +1,14 @@
+# Intelligence sync status for Claude Code
+
+`intelligence sync` renders this plugin into a project's
+`.claude/skills/intelligence/` from the Intelligence engine's
+`adapters/claude-plugin/` template when `targets.claude.plugin` is `true` in
+`intelligence.yaml`. Change the template in the engine, never a rendered copy:
+the next sync rewrites the copy, and setting the flag to `false` removes it.
+
+It is a Claude Code plugin whose hooks module (`hooks/register.js`) checks
+`intelligence sync --check` when a session starts and every five minutes,
+shows the result in a line above the prompt while something needs attention,
+and runs `intelligence sync` from a `Sync now` button there or the
+`/intelligence sync` command. Its requirements and limits are defined in the
+Intelligence CLI reference, `docs/cli.md`, under `intelligence sync`.

package/engine/adapters/claude-plugin/hooks/hooks.json

@@ -0,0 +1,3 @@
+{
+  "modules": ["./register.js"]
+}

package/engine/adapters/claude-plugin/hooks/register.js

@@ -0,0 +1,324 @@
+// Intelligence sync status for Claude Code.
+//
+// `intelligence sync` renders this file from the engine's claude-plugin
+// template when targets.claude.plugin is true (decision 0022). It is a Claude
+// Code mod: a hooks module with no Node.js APIs, reaching the project only
+// through the mods API `$`. It asks `intelligence sync --check` whether the
+// generated output is current when a session starts and every five minutes,
+// shows the answer in one line above the prompt while a check runs or
+// something needs attention, and runs `intelligence sync` from a button there
+// or the /intelligence command. It registers no tool and never submits a
+// prompt: it informs the person, never Claude.
+
+// A cold `sync --check` renders the project in a private copy, which takes
+// minutes on Git Bash; a warm one answers from its record in seconds. The
+// timeout stays just under the interval, so a slow check is waited for rather
+// than reported as a failure. A tick never starts a check while one of ours is
+// pending; one abandoned at the timeout can still finish beside the next.
+const CHECK_EVERY_MS = 300000
+const CHECK_TIMEOUT_MS = 290000
+// `$.process.run` allows ten minutes at most, which a full sync may need: it
+// first waits for any check holding the project lock (decision 0022).
+const SYNC_TIMEOUT_MS = 600000
+// Another command holding the project lock is asked again this soon, then
+// after doubling pauses up to the regular interval, so a lock that stays held
+// costs a few processes, not one every 15 seconds.
+const RETRY_MS = 15000
+// The spinner Claude Code draws while it works.
+const FRAMES = ['·', '✢', '✳', '✶', '✻', '✽', '✻', '✶', '✳', '✢']
+const FRAME_MS = 120
+// The CLI's refusal when another command holds the project lock.
+const LOCK_REFUSAL = /another intelligence sync is (running|starting)/
+// The CLI's word that the project was stamped by a newer CLI than itself: a
+// warning for a newer minor or patch, a refusal for a newer major.
+const CLI_BEHIND = /newer than this CLI's engine|IS_STATUS=ahead-of-engine/
+
+// What the last check found. `status` is one of unknown (no verdict yet), ok,
+// stale, error, missing-cli or old-cli; `busy` is true while a sync started
+// from here is running.
+const state = { status: 'unknown', detail: '', checkedAt: null, busy: false }
+// A check already in flight answers the next caller too, so a timer tick and
+// a /intelligence check never run two CLI processes side by side.
+let pendingCheck = null
+let retry = null
+let retryMs = RETRY_MS
+let ticker = null
+let frame = 0
+// The terminal and the Desktop app draw the band above the prompt; elsewhere,
+// such as the VS Code extension, the status line under the prompt carries the
+// text. The footer under the prompt is Claude Code's own and stays untouched.
+let band = false
+
+// The CLI reports its result as one `IS_STATUS=<status> IS_DETAIL=<text>`
+// line; everything else on stdout is progress.
+function parseStatus(stdout) {
+  const match = /^IS_STATUS=(\S+)(?: IS_DETAIL=(.*))?$/m.exec(stdout || '')
+  return { status: match ? match[1] : '', detail: match && match[2] ? match[2].trim() : '' }
+}
+
+function firstLine(text) {
+  const line = (text || '').split(/\r?\n/).find((l) => l.trim() !== '')
+  return line ? line.trim() : ''
+}
+
+// A failing CLI prints its progress before the reason, so the first line is
+// often a banner: prefer the line that says what went wrong.
+function reasonLine(text) {
+  const line = (text || '').split(/\r?\n/).find((l) => /^\s*ERROR:/.test(l))
+  return line ? line.trim().replace(/^ERROR:\s*/, '') : firstLine(text)
+}
+
+function errorMessage(err) {
+  return String(err && err.message ? err.message : err)
+}
+
+function clock(date) {
+  const hh = String(date.getHours()).padStart(2, '0')
+  const mm = String(date.getMinutes()).padStart(2, '0')
+  return hh + ':' + mm
+}
+
+function setState(status, detail) {
+  // A verdict ends a run of retries; the next held lock starts at 15 s again.
+  retryMs = RETRY_MS
+  state.status = status
+  state.detail = detail || ''
+  state.checkedAt = new Date()
+}
+
+function animating() {
+  return state.busy || state.status === 'unknown'
+}
+
+// The band's line: one short phrase, with Claude Code's spinner while a check
+// or a sync has not answered yet.
+function label() {
+  if (state.busy) return FRAMES[frame] + ' intelligence: syncing'
+  switch (state.status) {
+    case 'stale':
+      return 'intelligence: sync needed'
+    case 'missing-cli':
+      return 'intelligence: CLI not found'
+    case 'old-cli':
+      return 'intelligence: update the CLI'
+    case 'error':
+      return 'intelligence: check failed'
+    default:
+      return FRAMES[frame] + ' intelligence: checking'
+  }
+}
+
+// The full sentence: the /intelligence reply, and the status line where no
+// band draws. Claude Code prefixes a status line with the plugin's name.
+function statusText() {
+  if (state.busy) return 'syncing…'
+  const at = state.checkedAt ? ' · ' + clock(state.checkedAt) : ''
+  switch (state.status) {
+    case 'ok':
+      return 'up to date' + at
+    case 'stale':
+      return 'sync needed — run /intelligence sync' + at
+    case 'missing-cli':
+      return 'CLI not found on PATH'
+    case 'old-cli':
+      return 'the intelligence CLI on PATH is older than this project — run: intelligence upgrade'
+    case 'error':
+      return 'check failed: ' + state.detail + at
+    default:
+      return 'checking…'
+  }
+}
+
+// Every state change redraws the band above the prompt; the spinner turns only
+// while something is pending.
+function show($) {
+  if (animating() && !ticker) {
+    ticker = $.clock.every(FRAME_MS, () => {
+      frame = (frame + 1) % FRAMES.length
+      $.ui.invalidate('ui.render')
+    })
+  } else if (!animating() && ticker) {
+    ticker.cancel()
+    ticker = null
+  }
+  $.ui.status(band ? undefined : statusText())
+  $.ui.invalidate('ui.render')
+}
+
+// Ask again soon after a command that held the project lock; the verdict
+// shown meanwhile is the last one, never a guess.
+function retrySoon($) {
+  if (retry) return
+  retry = $.clock.after(retryMs, () => {
+    retry = null
+    check($)
+  })
+  retryMs = Math.min(retryMs * 2, CHECK_EVERY_MS)
+}
+
+async function check($) {
+  if (state.busy) return
+  if (pendingCheck) return pendingCheck
+  pendingCheck = runCheck($).finally(() => {
+    pendingCheck = null
+  })
+  return pendingCheck
+}
+
+async function runCheck($) {
+  let result
+  let cwd = ''
+  try {
+    // The project root, not the shell's cwd: a session started in a
+    // subdirectory still checks the project the plugin was rendered for.
+    cwd = await $.session.root()
+    result = await $.process.run(['intelligence', 'sync', '--check'], { cwd, timeoutMs: CHECK_TIMEOUT_MS })
+  } catch (err) {
+    // The call rejects when the program cannot start or outlives its
+    // timeout; the result arrives whatever the exit code otherwise.
+    const message = errorMessage(err)
+    if (/failed to start/i.test(message)) setState('missing-cli', message)
+    else if (await lockHeld($, cwd)) retrySoon($)
+    else setState('error', message)
+    show($)
+    return
+  }
+  const parsed = parseStatus(result.stdout)
+  // An older CLI renders this project with its own engine, so its verdict
+  // says nothing about what this project's CLI would write, and its sync
+  // would drop this plugin: say so instead of offering one.
+  if (CLI_BEHIND.test((result.stderr || '') + ' ' + (result.stdout || ''))) setState('old-cli', reasonLine(result.stderr))
+  // Exit 0 is up to date and 2 is `out-of-date`, the only verdicts sync
+  // --check gives; anything else is the CLI refusing to answer.
+  else if (result.exitCode === 0) setState('ok', parsed.detail)
+  else if (result.exitCode === 2) setState('stale', parsed.detail || 'sync needed')
+  // Another holder of the project lock — someone's sync, or another
+  // session's check — is not a fault: the last verdict stays, and the check
+  // asks again shortly instead of queueing ahead of a waiting sync.
+  else if (LOCK_REFUSAL.test(result.stderr || '')) retrySoon($)
+  else setState('error', parsed.detail || reasonLine(result.stderr) || 'exit ' + result.exitCode)
+  show($)
+}
+
+// A check cut off at its timeout behind another command, or still finishing
+// on its own, leaves the project lock in place: that is a command still
+// running, not a failed check. The process the timeout abandoned keeps running.
+async function lockHeld($, root) {
+  if (!root) return false
+  try {
+    return await $.fs.exists(root + '/.intelligence/sync.lock')
+  } catch {
+    return false
+  }
+}
+
+async function runSync($) {
+  if (state.busy) return
+  if (state.status === 'old-cli') {
+    $.ui.toast('update the intelligence CLI first: intelligence upgrade')
+    return 'not run'
+  }
+  state.busy = true
+  show($)
+  let outcome
+  let cwd = ''
+  try {
+    // A check of ours still running holds the project lock; the CLI would
+    // wait for it too, but waiting here keeps its late answer from landing
+    // after the sync's own.
+    if (pendingCheck) await pendingCheck
+    cwd = await $.session.root()
+    const result = await $.process.run(['intelligence', 'sync', '--compact'], { cwd, timeoutMs: SYNC_TIMEOUT_MS })
+    if (result.exitCode === 0) {
+      outcome = 'sync finished'
+    } else {
+      const reason = reasonLine(result.stderr) || parseStatus(result.stdout).detail || 'exit ' + result.exitCode
+      outcome = 'sync failed: ' + reason
+    }
+  } catch (err) {
+    // A sync past its timeout, which includes waiting for a check, keeps
+    // running and holding the lock: it has not failed yet.
+    if (!/failed to start/i.test(errorMessage(err)) && (await lockHeld($, cwd))) {
+      outcome = 'sync is still running; the status updates when it ends'
+    } else {
+      outcome = 'sync could not run: ' + errorMessage(err)
+    }
+  }
+  // The check, not the sync's own exit code, decides what the status shows:
+  // it is the same judgement the next timer tick would make. Until it answers
+  // the status is `checking`, so the band never offers `Sync now` again for
+  // the verdict the sync just replaced.
+  state.status = 'unknown'
+  state.detail = ''
+  state.busy = false
+  show($)
+  $.ui.toast(outcome)
+  await check($)
+  return outcome
+}
+
+export function register(on) {
+  on('session.start', async ($, e, next) => {
+    // A build without surfaces() draws in the terminal; the band is the default.
+    try {
+      band = (await $.session.surfaces()).some((s) => s === 'terminal' || s === 'desktop')
+    } catch {
+      band = true
+    }
+    // The label shows at once, turning, while a cold first check can take
+    // minutes.
+    show($)
+    // Neither the first check nor the timer is awaited: the session must
+    // never wait on the CLI.
+    check($)
+    $.clock.every(CHECK_EVERY_MS, () => check($))
+    // Registered last and guarded: a taken name throws, and a hook that
+    // throws is skipped from that line on.
+    try {
+      await $.command.register({
+        name: 'intelligence',
+        description: 'Show Intelligence sync status or run sync',
+        argumentHint: '[sync|check]',
+        immediate: true,
+      })
+    } catch (err) {
+      $.ui.log('/intelligence not registered: ' + errorMessage(err), { to: 'debug' })
+    }
+    return next(e)
+  })
+
+  on('command.run', { command: 'intelligence' }, async ($, e) => {
+    const args = (e.args || '').trim()
+    if (args === 'sync') {
+      if (state.busy) return { text: 'a sync started from here is still running' }
+      const outcome = await runSync($)
+      return { text: outcome + ' — ' + statusText() }
+    }
+    if (args === 'check') {
+      await check($)
+      return { text: statusText() }
+    }
+    if (args === '') {
+      const detail = state.detail && state.status !== 'ok' ? ' (' + state.detail + ')' : ''
+      return { text: statusText() + detail }
+    }
+    return { text: 'usage: /intelligence [sync|check]' }
+  })
+
+  // The band above the prompt, where Claude Code draws nothing of its own,
+  // carries the status while there is something to wait for or act on, and
+  // is gone while the project is up to date.
+  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
+    if (state.status === 'ok' && !state.busy) return next(e)
+    const { Box, Text, Button } = $.ui.resolve(e)
+    const color = state.status === 'error' || state.status === 'old-cli' ? 'red' : state.status === 'stale' ? 'yellow' : undefined
+    const children = [Text({ color, dimColor: animating(), children: [label()] })]
+    // A digit hotkey on the band also fires from an empty prompt, typed and
+    // left for a moment; a letter would need the band focused first. Plain,
+    // because only a plain button shows its hotkey in the terminal.
+    if (state.status === 'stale' && !state.busy) {
+      children.push(Button({ key: 'sync', label: 'Sync now', hotkey: '1', plain: true, onPress: () => runSync($) }))
+    }
+    return Box({ flexDirection: 'row', columnGap: 2, children })
+  })
+}

package/engine/adapters/claude.sh

@@ -6,6 +6,11 @@
 # Skills: copy skill directories in full (SKILL.md + bundled resources),
 #   effort -> Claude's effort level
 # Agents: tier -> model, effort -> effort, access -> tools/disallowedTools
+# Plugin: with `targets.claude.plugin: true`, the Claude Code mod in
+#   adapters/claude-plugin/ is rendered into <output>/skills/intelligence/
+#   (decision 0022). Claude Code loads a plugin from a project's skills
+#   directory, so the plugin lives inside a path this contract already owns:
+#   ownership, Git policy, snapshots and `sync --check` need no new record.
 #
 # Every per-file loop batches its work into one awk process (see the batched
 # helpers in lib/common.sh): process spawns dominate sync time on Windows.
@@ -29,6 +34,52 @@ adapter_contract_claude() {
     adapter_contract_include "$output/settings.json"
 }
 
+# claude_plugin_var <manifest> — the one reader of targets.claude.plugin. Sets
+# IS_CLAUDE_PLUGIN to 1 when the project renders the Claude Code plugin and 0
+# for the default; returns 1 for a value target_bool_var refuses.
+claude_plugin_var() {
+    local rc=0
+    target_bool_var "$1" claude plugin || rc=1
+    IS_CLAUDE_PLUGIN="$IS_TARGET_BOOL"
+    return "$rc"
+}
+
+# The directory name the plugin takes under <output>/skills: a source skill
+# rendered under this name would be overwritten, so sync refuses the pair.
+IS_CLAUDE_PLUGIN_NAME=intelligence
+
+# render_claude_plugin <output_dir> — copy the plugin template byte for byte,
+# stamp the engine version into its manifest and normalize line endings. The
+# template is in the engine's adapter directory, never in the content package:
+# it is executable tooling, and the bundle copies all of engine/. It is found
+# through the engine root, so a project's own claude.sh renders it too.
+render_claude_plugin() {
+    local output_dir="$1" tpl
+    local dst="$output_dir/skills/$IS_CLAUDE_PLUGIN_NAME"
+    # Rendered beside the destination, under a name no skill can take, and
+    # swapped in only when it differs: a running session reloads the mod on
+    # every file change, and announces each reload in its transcript.
+    local tmp="$output_dir/skills/.$IS_CLAUDE_PLUGIN_NAME.render.$$"
+    engine_root_var
+    tpl="$IS_ENGINE_ROOT/adapters/claude-plugin"
+    engine_version_var
+    rm -rf "$tmp"
+    mkdir -p "$tmp/.claude-plugin" "$tmp/hooks"
+    cp "$tpl/hooks/hooks.json" "$tpl/hooks/register.js" "$tmp/hooks/"
+    cp "$tpl/README.md" "$tmp/README.md"
+    awk -v v="$IS_ENGINE_VERSION" '{ sub(/__INTELLIGENCE_VERSION__/, v); print }' \
+        "$tpl/.claude-plugin/plugin.json" > "$tmp/.claude-plugin/plugin.json"
+    finalize_output_files "$tmp/.claude-plugin/plugin.json" "$tmp/hooks/hooks.json" \
+        "$tmp/hooks/register.js" "$tmp/README.md"
+    if [ -d "$dst" ] && [ ! -L "$dst" ] && diff -r -q "$tmp" "$dst" >/dev/null 2>&1; then
+        rm -rf "$tmp"
+    else
+        rm -rf "$dst"
+        mv "$tmp" "$dst"
+    fi
+    echo "  plugin: $IS_CLAUDE_PLUGIN_NAME (Claude Code mod $IS_ENGINE_VERSION)"
+}
+
 # Sync rules to Claude format (copy as-is, normalize LF)
 sync_claude_rules() {
     local repo_root="$1"
@@ -53,13 +104,32 @@ sync_claude_skills() {
     local config_file="$2"
     local output_dir="$3"
 
-    local i name
+    local i name clash="" nocase=0
     local -a skill_dirs=()
     # The catalog's skills are the ones the inventory renders, symlinked ones
     # included (decision 0017).
     output_rel_var "$repo_root" "$output_dir"
     source_artifacts_var "$repo_root" "$config_file" skills claude "$IS_OUTPUT_REL/skills/{}"
     [ "${#IS_SOURCE_FILES[@]}" -gt 0 ] || return 0
+    # The plugin takes one skill directory name; a skill rendered under it and
+    # the plugin would each erase the other, so neither is written. Names
+    # compare without case: on Windows and macOS `Intelligence/` is the same
+    # directory. (nocasematch, not ${name,,}: macOS ships bash 3.2.)
+    if [ "${IS_CLAUDE_PLUGIN:-0}" = 1 ]; then
+        shopt -q nocasematch && nocase=1
+        shopt -s nocasematch
+        for ((i = 0; i < ${#IS_SOURCE_FILES[@]}; i++)); do
+            if [[ "${IS_SOURCE_NAMES[i]}" == "$IS_CLAUDE_PLUGIN_NAME" ]]; then
+                clash="${IS_SOURCE_FILES[i]#"$repo_root/"}"
+                break
+            fi
+        done
+        [ "$nocase" = 1 ] || shopt -u nocasematch
+        if [ -n "$clash" ]; then
+            echo "ERROR: skill $clash renders as $IS_OUTPUT_REL/skills/$IS_CLAUDE_PLUGIN_NAME, the directory targets.claude.plugin: true reserves for the Claude Code plugin. Rename the skill or set targets.claude.plugin to false." >&2
+            return 1
+        fi
+    fi
     for ((i = 0; i < ${#IS_SOURCE_FILES[@]}; i++)); do
         skill_dirs+=("${IS_SOURCE_FILES[i]%/SKILL.md}/")
     done
@@ -156,18 +226,39 @@ sync_to_claude() {
 
     echo "=== Claude Code ==="
 
+    # The flag is read before anything is removed: a malformed value refuses
+    # the sync with the reason, and the output stays exactly as it was.
+    claude_plugin_var "$config_file" || {
+        echo "ERROR: targets.claude.plugin must be true or false: true renders the Claude Code plugin into ${output_dir#"$repo_root/"}/skills/$IS_CLAUDE_PLUGIN_NAME, false or omission does not." >&2
+        return 1
+    }
+
     # Clean generated content only — preserve any project-level files
     # the user manages directly (settings.json, settings.local.json,
     # commands/, statusline.sh, etc.).
     rm -rf "$output_dir/rules" "$output_dir/agents"
     if [ -d "$output_dir/skills" ]; then
-        find "$output_dir/skills" -mindepth 1 -maxdepth 1 \( -type d -o -type l \) -exec rm -rf {} +
+        # The plugin directory stays while the flag holds: Claude Code reloads
+        # a mod whose files change, so render_claude_plugin rewrites it only
+        # when its content differs. A skill of that name was refused above.
+        if [ "$IS_CLAUDE_PLUGIN" = 1 ]; then
+            find "$output_dir/skills" -mindepth 1 -maxdepth 1 \( -type d -o -type l \) \
+                ! -name "$IS_CLAUDE_PLUGIN_NAME" -exec rm -rf {} +
+        else
+            find "$output_dir/skills" -mindepth 1 -maxdepth 1 \( -type d -o -type l \) -exec rm -rf {} +
+        fi
     fi
     mkdir -p "$output_dir/rules" "$output_dir/skills" "$output_dir/agents"
 
     sync_claude_rules "$repo_root" "$config_file" "$output_dir"
+    # Called plainly, never on the left of `||`: that would turn errexit off
+    # for every copy inside, and a failed one would no longer fail the sync.
     sync_claude_skills "$repo_root" "$config_file" "$output_dir"
     sync_claude_agents "$repo_root" "$config_file" "$output_dir"
+    # The skills renderer has refused a skill of the plugin's name by now, so
+    # the plugin never lands on top of one. Cleared above with every other
+    # skill directory, it exists only while the flag says so.
+    [ "$IS_CLAUDE_PLUGIN" = 0 ] || render_claude_plugin "$output_dir"
 
     count_matching_files "$output_dir/rules" "*.md" \
         "$output_dir/skills" "SKILL.md" "$output_dir/agents" "*.md"

package/engine/adapters/copilot.sh

@@ -55,19 +55,13 @@ adapter_contract_copilot() {
 
 # copilot_commit_output_var <manifest> — the one reader of
 # targets.copilot.commit_output. Sets IS_COPILOT_COMMIT_OUTPUT to 1 when the
-# project commits generated output and 0 for the default; returns 1 for any
-# value other than true or false. No manifest — a caller reading ownership
-# only — is the default.
+# project commits generated output and 0 for the default; returns 1 for a value
+# target_bool_var refuses.
 copilot_commit_output_var() {
-    local manifest="$1" setting
-    IS_COPILOT_COMMIT_OUTPUT=0
-    [ -n "$manifest" ] && [ -f "$manifest" ] || return 0
-    setting="$(get_target_field "$manifest" "copilot" "commit_output")"
-    case "$setting" in
-        ''|false) ;;
-        true) IS_COPILOT_COMMIT_OUTPUT=1 ;;
-        *) return 1 ;;
-    esac
+    local rc=0
+    target_bool_var "$1" copilot commit_output || rc=1
+    IS_COPILOT_COMMIT_OUTPUT="$IS_TARGET_BOOL"
+    return "$rc"
 }
 
 # copilot_paths_rows <file>... — batch form of the old per-file `paths:`

package/engine/lib/common.sh

@@ -3629,6 +3629,24 @@ is_target_enabled() {
     ' "$file"
 }
 
+# target_bool_var <manifest> <target> <field> — the one reading of a boolean
+# target field (targets.copilot.commit_output, targets.claude.plugin). Sets
+# IS_TARGET_BOOL to 1 for true and 0 for false, omission or an empty value;
+# returns 1 for anything else, so a typo never decides silently. No manifest —
+# a caller reading ownership only — is the default.
+# shellcheck disable=SC2034  # IS_TARGET_BOOL is the return channel
+target_bool_var() {
+    local setting
+    IS_TARGET_BOOL=0
+    [ -n "$1" ] && [ -f "$1" ] || return 0
+    setting="$(get_target_field "$1" "$2" "$3")"
+    case "$setting" in
+        ''|false) ;;
+        true) IS_TARGET_BOOL=1 ;;
+        *) return 1 ;;
+    esac
+}
+
 # Get an arbitrary field from a target's config block.
 # Handles both inline (`claude: { enabled: true, output: ".claude" }`)
 # and block form. Uses POSIX awk only — no gawk-specific 3-arg match().

package/engine/lib/contract.sh

@@ -100,18 +100,27 @@ is_status() {
     fi
 }
 
+# engine_root_var — set IS_ENGINE_ROOT to the engine directory, one level above
+# this lib. A project adapter that overrides a built-in finds the engine's own
+# files through it, never beside itself.
+engine_root_var() {
+    local lib="${BASH_SOURCE[0]}"
+    case "$lib" in
+        */*) lib="${lib%/*}" ;;
+        *) lib="." ;;
+    esac
+    IS_ENGINE_ROOT="$lib/.."
+}
+
 # Engine version = VERSION one level above this lib (BASH_SOURCE works when
 # sourced). Empty if unreadable — callers treat empty as "no guard".
 # engine_version_var sets IS_ENGINE_VERSION, and IS_ENGINE_VERSION_FOUND=1 when
 # the file exists; it reads the file once per process.
 engine_version_var() {
     [ -z "${IS_ENGINE_VERSION_FOUND:-}" ] || return 0
-    local lib="${BASH_SOURCE[0]}" vf content=""
-    case "$lib" in
-        */*) lib="${lib%/*}" ;;
-        *) lib="." ;;
-    esac
-    vf="$lib/../VERSION"
+    local vf content=""
+    engine_root_var
+    vf="$IS_ENGINE_ROOT/VERSION"
     IS_ENGINE_VERSION=""
     IS_ENGINE_VERSION_FOUND=0
     [ -f "$vf" ] || return 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainova-systems/intelligence",
-  "version": "0.21.0",
+  "version": "0.22.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

@@ -129,6 +129,17 @@ Code ignore theirs, and never `.github/` itself. `targets.copilot.commit_output:
 true` keeps them tracked for Copilot on github.com; the setting is defined in
 [Generated output and version control](conventions.md#generated-output-and-version-control).
 
+The Claude adapter renders a Claude Code plugin into `<output>/skills/intelligence/`
+when `targets.claude.plugin` is `true` (decision 0022): a mod that checks
+`intelligence sync --check` at session start and every five minutes, shows the
+verdict in a line above the prompt and runs sync from a button there or
+`/intelligence sync`.
+The template is `engine/adapters/claude-plugin/`, copied with the engine version
+stamped into `plugin.json`. It lives inside the owned `skills` path, so it needs
+no contract record of its own. The field's values, the name collision it refuses
+and the plugin's limits are defined in the
+[CLI reference](https://github.com/ainova-systems/intelligence/blob/main/docs/cli.md#intelligence-sync).
+
 The engine calls:
 
 ```text
@@ -373,7 +384,7 @@ For a built-in adapter, add the same assertions to the repository's smoke or lif
 |---|---|
 | `agents` | `AGENTS.md` |
 | `antigravity` | `.agents/rules`, `.agents/agents`, `.agents/skills` |
-| `claude` | `.claude/rules`, `.claude/agents`, `.claude/skills` |
+| `claude` | `.claude/rules`, `.claude/agents`, `.claude/skills` (with `plugin: true`, `.claude/skills/intelligence` is the Claude Code plugin) |
 | `cursor` | `.cursor/rules`, `.cursor/agents`, `.cursor/skills` |
 | `copilot` | `.github/instructions`, `.github/agents`, `.github/skills` |
 | `codex` | `.codex/agents`, `.agents/skills`, marker-owned `AGENTS.override.md` |