@erclx/aitk 0.8.0 → 0.10.0

package/claude/skills/claude-worktree/SKILL.md

@@ -34,10 +34,10 @@ The directory test separates the defect from a genuinely bare repository, which
 
 Try each source in order. Stop at the first match.
 
-1. **Plan matched to current branch.** Take the branch name and replace `/` with `-` to get `<slug>`. If `<main-root>/.claude/plans/feature-<slug>.md` exists, use `<slug>`.
+1. **Plan matched to current branch.** Derive `<slug>` per Deriving the branch slug in `.claude/standards/skill.md`, or `${CLAUDE_SKILL_DIR}/../../standards/skill.md` when the project does not have it. An empty result falls through to the next source here rather than becoming `latest`, since the slug is one candidate among several. If `<main-root>/.claude/plans/feature-<slug>.md` exists, use `<slug>`.
 2. **Single plan file.** List `<main-root>/.claude/plans/feature-*.md`. If exactly one match, derive `<slug>` from the filename.
 3. **Multiple plan files, no branch match.** Ask the user which plan. Show the candidate slugs as a numbered list. Do not pick.
-4. **Current branch.** When no plan exists, use the branch name (with `/` replaced by `-`) if it is not `main` or `master`.
+4. **Current branch.** When no plan exists, use the `<slug>` from step 1 if it is not `main` or `master`.
    4b. **Session context.** When on `main` or `master` with no matching plan, read the current conversation to infer a kebab slug from the topic being discussed. Propose it: `Infer: <slug>. Confirm or rename?` Do not enter the worktree until the user confirms or provides a corrected name.
 5. **Ask.** None of the above applies. Ask the user for a name. Do not invent one.
 

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

@@ -24,7 +24,7 @@ its own reply, so skip the comment in step 6. The push and body sync still run.
 3. Invoke `aitk:git-commit` to generate one conventional commit from the staged diff
 4. Run `git push` to the tracking branch
 5. Check for existing review comments: `gh api 'repos/{owner}/{repo}/pulls/<number>/comments' --jq 'length'`, resolving `<number>` from `gh pr view --json number`.
-6. When invoked with `reply-owned`, skip this step's comment: the caller posts the reply. Otherwise, if the count is above zero, the followup addresses review feedback: post a one-line summary of the fix with `gh pr comment --body`, first scanning it for em dashes and semicolons and rewriting each since the hook does not see an inline comment body. If it is zero, run `gh pr view --json url,title,body` and update the body with `gh pr edit --body` when the new commit changes scope, and the title with `gh pr edit --title` when the scope shifted enough to make it inaccurate.
+6. When invoked with `reply-owned`, skip this step's comment: the caller posts the reply. Otherwise, if the count is above zero, the followup addresses review feedback: post a one-line summary of the fix with `gh pr comment --body`, first running the banned-character scan in `.claude/standards/prose.md` against it, or `${CLAUDE_SKILL_DIR}/../../standards/prose.md` when the project does not have it, since the hook does not see an inline comment body. If it is zero, run `gh pr view --json url,title,body` and update the body with `gh pr edit --body` when the new commit changes scope, and the title with `gh pr edit --title` when the scope shifted enough to make it inaccurate.
 
 ## After completion
 

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

@@ -40,12 +40,7 @@ After outputting the preview, execute the final command immediately. Claude Code
 
 ### Pre-publish scan
 
-Before running the final command, scan the title and body for banned characters and rewrite each occurrence:
-
-- `—` (em dash): split into two sentences or use a comma
-- `;` (semicolon): split into two sentences
-
-These bans come from `.claude/standards/prose.md`. Reading it is not enough. The scan is an explicit step.
+Before running the final command, run the banned-character scan in `.claude/standards/prose.md` against the title and body. The title and body go straight to the remote with nothing checking them on the way, so this scan is the only gate. It applies on top of the banned phrases in `${CLAUDE_SKILL_DIR}/references/issue.md`.
 
 ### Final command
 

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

@@ -69,12 +69,7 @@ Leave a box unchecked only for the human-only cases the reference defines, and n
 
 ### Pre-publish scan
 
-Before running the final command, scan the PR title and body for banned characters and rewrite each occurrence:
-
-- `—` (em dash): split into two sentences or use a comma
-- `;` (semicolon): split into two sentences
-
-These bans come from `.claude/standards/prose.md` and apply to PR text on top of `${CLAUDE_SKILL_DIR}/references/pr.md`. Reading `prose.md` is not enough. The scan is an explicit step.
+Before running the final command, run the banned-character scan in `.claude/standards/prose.md` against the PR title and body. The title and body go straight to the remote with nothing checking them on the way, so this scan is the only gate. It applies on top of the banned phrases in `${CLAUDE_SKILL_DIR}/references/pr.md`.
 
 ### Final command
 

package/claude/skills/git-split/REQUIREMENT.md

@@ -7,7 +7,7 @@ description: What branch splitting is for, the gaps it closes, and how it differ
 
 ## Gap
 
-Without this skill, a branch carrying unrelated commits ships as one pull request, which a reviewer reads by skimming because no single concern holds it together. Split by hand, commits get cherry-picked in an order that leaves a branch missing something it depends on. Merge order is the sharpest failure: merging the wrong branch first lands every other branch's content on main and leaves the remaining pull requests empty after rebase, with no signal that anything went wrong.
+Without this skill, a branch carrying unrelated commits ships as one pull request, which a reviewer reads by skimming because no single concern holds it together. Split by hand, commits get cherry-picked in an order that leaves a branch missing something it depends on. Merge order is the sharpest failure: merging the wrong branch first lands every other branch's content on main and leaves the remaining pull requests empty after rebase, with no signal that anything went wrong. Every body it writes stages under `.claude/.tmp/` and leaves through `gh`, neither of which the audit hook watches, so a banned character survives into a published pull request and has to be edited on the remote.
 
 ## Must
 
@@ -17,6 +17,7 @@ Without this skill, a branch carrying unrelated commits ships as one pull reques
 - Account for every commit ahead of main in the preview
 - State the merge order and the reason behind it, since the order is not recoverable from reading the pull requests afterward
 - Carry the restack loop for stacked mode, where each branch is rebased onto main once the one below it merges
+- Scan every generated title and body for banned characters as an explicit step before opening a pull request
 
 ## Must not
 

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

@@ -69,6 +69,8 @@ If Mode is Independent, append this line to the preview:
 
 After outputting the preview, execute the final commands immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
 
+Before running them, run the banned-character scan in `.claude/standards/prose.md` against every title and body, or `${CLAUDE_SKILL_DIR}/../../standards/prose.md` when the project does not have it. Each body stages under `.claude/.tmp/` and leaves through `gh`, so the hook sees neither and this scan is the only gate.
+
 ### Final commands
 
 For independent mode, base every branch on `main`:

package/docs/agents.md

@@ -79,6 +79,7 @@ Full help: `aitk <command> --help`.
 | `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 comments scan`     | Measure comment density by language and comment kind, with a trend recomputed from git         |
 
 ### Domain commands
 
@@ -95,6 +96,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `design`    | `render`                                                               |
 | `slides`    | `render`, `list`                                                       |
 | `tasks`     | `archive`                                                              |
+| `comments`  | `scan`                                                                 |
 
 Common patterns:
 
@@ -285,6 +287,30 @@ aitk tasks archive --pull-request 673 --json | jq -r 'if .ok then .task else .re
 
 For the board format, the `Pull request:` line, and the archive rules, see `.claude/standards/tasks.md`.
 
+## Comments
+
+`aitk comments scan [path]` reports comment density for a tree, split by language and by comment kind. It is the only command that parses the target's own source, so its scope stays deliberately narrow: TypeScript and bash, line-oriented, no AST.
+
+```bash
+aitk comments scan
+aitk comments scan src --json
+aitk comments scan --since v0.5.0
+```
+
+| Option               | Behavior                                                        |
+| -------------------- | --------------------------------------------------------------- |
+| `--json`             | Add a machine-readable record on stdout, keeping the frame      |
+| `--since <rev>`      | Report the trend from this revision instead of a snapshot alone |
+| `--languages <list>` | Comma-separated subset of `ts,sh` (default: both)               |
+
+A line counts as a comment when its first non-whitespace token opens one, which is what keeps a URL in a string literal from reading as a `//` comment without a parser. Density is `commentLines / lines`, reported and never graded. The command produces the number and a rule produces the judgment.
+
+Two exclusions are structural rather than tuning. Heredoc bodies are dropped from both the numerator and the denominator, because a scenario script carrying markdown inside one has `#` opening a heading rather than a comment, which inflated a measured 112 comment lines to 427. Fixture trees are pruned by path segment for the same reason. The line-1 shebang is not a comment, since every script has one and counting it puts a floor under density that reports the file count.
+
+`--since` recomputes each point from git via `ls-tree` and `cat-file --batch`, checking nothing out. No ledger is written or read. Six points spread evenly across the window by default, and the boundary revision is always included so the series keeps the reading it is measured against. This works only because density is a pure function of a tree. Which author or session wrote a comment is not recoverable from git and does not belong here.
+
+The degradation sweep reads its vocabulary from whichever rule publishes a `## Degradation vocabulary` heading, preferring `.claude/rules/` over `governance/rules/`, so one definition serves the toolkit and every target. Discovery anchors on the heading rather than a filename, because a renumbered rule would otherwise empty the vocabulary while the sweep still reported clean. With no such rule the sweep reports **skipped** rather than zero hits, since finding nothing and looking for nothing mean opposite things.
+
 ## Runtime catalogs
 
 Use these to discover what's available instead of hardcoding names.

package/docs/ai-workflow.md

@@ -131,7 +131,7 @@ Before the first feature session on a UI-heavy project, pick a design tier. The
 | `aitk:claude-feature`        | Before implementation, scan for conflicts and ambiguities                                                              |
 | `aitk:claude-roadmap`        | Sequence MVP scope into ordered versions in `.claude/ROADMAP.md`                                                       |
 | `aitk:claude-orchestrate`    | Assert the orchestrator role, refill the ready queue, and dispatch the roadmap, feature, and review skills             |
-| `aitk:claude-diagram`        | Draft `.claude/DIAGRAMS.md` with mermaid diagrams from architecture and code, then verify each rendered image          |
+| `aitk:claude-diagram`        | Draft per-kind mermaid entries under `.claude/diagrams/` from architecture and code, then verify each rendered image   |
 | `aitk:claude-design-propose` | Day one on a UI project, draft `.claude/DESIGN.md` from requirements. Use `claude-design-extract` if UI already exists |
 | `aitk:claude-review`         | In a fresh session, review all changes since main                                                                      |
 | `aitk:claude-pr-review`      | Review an open PR from an independent session, then close the review out against the commits added since               |

package/docs/target-projects.md

@@ -57,7 +57,7 @@ Scaffold installs tooling and seeds. It does not fill the planning docs or the d
 
 1. Fill `.claude/REQUIREMENTS.md` and `.claude/ARCHITECTURE.md`. The seed provides the files, the scope and decisions are yours to write.
 2. For a UI project, invoke `aitk:claude-design-propose` to draft `.claude/DESIGN.md` from the requirements and a `## Personality` section. Skip for non-UI projects.
-3. Optionally invoke `aitk:claude-diagram` to draft `.claude/DIAGRAMS.md` from the architecture. It renders each diagram to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds. A machine without a renderer still gets the diagrams and is told which check was skipped.
+3. Optionally invoke `aitk:claude-diagram` to draft entries under `.claude/diagrams/` from the architecture and the requirements. One file per diagram kind, so a later refresh of one kind leaves the others untouched. It renders each diagram it writes to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds. A machine without a renderer still gets the diagrams and is told which check was skipped.
 4. Start the feature loop. See [AI workflow](ai-workflow.md) for the per-feature sequence.
 
 ### Stack decision
@@ -77,7 +77,7 @@ Run `aitk tooling list --json` and `aitk gov list --json` to see the current cat
 `governance`, `standards`, and `wiki` are skippable:
 
 - `--skip governance`: leave `.claude/rules/` empty. Standards still install, so `.claude/standards/prose.md` lands with nothing pointing at it and no coding standard loads on a file match. The preview names any `--add` rules the skip drops, and the run prints the `aitk gov install <stack> <path>` command to add rules afterward, carrying those extras so one paste restores what the skip declined.
-- `--skip standards`: leave standards out. The governance rules still reference `.claude/standards/`, so their authority lines resolve to nothing. Toolkit skills are unaffected, since each falls back to the copy in its own plugin root.
+- `--skip standards`: leave standards out. The governance rules still reference `.claude/standards/`, so their authority lines resolve to nothing. Toolkit skills are unaffected, since each falls back to the copy in its own plugin root. That fallback now carries runtime behavior rather than reference prose alone, because the banned-character scan and the branch-slug transform are defined in the standards and cited by the skills that run them.
 - `--skip wiki`: skip the `.claude/wiki/` scaffold. A target that already carries a root `wiki/` keeps it, since the verb reports that folder rather than migrating it.
 
 ## Add a domain later

package/governance/rules/claude/560-diagrams.md

@@ -1,6 +1,7 @@
 ---
-description: Route .claude/DIAGRAMS.md edits to the diagrams standard for Mermaid conventions
+description: Route .claude/diagrams edits to the diagrams standard for Mermaid conventions
 paths:
+  - '.claude/diagrams/**'
   - '.claude/DIAGRAMS.md'
 ---
 
@@ -8,4 +9,11 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/diagrams.md` for Mermaid diagram layout, labeling, and narrative. It is the single source.
+- Follow `.claude/standards/diagrams.md` for Mermaid diagram layout, budgets, accessibility, verification, and explanation prose. It is the single source.
+- A diagram entry carries structure and flow, not implementation. Read the standard before adding or revising a kind.
+
+## Scope
+
+- Write a new diagram to `.claude/diagrams/<kind>.md`, never to `.claude/DIAGRAMS.md`
+- Convert a `.claude/DIAGRAMS.md` left by an older install into per-kind entries before editing it
+- Refresh only the entries whose source signal moved. Do not rewrite the folder wholesale.

package/governance/rules/claude/570-skill.md

@@ -15,4 +15,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/skill.md` for skill structure, frontmatter fields, and invocation rules. It is the single source.
+- Follow `.claude/standards/skill.md` for skill structure, frontmatter fields, invocation rules, and the shape a `REQUIREMENT.md` states. It is the single source.

package/package.json

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

package/scripts/core/install-check.sh

@@ -75,7 +75,7 @@ log_step "Assert scaffold"
 # no assertion can truncate silently: init still exits 0 because run_domain
 # catches a failed domain, and the gate stays green while the target is
 # missing everything that domain provides.
-for path in "CLAUDE.md" ".claude/snippets/compact-summary.md" ".claude/standards/prose.md" ".claude/wiki/index.md" ".claude" ".claude/context/index.md" ".claude/wireframes/index.md" \
+for path in "CLAUDE.md" ".claude/snippets/compact-summary.md" ".claude/standards/prose.md" ".claude/wiki/index.md" ".claude" ".claude/context/index.md" ".claude/wireframes/index.md" ".claude/diagrams/index.md" \
   ".prettierrc" ".editorconfig" ".lintstagedrc" ".husky/pre-commit" ".github/workflows/verify.yml" "scripts/verify.sh" \
   ".claude/rules/core/000-constitution.md"; do
   if [ ! -e "$TARGET_DIR/$path" ]; then

package/src/claude/seeds.ts

@@ -7,7 +7,13 @@ const SEEDS_DIR = join('tooling', 'claude', 'seeds')
 const CLAUDE_DIR = '.claude'
 const CLAUDE_MD = 'CLAUDE.md'
 const HOOKS = 'hooks'
-const SUBDIRS: readonly string[] = [HOOKS, 'context', 'tasks', 'wireframes']
+const SUBDIRS: readonly string[] = [
+  HOOKS,
+  'context',
+  'diagrams',
+  'tasks',
+  'wireframes',
+]
 
 export type SeedScope = 'claude' | 'root'
 

package/src/cli.ts

@@ -17,6 +17,7 @@ import { register as slides } from '@/commands/slides'
 import { register as feedback } from '@/commands/feedback'
 import { register as transcripts } from '@/commands/transcripts'
 import { register as tasks } from '@/commands/tasks'
+import { register as comments } from '@/commands/comments'
 
 const GREY = '\x1b[0;90m'
 const WHITE = '\x1b[1;37m'
@@ -44,6 +45,7 @@ function showHelp(): void {
     `${GREY}│${NC}    feedback           ${GREY}# Write toolkit feedback from stdin to .claude/review/${NC}`,
     `${GREY}│${NC}    transcripts <url>  ${GREY}# Fetch a YouTube transcript with metadata frontmatter${NC}`,
     `${GREY}│${NC}    tasks [cmd]        ${GREY}# Task board commands (archive)${NC}`,
+    `${GREY}│${NC}    comments [cmd]     ${GREY}# Measure comment density and trend (scan)${NC}`,
     `${GREY}│${NC}`,
     `${GREY}│${NC}  ${WHITE}Sandbox:${NC}`,
     `${GREY}│${NC}    aitk sandbox             ${GREY}# Interactive scenario picker${NC}`,
@@ -73,6 +75,7 @@ function showHelp(): void {
     `${GREY}│${NC}    pbpaste | aitk feedback`,
     `${GREY}│${NC}    aitk transcripts https://youtu.be/VIDEO_ID`,
     `${GREY}│${NC}    aitk tasks archive --pull-request 673 --json`,
+    `${GREY}│${NC}    aitk comments scan src --json`,
     `${GREY}└${NC}`,
   ]
   console.log(lines.join('\n'))
@@ -107,5 +110,6 @@ slides(program)
 feedback(program)
 transcripts(program)
 tasks(program)
+comments(program)
 
 program.parse()

package/src/commands/comments.ts

@@ -0,0 +1,234 @@
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import {
+  density,
+  type Language,
+  LANGUAGES,
+  type LanguageCount,
+  scanTree,
+} from '@/comments/scan'
+import { type TrendPoint, trend } from '@/comments/trend'
+import { loadVocabulary, type Vocabulary } from '@/comments/vocabulary'
+import { intro, logInfo, logStep, logWarn, outro, pipeOutput } from '@/ui'
+
+interface ScanCommandOptions {
+  readonly json?: boolean
+  readonly since?: string
+  readonly languages?: string
+}
+
+const LABELS: Record<Language, string> = {
+  ts: 'TypeScript',
+  sh: 'Bash',
+}
+
+export function register(program: Command): void {
+  const comments = program
+    .command('comments')
+    .description('Measure comment density and trend across a source tree')
+    .helpOption('-h, --help', 'Show this help message')
+
+  comments
+    .command('scan')
+    .description('Report comment density by language and by comment kind')
+    .argument('[path]', 'Tree to scan, defaulting to the current directory')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--since <rev>', 'Report the trend from this revision instead')
+    .option('--languages <list>', 'Comma-separated subset of ts,sh')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the scan completed',
+        '  1  refused, with the reason on stderr',
+        '',
+        'Examples:',
+        '  aitk comments scan',
+        '  aitk comments scan src --json',
+        '  aitk comments scan --since v0.5.0',
+        '',
+      ].join('\n'),
+    )
+    .action(async (path: string | undefined, opts: ScanCommandOptions) => {
+      process.exitCode = await runScan(path, opts)
+    })
+}
+
+function parseLanguages(list: string | undefined): Language[] | string {
+  if (!list) return [...LANGUAGES]
+
+  const requested = list
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+
+  const unknown = requested.filter(
+    (entry) => !LANGUAGES.includes(entry as Language),
+  )
+  if (unknown.length > 0) {
+    return `Unknown language: ${unknown.join(', ')}. Known: ${LANGUAGES.join(', ')}.`
+  }
+
+  return requested as Language[]
+}
+
+async function runScan(
+  path: string | undefined,
+  opts: ScanCommandOptions,
+): Promise<number> {
+  const root = resolve(path ?? process.cwd())
+  const emitJson = opts.json ?? false
+  const languages = parseLanguages(opts.languages)
+
+  intro('aitk comments scan')
+
+  if (typeof languages === 'string') {
+    logStep('Refused')
+    logWarn(languages)
+    outro()
+    return 1
+  }
+
+  const vocabulary = await loadVocabulary(root)
+  const scanOptions = {
+    languages,
+    vocabulary: vocabulary.kind === 'loaded' ? vocabulary.terms : [],
+  }
+
+  const snapshot = await scanTree(root, scanOptions)
+  reportSnapshot(snapshot)
+
+  const points = opts.since
+    ? await trend(root, { ...scanOptions, since: opts.since })
+    : []
+
+  if (opts.since) reportTrend(points, languages)
+
+  reportVocabulary(vocabulary, snapshot)
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        path: root,
+        vocabulary:
+          vocabulary.kind === 'loaded'
+            ? { source: vocabulary.source, terms: vocabulary.terms }
+            : null,
+        snapshot: snapshot.map(record),
+        trend: points.map((point) => ({
+          rev: point.rev,
+          date: point.date,
+          languages: point.languages.map(record),
+        })),
+      })}\n`,
+    )
+  }
+
+  return 0
+}
+
+function record(count: LanguageCount): Record<string, unknown> {
+  return {
+    language: count.language,
+    files: count.files,
+    lines: count.lines,
+    commentLines: count.commentLines,
+    density: Number(density(count).toFixed(4)),
+    docBlocks: count.docBlocks,
+    inlineComments: count.inlineComments,
+    degradationHits: count.degradationHits,
+  }
+}
+
+function percent(count: LanguageCount): string {
+  return `${(density(count) * 100).toFixed(1)}%`
+}
+
+function reportSnapshot(snapshot: readonly LanguageCount[]): void {
+  logStep('Snapshot')
+
+  for (const count of snapshot) {
+    if (count.files === 0) {
+      logInfo(`${LABELS[count.language]}: no files`)
+      continue
+    }
+
+    logInfo(
+      `${LABELS[count.language]}: ${count.commentLines} comment lines in ${count.lines} (${percent(count)}), ${count.files} files`,
+    )
+    logInfo(
+      `  ${count.docBlocks} doc blocks, ${count.inlineComments} inline comments`,
+    )
+  }
+}
+
+function reportTrend(
+  points: readonly TrendPoint[],
+  languages: readonly Language[],
+): void {
+  logStep('Trend')
+
+  if (points.length === 0) {
+    logWarn('No commits in range. Check the revision passed to --since.')
+    return
+  }
+
+  for (const language of languages) {
+    const rows = points
+      .map((point) => {
+        const count = point.languages.find(
+          (entry) => entry.language === language,
+        )
+        if (!count) return undefined
+        return `${point.rev.slice(0, 8)}  ${point.date}  ${String(count.lines).padStart(6)} lines  ${String(count.commentLines).padStart(5)} comments  ${percent(count).padStart(6)}`
+      })
+      .filter((row): row is string => row !== undefined)
+
+    // A language the tree does not carry would otherwise print a column of
+    // zeros, which reads as a measured decline rather than an absence.
+    const measured = points.some((point) =>
+      point.languages.some(
+        (entry) => entry.language === language && entry.files > 0,
+      ),
+    )
+    if (rows.length === 0 || !measured) continue
+
+    logInfo(LABELS[language])
+    pipeOutput(rows.join('\n'))
+  }
+}
+
+/**
+ * Reports the sweep as skipped when no rule publishes a vocabulary.
+ *
+ * Zero hits against an empty vocabulary is indistinguishable from a clean
+ * codebase in the output, and the two mean opposite things, so the absent case
+ * says so rather than printing a count nobody looked for.
+ */
+function reportVocabulary(
+  vocabulary: Vocabulary,
+  snapshot: readonly LanguageCount[],
+): void {
+  logStep('Degradation sweep')
+
+  if (vocabulary.kind === 'absent') {
+    logWarn('Skipped. No rule publishes a "Degradation vocabulary" heading.')
+    return
+  }
+
+  const hits = snapshot.flatMap((count) => count.degradationHits)
+  logInfo(`${vocabulary.terms.length} terms from ${vocabulary.source}`)
+
+  if (hits.length === 0) {
+    logInfo('No hits.')
+    return
+  }
+
+  logWarn(`${hits.length} hits`)
+  pipeOutput(
+    hits.map((hit) => `${hit.file}:${hit.line}  ${hit.term}`).join('\n'),
+  )
+}