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

package/claude/skills/claude-orchestrate/REQUIREMENT.md

@@ -21,6 +21,8 @@ The ban on writing at all fails on a different axis, which is that nothing enfor
 
 Output drifts everywhere the contract stops. The specified shape covers invocation alone, so a sweep report, a board report, and an analysis each end in a decision the human owns and each buries it under the evidence they would have skipped. A compaction is the same failure one step earlier, since the file that survives it has a stated reader and no stated writer, and the session improvises what to save and loses the reasoning the board never held.
 
+Naming that reader without naming the way in fails on the next axis, and it fails circularly. The command that routes a resume request lives in this body, which is the surface a long session is likeliest to have dropped, and dropping it is the condition the handoff exists to survive, so the session holding a complete handoff cannot reach the runbook that reads it back. The review poll is lost in the same moment and recovered by neither, since it is session-scoped and the resume performs no restart, which leaves a reader who follows the whole handoff with a board and no trigger.
+
 The runbooks the session cannot run from memory fail on a third axis, which is where they are kept. A runbook reached by an installed path is a dependency on a channel this skill does not travel on, so a project holding the plugin and running no install follows the citation to nothing, and nothing reports the break because a missing file produces no error until someone opens the path. Every one of them therefore has to ship inside the skill, the three covering the moments the loop cannot detect and the fourth holding the review trigger. That fourth one fails on an axis of its own, since it names one client's command as the way to start the loop, so a session holding a different recurring-prompt scheduler reaches no path and a client without that command reaches none either, and the file ships to every target holding the plugin.
 
 The session also records nothing of what it learns. Both other callers of memory capture are ship-chain skills and this one never ships, so the session taking every operator correction is the session with no moment that writes one down. Hanging that moment on the merge sweep answers it and bills the operator a capture pass per batch of merges while nothing is being built, which is a cost paid on the days shipping is fastest.
@@ -41,6 +43,10 @@ The session also records nothing of what it learns. Both other callers of memory
 - Re-resolve the board's plan pointers after any archive, since the archiving skill rewrites the task file and knows nothing about the board
 - Lead a sweep report, a board report, and an analysis with the state, the open decisions, and the next action, keeping the evidence below them
 - Write the pre-compact handoff with what no other file carries, and name the runbook that reads it back
+- Carry the resume invocation and the owed poll restart in the handoff file itself, not in the runbook that writes it alone, since the file is what survives a compaction and the runbook is what a session has to already be holding to read
+- State the invocation as a resume request to this skill with one client's command as the example, since the handoff ships to every target holding the plugin
+- Resolve every runbook path the handoff carries to an absolute path as it is written, since the reader holds no skill and the path variable does not expand in the turn that reads the file back
+- Distinguish this resume from the general-purpose `session-resume`, since the name an operator reaches for first reaches a skill that knows nothing about the board
 - Capture what the session learned at the handoff rather than in the merge sweep, and have the sweep report the debt dated from the last handoff, since a capture per batch of merges bills the operator a wait while nothing ships and an undated row reads the same however long the debt has run
 - Carry every runbook the session cannot run from memory inside the skill, so each citation resolves for a project holding the plugin and nothing else
 - State which rule wins where the tracked-file ban collides with the root instruction on small edits, and where a correction no open task owns goes

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

@@ -1,6 +1,6 @@
 ---
 title: Orchestrator handoff runbook
-description: Memory capture at the close of a session, what to write to .claude/tasks/session.md before a compaction, and what to leave to the board
+description: Memory capture at the close of a session, what to write to .claude/tasks/session.md before a compaction, what to leave to the board, and the resume invocation the file carries out
 ---
 
 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.
@@ -8,7 +8,7 @@ Capture what the session learned, then write the pre-compact handoff as orchestr
 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:
+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>`:
 
 ```markdown
 ---
@@ -35,12 +35,22 @@ description: <what the board cannot show, and the date it was written>
 ## Standing cautions
 
 <commands that lie, tools that measure the wrong tree, and anything unbacked>
+
+Resume by loading the orchestrator skill and asking it to resume after a compaction. This repository spells that `/aitk:claude-orchestrate` followed by the request. Following <RESUME_RUNBOOK> reaches the same place with no skill loaded at all.
+
+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.
 
-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 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.
+
+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.
+
+That block sits in this runbook and again in the file this runbook writes, which is the fix rather than a copy for a later pass to collapse. A session has to already be holding this runbook to read it, and a compaction that took the skill body took the routing to it too, so the session that most needs the resume is the one that can no longer find it. `session.md` survives that, so it carries the invocation itself. Each of the two reaches a reader the other cannot.
+
+The requirement is a resume request to the orchestrator skill with that skill loaded first. The command the block carries is this repository's spelling rather than the only one, since the skill ships to every target holding the plugin and each runs whatever client it runs. The poll restart is named beside it because the resume performs none.
 
 Step 1 exists because both other callers of capture are ship-chain skills and this session never ships. Without a call here, the session that receives every operator correction is the one session that records none. A compaction arriving with no warning takes the capture with it, and firing it once per batch of merges leaves the same window open across a long planning stretch, since a sweep runs only on a merge. The refill sweep reports the debt between handoffs so the operator knows one is owed.
 

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.71.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.

package/tooling/web/reference.md

@@ -12,7 +12,7 @@ Golden config files live in `tooling/web/configs/` and are copied into the targe
 
 - `eslint.config.js`: flat config with `@eslint/js`, `typescript-eslint`, React hooks, import sort, check-file, vitest rules scoped to test files, `eslint-config-prettier` last.
 - `src/test/setup.ts`: `@testing-library/jest-dom` import, `cleanup` after each test.
-- `e2e/screenshot.ts`: `CONFIG` and `ENGINE` split template. Per-project ROUTES or SURFACES edited in the CONFIG section only.
+- `e2e/screenshot.ts`: capture template. `ROUTES` and `STATES` consts at the top carry one route in a default and a dark state, and the loop below them writes `screenshots/<name>-<state>.png`. Per-project routes and states extend the two consts.
 - `.vscode/extensions.json` and `.vscode/settings.json`: editor wiring for ESLint, Tailwind, Playwright, Vitest.
 - `.github/workflows/verify.yml`: `static-checks`, `unit-tests`, `build-verify`, and `e2e-tests` jobs.
 - `scripts/verify.sh`: extends base verify with typecheck, lint, unit tests, and build in the full order.
@@ -90,6 +90,8 @@ Append rows:
 | `bun run test:e2e` | Run Playwright E2E tests. |
 | `bun run screenshot` | Build, preview, then capture screenshots. |
 
+`aitk tooling verify <stack>` is the only automated caller of `bun run screenshot`, running it for any stack whose `package.json` declares the script and asserting that PNG files land under `screenshots/`. No ship chain captures a screenshot, so the output path the seed writes is a contract that one verifier reads rather than a default a ship step depends on.
+
 ## Verify script
 
 The web layer's `scripts/verify.sh` replaces the base version. Order: typecheck, lint, format, spelling, shell, unit tests, build. Stack adapters may override if their typecheck or build differs.