@erclx/aitk 0.44.0 → 0.46.0

package/claude/skills/git-ship/SKILL.md

@@ -14,26 +14,29 @@ Run `git diff --cached --name-only 2>/dev/null` to check for staged files. If ou
 
 ## Sequence
 
-1. Invoke `aitk:claude-docs` to sync internal planning docs against session decisions
-2. Invoke `aitk:docs-sync` to sync public docs against changes since main
-3. Run `git add -A` to stage any files the sync skills wrote
-4. Invoke `aitk:git-stage` to group staged changes and commit by concern
-5. Invoke `aitk:git-branch` to rename branch to match conventional format
-6. Invoke `aitk:git-pr` to push branch and open pull request
-7. After the PR opens, watch CI. Poll `gh pr checks <number>` until no check is pending, then read the final status. On all-pass, continue. On any failure, stop the sequence and report the failing check with its URL. Do not auto-fix. This step may output on failure, the one exception to the no-text-between-steps rule.
-8. Invoke `aitk:claude-memory-capture` to extract durable patterns from the session into `.claude/memory/`
-9. If `claude-memory-capture` wrote or updated at least one entry this session, invoke `aitk:claude-memory-review` scoped to those entries to propose fixes while session context is fresh. If capture wrote nothing, skip this step.
+1. Invoke `aitk:claude-memory-capture` to route what this session learned to the context entries that own it and write the residue to `.claude/memory/`
+2. Invoke `aitk:claude-docs` to sync internal planning docs against session decisions, folding in the routed facts
+3. Invoke `aitk:docs-sync` to sync public docs against changes since main
+4. Run `git add -A` to stage any files the sync skills wrote
+5. Invoke `aitk:git-stage` to group staged changes and commit by concern
+6. Invoke `aitk:git-branch` to rename branch to match conventional format
+7. Invoke `aitk:git-pr` to push branch and open pull request
+8. After the PR opens, watch CI. Poll `gh pr checks <number>` until no check is pending, then read the final status. On all-pass, continue. On any failure, stop the sequence and report the failing check with its URL. Do not auto-fix. This step may output on failure, the one exception to the no-text-between-steps rule.
+9. If step 1 wrote or updated at least one memory file, invoke `aitk:claude-memory-review` scoped to those entries to propose fixes while session context is fresh. If the pen got nothing, skip this step.
+
+Capture leads the sequence because a routed fact lands in a context entry, which is a tracked file. Running it after the pull request opens leaves that edit off the branch entirely, so the fact reaches nothing. Memory files are gitignored either way, which is what hid the ordering while capture wrote only those.
 
 Stop at the Propose phase. Do not run Apply. Promoting an entry to `CLAUDE.md` or a skill body ships as its own change, separate from this feature.
 
 ## After completion
 
-Output up to three lines:
+Output up to four lines:
 
 ```plaintext
 ✅ Shipped
+<N facts routed to context entries>
 <N memories captured in .claude/memory/>
 <Memory proposal at .claude/review/memory-review-<slug>.md>
 ```
 
-Omit the second and third lines if `claude-memory-capture` wrote nothing this session, since no captures means no scoped review and no proposal.
+Omit the second line if nothing routed. Omit the third and fourth if `claude-memory-capture` wrote no memory file this session, since an empty pen means no scoped review and no proposal.

package/claude/skills/session-resume/SKILL.md

@@ -13,7 +13,7 @@ Read these in parallel, skipping any that do not exist:
 
 - `.claude/tasks/index.md`: the backlog, one line per task. Read this before any individual task file.
 - `.claude/plans/*.md`: execution detail for in-progress tasks
-- `.claude/memory/MEMORY.md` and any memory files relevant to the top backlog item
+- `.claude/memory/index.md` and any memory files relevant to the top backlog item
 
 Then read only the task files the summary needs, typically the top one. Do not read the whole folder.
 
@@ -33,4 +33,4 @@ Output three sections:
 
 End with one line: `Start with: <first Up next item>` and note whether it has a linked plan.
 
-Do not offer to remove entries. A completed task is archived out of `.claude/tasks/` when work ships. The git log is the authoritative record of shipped work. Plan files are archived per the plan lifecycle rule in `CLAUDE.md`. Memory is updated only when a recorded fact becomes wrong, never on resume.
+Do not offer to remove entries. A completed task is archived out of `.claude/tasks/` when work ships. The git log is the authoritative record of shipped work. Plan files are archived per the plan lifecycle rule in `CLAUDE.md`. Memory is updated only when a recorded fact becomes wrong, never on resume. A domain fact reaches a session through `.claude/context/`, which `claude-memory-capture` routes to and the three-tier model loads on demand, so the memory folder read here is the residue no context entry owns.

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

@@ -18,9 +18,26 @@ Run these from the target project root, in parallel, before acting:
 
 Load a domain doc with `aitk docs <topic>` only when the intent touches that domain. Read the live catalog for any domain you act on with `aitk <domain> list --json`. Never hardcode stack, rule, snippet, or standards names.
 
+## Diagnose
+
+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`:
+
+- `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
+
+State what the report found in one line per finding before acting on any of it.
+
 ## Route
 
-Map the stated intent to one lifecycle phase, then act:
+Map the stated intent, or what `## Diagnose` found, to one lifecycle phase, then act:
+
+- A domain in `unmigrated`: hand off to `migration-standards`
+- Anything in `superseded`: tell the user which files and what replaced them. Do not move or delete them
 
 - 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/commands.md

@@ -9,46 +9,47 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 
 ## Project-level
 
-| Command                  | Purpose                                                                                        |
-| ------------------------ | ---------------------------------------------------------------------------------------------- |
-| `aitk init [path]`       | Bootstrap a project with selected toolkit domains                                              |
-| `aitk sync [path]`       | Sync all installed domains in a target project                                                 |
-| `aitk sync --check`      | Report toolkit drift without writing (`--json`, `--exit-code`)                                 |
-| `aitk sandbox [cat:cmd]` | Run sandbox scenarios (interactive or routed), toolkit-only like the tree it reads             |
-| `aitk sandbox reset`     | Reset sandbox to baseline                                                                      |
-| `aitk sandbox clean`     | Wipe the sandbox                                                                               |
-| `aitk sandbox check`     | Score a provisioned sandbox against a scenario expectation (`--json` for the verdict)          |
-| `aitk sandbox coverage`  | Report which scenarios declare expectations (`--json`, `--strict`, `--skills`)                 |
-| `aitk indexes regen`     | Regenerate `index.md` files from sibling frontmatter                                           |
-| `aitk docs [topic]`      | Emit toolkit reference docs (`list`, or a topic by name)                                       |
-| `aitk design render`     | Render `.claude/DESIGN.md` tokens to HTML and CSS                                              |
-| `aitk slides render`     | Render a `.claude/SLIDES.md` source into a PowerPoint deck                                     |
-| `aitk slides list`       | List the available slide layouts (`--json` for the catalog)                                    |
-| `aitk feedback`          | Write toolkit feedback from stdin to `.claude/review/`, or open a GitHub issue with `--github` |
-| `aitk transcripts <url>` | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                          |
-| `aitk tasks archive`     | Move a shipped task off the board, clear its ordering row, and regenerate the index            |
-| `aitk tasks validate`    | Report board rows whose plan, task file, group, or file set does not hold (`--json`)           |
-| `aitk comments scan`     | Measure comment density by language and comment kind, with a trend recomputed from git         |
-| `aitk context audit`     | Report required sections, length, depth, bullet weight, cited paths, provenance, and drift     |
-| `aitk capture [source]`  | Render HTML capture sources to PNG, toolkit-only and absent from an installed package          |
+| Command                    | Purpose                                                                                        |
+| -------------------------- | ---------------------------------------------------------------------------------------------- |
+| `aitk init [path]`         | Bootstrap a project with selected toolkit domains                                              |
+| `aitk sync [path]`         | Sync all installed domains in a target project                                                 |
+| `aitk sync --check`        | Report toolkit drift without writing (`--json`, `--exit-code`)                                 |
+| `aitk sandbox [cat:cmd]`   | Run sandbox scenarios (interactive or routed), toolkit-only like the tree it reads             |
+| `aitk sandbox reset`       | Reset sandbox to baseline                                                                      |
+| `aitk sandbox clean`       | Wipe the sandbox                                                                               |
+| `aitk sandbox check`       | Score a provisioned sandbox against a scenario expectation (`--json` for the verdict)          |
+| `aitk sandbox coverage`    | Report which scenarios declare expectations (`--json`, `--strict`, `--skills`)                 |
+| `aitk indexes regen`       | Regenerate `index.md` files from sibling frontmatter                                           |
+| `aitk docs [topic]`        | Emit toolkit reference docs (`list`, or a topic by name)                                       |
+| `aitk design render`       | Render `.claude/DESIGN.md` tokens to HTML and CSS                                              |
+| `aitk slides render`       | Render a `.claude/SLIDES.md` source into a PowerPoint deck                                     |
+| `aitk slides list`         | List the available slide layouts (`--json` for the catalog)                                    |
+| `aitk feedback`            | Write toolkit feedback from stdin to `.claude/review/`, or open a GitHub issue with `--github` |
+| `aitk transcripts <url>`   | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                          |
+| `aitk tasks archive`       | Move a shipped task off the board, clear its ordering row, and regenerate the index            |
+| `aitk tasks validate`      | Report board rows whose plan, task file, group, or file set does not hold (`--json`)           |
+| `aitk comments scan`       | Measure comment density by language and comment kind, with a trend recomputed from git         |
+| `aitk context audit`       | Report required sections, length, depth, bullet weight, cited paths, provenance, and drift     |
+| `aitk claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md`                 |
+| `aitk capture [source]`    | Render HTML capture sources to PNG, toolkit-only and absent from an installed package          |
 
 ## Domain commands
 
 Each domain exposes a consistent shape where applicable: `list`, `install`, `sync`, `create`.
 
-| Domain      | Subcommands                                                            |
-| ----------- | ---------------------------------------------------------------------- |
-| `tooling`   | `list`, `sync`, `ref`, `create`, `verify`, `inject`, `prune-gitignore` |
-| `snippets`  | `list`, `install`, `sync`, `create`                                    |
-| `standards` | `list`, `install`, `sync`                                              |
-| `gov`       | `list`, `install`, `sync`, `build`                                     |
-| `claude`    | `init`, `sync`, `seeds list`, `skills list`, `setup [dest]`            |
-| `wiki`      | `init`                                                                 |
-| `design`    | `render`                                                               |
-| `slides`    | `render`, `list`                                                       |
-| `tasks`     | `archive`, `validate`                                                  |
-| `comments`  | `scan`                                                                 |
-| `context`   | `audit`                                                                |
+| Domain      | Subcommands                                                                 |
+| ----------- | --------------------------------------------------------------------------- |
+| `tooling`   | `list`, `sync`, `ref`, `create`, `verify`, `inject`, `prune-gitignore`      |
+| `snippets`  | `list`, `install`, `sync`, `create`                                         |
+| `standards` | `list`, `install`, `sync`                                                   |
+| `gov`       | `list`, `install`, `sync`, `build`                                          |
+| `claude`    | `init`, `sync`, `seeds list`, `skills list`, `skills audit`, `setup [dest]` |
+| `wiki`      | `init`                                                                      |
+| `design`    | `render`                                                                    |
+| `slides`    | `render`, `list`                                                            |
+| `tasks`     | `archive`, `validate`                                                       |
+| `comments`  | `scan`                                                                      |
+| `context`   | `audit`                                                                     |
 
 Common patterns:
 

package/docs/agents/index.md

@@ -20,4 +20,5 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
 - [Sandbox](sandbox.md): Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills
 - [Scripting](scripting.md): The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
+- [Skill audit](skills-audit.md): Measuring both skill corpora against standards/skill.md, the checks it reads, and the requirement gate that is the only failing one
 - [Tasks](tasks.md): Selecting a shipped task by stem or pull request, the refusal reasons, the board checks validate runs, and why the board root defaults to the main worktree

package/docs/agents/indexes.md

@@ -7,7 +7,9 @@ description: Flags, exit codes, and JSON shape for aitk indexes regen, plus when
 
 `aitk indexes regen` rewrites `index.md` files from sibling frontmatter. With no positional paths, it walks the current directory. With paths, each resolves by walking up to the nearest indexed ancestor, bounded by `--root`. Duplicates dedupe. The whole-repo walk prunes `.git`, `node_modules`, and anything `.gitignore` covers via `git check-ignore`.
 
-A positional path is not filtered that way, because the walk-up resolves on the filesystem and never consults git. That is the only way to regenerate an index inside a gitignored folder, and it is how `.claude/tasks/` stays current.
+A positional path is not filtered that way, because the walk-up resolves on the filesystem and never consults git. That is the only way to regenerate an index inside a gitignored folder, and it is how `.claude/tasks/` and `.claude/memory/` both stay current.
+
+Each is driven by a `PostToolUse` hook matching `Write|Edit|MultiEdit`, so a file moved by a shell `mv` fires nothing. A caller that relocates an entry runs the command itself once the last move is done.
 
 | Option          | Behavior                                                         |
 | --------------- | ---------------------------------------------------------------- |

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

@@ -117,6 +117,52 @@ commits touching its own source path. The `covers` field names the domains a
 target has actually stamped, so a domain that was never stamped is legible
 rather than reading as a clean one.
 
+### Surfaces reported beside the domains
+
+Three 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
+`.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
+source rather than from what a target installed, so an unmanaged directory would
+otherwise report every seed as `missing`.
+
+A root-layout domain counts as a marker on its own, because the detection fires
+only on root files the toolkit ships and a project in the old layout is one the
+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` 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
+file that never arrived. There is no `customized` verdict here, because that one
+needs a stamp and seeds carry none, so a file history cannot attribute stays
+`drifted`. Reconcile the section with `claude-seed-sync`, which merges one
+section at a time rather than replacing a file the project edits.
+
+`superseded` names a file a newer seed folder replaced, such as `.claude/TASKS.md`
+against the `.claude/tasks/` that now ships. The entry carries `replacedBy` and
+nothing else, and the file is never deleted, since the content belongs to the
+project and only its author can decide where it moves. The list derives from the
+seed tree rather than from a fixed set of filenames, so a folder added later is
+covered without a code change. Only an exact stem matches, which leaves a
+suffixed variant such as `TASKS-ARCHIVE.md` unreported.
+
+`unmigrated` names a domain sitting at the root layout an older toolkit installed
+to, with nothing at the path the current one reads. It carries `rootPath`,
+`installPath`, and a file count. Without it a project holding `standards/` at its
+root reports zero entries for that domain and reads as clean, which is the most
+misleading state the report can produce. Route it to `migration-standards`.
+
+`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.
+
 ## Bootstrap
 
 `aitk init` installs up to six core domains and reports each one independently. A

package/docs/agents/scripting.md

@@ -53,9 +53,10 @@ names one per line.
 Each entry also carries `requirement`, whether the folder holds a sibling
 `REQUIREMENT.md`. Every skill is meant to carry one, so a `false` is a gap to
 close rather than a recorded exemption, and the flag answers which skills are
-missing theirs without a caller listing the directory itself. Nothing gates the
-rule yet, which is why the flag is worth reading against the shipped corpus after
-a merge.
+missing theirs without a caller listing the directory itself. `aitk claude skills
+audit` gates that rule across both corpora, so read this flag for the state of
+the shipped catalog and the audit for whether a working tree conforms. Its
+surface is in `skills-audit.md`.
 
 ## Non-interactive examples
 

package/docs/agents/skills-audit.md

@@ -0,0 +1,55 @@
+---
+title: Skill audit
+description: Measuring both skill corpora against standards/skill.md, the checks it reads, and the requirement gate that is the only failing one
+---
+
+# Skill audit
+
+`aitk claude skills audit [path]` reports both skill corpora against the rules `standards/skill.md` states mechanically. It reads and reports. Fixing what it finds is separate work.
+
+```bash
+aitk claude skills audit
+aitk claude skills audit --json
+aitk claude skills audit --requirements-only
+```
+
+| Option                | Behavior                                                             |
+| --------------------- | -------------------------------------------------------------------- |
+| `--json`              | Add a machine-readable record on stdout, keeping the frame           |
+| `--requirements-only` | Run the gating presence check alone, printing nothing when it passes |
+
+## Corpus scope
+
+Both trees are measured. `claude/skills/` installs into a target and `.claude/skills/` stays in the toolkit, the standard governs each, so a run reading one reports a pass over half its subject. A tree the project does not carry is skipped, which puts a target holding `.claude/skills/` alone in scope. A run where neither resolves refuses, since a clean exit over nothing measured is the outcome the command exists to prevent.
+
+The audit reads the directory it is pointed at, defaulting to the cwd. `aitk claude skills list` resolves the shipped corpus from its own install root instead, so a dev-linked binary reports `main` no matter which worktree runs it. Auditing a branch needs the cwd reading, which is why the two commands resolve their root differently.
+
+## What it measures
+
+Each check traces to a line in the standard.
+
+- `REQUIREMENT.md` present in every skill folder
+- Frontmatter `name` matching the folder name
+- Frontmatter `description` present
+- `description` under 1024 characters
+- No `README.md` inside a skill folder
+- Folder name in kebab-case
+- Each `REQUIREMENT.md` declaring `Gap` and `Must`, matched at any heading level
+
+A body whose frontmatter does not parse reports as declaring neither field rather than ending the run, so one malformed file cannot hide the corpus behind it. A key present with an empty value reads as absent, since a blank `name` would otherwise report as a name disagreeing with every folder. A folder carrying no requirement is reported once under presence rather than counted again for the sections it therefore lacks.
+
+## What it leaves alone
+
+The report names its own blind spots on every run, including the run where everything passed. Whether each `Must` traces to a stated gap is the rule in that standard worth the most and no parser reads it. Whether a gap states an observed failure rather than an intent, and whether a description routes, are the same kind of judgment. The 5,000-word body ceiling is mechanical and still absent here.
+
+A check with no rule behind it prints an opinion as a defect, which is where the list stops.
+
+## Exit codes
+
+Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a skill folder carrying no `REQUIREMENT.md`. Only presence sets a failing code. Name, description, folder, and requirement-section findings print and return `0`, because each is a judgment a reader settles and failing a push on one would make the check something to route around.
+
+## The requirement gate
+
+`--requirements-only` is the half wired into `bun run check`. Presence of a required file is a fact with no false positives, and the rule had nothing reading it, so a skill shipped without the sibling passed every stage while the standard required it.
+
+The check is preventive rather than diagnostic. Every mechanical rule passed across both corpora the day it shipped, so what it buys is the regression it stops rather than a backlog it surfaces.

package/docs/ai-workflow.md

@@ -84,7 +84,7 @@ The sweep reads the whole board rather than the tasks the session touched. It is
 
 `aitk:claude-docs` decides which task closed by reading the diff rather than the conversation. It resolves a merge base against `origin/main`, unions the committed diff with the working tree and untracked files, then matches unchecked outcomes on the board against what shipped. A task that shipped without ever being discussed still gets marked. Requirements, architecture, and design stay session-sourced, because a diff cannot carry a judgment.
 
-`.claude/tasks/` is gitignored and resolves at the main worktree root, so every session shares one board. One file per task is what keeps concurrent sessions from overwriting each other, since a gitignored board has no history to recover a lost write from. Its `index.md` is generated by a hook rather than by `bun run check`, because the whole-repo index walk skips gitignored folders. A hand-maintained `priority.md` sits beside it carrying execution order and what each task is waiting on, which the alphabetical index cannot express.
+`.claude/tasks/` is gitignored and resolves at the main worktree root, so every session shares one board. One file per task is what keeps concurrent sessions from overwriting each other, since a gitignored board has no history to recover a lost write from. Its `index.md` is generated by a hook rather than by `bun run check`, because the whole-repo index walk skips gitignored folders. `.claude/memory/` carries the same arrangement, its own hook regenerating `index.md` from each entry's `title`, `description`, and `category`. A hand-maintained `priority.md` sits beside it carrying execution order and what each task is waiting on, which the alphabetical index cannot express.
 
 `aitk tasks validate` checks what those rows claim against what the tree holds: every plan pointer resolves, every row and task file map one to one, no task sits in two groups, and no two rows marked ready touch the same file. That last check is the half a reader cannot run by eye, and it is what keeps two workers from being handed colliding work. It reports and never writes, because a row is the orchestrator's claim and a validator repairing one would assert the claim it exists to test. Nothing fires it automatically, since the board is gitignored per-machine scratch with no shared moment to hang a hook on, so the orchestrator's sweep calls it at the point the readiness claim is made.
 
@@ -106,7 +106,8 @@ For features on a mature stack, chain the post-plan pipeline in one session. App
 - An empty changed-file list stops the chain rather than counting as prose-only. The filename test passes vacuously on an empty set, which routed a branch past review instead of through it.
 - Every stop leaves recoverable state. Fix and resume with `/git-ship`
 - Skip autoship for auth, migrations, security-sensitive changes, or work where the plan itself is uncertain
-- After the PR is open, both `autoship` and `git-ship` invoke `claude-memory-capture` to write session patterns into `.claude/memory/`. If capture wrote at least one entry, `claude-memory-review` then proposes a decision-ready fix scoped to those captures while context is fresh, otherwise it is skipped. They stop at Propose. Review the receipt and run Apply yourself, on its own commit separate from the feature. Run `claude-memory-review` standalone to curate the whole pen.
+- Both `autoship` and `git-ship` open with `claude-memory-capture`, which sends what the session learned to the surface that owns it. A fact about a domain carrying an entry in `.claude/context/index.md` is routed to that entry, and `claude-docs` folds it in on the next step, so it ships in the same pull request. Anything no entry owns stays a file in `.claude/memory/`. Capture leads rather than trails because a routed fact edits a tracked file, which has to reach the branch before the commit steps run.
+- If capture wrote at least one memory file, `claude-memory-review` then proposes a decision-ready fix scoped to those entries while context is fresh, otherwise it is skipped. It stops at Propose. Review the receipt and run Apply yourself, on its own commit separate from the feature. Run `claude-memory-review` standalone to curate the whole pen. An entry it retires moves to `.claude/.tmp/memory-archive/` rather than being deleted, since the folder is gitignored and a bulk pass has no undo.
 
 ### UI polish
 

package/docs/target-projects.md

@@ -104,7 +104,11 @@ 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.
 
-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.
+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`.
+
+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.
+
+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 or seed drift, since both need the user to move content only they can place. An unmigrated domain does count, because running the relocation closes it.
 
 Tooling is not covered by the stamp. Reconcile those configs with `aitk tooling <stack> <path>`.
 

package/package.json

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

package/scripts/core/verify.sh

@@ -183,6 +183,14 @@ main() {
   run_check "cd $PROJECT_ROOT && bun src/cli.ts context audit --citations-only" "A cited context path does not resolve. Run bun src/cli.ts context audit."
   log_info "Context citations resolve"
 
+  # Presence of a required file is a fact, so it gates. The name, description,
+  # folder, and requirement-section measures beside it report and are read from a
+  # bare run. `bun src/cli.ts` for the reason the stage above uses it, and the
+  # command reads the cwd, so this measures the worktree being pushed.
+  log_step "Skill requirements"
+  run_check "cd $PROJECT_ROOT && bun src/cli.ts claude skills audit --requirements-only" "A skill folder carries no REQUIREMENT.md. Run bun src/cli.ts claude skills audit."
+  log_info "Skill requirements present"
+
   log_step "Plugin manifests"
   if ! command -v claude >/dev/null 2>&1; then
     log_info "Skipped, claude is not installed"

package/src/claude/seeds.ts

@@ -7,10 +7,16 @@ const SEEDS_DIR = join('tooling', 'claude', 'seeds')
 const CLAUDE_DIR = '.claude'
 const CLAUDE_MD = 'CLAUDE.md'
 const HOOKS = 'hooks'
-const SUBDIRS: readonly string[] = [
+/**
+ * Seed subdirectories under `.claude/`. Exported because each one replaced a
+ * single file of the same stem in an older layout, which is what
+ * `@/sync/layout` pairs a target against to find a superseded artifact.
+ */
+export const SUBDIRS: readonly string[] = [
   HOOKS,
   'context',
   'diagrams',
+  'memory',
   'tasks',
   'wireframes',
 ]

package/src/claude/skills-audit.ts

@@ -0,0 +1,215 @@
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import {
+  type Frontmatter,
+  parseFrontmatter,
+  readField,
+} from '@/indexes/frontmatter'
+
+/** Returned when a skill folder carries no `REQUIREMENT.md`, the gating check. */
+export const EXIT_MISSING_REQUIREMENT = 2
+
+/** The description ceiling stated in the frontmatter rules of `standards/skill.md`. */
+export const DESCRIPTION_LIMIT = 1024
+
+/** The two headings the requirement template declares, matched at any level. */
+export const REQUIREMENT_SECTIONS: readonly string[] = ['Gap', 'Must']
+
+/**
+ * Both trees the standard governs. `claude/skills/` ships to a target and
+ * `.claude/skills/` stays here, and every rule measured below applies to each,
+ * so a corpus reading one of them reports a pass over half the subject.
+ */
+export const CORPORA: readonly string[] = [
+  join('claude', 'skills'),
+  join('.claude', 'skills'),
+]
+
+/** Kebab-case, which the standard states as no spaces, capitals, or underscores. */
+const KEBAB_CASE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+const HEADING = /^#{1,6}\s+(.+?)\s*$/
+
+export interface SkillFinding {
+  readonly rel: string
+  readonly detail: string
+}
+
+export interface CorpusReport {
+  readonly rel: string
+  readonly skills: number
+}
+
+export interface SkillsAudit {
+  readonly corpora: readonly CorpusReport[]
+  readonly skills: number
+  readonly missingRequirement: readonly string[]
+  readonly readme: readonly string[]
+  readonly folderName: readonly string[]
+  readonly missingDescription: readonly string[]
+  readonly nameMismatch: readonly SkillFinding[]
+  readonly longDescription: readonly SkillFinding[]
+  readonly requirementSections: readonly SkillFinding[]
+}
+
+interface SkillSource {
+  readonly rel: string
+  readonly folder: string
+  readonly hasReadme: boolean
+  readonly name: string | undefined
+  readonly description: string | undefined
+  /** Undefined when the folder carries no `REQUIREMENT.md` at all. */
+  readonly requirementHeadings: readonly string[] | undefined
+}
+
+/**
+ * Measures both skill corpora against the rules `standards/skill.md` states
+ * mechanically. A corpus the project does not carry is skipped rather than
+ * reported, so a target holding only `.claude/skills/` reads as in scope.
+ *
+ * Reads raw frontmatter rather than `listSkills`, which prefers the folder name
+ * over the declared one and so can never surface a disagreement between them.
+ */
+export async function auditSkills(root: string): Promise<SkillsAudit> {
+  const present = CORPORA.map((rel) => ({ rel, dir: join(root, rel) })).filter(
+    (corpus) => existsSync(corpus.dir),
+  )
+
+  const perCorpus = await Promise.all(
+    present.map((corpus) => readCorpus(corpus.rel, corpus.dir)),
+  )
+  const sources = perCorpus.flat()
+
+  return {
+    corpora: present.map((corpus, index) => ({
+      rel: corpus.rel,
+      skills: perCorpus[index]?.length ?? 0,
+    })),
+    skills: sources.length,
+    missingRequirement: sources
+      .filter((source) => source.requirementHeadings === undefined)
+      .map((source) => source.rel),
+    readme: sources
+      .filter((source) => source.hasReadme)
+      .map((source) => source.rel),
+    folderName: sources
+      .filter((source) => !KEBAB_CASE.test(source.folder))
+      .map((source) => source.rel),
+    missingDescription: sources
+      .filter((source) => source.description === undefined)
+      .map((source) => source.rel),
+    nameMismatch: sources.flatMap(nameFindings),
+    longDescription: sources.flatMap(lengthFindings),
+    requirementSections: sources.flatMap(sectionFindings),
+  }
+}
+
+/**
+ * Only a required file that is absent sets a failing code, which is a fact.
+ * Every other measure is a judgment a reader settles, and failing a push on one
+ * teaches contributors to route around the stage.
+ */
+export function auditExitCode(report: SkillsAudit): number {
+  return report.missingRequirement.length > 0 ? EXIT_MISSING_REQUIREMENT : 0
+}
+
+async function readCorpus(rel: string, dir: string): Promise<SkillSource[]> {
+  const paths = [
+    ...new Bun.Glob('*/SKILL.md').scanSync({ cwd: dir, onlyFiles: true }),
+  ].sort()
+
+  return Promise.all(paths.map((path) => readSkill(rel, dir, dirname(path))))
+}
+
+async function readSkill(
+  rel: string,
+  dir: string,
+  folder: string,
+): Promise<SkillSource> {
+  const skillDir = join(dir, folder)
+  const requirementPath = join(skillDir, 'REQUIREMENT.md')
+
+  const [body, requirement] = await Promise.all([
+    Bun.file(join(skillDir, 'SKILL.md')).text(),
+    existsSync(requirementPath)
+      ? Bun.file(requirementPath).text()
+      : Promise.resolve(undefined),
+  ])
+
+  const fields = readFields(body)
+
+  return {
+    rel: join(rel, folder),
+    folder,
+    hasReadme: existsSync(join(skillDir, 'README.md')),
+    name: declared(readField(fields, 'name')),
+    description: declared(readField(fields, 'description')),
+    requirementHeadings:
+      requirement === undefined ? undefined : headings(requirement),
+  }
+}
+
+/**
+ * Returns undefined rather than throwing on unparseable YAML, so one malformed
+ * body reports as missing its required fields instead of ending the audit
+ * before it reaches the rest of the corpus.
+ */
+function readFields(body: string): Frontmatter | undefined {
+  try {
+    return parseFrontmatter(body)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * A key carrying an empty value declares nothing, so blank reads as absent
+ * rather than as a name that disagrees with every folder.
+ */
+function declared(value: string | undefined): string | undefined {
+  const trimmed = value?.trim()
+  return trimmed === undefined || trimmed === '' ? undefined : trimmed
+}
+
+function headings(source: string): string[] {
+  return source
+    .split('\n')
+    .map((line) => HEADING.exec(line)?.[1])
+    .filter((text): text is string => text !== undefined)
+}
+
+function nameFindings(source: SkillSource): SkillFinding[] {
+  if (source.name === undefined) {
+    return [{ rel: source.rel, detail: 'frontmatter declares no name' }]
+  }
+  if (source.name === source.folder) return []
+  return [{ rel: source.rel, detail: `frontmatter name: ${source.name}` }]
+}
+
+function lengthFindings(source: SkillSource): SkillFinding[] {
+  const { description } = source
+  if (description === undefined) return []
+  if (description.length <= DESCRIPTION_LIMIT) return []
+  return [{ rel: source.rel, detail: `${description.length} characters` }]
+}
+
+/**
+ * Stays silent on a folder carrying no requirement at all, which the presence
+ * check already reports. Counting the same skill twice reads as two defects.
+ */
+function sectionFindings(source: SkillSource): SkillFinding[] {
+  const { requirementHeadings } = source
+  if (requirementHeadings === undefined) return []
+
+  const missing = REQUIREMENT_SECTIONS.filter(
+    (section) => !requirementHeadings.includes(section),
+  )
+  if (missing.length === 0) return []
+
+  return [
+    {
+      rel: join(source.rel, 'REQUIREMENT.md'),
+      detail: `missing: ${missing.join(', ')}`,
+    },
+  ]
+}