@erclx/aitk 3.19.0 → 3.20.0

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

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

package/claude/skills/create-rule/REQUIREMENT.md

@@ -1,39 +1,41 @@
 ---
 name: create-rule
-description: Why a project-local rule needs a band, a number checked against two catalogs, and a scope key that decides when it fires
+description: Why a project-local rule needs a subdir, a number from the band reserved for one, and a scope key that decides when it fires
 ---
 
 # Create rule requirement
 
 ## Gap
 
-Without this skill, a project rule is written straight into the rules folder on a number already taken, so two rules collide and one loses. The subtler collision was with the toolkit itself: a number free in the target today could be the number a shipped rule landed on tomorrow, and the next install double-booked it, so a rule the project wrote got overwritten by one it never chose. Writing under `.claude/rules/project/` closes that half regardless of the number, since the sync engine orphans the file by location before it ever compares names, but the band still needs a free number to stay readable against the toolkit's own numbering.
+Without this skill, a project rule is written straight into the rules folder on a number already taken, so two rules collide and one loses. The subtler collision was with the toolkit itself: a number free in the target today could be the number a shipped rule landed on tomorrow, and the next install double-booked it, so a rule the project wrote got overwritten by one it never chose. Writing under `.claude/rules/project/` closes that half regardless of the number, since the sync engine orphans the file by location before it ever compares names.
 
-The band gets picked by feel, so a UI copy rule lands in the always-on range and loads on every session for the rest of the project's life. The scope key fails in both directions. An always-on rule carrying a path scope fires only on files it was never about, and a path-scoped rule missing it loads constantly. Written from memory rather than from the rule standard, the body comes out in a shape the rest of the catalog does not share.
+Numbering in `900-999` closes the other half. A number scanned against today's toolkit catalog goes stale on the next release, and a reserved band does not.
+
+The subdir gets picked by feel, so a UI copy rule lands in the always-on folder and loads on every session for the rest of the project's life. The scope key fails in both directions. An always-on rule carrying a path scope fires only on files it was never about, and a path-scoped rule missing it loads constantly. Written from memory rather than from the rule standard, the body comes out in a shape the rest of the catalog does not share.
 
 ## Must
 
 - Resolve what the rule enforces and where it applies, asking only for what the request leaves missing
-- Pick the band from the topic and take its number range and folder from that choice
+- Pick the subdir from the topic and take the folder from that choice
 - Write under `.claude/rules/project/`, the subfolder the sync engine reads as project-authored by location
-- Check both the target's used prefixes and the toolkit catalog before taking a number
+- Take the lowest free number at or above `900`, scanning every project subdir the target holds rather than one
 - Read the rule standard before writing the body
 - Emit the path scope for a path-scoped rule and omit the key entirely for an always-on one
-- Preview the resolved path, band, number, and frontmatter, then write without pausing
+- Preview the resolved path, subdir, number, and frontmatter, then write without pausing
 - Say when the rule loads, since path-scoped and always-on rules behave differently
 
 ## Must not
 
 - Edit a toolkit source rule, which is authored in the toolkit and would be overwritten here
 - Work the body shape or the frontmatter from memory
-- Take a number without checking the toolkit catalog, which is the collision that surfaces later
+- Take a number below `900`, which a later toolkit release can ship into
 - Write more than one topic into a single rule
 
 ## Guards
 
 - No project Claude directory: stop, since there is nowhere for the rule to live
 - The request names no behavior to enforce: stop rather than inventing one
-- The toolkit CLI is not on PATH: scan the target alone and warn that a later install could collide
+- The reserved band holds no free number: stop rather than reaching below `900`
 
 ## Out of scope
 

package/claude/skills/create-rule/SKILL.md

@@ -5,7 +5,7 @@ description: Scaffolds a project-specific governance rule into `.claude/rules/pr
 
 # Create rule
 
-Author a project-local governance rule. The rule lives in the target project, not the toolkit, so `aitk gov sync` never overwrites it: the sync engine orphans anything under `.claude/rules/project/` by location, before it ever checks the rule's name against the toolkit catalog.
+Author a project-local governance rule. The rule lives in the target project, not the toolkit, so `aitk gov sync` never overwrites it: the sync engine orphans anything under `.claude/rules/project/` by location, before it ever checks the rule's name against the toolkit catalog. A rule written anywhere else under `.claude/rules/` survives the sync too, and the report offers it the path under the project subfolder it would take.
 
 ## Guards
 
@@ -19,30 +19,30 @@ Resolve both from the request, and ask only for what is missing. Attach a propos
 - What the rule enforces: one topic, phrased as a standard (`<topic> conventions`).
 - Scope: a path glob relative to the project root (`<dir>/**/*.<ext>`) for a path-scoped rule, or always-on when the rule states a global principle with no file scope.
 
-## Step 2: resolve band and subdir
+## Step 2: resolve the subdir
 
-Pick the band from the topic. Each band owns a number range and a subdir under `.claude/rules/project/`:
+Pick the subdir from the topic. It sits under `.claude/rules/project/` and names the rule's domain:
 
-- `core/` 000-099: global persona, testing, error handling, planning. Always-on, no `paths:`.
-- `lang/` 100-199: one programming language.
-- `framework/` 200-299: one framework.
-- `lib/` 300-399: one library or tool.
-- `ui/` 400-499: UI copy, accessibility, forms.
-- `claude/` 500-599: `.claude/` authoring surfaces.
+- `core/`: global persona, testing, error handling, planning. Always-on, no `paths:`.
+- `lang/`: one programming language.
+- `framework/`: one framework.
+- `lib/`: one library or tool.
+- `ui/`: UI copy, accessibility, forms.
+- `claude/`: `.claude/` authoring surfaces.
 
 ## Step 3: pick a free number
 
-Pick the lowest unused number in the band that collides with neither the project nor the toolkit catalog:
+A project-authored rule numbers in `900-999`, the band reserved for one. `000-899` belongs to the toolkit, so a number free in the target today is one a later release can ship into.
 
-- Scan the target's `.claude/rules/project/<subdir>/` for used prefixes.
-- Run `aitk gov list --json 2>/dev/null` and read the shipped rule numbers in the same range, so the band stays readable against the toolkit's own numbering even though location already keeps a later `aitk gov install` from touching this file.
-- If `aitk` is not on PATH, scan the target only and warn that the band could read confusingly against a later toolkit install.
+- Scan every `.claude/rules/project/<subdir>/` in the target for used prefixes, not only the subdir this rule lands in. The band runs as one sequence across all of them.
+- Take the lowest unused number at or above `900`.
+- Stop and say so if the band is full, rather than reaching below `900`.
 
 ## Step 4: write the rule
 
 Read `${CLAUDE_SKILL_DIR}/../../standards/rule.md` for frontmatter, body shape, and voice before writing the body. Do not work the shape from memory.
 
-Write `.claude/rules/project/<subdir>/<n>-<slug>.md` where `<slug>` is a 1-to-3-word kebab topic. Preview the resolved path, band, number, and frontmatter, then write immediately. The tool permission dialog is the confirmation gate.
+Write `.claude/rules/project/<subdir>/<n>-<slug>.md` where `<slug>` is a 1-to-3-word kebab topic. Preview the resolved path, subdir, number, and frontmatter, then write immediately. The tool permission dialog is the confirmation gate.
 
 Frontmatter carries the Claude shape. Path-scoped rules emit one `paths:` entry per glob. Always-on rules omit `paths:` entirely.
 

package/docs/agents/install-and-sync.md

@@ -16,6 +16,21 @@ is left alone regardless of its name, since that subfolder is project-authored
 by location. It also removes a stale `.claude/GOV.md`
 from the retired build. Use `aitk gov install` to add rules.
 
+A rule the toolkit finds no source for, sitting in a shared subdirectory rather
+than under `.claude/rules/project/`, is reported with the path under that
+subfolder it would take. The offer is conditional on the project having written
+the rule, since a rule the toolkit shipped and later renamed reaches the same
+line, and moving one there would mark it the project's for good. Nothing is
+moved either way, because a rule's installed path is one the project's own
+rules, skills, and docs may cite. `aitk standards rule` carries the reserved
+number bands behind that placement, where `900-999` is the range a
+project-authored rule takes and everything below it belongs to the toolkit.
+
+`aitk snippets sync` reports the same way for a snippet outside
+`.claude/snippets/project/`, since both adapters declare the subfolder.
+`aitk sync --check` does not. It skips every orphaned entry, so the destination
+reaches the two domain sync verbs alone.
+
 When the target's install recorded a stack, `aitk gov sync` also reports a
 rule that stack lists and `.claude/rules/` does not hold, as a `missing` entry
 carrying no change. This is what makes a target whose recorded sync point

package/governance/rules/claude/590-rule-authoring.md

@@ -8,8 +8,10 @@ paths:
 
 ## Numbering
 
-- Name a rule `.claude/rules/<subdirectory>/<n>-<slug>.md`, taking a number that collides with neither the project's rules nor any installed shared set.
-- Give every rule a numeric prefix and keep the slug to one to three kebab words.
+- Name a rule `.claude/rules/<subdirectory>/<n>-<slug>.md`. Give every rule a numeric prefix and keep the slug to one to three kebab words.
+- Treat `000-899` as reserved for a rule set that ships to targets, `000-599` across the shared subdirectories and `600-899` held for ones it has not added.
+- Number a rule the project authored itself in `900-999` and write it at `.claude/rules/project/<subdirectory>/<n>-<slug>.md`.
+- Do not take a reserved number for a project-authored rule because nothing installed holds it today. A later release can ship into it.
 
 ## Body
 

package/package.json

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

package/src/sync/engine.ts

@@ -81,9 +81,10 @@ export interface ScanEntry {
   /** Toolkit revision this file's content came from, when history proved it. */
   readonly since?: string
   /**
-   * Overrides `report`'s generic text for this entry's state. `collectMissing`
-   * is the one producer: a stack name is only known to the adapter that
-   * resolved it, and the generic `missing` line cannot carry one.
+   * Overrides `report`'s generic text for this entry's state. Two producers
+   * write one: `collectMissing`, since a stack name is only known to the
+   * adapter that resolved it, and an orphan sitting outside the declared
+   * project subfolder, since the generic line names no destination.
    */
   readonly notice?: string
 }
@@ -143,6 +144,9 @@ export interface SyncAdapter {
    * location rather than by the name inference `locateSource` runs.
    * Checked before `locateSource`, so a file here is orphaned even when its
    * name also matches a toolkit source, and never enters the stamp.
+   *
+   * Declaring it also gives the report a destination to name when the name
+   * inference orphans a file sitting anywhere else.
    */
   readonly projectSubdir?: string
   /** Defaults to applying. */
@@ -200,7 +204,7 @@ export function planSync(adapter: SyncAdapter, target: string): SyncPlan {
     const source = adapter.locateSource(file)
 
     if (source === undefined || !existsSync(source)) {
-      entries.push({ state: 'orphaned', rel: file.rel })
+      entries.push(misplacedOrphan(adapter, target, file))
       continue
     }
 
@@ -419,7 +423,8 @@ function report(adapter: SyncAdapter, plan: SyncPlan): void {
       logWarn(
         entry.notice ?? `${entry.rel} (listed by the stack, not installed)`,
       )
-    else logWarn(`${entry.rel} (not in toolkit source, skipping)`)
+    else
+      logWarn(entry.notice ?? `${entry.rel} (not in toolkit source, skipping)`)
   }
 
   for (const surface of plan.retired) {
@@ -486,6 +491,43 @@ function isProjectAuthored(adapter: SyncAdapter, file: InstalledFile): boolean {
   return file.relToRoot.split('/')[0] === adapter.projectSubdir
 }
 
+/**
+ * An orphan the name inference caught rather than the location test. No source
+ * name matched, which is what a project-authored file looks like and also what
+ * a file the toolkit shipped and later renamed looks like, so the line offers
+ * the destination on a condition rather than asserting who wrote the file.
+ * Moving a toolkit leftover into the project subfolder would mark it the
+ * project's permanently, and only the operator can tell the two apart.
+ *
+ * The stamp cannot tell them apart either. `recordStamp` skips a file whose
+ * source is gone and `writeStamp` replaces the domain's whole `files` map, so
+ * a renamed rule's entry survives exactly one sync past the rename, and a
+ * target installed before stamping shipped has no entry to read at all.
+ *
+ * Naming the destination is all this does. Moving the file rewrites a path the
+ * project's own rules, skills, and docs may cite, so the sync leaves it where
+ * it is.
+ */
+function misplacedOrphan(
+  adapter: SyncAdapter,
+  target: string,
+  file: InstalledFile,
+): ScanEntry {
+  const subdir = adapter.projectSubdir
+  if (subdir === undefined) return { state: 'orphaned', rel: file.rel }
+
+  const belongs = relative(
+    target,
+    resolve(adapter.installedRoot(target), subdir, file.relToRoot),
+  )
+
+  return {
+    state: 'orphaned',
+    rel: file.rel,
+    notice: `${file.rel} (not in toolkit source, skipping. Move it to ${belongs} if the project authored it.)`,
+  }
+}
+
 function isInside(target: string, path: string): boolean {
   const rel = relative(target, path)
   return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel)

package/standards/rule.md

@@ -33,17 +33,27 @@ Write both when both apply. A rule stating the directive and a skill stating how
 
 - Rules live at `.claude/rules/<subdirectory>/<n>-<slug>.md`
 - Subdirectories group by domain: `core/`, `lang/`, `framework/`, `lib/`, `ui/`, `claude/`
-- `<n>` is a number in the subdirectory's band and `<slug>` is a one-to-three-word kebab topic
-- Scaffold a rule with a number that collides with neither the project's rules nor any installed shared rule set
+- `<n>` is a number from the band reserved for the rule's source and `<slug>` is a one-to-three-word kebab topic
+- A rule the project authored itself lives at `.claude/rules/project/<subdirectory>/<n>-<slug>.md`, keeping the same subdirectory names
 - Give every rule a numeric prefix. A bare-word filename reads as a folder name where a stack names its rules, so a rule without one is unreachable from a stack entry.
 
+## Reserved numbers
+
+`000-899` is reserved for a rule set that ships to targets. `000-599` is what the six subdirectories above already divide, at 100 per subdirectory, and `600-899` is held for subdirectories a shipped set has not added yet.
+
+A project-authored rule takes `900-999`, one sequence across every subdirectory under `.claude/rules/project/`. Scanning for a free number instead is what fails, because a shipped set fills its own band release by release, so what reads as free today is what a later release lands on. One target authored `claude/561-self-check.md` on a day nothing shipped at 561, met `claude/561-teach.md` on its next install, and now reads two numbers differently from everywhere else.
+
+The cost is that a project-authored rule's leading digit stops naming its domain. Its subdirectory names it instead, and install preserves that either way. What a shared band costs is worse: a session that loads two rules reading as one number, with nothing in the folder to say which is which.
+
+`aitk gov sync` reports a rule it finds no toolkit source for, outside `.claude/rules/project/`, and offers the path under it. The offer is conditional on the project having authored the rule, because a rule the toolkit shipped and later renamed looks identical from the outside and moving one there would mark it the project's for good. Nothing is moved either way, since a rule's installed path is one the project's own rules, skills, and docs may cite.
+
 ## Two sources numbering into one folder
 
-A shared rule set and a project's own rules land in the same installed folder and draw from the same band, so the two need a division or they collide. Divide the band by source rather than by topic: one source takes the top of each band and the other takes the gaps between the tens. A rule set that ships to targets should take the tens, since it is the source a project cannot renumber.
+The reservation above divides one pair, being a shipped set against the rules a project wrote for itself. A third source numbering into the same folder needs its own division, which is the case for a rule set held back from targets and installed only where it was authored. Divide by source rather than by topic: one source takes the top of each subdirectory's band and the other takes the gaps between the tens.
 
-The collision this prevents is silent. Two rules that resolve to the same `<n>-<slug>` path leave one file in the installed folder, and neither the install nor the session that reads it reports which source lost. Nothing checks the division, so it holds only while both sources follow it.
+The collision this prevents is silent. Two rules that resolve to the same `<n>-<slug>` path leave one file in the installed folder, and neither the install nor the session that reads it reports which source lost. Nothing checks a division outside the reserved bands, so it holds only while both sources follow it.
 
-State the division where the rule sources are described, not in the rules themselves. A rule states its own topic, and a numbering convention spanning two sources belongs to whatever documents the pair.
+State that division where the rule sources are described, not inside the rules it divides. A rule states its own topic, and a numbering convention spanning two sources belongs to whatever documents the pair.
 
 ## Frontmatter