@erclx/aitk 0.72.0 → 0.73.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.72.0",
+  "version": "0.73.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/toolkit-operator/REQUIREMENT.md

@@ -21,6 +21,8 @@ The last failure is writing without re-checking. A domain sync brought a stricte
 - Map the stated intent to one lifecycle phase, then either run the simplest command that satisfies it or hand off
 - Resolve every stack, rule, snippet, and standard name from a catalog at runtime
 - Run the CLI non-interactively and report the command run, what changed, and the full path of anything written
+- Read the reverse walk beside the forward sections, so a folder the toolkit stopped shipping and a migration with a live case both reach the user
+- Hand off a named migration to the skill the report names, the way an unmigrated domain reaches `migration-standards`
 - Offer every audit whose surface the target carries, and offer none whose surface it lacks
 - Re-check the target after any operation that wrote, and report what those writes changed against the state read before acting
 
@@ -29,6 +31,7 @@ The last failure is writing without re-checking. A domain sync brought a stricte
 - Edit a managed file by hand instead of running the CLI that owns it
 - Reimplement a flow another skill owns
 - Hardcode a catalog name
+- Move, delete, or name a command against a folder in `unclaimed`. The toolkit stopped claiming the path and only the user knows whether the project owns what sits there
 - Run an audit the user did not pick, which turns a front door into a full sweep
 - Refuse to finish an operation over an audit finding, since every audit reports judgments beside facts and a router that stops on one is a router a target works around
 - Auto-trigger. It is a door the user opens, and a router that fires on its own routes requests nobody made.
@@ -38,6 +41,7 @@ The last failure is writing without re-checking. A domain sync brought a stricte
 - An intent matching a deep flow hands off rather than running a shallow version of it, since a partial scaffold is harder to recover from than none
 - An ignore-only fix on an unmeasured tooling report stops, names which cause applies, and names the command answering that cause. Unmeasured has several causes and they do not share a remedy, so one suggested command is wrong for at least one of them. No cause asks the user to supply a stack name, and none reads the zero counts under an unmeasured report as a clean target.
 - A re-check with no earlier report to compare against says the write ran without a baseline, rather than describing the target from scratch
+- A report missing a field this skill reads names the CLI version as the cause and reports that section as unread. Neither an absent key nor a hand-rolled substitute for it may be reported as a finding, since the first reads as a clean target and the second reaches a verdict only the field's attribution can make
 
 ## Out of scope
 

package/claude/skills/toolkit-operator/SKILL.md

@@ -22,23 +22,28 @@ Load a domain doc with `aitk docs <topic>` only when the intent touches that dom
 
 Run `aitk sync --check . --json` before routing. It reports what a target is behind on across every surface, so the intent comes from the project state rather than from the user having to know it already. Skip only when the user named a single operation to run.
 
-Read six fields off the report and carry each to `## Route`:
+Read seven fields off the report and carry each to `## Route`:
 
 - `unmigrated`: a domain sitting at the root layout with nothing under `.claude/`. The most urgent finding, because that domain reports no drift of its own while being entirely behind
 - `superseded`: a file a newer seed folder replaced. Report it and stop. No command moves it, since the content is the project's own
 - `seeds`: entries are `matching`, `stale`, `drifted`, or `missing`. Anything but `matching` needs the seed handoff
 - `domains[].entries`: per-file `stale`, `customized`, `stranded`, and `orphaned` as before
-- `historyUnavailable` on a domain or on `seeds`: attribution failed, so treat every difference as unverified and say so rather than reporting a file as untouched
+- `reverse`: what the target holds that no live catalog claims. `unclaimed` lists folders at roots the toolkit stopped shipping, each with an `attribution` of `dropped`, `unattributed`, or `project`. Act on the first two and leave `project` alone, which history proved the project owns. `migrations` names a proposal-only skill with a live case here and the `reason` it was measured from
+- `historyUnavailable` on a domain, on `seeds`, or on `reverse`: nothing could be dated, so treat every difference as unverified and say so rather than reporting a file as untouched. It is set on `reverse` when the toolkit itself ships without history, which is the registry-install case, so the walk found nothing rather than finding a clean target
 - `tooling`: read `measured` first. Every count under it is zero when it is false, which is an absence of measurement rather than a measured zero. Past that, `chain` names the stacks the install resolved, nearest first, and `counts.gitignore` counts the managed ignore entries the target is missing.
 
 State what the report found in one line per finding before acting on any of it.
 
+A `reverse` key the report does not carry at all is a CLI predating the field rather than a target with nothing unclaimed. Say the walk did not run and name the CLI version as the cause. Reading the absent key as an empty answer reports a clean target to a project nobody has looked at, and answering it from a filesystem walk of your own is worse, since that reaches a verdict the attribution the field carries is the only thing entitled to make.
+
 ## Route
 
 Map the stated intent, or what `## Diagnose` found, to one lifecycle phase, then act:
 
 - A domain in `unmigrated`: hand off to `migration-standards`
+- An entry in `migrations`: hand off to the skill its `skill` field names, spelled as the report spells it. Both of them propose without writing, so the handoff is where this stops
 - Anything in `superseded`: tell the user which files and what replaced them. Do not move or delete them
+- A folder in `unclaimed`: name it and the attribution it carries. No command moves it and the content may be the project's own, so the decision is the user's
 
 - First-time scaffold of a fresh project: hand off to `setup-init`
 - Governance rules for the project stack: hand off to `setup-gov`

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

@@ -210,6 +210,12 @@ code change. Scoping to those roots is what keeps the walk useful: walking the
 whole tree reports every project folder as unclaimed, which is true and says
 nothing.
 
+The managed gate above applies here too, and it is the one place it surprises.
+A directory holding a dropped folder and nothing else reports an empty `reverse`
+rather than the folder, because it carries none of the three markers. Read an
+empty section on an unmanaged target as a walk that never ran rather than as a
+clean result.
+
 Each entry carries `rel`, a file count, and an `attribution` of `dropped`,
 `project`, or `unattributed`. A dropped folder and one the project wrote are the
 same bytes at the same path, so the verdict is traced from history rather than

package/package.json

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

package/scripts/lib/sandbox-fixtures.sh

@@ -99,6 +99,67 @@ stage_toolkit_markdown() {
   done < <(find "$src" -maxdepth 1 -type f -name "*.md" ! -name "index.md" | sort | head -n "$count")
 }
 
+# The newest top-level path history records a deletion under that the toolkit no
+# longer ships. Read from history rather than hardcoded, so an arm stages a root
+# the walk will actually recognize instead of a name that has since come back.
+# `prompts` is preferred because it is the case measured in a real target, and
+# any other dropped root exercises the same walk.
+pick_dropped_root() {
+  local preferred="prompts"
+  local first=""
+  local candidate
+
+  while IFS= read -r candidate; do
+    [ -e "$PROJECT_ROOT/$candidate" ] && continue
+    [ "$candidate" = "$preferred" ] && {
+      echo "$preferred"
+      return 0
+    }
+    [ -n "$first" ] || first="$candidate"
+  done < <(git -C "$PROJECT_ROOT" log --all --diff-filter=D --name-only --format= |
+    awk -F/ 'NF > 1 { print $1 }' | sort -u)
+
+  echo "$first"
+}
+
+# Restores one file's exact published bytes from the commit before it was
+# deleted. Content is what the attribution matches on, so a file written by hand
+# would report unattributed and an arm would assert the wrong verdict.
+#
+# Both reads take the whole listing through a process substitution rather than a
+# pipeline ending in an early exit. `set -o pipefail` is on, and a `grep -m 1`
+# that matches the first line closes the pipe while git is still writing, so the
+# substitution returns git's SIGPIPE status and the arm fails on a listing it
+# actually read.
+restore_dropped_file() {
+  local root="$1"
+  local rel="" commit="" line
+
+  while IFS= read -r line; do
+    case "$line" in
+    "$root"/*)
+      rel="$line"
+      break
+      ;;
+    esac
+  done < <(git -C "$PROJECT_ROOT" log --all --diff-filter=D --name-only \
+    --format= -- "$root/")
+
+  [ -n "$rel" ] || return 1
+
+  while IFS= read -r line; do
+    commit="$line"
+    break
+  done < <(git -C "$PROJECT_ROOT" log --all --diff-filter=D --format=%H -- "$rel")
+
+  [ -n "$commit" ] || return 1
+
+  mkdir -p "$(dirname "$rel")"
+  git -C "$PROJECT_ROOT" show "$commit^:$rel" >"$rel" || return 1
+
+  echo "$rel"
+}
+
 # Stages one step of a scenario arm into the sandbox working directory.
 # Scenarios call this once per step so their own git operations stay between
 # the steps, where they are visible.