@erclx/aitk 0.44.0 → 0.45.0

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/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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.44.0",
+  "version": "0.45.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

@@ -11,6 +11,7 @@ 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(', ')}`,
+    },
+  ]
+}

package/src/claude/skills-list.ts

@@ -17,9 +17,9 @@ export interface SkillListing {
  * The folder name wins over the frontmatter `name` when they disagree, because
  * Claude Code invokes a skill by its directory.
  *
- * `requirement` reports whether the folder carries `REQUIREMENT.md`. Coverage is
- * selective by design, so a false is not a gap to close and this field carries no
- * reason for one. The toolkit records those separately from the catalog.
+ * `requirement` reports whether the folder carries `REQUIREMENT.md`. Every skill
+ * is meant to carry one, so a false is a gap rather than a recorded exemption.
+ * `aitk claude skills audit` is what fails on it, across both corpora.
  */
 export function listSkills(root: string): SkillListing[] {
   const skillsRoot = join(root, 'claude', 'skills')