@erclx/aitk 0.44.0 → 0.45.0

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/ui.ts

@@ -59,6 +59,11 @@ export function pipeOutput(text: string): void {
   )
 }
 
+/** Counts a noun for a report line, where the plural is the bare `s` form. */
+export function plural(count: number, noun: string): string {
+  return `${count} ${noun}${count === 1 ? '' : 's'}`
+}
+
 export function frameError(message: string): void {
   process.stderr.write(
     `${GREY}┌${NC}\n${GREY}│${NC} ${RED}✗${NC} ${message}\n${GREY}└${NC}\n`,

package/tooling/claude/reference.md

@@ -20,7 +20,7 @@ The claude stack installs the `.claude/` workflow directory into a project. Stat
 ├── plans/             ← execution detail for multi-step tasks, gitignored. `feature-*.md` entries swept by claude-docs.
 ├── review/            ← scratch for claude-review and claude-ui-test output, gitignored
 ├── .tmp/              ← ephemeral scratch space, gitignored
-└── memory/            ← session memory files, gitignored
+└── memory/            ← session facts no context entry owns, gitignored. `index.md` regenerated by a hook.
 ```
 
 ## Upgrading from a single-file board
@@ -33,6 +33,16 @@ Convert by hand, once per project:
 2. Run `aitk indexes regen --no-stage --root . .claude/tasks/<any-task>.md` to build the catalog.
 3. Delete `.claude/TASKS.md`, and swap its `.gitignore` entry for `.claude/tasks/`.
 
+## Upgrading a hand-appended memory index
+
+A project installed before the memory folder gained a generated index still holds `.claude/memory/MEMORY.md`, and its entries still carry `name` and `type` frontmatter. Nothing migrates it. `claude-memory-capture` stops appending rows once the new seed lands, so the old file freezes at whatever it held while the folder keeps growing past it.
+
+Convert by hand, once per project:
+
+1. Rewrite each entry's `name` key to `title` and its `type` key to a sentence-case `category`, quoting any `description` that opens with a backtick or a colon so the frontmatter parses.
+2. Replace `MEMORY.md` with an `index.md` carrying `title` and `subtitle` frontmatter and nothing else.
+3. Run `aitk indexes regen --no-stage --root . .claude/memory/index.md` to build the catalog, and compare its entry count against the file count before deleting anything.
+
 ## Upgrading from a single-file diagram set
 
 A project installed before the diagram surface became a folder still holds `.claude/DIAGRAMS.md`. Unlike the board, this one migrates itself. The `claude-diagram` skill reads the flat file when `.claude/diagrams/` holds no entries, splits it by kind into the folder, and reports what it wrote. The old file stays on disk so the split can be compared against its source, and deleting it is a manual step once that check passes.

package/tooling/claude/seeds/.claude/hooks/memory-index.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+
+# Regenerates .claude/memory/index.md after a memory file changes.
+#
+# The memory folder is gitignored, so the whole-repo walk in `bun run check`
+# drops it and never regenerates this index. A positional path bypasses that
+# filter, which makes this hook the only trigger that reaches the folder.
+
+input=$(cat)
+
+tool=$(printf '%s' "$input" | jq -r '.tool_name // empty')
+case "$tool" in
+Write | Edit | MultiEdit) ;;
+*) exit 0 ;;
+esac
+
+file_path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
+[ -n "$file_path" ] || exit 0
+
+case "$file_path" in
+*/.claude/memory/*.md) ;;
+*) exit 0 ;;
+esac
+
+case "$file_path" in
+*/.claude/memory/index.md) exit 0 ;;
+esac
+
+# Report a missing CLI rather than exiting quietly. The path guard above already
+# scopes this to a memory-file edit, so the message only fires where the stale
+# index it warns about is the actual outcome.
+if ! command -v aitk >/dev/null 2>&1; then
+  jq -nc --arg msg 'aitk is not on PATH, so .claude/memory/index.md was not regenerated and is now stale. Install the toolkit CLI or run aitk indexes regen by hand.' \
+    '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'
+  exit 0
+fi
+
+# The walk-up boundary has to come from the path, not from the session. Shared
+# scratch resolves at the main worktree root, so a session inside a linked
+# worktree passes a path that sits outside its own project directory and the
+# default boundary would reject it.
+root="${file_path%/.claude/memory/*}"
+[ -n "$root" ] || exit 0
+
+# `--no-stage` because a hook has no business touching the index. On a project
+# whose memory folder is not gitignored, the default auto-stage would silently
+# add memory files to whatever commit is being assembled.
+output=$(aitk indexes regen --no-stage --root "$root" "$file_path" 2>&1) && exit 0
+
+# Regen failed, which on this folder means a memory file is missing `title` or
+# `description`. Report it. Nothing else can: the folder is gitignored, so the
+# whole-repo walk never reaches it and no gate stage will ever fail on a stale
+# index. Staying quiet here is what makes the drift permanent.
+errors=$(printf '%s\n' "$output" | grep '^ERROR: ' | head -5)
+[ -n "$errors" ] || errors="$output"
+
+msg="Memory index regen failed, so .claude/memory/index.md is now stale. Fix the frontmatter and save again. $errors"
+jq -nc --arg msg "$msg" \
+  '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'
+exit 0

package/tooling/claude/seeds/.claude/memory/index.md

@@ -0,0 +1,8 @@
+---
+title: Memory
+subtitle: Session facts with no owning surface, grouped by kind. Feedback is the working set.
+---
+
+# Memory
+
+Session facts with no owning surface, grouped by kind. Feedback is the working set.

package/tooling/claude/seeds/.claude/settings.json

@@ -31,6 +31,10 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/tasks-index.sh"
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/memory-index.sh"
           }
         ]
       }

package/tooling/claude/seeds/CLAUDE.md

@@ -72,9 +72,12 @@
 ## Memory
 
 - Write all memory files to `.claude/memory/`, not `~/.claude/projects/`
+- A fact about a domain goes to that domain's `.claude/context/` entry, not to memory. `claude-memory-capture` routes it there and `claude-docs` folds it in. Memory keeps only what no context entry owns.
 - Save a feedback memory only when the same mistake happens twice in the session, or when the user explicitly corrects you. First-occurrence slips are noise.
 - Keep feedback memories to 3 lines: the rule, a one-line Why, and a one-line How to apply. Capture the pattern, not the recovery narrative.
 - Before creating a new memory file, check for an existing one on the same topic. Update rather than duplicate.
+- Give every entry `title`, `description`, and a sentence-case `category`. Never hand-edit `.claude/memory/index.md`. A hook regenerates it from sibling frontmatter.
+- Never delete a memory entry. `claude-memory-review` moves a retired one to `.claude/.tmp/memory-archive/`.
 
 ## Scratch