@erclx/aitk 0.44.0 → 0.46.0

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')

package/src/commands/claude.ts

@@ -12,6 +12,15 @@ import {
   type Seed,
 } from '@/claude/seeds'
 import { listSeeds, readSeedContents } from '@/claude/seeds-list'
+import {
+  auditExitCode,
+  auditSkills,
+  CORPORA,
+  DESCRIPTION_LIMIT,
+  REQUIREMENT_SECTIONS,
+  type SkillFinding,
+  type SkillsAudit,
+} from '@/claude/skills-audit'
 import { listSkills } from '@/claude/skills-list'
 import {
   planSettings,
@@ -24,6 +33,7 @@ import { execScript, PROJECT_ROOT } from '@/exec'
 import { isDirectory, resolveTarget } from '@/target'
 import { injectGitignore, pruneGitignore } from '@/tooling/inject'
 import {
+  frameError,
   intro,
   isNonInteractive,
   logAdd,
@@ -32,6 +42,8 @@ import {
   logStep,
   logWarn,
   outro,
+  pipeOutput,
+  plural,
   select,
 } from '@/ui'
 
@@ -49,12 +61,17 @@ interface SkillsListOptions {
   readonly names?: boolean
 }
 
+interface SkillsAuditOptions {
+  readonly json?: boolean
+  readonly requirementsOnly?: boolean
+}
+
 const SEEDED_FILES: readonly string[] = [
   'ARCHITECTURE.md',
   'REQUIREMENTS.md',
   'DESIGN.md',
 ]
-const SEEDED_DIRS: readonly string[] = ['tasks', 'wireframes']
+const SEEDED_DIRS: readonly string[] = ['memory', 'tasks', 'wireframes']
 const USER_DIR = join('tooling', 'claude', 'user')
 const STATUSLINE = 'statusline-command.sh'
 
@@ -139,15 +156,15 @@ export function register(program: Command): void {
 
   const skills = claude
     .command('skills')
-    .description('Plugin skill catalog (list)')
-    .argument('[subcommand]', "Only 'list' is supported")
+    .description('Plugin skill catalog (list, audit)')
+    .argument('[subcommand]', "One of 'list' or 'audit'")
     .helpOption('-h, --help', 'Show this help message')
     .action((subcommand: string | undefined) => {
       intro('aitk claude')
       logError(
         subcommand === undefined
-          ? "Missing subcommand. Use 'list'."
-          : `Unknown subcommand: ${subcommand}. Use 'list'.`,
+          ? "Missing subcommand. Use 'list' or 'audit'."
+          : `Unknown subcommand: ${subcommand}. Use 'list' or 'audit'.`,
       )
       outro()
       process.exitCode = 1
@@ -172,6 +189,41 @@ export function register(program: Command): void {
     .action((opts: SkillsListOptions) => {
       process.exitCode = runSkillsList(opts)
     })
+
+  skills
+    .command('audit')
+    .description(
+      'Report both skill corpora against the mechanical rules in standards/skill.md',
+    )
+    .argument('[path]', 'Project root, defaulting to the current directory')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option(
+      '--requirements-only',
+      'Run the gating requirement-presence check alone',
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the audit completed with every skill carrying a requirement',
+        '  1  refused, with the reason on stderr',
+        '  2  a skill folder carries no REQUIREMENT.md',
+        '',
+        'Only a missing REQUIREMENT.md sets a failing exit code. Name, description,',
+        'folder, and requirement-section findings are advisory.',
+        '',
+        'Examples:',
+        '  aitk claude skills audit',
+        '  aitk claude skills audit --json',
+        '  aitk claude skills audit --requirements-only',
+        '',
+      ].join('\n'),
+    )
+    .action(async (path: string | undefined, opts: SkillsAuditOptions) => {
+      process.exitCode = await runSkillsAudit(path, opts)
+    })
 }
 
 function succeed(message: string): number {
@@ -413,3 +465,229 @@ function runSkillsList(opts: SkillsListOptions): number {
   outro()
   return 0
 }
+
+/**
+ * Measures the tree at the cwd rather than the toolkit root the catalog reads,
+ * so a linked worktree audits its own branch instead of reporting on `main`. A
+ * target carrying `.claude/skills/` alone is in scope for the same reason.
+ */
+async function runSkillsAudit(
+  path: string | undefined,
+  opts: SkillsAuditOptions,
+): Promise<number> {
+  const root = resolve(path ?? process.cwd())
+  const gateOnly = opts.requirementsOnly ?? false
+  const report = await auditSkills(root)
+
+  if (report.corpora.length === 0) {
+    return refuseAudit(
+      `No skill corpus under ${root}. Looked for ${CORPORA.join(' and ')}.`,
+      gateOnly,
+    )
+  }
+
+  if (gateOnly) {
+    reportRequirementGate(report)
+  } else {
+    intro('aitk claude skills audit')
+    reportScope(report)
+    reportRequirements(report)
+    reportFrontmatter(report)
+    reportFolder(report)
+    reportRequirementShape(report)
+    reportUnmeasured()
+    outro()
+  }
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        corpora: report.corpora.map((corpus) => ({
+          path: corpus.rel,
+          skills: corpus.skills,
+        })),
+        skills: report.skills,
+        findings: {
+          missingRequirement: report.missingRequirement,
+          nameMismatch: report.nameMismatch,
+          missingDescription: report.missingDescription,
+          longDescription: report.longDescription,
+          readme: report.readme,
+          folderName: report.folderName,
+          requirementSections: report.requirementSections,
+        },
+        checkpoints: {
+          descriptionLimit: DESCRIPTION_LIMIT,
+          requirementSections: REQUIREMENT_SECTIONS,
+          corpora: CORPORA,
+        },
+      })}\n`,
+    )
+  }
+
+  return auditExitCode(report)
+}
+
+function refuseAudit(message: string, gateOnly: boolean): number {
+  if (gateOnly) {
+    frameError(message)
+    return 1
+  }
+
+  intro('aitk claude skills audit')
+  logStep('Refused')
+  logWarn(message)
+  outro()
+  return 1
+}
+
+/**
+ * Prints nothing when every skill carries a requirement.
+ *
+ * `--requirements-only` is what `verify.sh` runs on every push, and that script
+ * pipes a stage's whole output into its own frame. A passing gate that printed
+ * its frame would nest one inside the other on every contributor's push.
+ */
+function reportRequirementGate(report: SkillsAudit): void {
+  const missing = report.missingRequirement
+  if (missing.length === 0) return
+
+  intro('aitk claude skills audit')
+  logError(
+    missing.length === 1
+      ? '1 skill folder carries no REQUIREMENT.md'
+      : `${missing.length} skill folders carry no REQUIREMENT.md`,
+  )
+  pipeOutput(missing.join('\n'))
+  outro()
+}
+
+function reportFindings(findings: readonly SkillFinding[]): void {
+  pipeOutput(
+    findings.map((found) => `${found.rel}  ${found.detail}`).join('\n'),
+  )
+}
+
+/**
+ * Names each corpus that resolved, since a corpus the tree does not carry is
+ * skipped silently and a count taken over one of the two reads as the whole.
+ */
+function reportScope(report: SkillsAudit): void {
+  logStep('Scope')
+  for (const corpus of report.corpora) {
+    logInfo(`${corpus.rel}: ${plural(corpus.skills, 'skill')}`)
+  }
+}
+
+function reportRequirements(report: SkillsAudit): void {
+  logStep('Requirements')
+  logInfo('Every skill folder carries REQUIREMENT.md beside SKILL.md.')
+  logInfo('This is the only measure here that fails a run.')
+
+  if (report.missingRequirement.length === 0) {
+    logInfo('Every skill carries one.')
+    return
+  }
+
+  logWarn(`${plural(report.missingRequirement.length, 'skill')} without one`)
+  pipeOutput(report.missingRequirement.join('\n'))
+}
+
+function reportFrontmatter(report: SkillsAudit): void {
+  logStep('Frontmatter')
+  logInfo(
+    `name matches the folder, and description is present and under ${DESCRIPTION_LIMIT} characters.`,
+  )
+  logInfo('A body whose frontmatter does not parse reads as declaring neither.')
+
+  const findings =
+    report.nameMismatch.length +
+    report.missingDescription.length +
+    report.longDescription.length
+  if (findings === 0) {
+    logInfo('Every body declares both fields.')
+    return
+  }
+
+  if (report.nameMismatch.length > 0) {
+    logWarn(
+      `${plural(report.nameMismatch.length, 'body')} whose name does not match its folder`,
+    )
+    reportFindings(report.nameMismatch)
+  }
+
+  if (report.missingDescription.length > 0) {
+    logWarn(
+      `${plural(report.missingDescription.length, 'body')} without a description`,
+    )
+    pipeOutput(report.missingDescription.join('\n'))
+  }
+
+  if (report.longDescription.length > 0) {
+    logWarn(
+      `${plural(report.longDescription.length, 'description')} past the ${DESCRIPTION_LIMIT}-character ceiling`,
+    )
+    reportFindings(report.longDescription)
+  }
+}
+
+function reportFolder(report: SkillsAudit): void {
+  logStep('Folder')
+  logInfo(
+    'No README.md inside a skill folder, and a folder name in kebab-case carrying no capital or underscore.',
+  )
+
+  if (report.readme.length === 0 && report.folderName.length === 0) {
+    logInfo('Every folder conforms.')
+    return
+  }
+
+  if (report.readme.length > 0) {
+    logWarn(`${plural(report.readme.length, 'folder')} carrying a README.md`)
+    pipeOutput(report.readme.join('\n'))
+  }
+
+  if (report.folderName.length > 0) {
+    logWarn(
+      `${plural(report.folderName.length, 'folder name')} outside kebab-case`,
+    )
+    pipeOutput(report.folderName.join('\n'))
+  }
+}
+
+function reportRequirementShape(report: SkillsAudit): void {
+  logStep('Requirement shape')
+  logInfo(
+    `Each REQUIREMENT.md declares ${REQUIREMENT_SECTIONS.join(' and ')}, matched at any heading level.`,
+  )
+  logInfo(
+    'A folder carrying no requirement is reported above rather than counted twice here.',
+  )
+
+  if (report.requirementSections.length === 0) {
+    logInfo('Every requirement declares both.')
+    return
+  }
+
+  logWarn(
+    `${plural(report.requirementSections.length, 'requirement')} short a declared section`,
+  )
+  reportFindings(report.requirementSections)
+}
+
+/**
+ * Stated on every run, including the run where everything above passed. A
+ * report that lists only what it measured reads as a verdict on the standard
+ * rather than on the half of it a parser can reach.
+ */
+function reportUnmeasured(): void {
+  logStep('Unmeasured')
+  logInfo(
+    'The standard states rules no parser reads, and a pass above says nothing about them.',
+  )
+  logInfo(
+    'Whether each Must traces to a stated gap, whether a gap reads as an observed failure rather than an intent, and whether a description routes.',
+  )
+  logInfo('The 5,000-word body ceiling is mechanical and still absent here.')
+}

package/src/commands/context.ts

@@ -31,6 +31,7 @@ import {
   logWarn,
   outro,
   pipeOutput,
+  plural,
 } from '@/ui'
 
 /** Returned when an unresolved citation is found, which is the gating check. */
@@ -253,10 +254,6 @@ function reportGate(report: ScannedCitations): void {
   outro()
 }
 
-function plural(count: number, noun: string): string {
-  return `${count} ${noun}${count === 1 ? '' : 's'}`
-}
-
 /**
  * Names the resolved path of every audited folder, plus the requested names
  * that resolved nowhere.

package/src/commands/sync.ts

@@ -95,6 +95,16 @@ async function runCheck(target: string, options: SyncOptions): Promise<number> {
 function renderCheck(report: CheckReport): void {
   intro('aitk sync --check')
 
+  if (!report.managed) {
+    logStep('Not a toolkit project')
+    logWarn('No .claude/ directory and no CLAUDE.md at the target.')
+    logInfo(
+      'Run `aitk init` to install, or /aitk:setup-init to resolve a stack.',
+    )
+    outro()
+    return
+  }
+
   for (const domain of report.domains) {
     logStep(domain.domain)
 
@@ -123,14 +133,33 @@ function renderCheck(report: CheckReport): void {
     }
   }
 
+  for (const entry of report.unmigrated) {
+    logStep(`${entry.domain} (not migrated)`)
+    logWarn(
+      `${entry.files} files at ${entry.rootPath}/, nothing at ${entry.installPath}/`,
+    )
+    logInfo('Run /aitk:migration-standards to relocate them.')
+  }
+
+  renderSeeds(report)
+
+  if (report.superseded.length > 0) {
+    logStep('Superseded by a newer layout')
+    for (const entry of report.superseded) {
+      logWarn(`${entry.rel} (replaced by ${entry.replacedBy}/)`)
+    }
+    logInfo('Move the content yourself. No sync command touches these.')
+  }
+
   if (report.newSkills.length > 0) {
     logStep('New skills, no sync needed')
     for (const name of report.newSkills) logInfo(name)
   }
 
   outro()
+  const unmigrated = report.unmigrated.map((entry) => entry.domain)
   const uncovered = STAMP_DOMAINS.filter(
-    (domain) => !report.covers.includes(domain),
+    (domain) => !report.covers.includes(domain) && !unmigrated.includes(domain),
   )
   const unstamped =
     uncovered.length === 0 ? '' : `Unstamped: ${uncovered.join(', ')}. `
@@ -139,6 +168,30 @@ function renderCheck(report: CheckReport): void {
   )
 }
 
+/**
+ * Seeds print their own section because no sync command applies them. A `stale`
+ * seed is safe to take whole and a `drifted` one holds edits, which is the split
+ * `claude-seed-sync` reads to decide what needs a section-level merge.
+ */
+function renderSeeds(report: CheckReport): void {
+  const notable = report.seeds.entries.filter(
+    (entry) => entry.state !== 'matching',
+  )
+
+  if (notable.length === 0) return
+
+  logStep('seeds')
+  if (report.seeds.historyUnavailable) {
+    logWarn('This toolkit has no git history. Drift below is unattributed.')
+  }
+
+  for (const entry of notable) {
+    logWarn(`${entry.rel} (${entry.state})`)
+  }
+
+  logInfo('Run /aitk:claude-seed-sync to reconcile these section by section.')
+}
+
 async function runSync(target: string): Promise<number> {
   intro('aitk sync')
 

package/src/sync/check.ts

@@ -1,8 +1,16 @@
+import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { execa } from 'execa'
 import { createGovAdapter } from '@/gov/adapter'
 import { createSnippetsAdapter } from '@/snippets/adapter'
 import { planSync, type ScanEntry, type SyncAdapter } from '@/sync/engine'
+import {
+  collectSuperseded,
+  detectUnmigrated,
+  type SupersededEntry,
+  type UnmigratedDomain,
+} from '@/sync/layout'
+import { buildSeedsReport, type SeedsReport } from '@/sync/seeds-report'
 import {
   readStamp,
   STAMP_DOMAINS,
@@ -68,7 +76,16 @@ export interface UpstreamCommit {
 
 export interface CheckReport {
   readonly covers: readonly StampDomain[]
+  /** False when the target is not a toolkit project, so every section stays empty. */
+  readonly managed: boolean
   readonly domains: readonly DomainReport[]
+  /**
+   * Reported beside the domains rather than as one of them, because seeds carry
+   * no stamp and produce no change. See `@/sync/seeds-report`.
+   */
+  readonly seeds: SeedsReport
+  readonly superseded: readonly SupersededEntry[]
+  readonly unmigrated: readonly UnmigratedDomain[]
   readonly newSkills: readonly string[]
 }
 
@@ -78,6 +95,33 @@ export function installedStampDomains(target: string): StampDomain[] {
   )
 }
 
+/**
+ * Whether the target is a toolkit-managed project at all. Seeds are enumerated
+ * from the source rather than from what a target installed, so without this gate
+ * a directory the toolkit has never touched reports every seed as `missing` and
+ * routes to a skill that reconciles section by section. `installedStampDomains`
+ * gates the three scanned domains the same way, which is why they stay quiet on
+ * the same directory.
+ *
+ * An unmigrated domain counts as a marker in its own right. `detectUnmigrated`
+ * fires only on root files whose basename the toolkit ships, so it firing proves
+ * the toolkit installed here before the layout moved under `.claude/`. Reading
+ * only the markers would report such a target as unmanaged while the same report
+ * carried its unmigrated domain, and a consumer reading the JSON would route to
+ * the relocation while the rendered half routed to install.
+ */
+export function isManagedTarget(
+  target: string,
+  unmigrated: readonly UnmigratedDomain[],
+): boolean {
+  if (unmigrated.length > 0) return true
+
+  return (
+    isDirectory(join(target, '.claude')) ||
+    existsSync(join(target, 'CLAUDE.md'))
+  )
+}
+
 export function countStates(entries: readonly ScanEntry[]): StateCounts {
   return {
     matching: count(entries, 'matching'),
@@ -93,8 +137,16 @@ export function countStates(entries: readonly ScanEntry[]): StateCounts {
  * Whether the target has diverged from the toolkit in a way a sync could close.
  * Orphaned files are excluded: a project-authored rule never converges, and
  * counting it would leave `--exit-code` failing forever with no remedy.
+ *
+ * An unmigrated domain counts, because running the relocation closes it. A
+ * superseded artifact does not, for the same reason orphaned files do not: only
+ * the user can move content they wrote, so failing a job on it leaves the job
+ * red with no mechanical remedy. Seeds are excluded on the same grounds, since
+ * every seed a project edits would otherwise fail the check forever.
  */
 export function hasDrift(report: CheckReport): boolean {
+  if (report.unmigrated.length > 0) return true
+
   return report.domains.some(
     (domain) =>
       domain.counts.stale +
@@ -126,9 +178,28 @@ export async function buildCheckReport(
     .map((domain) => domain.commit)
     .filter((commit): commit is string => commit !== undefined)
 
+  const unmigrated = detectUnmigrated(toolkitRoot, target)
+  const managed = isManagedTarget(target, unmigrated)
+
+  if (!managed) {
+    return {
+      covers: [],
+      managed,
+      domains: [],
+      seeds: { entries: [], historyUnavailable: false },
+      superseded: [],
+      unmigrated: [],
+      newSkills: [],
+    }
+  }
+
   return {
     covers: stamp?.covers ?? [],
+    managed,
     domains,
+    seeds: buildSeedsReport(toolkitRoot, target),
+    superseded: collectSuperseded(target),
+    unmigrated,
     newSkills: await readNewSkills(toolkitRoot, anchors),
   }
 }