@erclx/aitk 0.92.0 → 0.93.0

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

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

package/claude/skills/claude-orchestrate/references/orchestrator-handoff.md

@@ -6,9 +6,10 @@ description: Memory capture at the close of a session, what to write to .claude/
 Capture what the session learned, then write the pre-compact handoff as orchestrator. Do both before a compaction, because a compaction keeps conclusions and drops the reasoning that produced them, and no other file in the repository carries that reasoning.
 
 1. Invoke `aitk:claude-memory-capture` and tell it this session does not commit. Capture reads the session and this handoff summarizes it, so capturing first lets the handoff cite what was written instead of restating the same lesson in prose.
-2. Resolve the main worktree root with `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`. Write `.claude/tasks/session.md` under it.
-3. Write only what a compaction destroys and no other file already carries. The board holds the ordering and what each task waits on, a task file holds its own findings, and a groundwork folder holds its track.
-4. Use this shape, resolving `${CLAUDE_SKILL_DIR}/references/orchestrator-resume.md` and `${CLAUDE_SKILL_DIR}/references/orchestrator-poll.md` to absolute paths as you write it and pasting each in place of `<RESUME_RUNBOOK>` and `<POLL_RUNBOOK>`:
+2. Run `aitk claude skills drift <commit this session started from>` and re-read any body it names before writing anything below. Nothing on the machine records that commit, so recover it from how long the session has been running with `git log -1 --format=%H --before='<duration> ago'`, rounding the duration up rather than down. A ref older than the oldest load over-reports and confirming a name costs one read of the body, so the generous end is the safe one and a guess at the exact commit is not worth making. A skill body enters a session once and re-invoking the skill replays the held copy rather than the file, so the drift is worst at exactly this moment and a name here is a body this session has been following out of date. Record what it named under `## Standing cautions`. The verb answers where the working directory carries `claude/skills/` with history behind it, which is the toolkit repository itself, and refuses by naming the absent tree anywhere else. A project consuming the plugin from a marketplace cache is that second case, so read the refusal as the boundary rather than as a fault.
+3. Resolve the main worktree root with `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`. Write `.claude/tasks/session.md` under it.
+4. Write only what a compaction destroys and no other file already carries. The board holds the ordering and what each task waits on, a task file holds its own findings, and a groundwork folder holds its track.
+5. Use this shape, resolving `${CLAUDE_SKILL_DIR}/references/orchestrator-resume.md` and `${CLAUDE_SKILL_DIR}/references/orchestrator-poll.md` to absolute paths as you write it and pasting each in place of `<RESUME_RUNBOOK>` and `<POLL_RUNBOOK>`:
 
 ```markdown
 ---
@@ -41,10 +42,10 @@ Resume by loading the orchestrator skill and asking it to resume after a compact
 That resume reads the board and stops. It restarts nothing, so the review poll is a second thing owed here, and <POLL_RUNBOOK> holds the prompt and the condition. Do not reach for `session-resume`, which reads tracked work and knows nothing about this board or the workers on it.
 ```
 
-5. Cite a commit, a task, or a file and line for every claim, so the next session can tell a read from a recall.
-6. Overwrite the previous handoff rather than appending to it. A stale entry read as current is worse than no handoff.
+6. Cite a commit, a task, or a file and line for every claim, so the next session can tell a read from a recall.
+7. Overwrite the previous handoff rather than appending to it. A stale entry read as current is worse than no handoff.
 
-The substitution belongs in step 4 because step 6 ends the write. A reader who treats the list as finished there ships the literal placeholders, and the variable expands while this runbook renders rather than in the turn that reads the handoff back, so a path left unresolved reaches a session holding no skill as a string matching nothing. `orchestrator-poll.md` resolves its script at the same point and for the same reason.
+The substitution belongs in step 5 because step 7 ends the write. A reader who treats the list as finished there ships the literal placeholders, and the variable expands while this runbook renders rather than in the turn that reads the handoff back, so a path left unresolved reaches a session holding no skill as a string matching nothing. `orchestrator-poll.md` resolves its script at the same point and for the same reason.
 
 Add a section only for content that fits none of the four and would otherwise be lost. Do not restate the board, and do not summarize the work that shipped, because git already carries it. The closing block is the one exception, and the paragraph below states why.
 

package/docs/agents/commands.md

@@ -40,27 +40,28 @@ 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 capture [source]`    | Render HTML capture sources to PNG, toolkit-only and absent from an installed package                                                     |
 
 ## Domain commands
 
 Each domain exposes a consistent shape where applicable: `list`, `install`, `sync`, `create`.
 
-| Domain      | Subcommands                                                                 |
-| ----------- | --------------------------------------------------------------------------- |
-| `tooling`   | `list`, `sync`, `ref`, `create`, `verify`, `inject`, `prune-gitignore`      |
-| `snippets`  | `list`, `install`, `sync`, `create`                                         |
-| `standards` | `list`, `install`, `sync`, `<name>`                                         |
-| `gov`       | `list`, `install`, `sync`, `build`                                          |
-| `claude`    | `init`, `sync`, `seeds list`, `skills list`, `skills audit`, `setup [dest]` |
-| `wiki`      | `init`                                                                      |
-| `design`    | `render`                                                                    |
-| `slides`    | `render`, `list`                                                            |
-| `tasks`     | `archive`, `validate`                                                       |
-| `intake`    | `list`, `answer`                                                            |
-| `comments`  | `scan`                                                                      |
-| `context`   | `audit`                                                                     |
-| `markdown`  | `audit`                                                                     |
+| Domain      | Subcommands                                                                                 |
+| ----------- | ------------------------------------------------------------------------------------------- |
+| `tooling`   | `list`, `sync`, `ref`, `create`, `verify`, `inject`, `prune-gitignore`                      |
+| `snippets`  | `list`, `install`, `sync`, `create`                                                         |
+| `standards` | `list`, `install`, `sync`, `<name>`                                                         |
+| `gov`       | `list`, `install`, `sync`, `build`                                                          |
+| `claude`    | `init`, `sync`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `setup [dest]` |
+| `wiki`      | `init`                                                                                      |
+| `design`    | `render`                                                                                    |
+| `slides`    | `render`, `list`                                                                            |
+| `tasks`     | `archive`, `validate`                                                                       |
+| `intake`    | `list`, `answer`                                                                            |
+| `comments`  | `scan`                                                                                      |
+| `context`   | `audit`                                                                                     |
+| `markdown`  | `audit`                                                                                     |
 
 Common patterns:
 

package/docs/agents/index.md

@@ -24,5 +24,5 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Sandbox](sandbox.md): Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills
 - [Scripting](scripting.md): The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
 - [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, the liveness confidence field, the unresolved reasons, and what the read depends on
-- [Skill audit](skills-audit.md): Measuring both skill corpora against standards/skill.md, the checks it reads, and the requirement gate that is the only failing one
+- [Skill audit](skills-audit.md): Measuring both skill corpora against standards/skill.md, the checks it reads, the requirement gate that is the only failing one, and the drift verb that names bodies rewritten since a ref
 - [Tasks](tasks.md): Selecting a shipped task by stem or pull request, recording a number and closing an outcome, the refusal reasons, the board checks validate runs, and why the board root defaults to the main worktree

package/docs/agents/skills-audit.md

@@ -1,6 +1,6 @@
 ---
 title: Skill audit
-description: Measuring both skill corpora against standards/skill.md, the checks it reads, and the requirement gate that is the only failing one
+description: Measuring both skill corpora against standards/skill.md, the checks it reads, the requirement gate that is the only failing one, and the drift verb that names bodies rewritten since a ref
 ---
 
 # Skill audit
@@ -53,3 +53,36 @@ Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a skill folde
 `--requirements-only` is the half wired into `bun run check`. Presence of a required file is a fact with no false positives, and the rule had nothing reading it, so a skill shipped without the sibling passed every stage while the standard required it.
 
 The check is preventive rather than diagnostic. Every mechanical rule passed across both corpora the day it shipped, so what it buys is the regression it stops rather than a backlog it surfaces.
+
+## Drift since a ref
+
+`aitk claude skills drift <ref>` names the shipped skill bodies rewritten between that commit and the current `HEAD`.
+
+```bash
+aitk claude skills drift HEAD~20
+aitk claude skills drift 02d7b265 --json
+```
+
+| Option   | Behavior                                                   |
+| -------- | ---------------------------------------------------------- |
+| `--json` | Add a machine-readable record on stdout, keeping the frame |
+
+A skill body enters a session once and stays. Re-invoking the skill replays the copy the session already holds rather than re-reading the file, so a session that outlives a merge touching a body it loaded keeps applying what it loaded and nothing compares the two. A compaction carries the held copy forward with the summary it writes, which makes the exposure the age of the oldest load rather than the age of the session.
+
+The ref is required and carries no default. `HEAD` is the only value the command could supply for itself, and it answers every run with nothing moved, which is the silence this verb exists to break. A session passes the commit it started from.
+
+Nothing on the machine records that commit, so a session recovers it from its own elapsed run time with `git log -1 --format=%H --before='<duration> ago'` and rounds the duration up. Over-reporting costs one read of a body while under-reporting costs the answer, so the generous end of the estimate is the correct one and no session needs to pin the exact commit.
+
+### What drift reads
+
+Bodies alone, one `SKILL.md` per folder, across `claude/skills/` and not the internal tree. A reference or a requirement beside the body is read by whoever opens it and holds no copy that outlives the read, and the internal corpus never loads into a target session at all.
+
+The report names the newest commit that rewrote each body rather than the first, so a body rewritten twice in the range points at the version on disk now.
+
+### What drift cannot answer
+
+The report says a file moved, not that a session holds a stale copy. A session cannot read its own loaded body as bytes, so the comparison runs against history and a ref older than the oldest load over-reports. That is the safe direction, since confirming a name costs one read of the body while the failure being answered is silence. Every run states the bound, including the run that names nothing.
+
+Two cases fall outside the range. An uncommitted edit in the working tree is not history yet, so a body changed and left unstaged reports as unmoved. A target project loads the plugin from a marketplace cache with no repository behind it, where the verb refuses and names the absent history rather than reporting a clean tree.
+
+Exit codes are `0` when history was read, whether or not a body moved, and `1` when the question could not be answered. An absent shipped corpus, an absent repository, and a ref matching no commit each refuse with their own reason on stderr. A command exiting zero on a question it never answered is the failure `.claude/ARCHITECTURE.md` already records against two skills, which is why no path here reports an empty result in place of a refusal.

package/package.json

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

package/src/claude/skills-drift.ts

@@ -0,0 +1,156 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { execaSync } from 'execa'
+import { gitEnv } from '@/git-env'
+
+/**
+ * The shipped corpus alone. A session loads a body from the plugin root, which
+ * resolves to `claude/skills/`, so the internal tree carries no held copy that
+ * could go stale in one.
+ *
+ * Held with posix separators because it is passed to git as a pathspec. Git
+ * emits and accepts posix separators on every platform, so a `join()` form would
+ * reach a Windows checkout as `claude\skills`, match no path, and return an
+ * empty log that reads as a tree where nothing moved.
+ */
+const SHIPPED_SKILLS = 'claude/skills'
+
+/** A `%H` line, which is 40 hex characters under sha1 and 64 under sha256. */
+const COMMIT = /^[0-9a-f]{40,64}$/
+
+/**
+ * A skill body, which is the only file in the folder a session loads. A
+ * reference or a requirement beside it is read by whoever opens it, so it holds
+ * no copy that outlives the read.
+ */
+const BODY = /^claude\/skills\/([^/]+)\/SKILL\.md$/
+
+export interface MovedBody {
+  readonly name: string
+  /** The newest commit that rewrote this body, not the first. */
+  readonly commit: string
+}
+
+export type DriftReport =
+  | {
+      readonly kind: 'measured'
+      readonly base: string
+      readonly head: string
+      readonly moved: readonly MovedBody[]
+    }
+  | { readonly kind: 'unreadable'; readonly reason: string }
+
+/**
+ * Reads `--name-only` log output into one entry per skill whose body moved.
+ *
+ * Reverse-chronological input means the first commit naming a body is the
+ * newest that rewrote it, so an existing name is never overwritten. A body
+ * rewritten twice therefore reports the recent commit, which is the one a
+ * session can read to see what it is missing.
+ */
+export function parseMovedBodies(output: string): MovedBody[] {
+  const moved = new Map<string, string>()
+  let commit = ''
+
+  for (const line of output.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed === '') continue
+
+    if (COMMIT.test(trimmed)) {
+      commit = trimmed
+      continue
+    }
+
+    const match = BODY.exec(trimmed)
+    if (match === null || commit === '') continue
+    if (!moved.has(match[1])) moved.set(match[1], commit)
+  }
+
+  return [...moved]
+    .map(([name, sha]) => ({ name, commit: sha }))
+    .sort((left, right) => left.name.localeCompare(right.name))
+}
+
+/**
+ * Which shipped skill bodies were rewritten between `ref` and the current
+ * `HEAD` of the tree at `root`.
+ *
+ * This measures a file moving rather than a held copy differing. A session
+ * cannot read its own loaded body as bytes, so the comparison runs against
+ * history and a session passing a ref older than its oldest load over-reports.
+ * That is the safe direction, since confirming a name costs one read of the
+ * body while the failure this answers is silence.
+ *
+ * Every path that cannot answer returns `unreadable` with its own reason. A
+ * target project loads the plugin from a marketplace cache with no history
+ * behind it, where reporting an empty result would read as a clean tree.
+ */
+export function readDrift(root: string, ref: string): DriftReport {
+  if (!existsSync(join(root, SHIPPED_SKILLS))) {
+    return {
+      kind: 'unreadable',
+      reason: `No shipped skill corpus under ${root}. Looked for ${SHIPPED_SKILLS}.`,
+    }
+  }
+
+  const head = revParse(root, 'HEAD')
+  if (head === undefined) {
+    return {
+      kind: 'unreadable',
+      reason: `No git history under ${root}. A plugin loaded from a marketplace cache carries none, so a ref cannot be resolved there.`,
+    }
+  }
+
+  const base = revParse(root, ref)
+  if (base === undefined) {
+    return {
+      kind: 'unreadable',
+      reason: `Ref ${ref} resolves to no commit in ${root}. Pass a commit this tree carries.`,
+    }
+  }
+
+  const result = execaSync(
+    'git',
+    [
+      '-C',
+      root,
+      'log',
+      '--name-only',
+      '--no-renames',
+      '--format=%H',
+      `${base}..${head}`,
+      '--',
+      SHIPPED_SKILLS,
+    ],
+    { reject: false, env: gitEnv(), extendEnv: false },
+  )
+
+  if (result.exitCode !== 0) {
+    return {
+      kind: 'unreadable',
+      reason: `Reading history between ${ref} and HEAD failed: ${result.stderr || result.stdout}`,
+    }
+  }
+
+  return {
+    kind: 'measured',
+    base,
+    head,
+    moved: parseMovedBodies(result.stdout),
+  }
+}
+
+/**
+ * The commit a ref names, or `undefined` when the tree carries no repository or
+ * no such ref. `^{commit}` is what turns a tag or a tree into the commit behind
+ * it, so a caller never compares a ref against an object of another type.
+ */
+function revParse(root: string, ref: string): string | undefined {
+  const result = execaSync(
+    'git',
+    ['-C', root, 'rev-parse', '--verify', '--quiet', `${ref}^{commit}`],
+    { reject: false, env: gitEnv(), extendEnv: false },
+  )
+
+  return result.exitCode === 0 ? result.stdout.trim() : undefined
+}

package/src/commands/claude.ts

@@ -21,6 +21,7 @@ import {
   type SkillFinding,
   type SkillsAudit,
 } from '@/claude/skills-audit'
+import { type DriftReport, readDrift } from '@/claude/skills-drift'
 import { listSkills } from '@/claude/skills-list'
 import {
   planSettings,
@@ -67,6 +68,10 @@ interface SkillsAuditOptions {
   readonly requirementsOnly?: boolean
 }
 
+interface SkillsDriftOptions {
+  readonly json?: boolean
+}
+
 const SEEDED_FILES: readonly string[] = [
   'ARCHITECTURE.md',
   'REQUIREMENTS.md',
@@ -157,15 +162,15 @@ export function register(program: Command): void {
 
   const skills = claude
     .command('skills')
-    .description('Plugin skill catalog (list, audit)')
-    .argument('[subcommand]', "One of 'list' or 'audit'")
+    .description('Plugin skill catalog (list, audit, drift)')
+    .argument('[subcommand]', "One of 'list', 'audit', or 'drift'")
     .helpOption('-h, --help', 'Show this help message')
     .action((subcommand: string | undefined) => {
       intro('aitk claude')
       logError(
         subcommand === undefined
-          ? "Missing subcommand. Use 'list' or 'audit'."
-          : `Unknown subcommand: ${subcommand}. Use 'list' or 'audit'.`,
+          ? "Missing subcommand. Use 'list', 'audit', or 'drift'."
+          : `Unknown subcommand: ${subcommand}. Use 'list', 'audit', or 'drift'.`,
       )
       outro()
       process.exitCode = 1
@@ -225,6 +230,34 @@ export function register(program: Command): void {
     .action(async (path: string | undefined, opts: SkillsAuditOptions) => {
       process.exitCode = await runSkillsAudit(path, opts)
     })
+
+  skills
+    .command('drift')
+    .description('Name the shipped skill bodies rewritten since a given ref')
+    .argument('<ref>', 'The commit a session started from')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  history was read, whether or not a body moved',
+        '  1  the question could not be answered, with the reason on stderr',
+        '',
+        'A moved body means the file changed, not that a session holds a stale',
+        'copy. Passing a ref older than the oldest load over-reports, which is',
+        'the safe direction. Confirm a name by reading the body.',
+        '',
+        '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)
+    })
 }
 
 function succeed(message: string): number {
@@ -467,6 +500,75 @@ function runSkillsList(opts: SkillsListOptions): number {
   return 0
 }
 
+/**
+ * Measures the cwd for the same reason the audit does, and takes the ref as a
+ * required argument with no default. `HEAD` would be the only defensible one and
+ * it answers every run with nothing moved, which is the silence this reports
+ * against.
+ */
+function runSkillsDrift(ref: string, opts: SkillsDriftOptions): number {
+  const root = process.cwd()
+  const report = readDrift(root, ref)
+
+  if (report.kind === 'measured') {
+    intro('aitk claude skills drift')
+    reportDrift(report, ref)
+    outro()
+  } else {
+    frameError(report.reason)
+  }
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        report.kind === 'measured'
+          ? {
+              root,
+              ref,
+              base: report.base,
+              head: report.head,
+              moved: report.moved,
+            }
+          : { root, ref, unreadable: report.reason },
+      )}\n`,
+    )
+  }
+
+  return report.kind === 'measured' ? 0 : 1
+}
+
+/**
+ * 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
+ * command has no access to that.
+ */
+function reportDrift(
+  report: Extract<DriftReport, { kind: 'measured' }>,
+  ref: string,
+): void {
+  logStep('Range')
+  logInfo(`${ref} to HEAD, resolved as ${report.base}..${report.head}.`)
+  logInfo(
+    'A body here changed on disk. Whether a session still holds the old one is what reading it settles.',
+  )
+
+  logStep('Moved bodies')
+  if (report.moved.length === 0) {
+    logInfo('No shipped body changed in this range.')
+    return
+  }
+
+  const count = report.moved.length
+  logWarn(
+    `${count} skill ${count === 1 ? 'body' : 'bodies'} rewritten since ${ref}`,
+  )
+  pipeOutput(
+    report.moved
+      .map((moved) => `${moved.name}  ${moved.commit.slice(0, 8)}`)
+      .join('\n'),
+  )
+}
+
 /**
  * Measures the tree at the cwd rather than the toolkit root the catalog reads,
  * so a linked worktree audits its own branch instead of reporting on `main`. A