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

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/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/governance/rules/core/070-planning.md

@@ -8,6 +8,8 @@ description: Enforce planning standards before implementation
 
 - Analyze requests and output a numbered implementation plan before execution.
 - Challenge ambiguous or over-engineered requests before implementation.
+- Search the project, its dependencies, and the standard library for an existing implementation before writing new code.
+- State where the search ran and why each candidate was rejected. Do not assert a search without naming its results.
 - Propose the simplest solution that satisfies the requirement before implementing complex patterns.
 - Write or update tests as part of every implementation plan.
 - Do not modify code without a confirmed plan.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.69.0",
+  "version": "0.71.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()
+}

package/standards/skill.md

@@ -11,7 +11,7 @@ Skills give Claude Code domain-specific constraints and rules inline, so it can
 
 ## Scope
 
-Governs a skill folder under `skills/` as one artifact: `SKILL.md`, its sibling `REQUIREMENT.md`, and the bundled reference, script, and asset folders beside them.
+Governs a skill folder under `skills/` as one artifact: `SKILL.md`, its siblings `REQUIREMENT.md` and `EVAL.md`, and the bundled reference, script, and asset folders beside them.
 
 Does not govern:
 
@@ -88,7 +88,9 @@ allowed-tools: <tools required>
 
 ## Structure
 
-- Skill is a folder named in kebab-case containing `SKILL.md` (required), `REQUIREMENT.md` (required), `scripts/` (optional), `references/` (optional), `assets/` (optional)
+- Skill is a folder named in kebab-case containing `SKILL.md` (required), `REQUIREMENT.md` (required), `EVAL.md` (optional), `scripts/` (optional), `references/` (optional), `assets/` (optional)
+- Name a file sitting directly in the skill folder in capitals and a bundled folder in lowercase, so the parts a reader opens are distinct from the ones a skill loads
+- `EVAL.md` holds prompts and a judging rubric a person runs by hand, so a skill carrying one needs no runner beside it
 - `SKILL.md` must start with YAML frontmatter between `---` delimiters
 - No `README.md` inside the skill folder
 - No spaces, capitals, or underscores in folder or skill name