@erclx/aitk 0.110.0 → 0.111.0

package/README.md

@@ -38,11 +38,15 @@ Nothing refreshes on its own. Claude Code ships auto-update off for third-party
 ```bash
 claude plugin marketplace update aitk
 claude plugin update aitk@aitk
-bun install --global @erclx/aitk
+aitk upgrade
 ```
 
 The first two update the skills, the third updates the CLI, and they move independently. Restart Claude Code, or run `/reload-plugins`, to pick the skills up.
 
+`aitk upgrade` reads the package manager off its own install path and reinstalls with that one, so you don't have to remember which put it there. It names what it detected before it runs anything, and it refuses a source checkout rather than reinstalling over your clone.
+
+You don't have to wait until something breaks to find out you're behind. `aitk sync --check` and `aitk claude skills drift` both report the installed version against the newest published one, and neither changes its exit code over it, so an offline machine reads unknown rather than red.
+
 To stop doing this by hand, turn auto-update on once under `/plugin` in the Marketplaces tab. Confirm what you are running with `aitk --version` and `claude plugin list`.
 
 ## Why

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.110.0",
+  "version": "0.111.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents/commands.md

@@ -13,7 +13,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
 | `aitk init [path]`         | Bootstrap a project with selected toolkit domains                                                                                         |
 | `aitk sync [path]`         | Sync all installed domains in a target project                                                                                            |
-| `aitk sync --check`        | Report toolkit drift without writing (`--json`, `--exit-code`)                                                                            |
+| `aitk sync --check`        | Report toolkit drift and the installed version against the newest published (`--json`, `--exit-code`)                                     |
 | `aitk sandbox [cat:cmd]`   | Run sandbox scenarios (interactive or routed), toolkit-only like the tree it reads                                                        |
 | `aitk sandbox reset`       | Reset sandbox to baseline                                                                                                                 |
 | `aitk sandbox clean`       | Wipe the sandbox                                                                                                                          |
@@ -44,11 +44,12 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk context audit`       | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, and index drift |
 | `aitk markdown audit`      | Fail any markdown path on a banned character, word, or spelling, and report the structural checkpoints                                    |
 | `aitk claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md`                                                            |
-| `aitk claude skills drift` | Name the shipped skill bodies rewritten between a given ref and `HEAD` (`--json`)                                                         |
+| `aitk claude skills drift` | Name the shipped skill bodies rewritten between a given ref and `HEAD`, and the installed version against the newest published (`--json`) |
 | `aitk gov test-order`      | Report where an implementation reached history ahead of the test covering it (`--json`)                                                   |
 | `aitk audits run`          | Run every audit as one set, report per check under one verdict, and compare each count to the recorded baseline (`--json`, `--record`)    |
 | `aitk audits list`         | List every audit the set runs, with the corpus each reads and whether it gates (`--json`)                                                 |
 | `aitk capture [source]`    | Render HTML capture sources to PNG, toolkit-only and absent from an installed package                                                     |
+| `aitk upgrade`             | Reinstall the CLI globally with the package manager the install path names (`--json`)                                                     |
 
 ## Domain commands
 
@@ -78,3 +79,17 @@ Common patterns:
 - `install <name> <path>` → install a specific entry into a target project.
 - `sync <path>` → reapply all installed entries in a target project.
 - `create [name]` → scaffold a new authoring entry in this repo.
+
+## Version skew
+
+`aitk sync --check` and `aitk claude skills drift` are the two moments a target
+already stops to reconcile with the toolkit, so each reports the installed
+version against the newest published one. No other command performs the lookup,
+which keeps a registry round trip out of the catalog reads an agent runs in a
+loop.
+
+The report carries three states and never changes an exit code. `behind` names
+`aitk upgrade` as the remedy, `current` says so, and `unknown` carries the
+reason the registry could not be reached. Branch on the `skew.state` field in
+the JSON record rather than on the exit, since an offline machine has to read as
+unmeasured rather than as a failing check.

package/docs/target-projects.md

@@ -114,6 +114,12 @@ When the toolkit updates, target projects pull changes per domain. There is one
 
 `aitk sync --check <path>` reports what has drifted without writing anything. It splits each difference by cause, which is the question that decides what to do next.
 
+#### The binary first
+
+The report opens by naming the binary running it. The installed version reads against the newest published one, and a version behind that points you at `aitk upgrade`, since every section under it is a reading taken by whichever toolkit you happen to have. An unreachable registry reports unknown with its reason rather than failing, so `--exit-code` still gates on the drift the check measured locally and an offline machine stays green.
+
+#### Then the causes
+
 A `stale` file still matches what the toolkit installed, so the update is mechanical. A `customized` file carries local edits, so taking the upstream version is a decision and `aitk:claude-seed-sync` is the tool for it. A `stranded` file sits where an older toolkit installed it and the toolkit has since moved, which is what `aitk:migration-standards` handles.
 
 That attribution comes from `.claude/aitk.json`, a stamp every install and sync writes. Standards, snippets, and governance record a hash per installed file. Tooling records the stack chain it resolved instead, since its install runs no per-file walk to attribute.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.110.0",
+  "version": "0.111.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/cli.ts

@@ -1,7 +1,5 @@
 #!/usr/bin/env bun
 
-import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
 import { Command } from 'commander'
 import { register as init } from '@/commands/init'
 import { register as sandbox } from '@/commands/sandbox'
@@ -28,7 +26,8 @@ import { register as markdown } from '@/commands/markdown'
 import { register as records } from '@/commands/records'
 import { register as sessions } from '@/commands/sessions'
 import { register as audits } from '@/commands/audits'
-import { PROJECT_ROOT } from '@/project-root'
+import { register as upgrade } from '@/commands/upgrade'
+import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
 
 const GREY = '\x1b[0;90m'
 const WHITE = '\x1b[1;37m'
@@ -65,6 +64,7 @@ function showHelp(): void {
     `${GREY}│${NC}    records [cmd]      ${GREY}# Session records under .claude/ (validate, push, pull)${NC}`,
     `${GREY}│${NC}    sessions [cmd]     ${GREY}# Resolve live sessions to worktree and branch (list)${NC}`,
     `${GREY}│${NC}    audits [cmd]       ${GREY}# Run every health check as one set (run, list)${NC}`,
+    `${GREY}│${NC}    upgrade            ${GREY}# Reinstall the CLI globally with the manager that installed it${NC}`,
     `${GREY}│${NC}`,
     `${GREY}│${NC}  ${WHITE}Sandbox:${NC}`,
     `${GREY}│${NC}    aitk sandbox             ${GREY}# Interactive scenario picker${NC}`,
@@ -104,31 +104,16 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk records push --json`,
     `${GREY}│${NC}    aitk sessions list --json`,
     `${GREY}│${NC}    aitk audits run --json`,
+    `${GREY}│${NC}    aitk upgrade --json`,
     `${GREY}└${NC}`,
   ]
   console.log(lines.join('\n'))
 }
 
-/**
- * Read at runtime rather than inlined, because a literal here is a second place
- * the version lives and it stopped tracking `package.json` at `0.1.0`. The
- * release tool writes one file and this follows it. `package.json` ships in
- * every npm tarball regardless of the `files` list, so the read resolves from a
- * registry install as well as from a clone.
- */
-function readVersion(): string {
-  try {
-    const raw = readFileSync(join(PROJECT_ROOT, 'package.json'), 'utf8')
-    return (JSON.parse(raw) as { version?: string }).version ?? 'unknown'
-  } catch {
-    return 'unknown'
-  }
-}
-
 const program = new Command()
 program
   .name('aitk')
-  .version(readVersion())
+  .version(readInstalled().version ?? UNKNOWN_LABEL)
   .enablePositionalOptions()
   .helpOption(false)
 program.action(() => showHelp())
@@ -163,5 +148,6 @@ markdown(program)
 records(program)
 sessions(program)
 audits(program)
+upgrade(program)
 
 program.parse()

package/src/commands/claude.ts

@@ -48,6 +48,7 @@ import {
   plural,
   select,
 } from '@/ui'
+import { describeSkew, readSkew, type SkewReport } from '@/version/skew'
 
 const GREEN = '\x1b[0;32m'
 const GREY = '\x1b[0;90m'
@@ -249,14 +250,18 @@ export function register(program: Command): void {
         'copy. Passing a ref older than the oldest load over-reports, which is',
         'the safe direction. Confirm a name by reading the body.',
         '',
+        'Every run also reports the installed version against the newest',
+        'published one. That report never changes the exit code, so an offline',
+        'machine reads it as unknown rather than as a failure.',
+        '',
         'Examples:',
         '  aitk claude skills drift HEAD~20',
         '  aitk claude skills drift 02d7b265 --json',
         '',
       ].join('\n'),
     )
-    .action((ref: string, opts: SkillsDriftOptions) => {
-      process.exitCode = runSkillsDrift(ref, opts)
+    .action(async (ref: string, opts: SkillsDriftOptions) => {
+      process.exitCode = await runSkillsDrift(ref, opts)
     })
 }
 
@@ -506,16 +511,28 @@ function runSkillsList(opts: SkillsListOptions): number {
  * it answers every run with nothing moved, which is the silence this reports
  * against.
  */
-function runSkillsDrift(ref: string, opts: SkillsDriftOptions): number {
+async function runSkillsDrift(
+  ref: string,
+  opts: SkillsDriftOptions,
+): Promise<number> {
   const root = process.cwd()
   const report = readDrift(root, ref)
+  const skew = await readSkew()
 
   if (report.kind === 'measured') {
     intro('aitk claude skills drift')
+    reportSkew(skew)
     reportDrift(report, ref)
     outro()
   } else {
     frameError(report.reason)
+    // The refusal path names the binary too. A project consuming the plugin
+    // from a marketplace cache is refused here for having no history, and that
+    // is the moment a skew warning is worth most, since an old binary is one
+    // reason the cache and the CLI disagree in the first place.
+    if (skew.state === 'behind') {
+      process.stderr.write(`${GREY}${describeSkew(skew)}${NC}\n`)
+    }
   }
 
   if (opts.json) {
@@ -528,8 +545,9 @@ function runSkillsDrift(ref: string, opts: SkillsDriftOptions): number {
               base: report.base,
               head: report.head,
               moved: report.moved,
+              skew,
             }
-          : { root, ref, unreadable: report.reason },
+          : { root, ref, unreadable: report.reason, skew },
       )}\n`,
     )
   }
@@ -537,6 +555,18 @@ function runSkillsDrift(ref: string, opts: SkillsDriftOptions): number {
   return report.kind === 'measured' ? 0 : 1
 }
 
+/**
+ * The binary reports before the range does, for the reason the range section
+ * states about itself: the command answers what changed on disk, and a binary
+ * behind the published one is a second way the tree a session reads differs
+ * from the tree it holds.
+ */
+function reportSkew(skew: SkewReport): void {
+  logStep('Toolkit version')
+  if (skew.state === 'behind') logWarn(describeSkew(skew))
+  else logInfo(describeSkew(skew))
+}
+
 /**
  * States the bound on every run, including the run that names nothing. A report
  * listing only what moved reads as a verdict on what a session holds, and the

package/src/commands/sync.ts

@@ -30,6 +30,7 @@ import {
   logWarn,
   outro,
 } from '@/ui'
+import { describeSkew } from '@/version/skew'
 
 const GREY = '\x1b[0;90m'
 const YELLOW = '\x1b[0;33m'
@@ -100,6 +101,8 @@ async function runCheck(target: string, options: SyncOptions): Promise<number> {
 function renderCheck(report: CheckReport): void {
   intro('aitk sync --check')
 
+  renderSkew(report)
+
   if (!report.managed) {
     logStep('Not a toolkit project')
     logWarn('No .claude/ directory and no CLAUDE.md at the target.')
@@ -182,6 +185,24 @@ function renderCheck(report: CheckReport): void {
   )
 }
 
+/**
+ * The binary reports before any domain does, since a stale binary is what makes
+ * every section below it a reading from the wrong toolkit. It prints on all
+ * three states rather than only when behind: a check that goes quiet when the
+ * registry is unreachable is indistinguishable from one that found nothing.
+ */
+function renderSkew(report: CheckReport): void {
+  const { skew } = report
+  logStep('toolkit version')
+
+  if (skew.state === 'behind') {
+    logWarn(describeSkew(skew))
+    return
+  }
+
+  logInfo(describeSkew(skew))
+}
+
 /**
  * Tooling prints whether it was measured before it prints any count, because a
  * target with no chain recorded produces the same zero a current target does.

package/src/commands/upgrade.ts

@@ -0,0 +1,231 @@
+import type { Command } from 'commander'
+import { execa } from 'execa'
+import { PROJECT_ROOT } from '@/project-root'
+import {
+  frameError,
+  intro,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  select,
+} from '@/ui'
+import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
+import { detectManager, installCommand, type Manager } from '@/version/manager'
+import {
+  describeSkew,
+  latestOf,
+  readSkew,
+  type SkewReport,
+} from '@/version/skew'
+
+interface UpgradeOptions {
+  readonly json?: boolean
+}
+
+interface UpgradeRecord {
+  readonly root: string
+  readonly manager?: string
+  readonly command?: string
+  readonly before: string
+  readonly after?: string
+  readonly latest?: string
+  readonly state: 'upgraded' | 'current' | 'cancelled' | 'refused'
+  readonly reason?: string
+}
+
+export function register(program: Command): void {
+  program
+    .command('upgrade')
+    .description(
+      'Reinstall the CLI globally with whichever package manager installed it',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the binary is current, the reinstall completed, or it was cancelled',
+        '  1  refused or the reinstall failed, with the reason on stderr',
+        '',
+        'The package manager is read off the install path rather than guessed',
+        'from PATH, and named before anything runs. A source checkout matches no',
+        'install tree and is refused rather than reinstalled over.',
+        '',
+        'Examples:',
+        '  aitk upgrade',
+        '  aitk upgrade --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: UpgradeOptions) => {
+      process.exitCode = await runUpgrade(opts)
+    })
+}
+
+/**
+ * Detection runs before the registry lookup so the one case that cannot upgrade
+ * at all, a source checkout, refuses without waiting on a network call whose
+ * answer it would then discard.
+ */
+async function runUpgrade(opts: UpgradeOptions): Promise<number> {
+  const installed = readInstalled()
+  const before = installed.version ?? UNKNOWN_LABEL
+
+  intro('aitk upgrade')
+  logStep('Installed')
+  logInfo(`${installed.name ?? UNKNOWN_LABEL} ${before}`)
+  logInfo(PROJECT_ROOT)
+
+  const manager = detectManager(PROJECT_ROOT)
+  if (manager === undefined) {
+    return refuse(
+      opts,
+      before,
+      `No package manager owns ${PROJECT_ROOT}. A source checkout is upgraded by pulling, not by reinstalling over it.`,
+    )
+  }
+
+  // A manifest that did not parse, or carried no `name`, would otherwise reach
+  // `installCommand` and produce a global install of whatever sits under that
+  // placeholder on the registry. The prompt below defaults to yes headlessly,
+  // so nothing downstream would stop it.
+  if (installed.name === undefined) {
+    return refuse(
+      opts,
+      before,
+      `No package name in ${PROJECT_ROOT}/package.json, so there is nothing safe to reinstall. Repair the manifest, or reinstall by name yourself.`,
+      manager,
+    )
+  }
+
+  const command = installCommand(manager.id, installed.name)
+  logStep('Detected')
+  logInfo(`${manager.id}, from the \`${manager.evidence}\` path segment`)
+  logInfo(command.join(' '))
+
+  const skew = await readSkew({ installed })
+  logStep('Published')
+  logInfo(describeSkew(skew))
+
+  if (skew.state === 'current') {
+    outro()
+    emit(opts, {
+      ...base(before, manager, command, skew),
+      after: before,
+      state: 'current',
+    })
+    return 0
+  }
+
+  return await applyUpgrade(opts, before, skew, manager, command)
+}
+
+/**
+ * Runs the reinstall and reads the version back off disk rather than trusting
+ * the manager's own report, since each spells success differently and one of
+ * them exits zero on a no-op. The read is the same `package.json` the CLI names
+ * on `--version`, which the install has overwritten by this point.
+ *
+ * An `unknown` skew reaches here rather than stopping. The operator asked for
+ * the reinstall, and the manager reports its own network failure in terms the
+ * dist-tag endpoint cannot.
+ */
+async function applyUpgrade(
+  opts: UpgradeOptions,
+  before: string,
+  skew: SkewReport,
+  manager: Manager,
+  command: readonly string[],
+): Promise<number> {
+  const proceed = await select({
+    message: `Run \`${command.join(' ')}\`?`,
+    options: [
+      { value: true, label: 'Upgrade' },
+      { value: false, label: 'Cancel' },
+    ],
+    nonInteractiveDefault: true,
+  })
+
+  if (!proceed) {
+    logWarn('Cancelled')
+    outro()
+    emit(opts, { ...base(before, manager, command, skew), state: 'cancelled' })
+    return 0
+  }
+
+  logStep('Upgrading')
+  const [bin, ...args] = command
+  // The manager's own progress goes to stderr with the rest of the UI, leaving
+  // stdout carrying nothing but the record. Inheriting all three streams would
+  // put npm's output ahead of the JSON and break every wrapper parsing it.
+  const result = await execa(bin, args, {
+    reject: false,
+    stdin: 'inherit',
+    stdout: process.stderr,
+    stderr: 'inherit',
+  })
+
+  if (result.exitCode !== 0) {
+    return refuse(
+      opts,
+      before,
+      `\`${command.join(' ')}\` exited ${result.exitCode}. Run it yourself to read what it reported.`,
+      manager,
+    )
+  }
+
+  const after = readInstalled().version ?? UNKNOWN_LABEL
+  logStep('Installed')
+  logInfo(after === before ? `${after}, unchanged` : `${before} to ${after}`)
+  outro()
+
+  emit(opts, {
+    ...base(before, manager, command, skew),
+    after,
+    state: 'upgraded',
+  })
+  return 0
+}
+
+function base(
+  before: string,
+  manager: Manager,
+  command: readonly string[],
+  skew: SkewReport,
+): Omit<UpgradeRecord, 'state'> {
+  const latest = latestOf(skew)
+
+  return {
+    root: PROJECT_ROOT,
+    manager: manager.id,
+    command: command.join(' '),
+    before,
+    ...(latest === undefined ? {} : { latest }),
+  }
+}
+
+function refuse(
+  opts: UpgradeOptions,
+  before: string,
+  reason: string,
+  manager?: Manager,
+): number {
+  outro()
+  frameError(reason)
+  emit(opts, {
+    root: PROJECT_ROOT,
+    ...(manager === undefined ? {} : { manager: manager.id }),
+    before,
+    state: 'refused',
+    reason,
+  })
+  return 1
+}
+
+function emit(opts: UpgradeOptions, record: UpgradeRecord): void {
+  if (opts.json !== true) return
+  process.stdout.write(`${JSON.stringify(record)}\n`)
+}

package/src/sync/check.ts

@@ -27,6 +27,7 @@ import { createStandardsAdapter } from '@/standards/adapter'
 import { isDirectory } from '@/target'
 import { loadManifest } from '@/tooling/manifest'
 import { scan } from '@/tooling/scan'
+import { readSkew, type SkewReport } from '@/version/skew'
 
 /**
  * Domains the sync engine walks file by file. Tooling is a stamp domain without
@@ -163,6 +164,17 @@ export interface CheckReport {
    * the same question correctly. See `@/sync/reverse`.
    */
   readonly reverse: ReverseReport
+  /**
+   * The binary running the check, not the target. It reports on an unmanaged
+   * target too, since a reader told to run `aitk init` is better off knowing
+   * first whether the binary about to install is the current one.
+   *
+   * `hasDrift` deliberately ignores it. A registry lookup inside a check that
+   * gates would fail CI on an offline machine for a condition the check never
+   * measured, and the state reaching the reader is the point rather than the
+   * exit code.
+   */
+  readonly skew: SkewReport
 }
 
 export function installedStampDomains(target: string): ScannedDomain[] {
@@ -300,6 +312,10 @@ export async function buildCheckReport(
 ): Promise<CheckReport> {
   const stamp = readStamp(target)
 
+  // Started before the local scan and awaited after it, so the network wait
+  // overlaps work the report needs anyway rather than adding to it.
+  const skewRead = readSkew()
+
   const domains = await Promise.all(
     installedStampDomains(target).map((domain) =>
       buildDomainReport(toolkitRoot, target, stamp, domain),
@@ -324,6 +340,7 @@ export async function buildCheckReport(
       unmigrated: [],
       newSkills: [],
       reverse: emptyReverseReport(),
+      skew: await skewRead,
     }
   }
 
@@ -337,6 +354,7 @@ export async function buildCheckReport(
     unmigrated,
     newSkills: await readNewSkills(toolkitRoot, anchors),
     reverse: buildReverseReport(toolkitRoot, target),
+    skew: await skewRead,
   }
 }
 

package/src/version/compare.ts

@@ -0,0 +1,53 @@
+/**
+ * A `major.minor.patch` core with an optional prerelease tail. The registry
+ * publishes both shapes under the same dist tag, so a comparison that only
+ * understood the core would read `1.0.0-rc.1` as unparseable and report the
+ * whole lookup as unknown.
+ */
+const VERSION =
+  /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/
+
+export interface ParsedVersion {
+  readonly major: number
+  readonly minor: number
+  readonly patch: number
+  /** Absent on a release, which sorts above every prerelease of the same core. */
+  readonly prerelease?: string
+}
+
+export function parseVersion(raw: string): ParsedVersion | undefined {
+  const match = VERSION.exec(raw.trim())
+  if (match === null) return undefined
+
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    ...(match[4] === undefined ? {} : { prerelease: match[4] }),
+  }
+}
+
+/**
+ * Negative when `left` is older, positive when it is newer, zero when the two
+ * name the same version.
+ *
+ * Prerelease identifiers compare as whole strings rather than dot segment by
+ * dot segment, which is narrower than semver states. Every version this repo
+ * publishes is a plain core, so the ordering inside a prerelease series decides
+ * nothing here, and the one comparison that matters is that any prerelease
+ * sorts below the release sharing its core.
+ */
+export function compareVersions(
+  left: ParsedVersion,
+  right: ParsedVersion,
+): number {
+  if (left.major !== right.major) return left.major - right.major
+  if (left.minor !== right.minor) return left.minor - right.minor
+  if (left.patch !== right.patch) return left.patch - right.patch
+
+  if (left.prerelease === right.prerelease) return 0
+  if (left.prerelease === undefined) return 1
+  if (right.prerelease === undefined) return -1
+
+  return left.prerelease < right.prerelease ? -1 : 1
+}

package/src/version/installed.ts

@@ -0,0 +1,40 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { PROJECT_ROOT } from '@/project-root'
+
+/** What a reader prints in place of a field the manifest did not carry. */
+export const UNKNOWN_LABEL = 'unknown'
+
+/**
+ * Either field is absent when the manifest could not be read or did not carry
+ * it. They are optional rather than sentinel strings so a caller has to narrow
+ * before using one, which is what makes a name the manifest never supplied
+ * impossible to interpolate into a shell command. A sentinel typed `string`
+ * reads as an ordinary value at every call site and hides that case.
+ */
+export interface InstalledPackage {
+  readonly name?: string
+  readonly version?: string
+}
+
+/**
+ * Read at runtime rather than inlined, because a literal is a second place the
+ * version lives and it stopped tracking `package.json` at `0.1.0`. The release
+ * tool writes one file and this follows it. `package.json` ships in every npm
+ * tarball regardless of the `files` list, so the read resolves from a registry
+ * install as well as from a clone.
+ *
+ * This sits apart from the skew read so `src/cli.ts` can name the version on
+ * every invocation without pulling the registry lookup into the startup import
+ * graph of a CLI that compiles nothing ahead of time.
+ */
+export function readInstalled(root: string = PROJECT_ROOT): InstalledPackage {
+  try {
+    const raw = readFileSync(join(root, 'package.json'), 'utf8')
+    const parsed = JSON.parse(raw) as { name?: string; version?: string }
+
+    return { name: parsed.name, version: parsed.version }
+  } catch {
+    return {}
+  }
+}

package/src/version/manager.ts

@@ -0,0 +1,67 @@
+export type ManagerId = 'bun' | 'pnpm' | 'yarn' | 'npm'
+
+export interface Manager {
+  readonly id: ManagerId
+  /** The path segment the detection matched, so a wrong read is correctable. */
+  readonly evidence: string
+}
+
+/**
+ * Segments that only appear in one manager's global install tree, checked
+ * before the `node_modules` fallback because every one of these trees contains
+ * a `node_modules` too.
+ */
+const SIGNATURES: readonly (readonly [ManagerId, string])[] = [
+  ['bun', '.bun'],
+  ['pnpm', 'pnpm'],
+  ['pnpm', '.pnpm'],
+  ['yarn', 'yarn'],
+  ['yarn', '.yarn'],
+]
+
+/**
+ * Which package manager installed the package rooted at `root`, read off the
+ * install path rather than guessed from what is on `PATH`.
+ *
+ * Removing the guess is the whole case for the upgrade verb, so a detection
+ * that cannot be read back is worth no more than the guess it replaced. The
+ * evidence travels with the answer and the verb prints it before running
+ * anything, which lets an operator correct a wrong read without the detection
+ * having to be right every time.
+ *
+ * Returns `undefined` for a path outside any install tree, which is a source
+ * checkout. That is not a case to guess at either: reinstalling over a clone
+ * would replace what the operator is working in.
+ */
+export function detectManager(root: string): Manager | undefined {
+  const segments = root.split(/[/\\]/).filter((segment) => segment !== '')
+
+  for (const [id, signature] of SIGNATURES) {
+    if (segments.includes(signature)) return { id, evidence: signature }
+  }
+
+  if (segments.includes('node_modules')) {
+    return { id: 'npm', evidence: 'node_modules' }
+  }
+
+  return undefined
+}
+
+/** The global reinstall each manager spells, pinned to the newest published. */
+export function installCommand(
+  manager: ManagerId,
+  name: string,
+): readonly string[] {
+  const spec = `${name}@latest`
+
+  switch (manager) {
+    case 'bun':
+      return ['bun', 'add', '--global', spec]
+    case 'pnpm':
+      return ['pnpm', 'add', '--global', spec]
+    case 'yarn':
+      return ['yarn', 'global', 'add', spec]
+    case 'npm':
+      return ['npm', 'install', '--global', spec]
+  }
+}

package/src/version/skew.ts

@@ -0,0 +1,192 @@
+import { PROJECT_ROOT } from '@/project-root'
+import { compareVersions, parseVersion } from '@/version/compare'
+import {
+  type InstalledPackage,
+  readInstalled,
+  UNKNOWN_LABEL,
+} from '@/version/installed'
+import { detectManager } from '@/version/manager'
+
+const REGISTRY = 'https://registry.npmjs.org'
+
+/**
+ * Short enough that a check waiting on a dead network still returns inside the
+ * time an operator would give the command anyway. The skew line is one section
+ * of a report the rest of which needs no network at all, so the budget is set
+ * against how long the report may be held up rather than against how long the
+ * registry usually takes.
+ */
+const LOOKUP_TIMEOUT_MS = 3_000
+
+/**
+ * Three states and no fourth. `unknown` covers every way the question could not
+ * be answered and carries the reason, which is what a caller reports instead of
+ * a version.
+ *
+ * An installed version ahead of the published one reports `current`. That is a
+ * source checkout between a release commit and the publish job, or a local
+ * build, and neither is skew. Giving it a state of its own would fire a warning
+ * on every maintainer run for a condition with no remedy.
+ */
+export type SkewState = 'current' | 'behind' | 'unknown'
+
+interface SkewBase {
+  readonly name: string
+  readonly installed: string
+}
+
+/**
+ * A union rather than one shape with two optional fields, so a `behind` report
+ * cannot exist without the version it is behind and an `unknown` one cannot
+ * exist without its reason. Both are what `describeSkew` renders into a line an
+ * operator reads, and an optional field renders the word `undefined` there.
+ */
+export type SkewReport =
+  | (SkewBase & {
+      readonly state: 'current' | 'behind'
+      readonly latest: string
+    })
+  | (SkewBase & { readonly state: 'unknown'; readonly reason: string })
+
+/** Resolves the newest published version, or throws for `readSkew` to absorb. */
+export type LatestLookup = (name: string) => Promise<string>
+
+export interface SkewOptions {
+  readonly installed?: InstalledPackage
+  readonly lookup?: LatestLookup
+}
+
+/**
+ * The installed version against the newest published one.
+ *
+ * Never rejects and never reports through an exit code. `aitk sync --check
+ * --exit-code` gates CI on drift it measured locally, so a lookup that failed
+ * the caller would turn an offline machine into a failing check and the check
+ * would be routed around. Every failure lands in `unknown` with its reason.
+ */
+export async function readSkew(options: SkewOptions = {}): Promise<SkewReport> {
+  const installed = options.installed ?? readInstalled()
+  const lookup = options.lookup ?? fetchLatest
+  const { name, version } = installed
+
+  if (version === undefined) {
+    return unknown(
+      installed,
+      'No version in the package manifest, so there is nothing to compare.',
+    )
+  }
+
+  if (name === undefined) {
+    return unknown(
+      installed,
+      'No name in the package manifest, so the registry has nothing to look up.',
+    )
+  }
+
+  const local = parseVersion(version)
+  if (local === undefined) {
+    return unknown(
+      installed,
+      `Installed version ${version} is not a version this can parse.`,
+    )
+  }
+
+  let raw: string
+  try {
+    raw = await lookup(name)
+  } catch (error) {
+    return unknown(installed, `Registry lookup failed: ${describe(error)}`)
+  }
+
+  const published = parseVersion(raw)
+  if (published === undefined) {
+    return unknown(
+      installed,
+      `Registry reported ${raw} as the newest version, which is not a version this can parse.`,
+    )
+  }
+
+  return {
+    state: compareVersions(local, published) < 0 ? 'behind' : 'current',
+    name,
+    installed: version,
+    latest: raw,
+  }
+}
+
+function unknown(installed: InstalledPackage, reason: string): SkewReport {
+  return {
+    state: 'unknown',
+    name: installed.name ?? UNKNOWN_LABEL,
+    installed: installed.version ?? UNKNOWN_LABEL,
+    reason,
+  }
+}
+
+/** The newest published version, or `undefined` when it could not be read. */
+export function latestOf(report: SkewReport): string | undefined {
+  return report.state === 'unknown' ? undefined : report.latest
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * The dist-tag endpoint rather than the full packument, which for this package
+ * carries every published manifest and is the larger part of a megabyte. The
+ * question is one string and this is the endpoint that answers only it.
+ */
+async function fetchLatest(name: string): Promise<string> {
+  const response = await fetch(
+    `${REGISTRY}/-/package/${encodeURIComponent(name)}/dist-tags`,
+    {
+      signal: AbortSignal.timeout(LOOKUP_TIMEOUT_MS),
+      headers: { accept: 'application/json' },
+    },
+  )
+
+  if (!response.ok) {
+    throw new Error(`registry returned ${response.status}`)
+  }
+
+  const tags = (await response.json()) as Record<string, unknown>
+  const latest = tags.latest
+
+  if (typeof latest !== 'string') {
+    throw new Error('registry reported no latest dist-tag')
+  }
+
+  return latest
+}
+
+/**
+ * One line naming the state, for a caller that renders the skew beside sections
+ * it does not own. Held here so `aitk sync --check` and `aitk claude skills
+ * drift` cannot word the same three states differently.
+ *
+ * The remedy is chosen by the same detection `aitk upgrade` runs, because both
+ * callers run from a source checkout routinely and that is where the verb
+ * refuses. Naming it unconditionally sends a contributor whose clone sits a
+ * release behind to a command that declines. The read is a match against the
+ * root string rather than a filesystem call, so the line stays cheap.
+ */
+export function describeSkew(
+  report: SkewReport,
+  root: string = PROJECT_ROOT,
+): string {
+  if (report.state === 'unknown') {
+    return `Installed ${report.installed}, published unknown. ${report.reason}`
+  }
+
+  if (report.state === 'current') {
+    return `Installed ${report.installed}, which is the newest published.`
+  }
+
+  const remedy =
+    detectManager(root) === undefined
+      ? 'This is a source checkout, so pull rather than reinstalling.'
+      : 'Run `aitk upgrade`.'
+
+  return `Installed ${report.installed}, published ${report.latest}. ${remedy}`
+}