@erclx/aitk 0.68.0 → 0.70.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.68.0",
+  "version": "0.70.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -11,6 +11,10 @@ Without this skill, the session holding the cross-feature picture starts buildin
 
 The queue fails in both directions. It empties and a free worker waits, or it fills with whatever is oldest rather than with what establishes a mechanism. A plan handed over unverified is the quiet one, since it goes stale from whatever merged after it was written, and a worker that trusts its account of the tree builds against a shape that no longer exists. A second orchestrator makes all of this unrecoverable, because the board is gitignored and neither session can read the other's writes.
 
+Refilling on a merge and on a thinning ready list leaves the window between them unwatched. A wave mid-build has merged nothing and has moved no rows, so both conditions stay silent across the whole build and the wave finishes into an empty queue, which lands planning on the critical path directly after the stretch where it would have cost nothing.
+
+Writing those plans against the tree alone is the second half, since several branches are already changing the shape a plan describes. A plan carrying a bare path list rather than a constraint per in-flight track leaves the worker guessing which act each path forbids, which is the dangling citation the rule against bare paths already exists to prevent.
+
 The session also writes surfaces it is told only how to read. Refilling the queue promotes and demotes rows in the priority file with no stated method, so a session invents one, and an inline rewrite exits clean when it matches nothing and leaves the board wrong with nothing reporting it. A row carrying prose where a plan pointer belongs costs a worker dispatch, because the ship chain refuses at its guard after the worktree is already open. A plan archived from a worker's own branch strands the pointer the board still carries, and the row reads as correct until someone follows it.
 
 The ban on writing at all fails on a different axis, which is that nothing enforces it and a session weighs proportionality against it. A one-line prose correction found while orchestrating satisfies the root instruction to handle a small edit immediately and violates this rule, and a session given no statement of which one wins takes the smaller apparent cost and authors the change. That removes the independent pass the repository built to catch what a self-review misses, and the vantage does not come back, since no later session can review the change without re-deriving the context that produced it. A correction no open task owns has nowhere to go either, so the route matters as much as the ban.
@@ -30,6 +34,8 @@ The session also records nothing of what it learns. Both other callers of memory
 - Place every finding a merged pull request produced against the surface that owns it
 - Date the roadmap line from that file's last commit, so an old sequence reads as old
 - Keep one planned, non-conflicting task in reserve beyond what is running
+- Refill the queue while a wave is still building, rather than on a merge and a thinning list alone, since neither of those fires across the window planning costs nothing
+- Carry a constraint naming each in-flight track's file set in every plan written from here, stating per set which of the two acts it forbids, since a bare path list leaves a broken citation in place
 - Write the priority file with an editing tool that errors on a non-match, since the board is where a silent failure costs a dispatch
 - Carry a plan pointer in the Plan column and a file set in the Touches column, so a row's readiness and disjointness claims stay checkable
 - Re-resolve the board's plan pointers after any archive, since the archiving skill rewrites the task file and knows nothing about the board

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

@@ -94,13 +94,15 @@ Write no shape for a correction. A correction is a sentence, and a format for ad
 ## The loop
 
 1. Own the roadmap while a scope exists to sequence. Capture a needed draft or resequence of `.claude/ROADMAP.md` in the plan or a task file, naming the MVP list in `.claude/REQUIREMENTS.md` as the source, so a worker runs `claude-roadmap` in its branch and the tracked edit ships in a PR rather than dirtying main. Stop owning it once that list has shipped, since later work then arrives as discrete items rather than as versions.
-2. Plan the next feature. Run `claude-feature` here, with the cross-feature context, to write a plan to `.claude/plans/`. Planning stays in this warm session so the plan front-loads reasoning a cold worker would otherwise re-derive. A constraint supplied from here that names a surface to leave alone states which of two acts it forbids, and the rule governing that is Step 3 of `claude-feature` under Constraints.
+2. Plan the next feature. Run `claude-feature` here, with the cross-feature context, to write a plan to `.claude/plans/`. Planning stays in this warm session so the plan front-loads reasoning a cold worker would otherwise re-derive. Every plan written from here also carries a constraint per track in flight, which the paragraph below this list states.
 3. Decide parallelism and merge order. Note which plans touch a shared wiring seam so their PRs merge in sequence, not at once.
 4. Verify the plan against the tree. Reading it is not enough, since a plan goes stale from whatever merged after it was written. Grep for each construct it names and count the sites against the count it claims. Check that every phase label it cites is still open. Open each file it describes rather than trusting its account of the contents. Correct the plan before handing it over.
 5. Hand off. The human opens a worker worktree with `claude-worktree` and runs `claude-autoship` against the plan. The orchestrator does not spawn workers.
 6. Review the PR. When a worker opens a PR, run `claude-pr-review` to post findings to it. This is the deep, independent pass. The worker's autoship self-review was only the green gate. Learning that a PR moved is the mechanical half, so read `${CLAUDE_SKILL_DIR}/references/orchestrator-poll.md` and start the poll it carries on the first dispatch rather than checking the board by hand. It routes a moved or answered pull request straight to a re-review and reports an opened one without acting, which keeps every first pass a batched judgment this session triggers.
 7. Close the loop. After the worker runs `claude-address-review`, re-review if needed, then the human merges. Tell the trailing worker to rebase when its branch shares a seam with the merged one.
 
+A plan written here is written against a tree several branches are already changing, so it names the file set of every track in flight as a constraint, one set per track, read from the Touches column of that track's row. State for each set which of the two acts it forbids, per Constraints in `.claude/standards/plan.md`, or `${CLAUDE_SKILL_DIR}/../../standards/plan.md` when the project does not have it. A bare path list leaves the worker guessing, which is how a plan ends up forbidding the repair of a citation the change broke.
+
 ## Boundaries
 
 - Run one orchestrator at a time. The board is gitignored, so a second session sees none of this one's writes: two task files land minutes apart under different labels for the same work, one session archives a task mid-sweep in the other, and each archives a plan the other had retargeted. An Owner column does not fix this, since neither session can read the other's rows.
@@ -114,7 +116,13 @@ The tracked-file boundary collides with `CLAUDE.md`, which says to handle a smal
 
 ## Refilling the ready queue
 
-Keep enough planned, non-conflicting tasks available that a free worker never waits, and place the findings the last merge produced before promoting anything new. Run this after every merge and whenever the ready list thins. `${CLAUDE_SKILL_DIR}/references/orchestrator-sweep.md` wraps this procedure for a batch of merges and adds the plan re-verification that a merge invalidates.
+Keep enough planned, non-conflicting tasks available that a free worker never waits, and place the findings the last merge produced before promoting anything new. Run this after every merge, whenever the ready list thins, and whenever a wave is in flight with fewer unclaimed plans than there are workers building. `${CLAUDE_SKILL_DIR}/references/orchestrator-sweep.md` wraps this procedure for a batch of merges and adds the plan re-verification that a merge invalidates.
+
+The third trigger reaches a window the first two cannot. A session with three workers mid-build has merged nothing and has watched its ready list sit still, so both reactive triggers stay silent across the one stretch where planning costs the session nothing, and the wave finishes into an empty `## Run now`. Nothing starts this pass, in the way nothing starts the review poll, so it holds only while the session applies it.
+
+It counts unclaimed plans against workers rather than reading the reserve in step 4, which is sized for one worker finishing and falls short of a wave landing together. A plan a worker has already taken serves nobody who finishes next, so counting it is what lets the queue read full while it is about to empty. How many to write forward past that floor is the parallelism call rather than a count of free slots, and `## Parallelism` below states what binds it.
+
+### Running the refill
 
 1. Run `gh pr list --state open` and `git log --oneline -8`. Report any pull request whose review has not been posted and stop for that one first.
 2. For each pull request merged since the last sweep, place every finding it produced. Route a finding that changes a rule to the standard or rule that states it, one that changes another task to that task's Findings, and one that overturns a groundwork lean to that folder marked answered. Never leave a finding in a pull request thread alone.
@@ -122,7 +130,7 @@ Keep enough planned, non-conflicting tasks available that a free worker never wa
 4. Read `.claude/tasks/priority.md` and count entries under its `## Run now` heading that carry a written plan. Keep one in reserve beyond what is running.
 5. Promote by whether a task establishes functionality rather than by age. Prefer a task that adds or proves a mechanism over one that trims, tidies, or audits an existing surface.
 6. Before promoting a candidate, list the files it touches against every task already running, per Parallelism below. Name the overlap and serialize when the sets are not disjoint.
-7. Write a plan for each newly promoted task with `claude-feature`, then report:
+7. Write a plan for each newly promoted task with `claude-feature`, carrying the in-flight constraint that The loop above states, then report:
 
 ```plaintext
 Capture: owed since <the last handoff, or session start when none has run>

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

@@ -11,7 +11,9 @@ Without this skill, using the toolkit means knowing which skill to pick, and the
 
 Two failures come from acting on memory. A session that names a stack, rule, or snippet from what it remembers rather than from the live catalog runs against an entry that has been renamed or removed. And a session that edits a managed file by hand produces a change the next sync overwrites, which reads as the toolkit undoing work rather than as the edit having been made in the wrong place.
 
-The last failure is duplication. A front door that answers everything itself reimplements first-time detection and seed diffing inline, badly, beside the skills that already do both. The value of a router is that it stops at the handoff.
+The third failure is duplication. A front door that answers everything itself reimplements first-time detection and seed diffing inline, badly, beside the skills that already do both. The value of a router is that it stops at the handoff.
+
+The last failure is writing without re-checking. A domain sync brought a stricter standard into a target and left ten of its eleven context entries non-compliant in the same moment, and the run reported success because reporting the command was where its work ended. A person found the breakage afterwards by running an audit by hand. The audit that would have caught it is built and reachable from nothing the router offers, so one session held both the defect and its detector and connected neither to the other.
 
 ## Must
 
@@ -19,17 +21,23 @@ The last failure is duplication. A front door that answers everything itself rei
 - 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
+- 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
 
 ## Must not
 
 - Edit a managed file by hand instead of running the CLI that owns it
 - Reimplement a flow another skill owns
 - Hardcode a catalog name
+- 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.
 
 ## Guards
 
 - 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
 
 ## Out of scope
 

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

@@ -22,13 +22,14 @@ 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 five fields off the report and carry each to `## Route`:
+Read six 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
+- `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.
 
@@ -45,8 +46,30 @@ Map the stated intent, or what `## Diagnose` found, to one lifecycle phase, then
 - Seed or standards drift in `CLAUDE.md` or `.claude/` preambles: hand off to `claude-seed-sync`
 - Install one snippet, standard, or rule: run the domain `install` command
 - Sync one domain or every installed domain: run `aitk <domain> sync` or `aitk sync`
+- Fix only the ignore entries of the installed stack: run `aitk tooling inject --gitignore <stack>`
 - Browse what is available: run `aitk <domain> list`
 
+That row runs on a measured tooling report alone, so `measured` decides before `chain` is read at all. A false one splits three ways. Report tooling as unmeasured in each, name the cause, and run nothing, since the zero counts underneath are unmeasured rather than clean:
+
+- An empty `chain` at a workspace root, which carries `pnpm-workspace.yaml` or a `workspaces` key in `package.json`: no chain is recorded there by design, since one would guess at what the packages hold. Name `aitk tooling sync <stack> <path>` against a package.
+- An empty `chain` anywhere else: no tooling install is recorded, so name `aitk tooling sync` as the command that records one rather than asking the user for a stack.
+- A `chain` carrying names: this toolkit no longer ships those stacks. Name them, since injecting would write against a retired name.
+
+On a measured report, take `<stack>` from the first name in `tooling.chain`, which records the stack nearest the target. Inject re-resolves that leaf's own chain, so a target whose recorded chain is shorter receives the entries from the layer its install skipped. Say so before running it.
+
+### Audits
+
+Four audits measure a surface without changing it. Offer the ones whose surface the target carries, list them together, and let the user pick. Run none of them unasked, and never treat a finding as a reason to abandon the operation the user asked for, since each reports judgments beside facts.
+
+- `.claude/context/` present: offer `aitk context audit`
+- A record folder present under `.claude/`, one of `plans`, `groundwork`, `intake`, or `memory`: offer `aitk records validate <kind>` for each one found
+- Markdown that git lists: offer `aitk markdown audit`
+- TypeScript or shell source present: offer `aitk comments scan`
+
+An audit offered against a surface the target lacks reports an empty run as a finding, which is the same defect as never offering it at all. Check the surface before naming the command.
+
+The markdown row is the one every target satisfies, since a project with no markdown is not one this reaches. Its condition is stated so the four rows read alike, and the row needs no gate beyond it.
+
 ## Execute
 
 For operations this skill runs directly:
@@ -54,6 +77,13 @@ For operations this skill runs directly:
 - Read the catalog first with `aitk <domain> list --json`, then match against project context
 - Run the CLI with `AITK_NON_INTERACTIVE=1` so it skips prompts. The tool permission dialog is the confirmation gate.
 - Report the command run and what changed. Emit the full relative path for any file written.
+- Re-run `aitk sync --check . --json` after any operation that wrote, and compare it against the report `## Diagnose` read before acting
+- Report the fields that moved and name the write that moved each one. Do not restate the second report, since the value sits in the difference alone.
+- State a field that moved the wrong way and leave it for the user to decide on. The re-check reports and never repairs.
+
+A write can leave a target worse in a field the write never named, which stays silent while the operation itself succeeds. The re-check is what makes that visible, so it runs before the operation is reported as done.
+
+The comparison needs the earlier report. When `## Diagnose` was skipped because the user named a single operation, say the write ran with no baseline rather than describing the target from scratch, which would attribute differences another session made to this run.
 
 ## Boundaries
 

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

@@ -142,11 +142,11 @@ edit and a job counting those stays red with no remedy.
 
 ### Surfaces reported beside the domains
 
-Three sections sit outside the per-domain scan, because each names something
+Four sections sit outside the per-domain scan, because each names something
 that walk cannot see. None of them produces a change, and no sync command
 applies any of them.
 
-All three report only against a toolkit-managed target, which is one carrying a
+All four report only against a toolkit-managed target, which is one carrying a
 `.claude/` directory, a `CLAUDE.md`, or a domain still at the root layout. The
 report says so through `managed` in the JSON and routes an unmanaged directory to
 `aitk init`. Seeds are why the gate exists, since they enumerate from the toolkit
@@ -159,6 +159,8 @@ toolkit installed. When `managed` is false every section comes back empty rather
 than the render alone going quiet, so a consumer reading `--json` never acts on a
 finding the rendered half withheld.
 
+#### Seeds, superseded artifacts, and unmigrated domains
+
 `seeds` classifies every seed the toolkit ships against the target's copy, as
 `matching`, `stale`, `drifted`, or `missing`. `missing` has no per-domain
 equivalent, since the domain walk lists what a target installed and cannot see a
@@ -194,11 +196,57 @@ the toolkit ships, so a root folder holding the project's own documents beside
 the installed ones reports the installed subset, where a listing reports every
 file and proposes relocating the lot.
 
+#### The reverse walk
+
+`reverse` is the one section built by walking the target rather than the
+catalog. Every other surface enumerates toolkit-owned keys and asks whether the
+target matches, so a folder the toolkit deleted appears in none of them. It
+carries `unclaimed`, `migrations`, and `historyUnavailable`.
+
+`unclaimed` names a folder the target holds at a top-level path the toolkit once
+shipped and has since deleted. The candidate roots come from the toolkit's own
+history rather than from a list, so a root dropped later is covered without a
+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.
+
+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
+guessed from the filesystem.
+
+Content matching a version the toolkit published reads as `dropped` and carries
+the `since` commit that published it. Names the toolkit shipped holding content
+it never published read as `unattributed`, which is a state in its own right
+rather than a soft yes. No overlap at all reads as `project`, and the render
+drops those while the JSON keeps them.
+
+Only files whose path the toolkit once held are hashed, so a project folder
+colliding on a retired name costs the walk no reads. The cost is that a file the
+toolkit shipped and the target renamed goes unmatched, the same limit the
+`unmigrated` count carries.
+
+`migrations` names a proposal-only skill with a live case in this target, which
+is the treatment `unmigrated` already gives `migration-standards`. It fires on a
+`CLAUDE.md` past 250 lines for `migration-claude-md`, and on a `docs/` folder
+holding markdown with no populated `.claude/context/` for `migration-context`.
+Each entry carries the skill name and the measurement behind it, so a consumer
+can check the proposal before running it. Without the field both skills are
+documented and unreachable from any report.
+
+#### What counts toward the gate
+
 `unmigrated` counts toward `--exit-code`, since running the relocation closes it.
 `superseded` and every seed state are excluded, for the reason `orphaned` already
 is: only the user can move content they wrote, so failing a job on it leaves the
 job red with no mechanical remedy.
 
+The whole `reverse` section is excluded on the same grounds, and more strongly.
+Every entry in it is a judgment about a file the project may own, and one of its
+three verdicts is a labelled unknown by design. The unmigrated detection shipped
+that exact false positive once, failing a push with no action that cleared it,
+so this section reports and gates nothing.
+
 ## Bootstrap
 
 `aitk init` installs up to six core domains and reports each one independently. A

package/docs/agents/markdown-audit.md

@@ -49,7 +49,7 @@ Two ban shapes stay unmeasured and the report says so on every run. A phrase ban
 
 ### Bullets, paragraphs, and depth
 
-Bullet weight and depth are the checks that moved off `aitk context audit`, unchanged in what they measure. A top-level bullet reports past roughly 400 characters with continuation lines folded in and nested items left out. A run of lines no heading breaks reports past roughly 40 rendered lines, measured at 80 columns, skipping fenced blocks and exempting a flat peer list averaging under 130 characters a bullet and a run that is entirely table rows.
+Bullet weight and depth are the checks that moved off `aitk context audit`, unchanged in what they measure. A top-level bullet reports past roughly 400 characters with continuation lines folded in and nested items left out. A run of lines no heading breaks reports past roughly 40 rendered lines, measured at 80 columns, skipping fenced blocks and exempting a flat peer list averaging under 130 characters a bullet and a run that is entirely table rows. Each file reports its longest run alone, so a second run past the checkpoint in the same file is never named.
 
 Every weight and depth measure counts the text a reader is shown. A link reduces to its anchor text and an autolink drops whole, since no reader is shown either destination. A backticked path stays counted, which is where these measures part from the ban scan above: that one blanks a code span so a standard quoting its own banned character does not report itself, and discounting the same span here would under-report a paragraph carrying several. One file holds both span sets and each answers its own question.
 

package/docs/target-projects.md

@@ -104,11 +104,19 @@ That attribution comes from `.claude/aitk.json`, a stamp every install and sync
 
 A project that has never synced under a toolkit new enough to write a stamp falls back to the toolkit's own git history. Installed content matching any version that history published proves the file untouched, so it reports `stale` naming the commit it came from, and content matching no published version stays `drifted`. That fallback needs the toolkit as a git checkout. Installed from the registry it ships source without history, and the report says attribution was unavailable rather than reading every file as a local edit.
 
-Three further causes sit outside the per-domain scan, each naming something that walk cannot see. A seed the project edited is reported under `seeds` and reconciled with `aitk:claude-seed-sync`, since no sync command touches a seed. A file a newer seed folder replaced is reported under `superseded`, such as `.claude/TASKS.md` against the `.claude/tasks/` that now ships, and nothing moves it because the content is the project's own. A domain sitting at the root layout with nothing under `.claude/` is reported under `unmigrated` and handed to `aitk:migration-standards`.
+Four further causes sit outside the per-domain scan, each naming something that walk cannot see. A seed the project edited is reported under `seeds` and reconciled with `aitk:claude-seed-sync`, since no sync command touches a seed. A file a newer seed folder replaced is reported under `superseded`, such as `.claude/TASKS.md` against the `.claude/tasks/` that now ships, and nothing moves it because the content is the project's own. A domain sitting at the root layout with nothing under `.claude/` is reported under `unmigrated` and handed to `aitk:migration-standards`.
 
-That last one matters most on an older project. Before it existed, a target holding `standards/` at its root reported zero entries for that domain, so a project that had never migrated was indistinguishable from one that was fully current.
+That third one matters most on an older project. Before it existed, a target holding `standards/` at its root reported zero entries for that domain, so a project that had never migrated was indistinguishable from one that was fully current.
 
-Add `--json` for the machine-readable report, and `--exit-code` to fail a CI job when a target falls behind. Files the project authored itself never count toward that exit code, and neither do superseded artifacts, seed drift, or tooling, since each reports content the project is expected to edit or place itself. An unmigrated domain does count, because running the relocation closes it.
+#### What the toolkit stopped shipping
+
+The fourth cause runs backwards. Every one above starts from what the toolkit ships and asks whether the target matches, so a folder the toolkit dropped appears in none of them. `reverse` walks the target instead and reports a folder sitting at a top-level path the toolkit once shipped and has since deleted.
+
+Each entry carries a verdict, since a dropped folder and one the project wrote are the same bytes at the same path. `dropped` names the commit that published the content. `unattributed` means the toolkit shipped that path and the content matches no version it published. `project` means the folder only shares a retired name. Nothing acts on any of them, and the verdict is what makes the list safe to read.
+
+The same field names a proposal-only skill with a live case here under `migrations`, which is how `aitk:migration-claude-md` and `aitk:migration-context` become reachable. Each entry carries the measurement behind the proposal rather than the proposal alone.
+
+Add `--json` for the machine-readable report, and `--exit-code` to fail a CI job when a target falls behind. Files the project authored itself never count toward that exit code, and neither do superseded artifacts, seed drift, tooling, or anything the reverse walk reports, since each names content the project is expected to edit or place itself. An unmigrated domain does count, because running the relocation closes it.
 
 Tooling reports under a section of its own, and `measured` there says whether the target ever recorded a chain. One that never ran a tooling sync reports unmeasured rather than clean, which is what separates tooling nobody has looked at from tooling that is current. A workspace root records nothing either way, since each package resolves its own chain. Reconcile the configs with `aitk tooling sync <stack> <path>`.
 

package/package.json

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

package/src/commands/sync.ts

@@ -18,6 +18,7 @@ import {
   SYNC_DOMAINS,
   type SyncDomain,
 } from '@/sync/target'
+import type { UnclaimedFolder } from '@/sync/reverse'
 import { runGitWorkflow } from '@/sync/workflow'
 import { resolveTarget } from '@/target'
 import {
@@ -162,6 +163,9 @@ function renderCheck(report: CheckReport): void {
     for (const name of report.newSkills) logInfo(name)
   }
 
+  renderUnclaimed(report)
+  renderMigrations(report)
+
   outro()
   // Scanned domains only. Tooling renders a section on every managed target, so
   // naming it here repeats what that section already said under a second
@@ -237,6 +241,71 @@ function renderSeeds(report: CheckReport): void {
   logInfo('Run /aitk:claude-seed-sync to reconcile these section by section.')
 }
 
+/**
+ * Names the attribution before the count, the way the tooling section does. A
+ * dropped folder and a project-authored one are the same bytes at the same
+ * path, so the count alone is the one thing an operator cannot act on.
+ *
+ * A folder history proved the project owns is dropped from the render and kept
+ * in the JSON. Printing it costs a line on every run for a name collision no
+ * remedy closes, which is the bar this section had to clear to exist at all.
+ */
+function renderUnclaimed(report: CheckReport): void {
+  const { unclaimed, historyUnavailable } = report.reverse
+  const notable = unclaimed.filter((entry) => entry.attribution !== 'project')
+
+  if (notable.length === 0 && !historyUnavailable) return
+
+  logStep('No longer shipped by the toolkit')
+
+  if (historyUnavailable) {
+    logWarn('This toolkit has no git history, so nothing could be walked.')
+    return
+  }
+
+  for (const entry of notable) {
+    logWarn(`${entry.rel}/ (${describeUnclaimed(entry)})`)
+  }
+
+  logInfo(
+    'Decide what happens to these yourself. No sync command touches them.',
+  )
+}
+
+/**
+ * State first, then the count, then where the content came from. The revision
+ * is the commit that published the content the target still holds, never the
+ * one that dropped the folder, so it takes a clause of its own. Suffixed onto
+ * `dropped upstream` it reads as the date of the drop, and an operator running
+ * `git show` on it lands on the commit that added the folder.
+ */
+function describeUnclaimed(entry: UnclaimedFolder): string {
+  const state =
+    entry.attribution === 'dropped' ? 'dropped upstream' : 'unattributed'
+  const counted = `${state}, ${entry.files} files`
+
+  if (entry.since === undefined) return counted
+
+  return `${counted}, content published at ${entry.since.slice(0, 7)}`
+}
+
+/**
+ * The two proposal-only skills no other field reaches. `migration-standards`
+ * gets the same treatment from the unmigrated section above, which is the
+ * precedent this follows rather than a second spelling of it.
+ */
+function renderMigrations(report: CheckReport): void {
+  const { migrations } = report.reverse
+  if (migrations.length === 0) return
+
+  logStep('Migrations with a case here')
+
+  for (const candidate of migrations) {
+    logWarn(candidate.reason)
+    logInfo(`Run /aitk:${candidate.skill} for a proposal.`)
+  }
+}
+
 async function runSync(target: string): Promise<number> {
   intro('aitk sync')
 

package/src/sync/check.ts

@@ -10,6 +10,11 @@ import {
   type SupersededEntry,
   type UnmigratedDomain,
 } from '@/sync/layout'
+import {
+  buildReverseReport,
+  emptyReverseReport,
+  type ReverseReport,
+} from '@/sync/reverse'
 import { buildSeedsReport, type SeedsReport } from '@/sync/seeds-report'
 import {
   readStamp,
@@ -151,6 +156,13 @@ export interface CheckReport {
   readonly superseded: readonly SupersededEntry[]
   readonly unmigrated: readonly UnmigratedDomain[]
   readonly newSkills: readonly string[]
+  /**
+   * The one section built by walking the target rather than the catalog. It
+   * reports beside `superseded`, `unmigrated`, and `newSkills` rather than
+   * absorbing them, because each of those already answers a narrower version of
+   * the same question correctly. See `@/sync/reverse`.
+   */
+  readonly reverse: ReverseReport
 }
 
 export function installedStampDomains(target: string): ScannedDomain[] {
@@ -258,6 +270,11 @@ export function countStates(entries: readonly ScanEntry[]): StateCounts {
  * project is expected to edit, so a job counting it stays red with no remedy.
  * Being unmeasured is not what excludes it, since an unmeasured report carries
  * zero changes and would pass a count either way.
+ *
+ * The reverse report is excluded because every entry in it is a judgment about
+ * a file the project may own. `detectUnmigrated` already shipped that exact
+ * false positive once, failing a push with no action that cleared it, and a
+ * walk that reports `unattributed` by design would repeat it.
  */
 export function hasDrift(report: CheckReport): boolean {
   if (report.unmigrated.length > 0) return true
@@ -306,6 +323,7 @@ export async function buildCheckReport(
       superseded: [],
       unmigrated: [],
       newSkills: [],
+      reverse: emptyReverseReport(),
     }
   }
 
@@ -318,6 +336,7 @@ export async function buildCheckReport(
     superseded: collectSuperseded(target),
     unmigrated,
     newSkills: await readNewSkills(toolkitRoot, anchors),
+    reverse: buildReverseReport(toolkitRoot, target),
   }
 }
 

package/src/sync/history.ts

@@ -101,7 +101,7 @@ export function readHistoryIndex(
  * caller's `relative()` output has to be converted before it can match a path
  * the log emitted.
  */
-function toRepoPath(path: string): string {
+export function toRepoPath(path: string): string {
   return path.split(sep).join('/')
 }
 

package/src/sync/reverse.ts

@@ -0,0 +1,270 @@
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { execaSync } from 'execa'
+import { gitEnv } from '@/git-env'
+import {
+  findInstalledOrigin,
+  type HistoryIndex,
+  readHistoryIndex,
+  toRepoPath,
+} from '@/sync/history'
+
+const CLAUDE_DIR = '.claude'
+
+/**
+ * A `CLAUDE.md` past this many lines has more in it than the always-load tier
+ * is for. The figure is the checkpoint `.claude/standards/context.md` sets for
+ * a context entry, raised because `CLAUDE.md` legitimately carries more than
+ * one domain. It gates a proposal rather than a failure, so being approximate
+ * costs a line an operator can ignore.
+ */
+const CLAUDE_MD_LINES = 250
+
+/**
+ * Who put an unclaimed folder in the target. A dropped folder and one the
+ * project wrote are the same bytes at the same path, so this is traced from the
+ * toolkit's own history and never guessed from the filesystem.
+ *
+ * `unattributed` is a verdict in its own right rather than a soft `dropped`.
+ * The toolkit shipped a path of that name and the content matches no version it
+ * ever published, which is exactly what history proving nothing looks like. An
+ * operator can act on a labelled unknown and cannot act on a guess.
+ */
+export type Attribution = 'dropped' | 'project' | 'unattributed'
+
+/**
+ * A folder the target holds at a root the toolkit has stopped shipping.
+ * Carries no source and queues no change, because only the user can decide what
+ * happens to content the toolkit no longer claims.
+ */
+export interface UnclaimedFolder {
+  readonly rel: string
+  readonly files: number
+  readonly attribution: Attribution
+  /** Toolkit revision whose version of a file here the target still holds. */
+  readonly since?: string
+}
+
+/**
+ * A proposal-only skill with a live case in this target. The skills propose and
+ * never execute, so the report names one rather than queueing a change, which
+ * is the treatment `unmigrated` already gives `migration-standards`.
+ */
+export interface MigrationCandidate {
+  readonly skill: string
+  /** What was measured, so the proposal is checkable before it is run. */
+  readonly reason: string
+}
+
+export interface ReverseReport {
+  readonly unclaimed: readonly UnclaimedFolder[]
+  readonly migrations: readonly MigrationCandidate[]
+  /** Set when the walk needed history to run and this toolkit has none. */
+  readonly historyUnavailable: boolean
+}
+
+const EMPTY_REVERSE: ReverseReport = {
+  unclaimed: [],
+  migrations: [],
+  historyUnavailable: false,
+}
+
+/**
+ * Asks the question every other detection surface asks backwards: what does the
+ * target hold that no live catalog claims. The forward direction enumerates
+ * toolkit-owned keys and tests the target against them, so a folder the toolkit
+ * deleted appears in no section at all.
+ *
+ * Scoped to roots the toolkit itself has dropped rather than to the whole tree.
+ * Walking the tree reports every project folder as unclaimed, which is true and
+ * useless, and the question here is only what the toolkit put there and then
+ * stopped claiming.
+ *
+ * Reports beside `superseded`, `unmigrated`, and `newSkills` rather than
+ * absorbing them. Each of those answers a narrower version of the same question
+ * and none is wrong today, so folding them in would change what two shipped
+ * sections print in the same change that introduces a third.
+ */
+export function buildReverseReport(
+  toolkitRoot: string,
+  target: string,
+): ReverseReport {
+  const roots = readDroppedRoots(toolkitRoot)
+  const migrations = detectMigrations(target)
+
+  if (roots === undefined) {
+    return { unclaimed: [], migrations, historyUnavailable: true }
+  }
+
+  const unclaimed: UnclaimedFolder[] = []
+
+  for (const root of roots) {
+    for (const rel of [root, join(CLAUDE_DIR, root)]) {
+      const files = listFiles(join(target, rel))
+      if (files.length === 0) continue
+
+      unclaimed.push(attributeFolder(toolkitRoot, target, rel, root, files))
+    }
+  }
+
+  return { unclaimed, migrations, historyUnavailable: false }
+}
+
+export function emptyReverseReport(): ReverseReport {
+  return EMPTY_REVERSE
+}
+
+/**
+ * Top-level toolkit paths that history records a deletion under and that no
+ * longer exist in the working tree. Both halves are load-bearing: a path with
+ * deletions that still exists is a live root the forward direction already
+ * covers, and a path that never lost a file was never dropped.
+ *
+ * Read as one log over the whole repository rather than per candidate, since
+ * the candidate set is what the call produces. A root-level file is skipped
+ * because this walk matches target folders, and a deleted `README.md` names no
+ * folder to look for.
+ */
+function readDroppedRoots(toolkitRoot: string): readonly string[] | undefined {
+  const result = execaSync(
+    'git',
+    [
+      '-C',
+      toolkitRoot,
+      'log',
+      '--all',
+      '--diff-filter=D',
+      '--name-only',
+      '--format=',
+    ],
+    { reject: false, env: gitEnv(), extendEnv: false },
+  )
+
+  if (result.exitCode !== 0) return undefined
+
+  const roots = new Set<string>()
+
+  for (const line of result.stdout.split('\n')) {
+    const trimmed = line.trim()
+    const boundary = trimmed.indexOf('/')
+    if (boundary <= 0) continue
+
+    roots.add(trimmed.slice(0, boundary))
+  }
+
+  return [...roots]
+    .filter((root) => !existsSync(join(toolkitRoot, root)))
+    .sort()
+}
+
+/**
+ * Splits a found folder three ways against the toolkit's history of the root it
+ * sits at. Content matching a published version proves the toolkit put the file
+ * there. Names the toolkit shipped with content it never published proves only
+ * that the two collided, which is the unattributed case. No name overlap at all
+ * is a folder the project owns that happens to share a retired name.
+ *
+ * Only files whose relative path the toolkit once held are hashed, so a project
+ * folder colliding on name costs the walk no reads. The cost is that a file the
+ * toolkit shipped and the target renamed goes unmatched, the same limit
+ * `countToolkitOwned` carries for the forward direction.
+ */
+function attributeFolder(
+  toolkitRoot: string,
+  target: string,
+  rel: string,
+  root: string,
+  files: readonly string[],
+): UnclaimedFolder {
+  const index = readHistoryIndex(toolkitRoot, [root])
+
+  if (index === undefined) {
+    return { rel, files: files.length, attribution: 'unattributed' }
+  }
+
+  let covered = false
+
+  for (const file of files) {
+    const sourceRel = toRepoPath(join(root, file))
+    if (!covers(index, sourceRel)) continue
+
+    covered = true
+    const since = findInstalledOrigin(index, sourceRel, join(target, rel, file))
+
+    if (since !== undefined) {
+      return { rel, files: files.length, attribution: 'dropped', since }
+    }
+  }
+
+  return {
+    rel,
+    files: files.length,
+    attribution: covered ? 'unattributed' : 'project',
+  }
+}
+
+function covers(index: HistoryIndex, sourceRel: string): boolean {
+  return index.get(sourceRel) !== undefined
+}
+
+/**
+ * Live cases for the two proposal-only skills no report field has ever named.
+ * `migration-standards` reaches an operator through `unmigrated`, and without
+ * this its two siblings are documented and unreachable.
+ *
+ * Both tests read what the skill itself acts on, so a proposal the report makes
+ * is one the skill has work to do for. A context tier that already holds files
+ * settles the `docs/` split, whether or not the toolkit is what made it.
+ */
+export function detectMigrations(target: string): MigrationCandidate[] {
+  const found: MigrationCandidate[] = []
+  const claudeMd = join(target, 'CLAUDE.md')
+
+  if (existsSync(claudeMd)) {
+    const lines = countLines(readFileSync(claudeMd, 'utf8'))
+    if (lines > CLAUDE_MD_LINES) {
+      found.push({
+        skill: 'migration-claude-md',
+        reason: `CLAUDE.md carries ${lines} lines, past the ${CLAUDE_MD_LINES} the three-tier split is for`,
+      })
+    }
+  }
+
+  const docs = listFiles(join(target, 'docs')).filter(isMarkdown).length
+  const context = listFiles(join(target, CLAUDE_DIR, 'context')).length
+
+  if (docs > 0 && context === 0) {
+    found.push({
+      skill: 'migration-context',
+      reason: `${docs} markdown files under docs/ with no .claude/context/ tier`,
+    })
+  }
+
+  return found
+}
+
+function isMarkdown(rel: string): boolean {
+  return rel.endsWith('.md')
+}
+
+/**
+ * Lines as `wc -l` counts them, so the figure in the reason matches what an
+ * operator gets from the shell. Splitting alone overstates a file ending in a
+ * newline by one, and the reason states a measurement rather than a rank.
+ */
+function countLines(content: string): number {
+  const parts = content.split('\n')
+  return parts.at(-1) === '' ? parts.length - 1 : parts.length
+}
+
+/**
+ * Every file under a directory, dotfiles included. A dropped root can hold any
+ * extension, so this does not filter to markdown the way the domain walk does.
+ */
+function listFiles(dir: string): string[] {
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return []
+
+  return [
+    ...new Bun.Glob('**/*').scanSync({ cwd: dir, onlyFiles: true, dot: true }),
+  ].sort()
+}