@erclx/aitk 3.25.0 → 3.25.2

package/claude/skills/migration-standards/REQUIREMENT.md

@@ -1,50 +0,0 @@
----
-name: migration-standards
-description: Why the root-to-.claude snippets relocation ships as git mv commands the user runs, which inbound references are worth fixing, and why standards no longer travel with it
----
-
-# Migration standards requirement
-
-## Gap
-
-Without this skill, a project whose rules cite `.claude/snippets/` while the files sit at the root gets fixed by hand, and the hand fix loses what version control was holding. A plain `mv` breaks the rename chain, so every relocated snippet reads as a delete beside an unrelated add and its history stops at the move.
-
-A fourth failure comes before those three, from deciding what is unmigrated by listing the folder. A root `snippets/` can hold the project's own prompts and nothing the toolkit ever installed, and a listing cannot tell the two apart, so the skill proposes moving project files under `.claude/` where a sync walks them. The drift report already answers this, counting only files whose basename the toolkit ships, and it is the same report `toolkit-operator` reads to route here.
-
-Standards left this skill when the corpus stopped installing into a project. The report no longer names the domain, so a body still describing the move would propose relocating a folder the project authored, which is the exact failure the paragraph above records in the other direction.
-
-Taking detection from a command opens a failure the listing never had. A CLI predating the field exits zero with a well-formed report that never mentions it, so a skill treating an absent key as an empty answer tells a project whose every domain sits at the root that it has nothing to relocate. That is the population this skill exists for, and a silent false negative there costs more than the unfiltered count reading the folder would have produced.
-
-The re-sync the skill names has the same gap in the other direction. The relocation is what makes those commands land on a path that held nothing before, so the run hands over a command whose overwrite behavior it never states, and the reference holding that answer is named in the boundary below where no session reads it. Claude Code loads the skill entry alone.
-
-Three failures follow from acting without looking first. A move onto an existing `.claude/snippets/` copy overwrites the files already installed there, which is the case the relocation was supposed to be unnecessary for. A `git mv` on a dirty tree lands the relocation in the same commit as unrelated work, so neither can be reviewed or reverted alone. And a session that rewrites every inbound reference spends its effort on toolkit-owned rules and skills, which the next sync overwrites, while the author-owned lines that actually break go unmentioned.
-
-## Must
-
-- Take what to relocate from `aitk sync --check --json`, and report its filtered count rather than a folder listing
-- Say in one line that a root `standards/` folder is left alone, since a user who came here expecting both domains reads silence as an oversight
-- Keep the listing as the fallback for a target where `aitk` is absent, the command fails, or the report carries no `unmigrated` key, and say that its counts are unfiltered
-- Detect an existing copy under `.claude/` and skip the move rather than merging into it
-- Read the working tree state and require it clean before the moves, since the relocation has to be revertible on its own
-- Propose `git mv` so history follows each file
-- Report author-owned inbound references as TODO lines the user fixes, and leave the reference itself untouched
-- Name the re-sync commands that reinstall toolkit-owned content at the new path, since the move alone leaves the install stale
-- Route to the overwrite contract from the body where those commands are printed, and carry its destructive rows into the reminder
-- Report the already-relocated case as a pass
-
-## Must not
-
-- Run the moves, or edit `CLAUDE.md`, a rule file, or a doc
-- Surface references inside toolkit-owned rules and skills, which the next sync rewrites anyway
-
-## Guards
-
-- No root `snippets/` present stops, since there is nothing to relocate
-- A directory that is not a git work tree stops, since `git mv` needs version control and a plain move is the failure the skill exists to prevent
-
-## Out of scope
-
-- Classifying `CLAUDE.md` sections into the three-tier model: `migration-claude-md`
-- Relocating `docs/` files by audience: `migration-context`
-- Running the re-sync, which the user does after applying the moves
-- What each sync command overwrites once it runs: `toolkit-cli`

package/claude/skills/migration-standards/SKILL.md

@@ -1,99 +0,0 @@
----
-name: migration-standards
-description: Proposes `git mv` commands to relocate a target project's root `snippets/` folder into `.claude/snippets/`, the install layout newer toolkit versions expect. Use when asked to "relocate snippets", "move snippets to .claude", "migrate snippets to .claude", or after a toolkit upgrade leaves a rule pointing at `.claude/snippets/` while the files sit at the root. Do NOT auto-execute moves or edit rule files. Proposal only.
----
-
-# Claude standards relocate
-
-Snippets is the one domain this skill relocates. Standards used to travel beside it and the toolkit corpus now installs into no project at all, so a root `standards/` folder in a target holds work the project authored and nothing proposes moving it. `aitk standards <name>` reads a toolkit standard wherever a session needs one.
-
-## Guards
-
-- If `snippets/` does not exist at `pwd`, stop: `❌ No root snippets/ to relocate.`
-- If `pwd` is not a git work tree, stop: `❌ Not a git repository. git mv needs version control.`
-
-## Step 1: read the report
-
-Run `aitk sync --check . --json` from the project root. Its `unmigrated` array is the detection. Each entry carries `domain`, `rootPath`, `installPath`, and `files`, and a domain appears only when the root folder holds a file the toolkit ships and nothing sits at the install path. Report `files` as the count, since it excludes files the project wrote into the same folder.
-
-Run these beside it, in parallel. The report answers whether to move and neither of these is derivable from it:
-
-- `ls .claude/snippets/ 2>/dev/null`: separate a domain already relocated from one never installed, which the report cannot, since both are absent from `unmigrated`
-- `git status --short 2>/dev/null`: confirm a clean tree before proposing moves
-
-### When the report is unavailable
-
-Fall back to `ls snippets/` on any of three conditions. Say in the output that the count is unfiltered, because a root folder can hold project-authored files the report would have excluded and the fallback counts every one of them.
-
-- `aitk` is not on `PATH`
-- The command exits non-zero
-- The report parses and carries no `unmigrated` key at all
-
-The third is the one that decides whether this skill works for the projects it exists for. `unmigrated` reached a release in `0.46.0`, and a CLI older than that exits zero with a well-formed report that never mentions the field. Reading an absent key as an empty list sends the run down the nothing-to-relocate branch and reports a clean layout to a project whose every domain sits at the root, which is a silent false negative where the unfiltered count is a visible imprecision.
-
-An absent key and an empty array are different states, so test for the key rather than for emptiness. A current CLI reporting `"unmigrated": []` has looked and found nothing, and falling back there would trade a correct answer for a listing that proposes moving whatever the folder happens to hold.
-
-Do not fall back on `historyUnavailable`. That field reports failed attribution on a domain or on `seeds`, and `unmigrated` is a filesystem read carrying no attribution of its own, so a report that cannot date a file still detects the layout correctly.
-
-## Step 2: check conflicts
-
-- If `.claude/snippets/` already holds `.md` files, mark snippets as "already relocated" and skip the move.
-- If `git status` is not clean, add a TODO line telling the user to commit or stash first. `git mv` on a dirty tree mixes the move with unrelated changes.
-- If the root folder holds files and no domain names it in a report that carried the key, propose nothing. The content is the project's own, and moving it under `.claude/` puts project files where a sync walks. This reads a present key alone. A report with no `unmigrated` key never reaches here, since Step 1 sends it to the fallback.
-- A root `standards/` folder is never a conflict and never a move. Say so in one line when one is present, since a user who came here expecting both domains reads silence as an oversight.
-
-## Step 3: find author-owned inbound references
-
-Toolkit-owned rules and skills are re-synced, so do not rewrite them. Surface only references the user authored:
-
-```bash
-git grep -n "snippets/" -- 'CLAUDE.md' '.claude/rules/**' 'docs/**' 2>/dev/null
-```
-
-Report each hit as a TODO line. Exclude paths already under `.claude/snippets/`.
-
-## Step 4: output
-
-Print one grouped proposal block. Omit empty groups.
-
-```markdown
-## Relocate
-
-- snippets/ → .claude/snippets/ (<count> files)
-
-## Already relocated
-
-- .claude/snippets/ exists. Skipping.
-
-## Left alone
-
-- standards/ is the project's own. No toolkit standard installs into a project.
-
-## Suggested git mv commands
-
-mkdir -p .claude
-git mv snippets .claude/snippets
-
-## Re-sync after moving
-
-aitk snippets sync .
-aitk gov sync .
-
-## Inbound references to verify
-
-- CLAUDE.md:42 references snippets/align.md
-- docs/contributing.md:8 references snippets/claude/feature
-
-## Reminder
-
-Re-syncing reinstalls toolkit-owned rules and snippets at the new path. Author-owned references above need a manual one-line fix.
-```
-
-Two states produce no proposal at all, and each gets its own line rather than an empty block:
-
-- The folder already lives under `.claude/`: `✅ snippets/ already lives under .claude/. Nothing to relocate.`
-- The root folder exists and no domain names it in `unmigrated`: `✅ snippets/ holds no file the toolkit installed. Nothing to relocate.` The guard passed because the folder is there, so a session that printed nothing would leave the user reading silence as a failed run rather than as the answer.
-
-Read the `toolkit-cli` skill before printing the re-sync block, and name in the reminder any surface it lists as overwritten. The user runs those commands against a tree the moves above relocated, and that relocation is what puts an overwrite onto files never installed at the new path.
-
-Do not run the `git mv` commands. Do not edit `CLAUDE.md`, rule files, or docs. The user runs the commands and fixes author-owned references after reviewing.

package/src/snippets/adapter.ts

@@ -1,35 +0,0 @@
-import { existsSync } from 'node:fs'
-import { join } from 'node:path'
-import { snippetsSourceDir } from '@/snippets/categories'
-import type { InstalledFile, SyncAdapter } from '@/sync/engine'
-
-/**
- * Matches installed snippets to sources by relative path, where gov matches by
- * rule name. `derive_dest_rel_path` in `scripts/snippets/install.sh` keeps the
- * immediate parent for a nested snippet and flattens a root-level one to its
- * filename, which is the shape a source-relative path already has, so
- * destination and source rel paths agree for everything the toolkit ships.
- */
-export function createSnippetsAdapter(root: string): SyncAdapter {
-  const sourceDir = snippetsSourceDir(root)
-
-  return {
-    banner: 'aitk snippets sync',
-    label: 'snippets',
-    missingMessage:
-      "No .claude/snippets/ found in target. Run 'aitk snippets install' first.",
-    unit: 'snippets',
-    installedRoot: (target: string) => join(target, '.claude', 'snippets'),
-    locateSource: (file: InstalledFile) => locateSource(sourceDir, file),
-    projectSubdir: 'project',
-    stamp: { domain: 'snippets', toolkitRoot: root },
-  }
-}
-
-function locateSource(
-  sourceDir: string,
-  file: InstalledFile,
-): string | undefined {
-  const source = join(sourceDir, file.relToRoot)
-  return existsSync(source) ? source : undefined
-}

package/src/snippets/install.ts

@@ -1,172 +0,0 @@
-import { existsSync } from 'node:fs'
-import { basename, dirname, join } from 'node:path'
-import { copyPreservingMode } from '@/copy'
-import {
-  BASE_CATEGORY,
-  categoryDir,
-  categoryExists,
-  listCategories,
-  listEntries,
-  NONE_CATEGORY,
-  snippetsSourceDir,
-} from '@/snippets/categories'
-import { findPreset, loadPresets } from '@/snippets/presets'
-import { isDirectory } from '@/target'
-
-export const ALL_CATEGORY = 'all'
-
-export interface SnippetFile {
-  readonly src: string
-  readonly relPath: string
-}
-
-export type SnippetResolution =
-  | {
-      readonly ok: true
-      readonly step: string
-      readonly files: readonly SnippetFile[]
-      readonly missing: readonly string[]
-    }
-  | { readonly ok: false; readonly unknownCategory: string }
-
-export function installedSnippetsDir(target: string): string {
-  return join(target, '.claude', 'snippets')
-}
-
-/**
- * Derives the destination path. A snippet directly under `snippets/` installs
- * flat and a nested one keeps its immediate parent, so the installed tree
- * mirrors the source one level deep.
- */
-export function deriveDestRelPath(root: string, src: string): string {
-  const parent = dirname(src)
-  const filename = basename(src)
-
-  return parent === snippetsSourceDir(root)
-    ? filename
-    : `${basename(parent)}/${filename}`
-}
-
-function filesInCategory(root: string, category: string): SnippetFile[] {
-  return listEntries(root, category).map((slug) => {
-    const src = join(categoryDir(root, category), `${slug}.md`)
-    return { src, relPath: deriveDestRelPath(root, src) }
-  })
-}
-
-/**
- * Resolves the one argument three ways. `all` wins, then a preset name, then a
- * folder, which is the bash precedence and matters because a folder sharing a
- * preset name resolves to the preset.
- *
- * Preset slugs pass the internal-category filter too. A slug is a path relative
- * to `snippets/`, so a preset naming `aitk/<slug>` would otherwise reach an
- * internal snippet through the one install path the filter did not cover.
- */
-export function resolveSnippets(
-  root: string,
-  category: string,
-): SnippetResolution {
-  if (category === ALL_CATEGORY) {
-    const files = listCategories(root).flatMap((name) =>
-      filesInCategory(root, name),
-    )
-    return { ok: true, step: 'Resolving all categories', files, missing: [] }
-  }
-
-  if (category === NONE_CATEGORY) {
-    return {
-      ok: true,
-      step: 'Resolving category: none',
-      files: [],
-      missing: [],
-    }
-  }
-
-  const preset = findPreset(root, category)
-  if (preset) {
-    const files: SnippetFile[] = []
-    const missing: string[] = []
-
-    for (const slug of preset.slugs) {
-      const src = join(snippetsSourceDir(root), `${slug}.md`)
-      if (existsSync(src)) files.push({ src, relPath: `${slug}.md` })
-      else missing.push(slug)
-    }
-
-    return { ok: true, step: `Resolving preset: ${category}`, files, missing }
-  }
-
-  if (category !== BASE_CATEGORY && !categoryExists(root, category)) {
-    return { ok: false, unknownCategory: category }
-  }
-
-  return {
-    ok: true,
-    step: `Resolving category: ${category}`,
-    files: filesInCategory(root, category),
-    missing: [],
-  }
-}
-
-/**
- * Lists everything the picker offers: presets first, then `base`, then the
- * folder categories, matching the order the bash built the menu in.
- */
-export function installableCategories(root: string): string[] {
-  return [
-    ...loadPresets(root).map((preset) => preset.name),
-    ...listCategories(root),
-  ]
-}
-
-export async function installSnippets(
-  files: readonly SnippetFile[],
-  target: string,
-): Promise<string[]> {
-  const destDir = installedSnippetsDir(target)
-  const installed: string[] = []
-
-  for (const file of files) {
-    await copyPreservingMode(file.src, join(destDir, file.relPath))
-    installed.push(join('.claude', 'snippets', file.relPath))
-  }
-
-  return installed
-}
-
-function snippetsRuleSourceDir(root: string): string {
-  return join(root, 'governance', 'rules', 'snippets')
-}
-
-function installedSnippetsRuleDir(target: string): string {
-  return join(target, '.claude', 'rules', 'snippets')
-}
-
-/**
- * Installs the `@`-reference convention rule alongside the snippets a caller
- * took. No stack names this folder, so a project that declined snippets never
- * receives a rule describing a behavior it holds no snippet to exercise.
- */
-export async function installSnippetsRule(
-  root: string,
-  target: string,
-): Promise<string[]> {
-  const dir = snippetsRuleSourceDir(root)
-  if (!isDirectory(dir)) return []
-
-  const installed: string[] = []
-
-  for (const rel of new Bun.Glob('*.md').scanSync({
-    cwd: dir,
-    onlyFiles: true,
-  })) {
-    await copyPreservingMode(
-      join(dir, rel),
-      join(installedSnippetsRuleDir(target), rel),
-    )
-    installed.push(join('.claude', 'rules', 'snippets', rel))
-  }
-
-  return installed
-}