@erclx/aitk 3.0.0 → 3.2.0

package/src/audits/catalog.ts

@@ -1,4 +1,6 @@
+import type { ReachRefusal } from '@/claude/skills-reach'
 import type { AuditRefusal } from '@/deps/audit'
+import type { LabelAuditRefusal } from '@/labels/audit'
 import type { ValidateRefusal as RecordRefusal } from '@/records/validate'
 import type { ScanRefusal } from '@/secrets/scan'
 import type { ValidateRefusal as BoardRefusal } from '@/tasks/validate'
@@ -286,6 +288,21 @@ function skillCounts(record: unknown): Record<string, number> | undefined {
   )
 }
 
+/**
+ * Reads the unqualified citations alone, leaving the qualified ones out.
+ *
+ * A qualified citation is a repair that already landed, so folding the two
+ * together would report a corpus getting worse every time one is fixed. The
+ * key is still read rather than assumed present, since a record carrying
+ * neither array is a shape that moved rather than a catalog with nothing in it.
+ */
+function reachCounts(record: unknown): Record<string, number> | undefined {
+  const root = asObject(record)
+  if (root === undefined || !Array.isArray(root.qualified)) return undefined
+
+  return allOf({ unqualifiedCitations: lengthOf(root.unqualified) })
+}
+
 function boardCounts(record: unknown): Record<string, number> | undefined {
   const root = asObject(record)
   if (root === undefined) return undefined
@@ -318,6 +335,27 @@ function advisoryCounts(record: unknown): Record<string, number> | undefined {
   return counts
 }
 
+/**
+ * Reads the uncovered paths alone, which is the half that is a finding.
+ *
+ * The declined paths are deliberately not counted. They are whichever declined
+ * rows this branch happened to touch rather than a measure of the map, so a
+ * clean trunk reads zero while the map declares eight, and the number would
+ * describe the branch rather than the decision.
+ *
+ * Retaining it also broke the verdict. `classify` reads a clean run as quiet
+ * only when every count is zero, so a branch touching one declined path exited
+ * 0 and still reported as carrying findings.
+ */
+function labelCoverageCounts(
+  record: unknown,
+): Record<string, number> | undefined {
+  const root = asObject(record)
+  if (root === undefined) return undefined
+
+  return allOf({ uncovered: lengthOf(root.uncovered) })
+}
+
 function findingsOnly(record: unknown): Record<string, number> | undefined {
   const root = asObject(record)
   if (root === undefined) return undefined
@@ -403,6 +441,26 @@ export const AUDITS: readonly AuditSpec[] = [
     corpus: 'tracked',
     counts: skillCounts,
   },
+  {
+    id: 'skills-reach',
+    label: 'Shipped citation reach',
+    argv: ['claude', 'skills', 'reach', '--json'],
+    // Reports rather than gates, on the split this file already draws. A body
+    // naming a toolkit path is sometimes correct, since the instruction may be
+    // meant for a session in this repository, so the verdict is a judgment and
+    // a push failing on one teaches a contributor to route around the stage.
+    gatingExits: [],
+    corpus: 'tracked',
+    // The one reason this verb refuses for, and it is an absence rather than a
+    // break. A tracked corpus normally allows nothing, since a tree that ships
+    // to targets and cannot be found is a broken checkout, and this is the
+    // second exception on the same test the secret scan takes: no target holds
+    // `claude/skills/`, so without the allowance every project installing this
+    // CLI reports the verb unmeasured on every run and never changes, which is
+    // the permanent signal the per-machine allowance exists against.
+    absentReasons: ['no-skills'] satisfies ReachRefusal[],
+    counts: reachCounts,
+  },
   {
     id: 'tasks',
     label: 'Task board',
@@ -463,6 +521,33 @@ export const AUDITS: readonly AuditSpec[] = [
     ] satisfies ScanRefusal[],
     counts: findingsOnly,
   },
+  {
+    id: 'labels',
+    label: 'Pull request label coverage',
+    argv: ['labels', 'audit', '--json'],
+    // Reports rather than gates, on the split this file already draws. Whether
+    // an uncovered surface deserves a label is a judgment, and a push failing
+    // on one would ask a contributor to answer a question only the person who
+    // owns the surface can.
+    gatingExits: [],
+    // The map is committed, so every clone reads the same rows and a delta is
+    // shared. The changed set the rows are read against is the branch's, which
+    // is what makes a clean trunk report zero rather than nothing.
+    corpus: 'tracked',
+    // Only `uncovered` is retained, for the reason its extractor states.
+    //
+    // The one reason that means this project declares no surfaces to cover,
+    // which is the recorded decision that a project without a map is labelled
+    // silently. A tracked corpus normally allows nothing absent, and this is
+    // the second exception beside the secret scan rather than a default.
+    //
+    // The other three are deliberately left out. A map that will not parse, a
+    // map with no usable row, and a range git could not answer are each a
+    // corpus that exists and went unread, so calling any of them an absence
+    // would report a pass over a branch nobody measured.
+    absentReasons: ['no-map'] satisfies LabelAuditRefusal[],
+    counts: labelCoverageCounts,
+  },
   {
     id: 'deps',
     label: 'Dependency advisories',

package/src/claude/skills-reach.ts

@@ -0,0 +1,193 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * The tree that installs into a target. The internal skills under `.claude/`
+ * never leave this repository, so a citation there is read by a session that
+ * already has the file and cannot be a reach defect.
+ */
+const SHIPPED_SKILLS = join('claude', 'skills')
+
+/**
+ * The authoring roots this repository owns and no install channel delivers.
+ *
+ * Every entry is a folder a target never holds under that spelling. Standards
+ * install nowhere and are reached through the plugin corpus, rules install
+ * under `.claude/rules/`, snippets under `.claude/snippets/`, and the rest are
+ * this repository's own source, docs, and catalogs.
+ *
+ * `src/`, `scripts/`, and bare `docs/` are deliberately absent. A body naming
+ * one of those is describing the reader's own tree, so listing them would
+ * report a correct citation on every run and bury the defect this measures.
+ * `docs/agents/` is the exception, being the CLI contract pages that exist
+ * here alone.
+ */
+const AUTHORING_ROOTS = [
+  '.claude/context/',
+  'claude/',
+  'docs/agents/',
+  'governance/',
+  'internal/',
+  'snippets/',
+  'standards/',
+  'tooling/',
+  'wiki/',
+] as const
+
+/**
+ * What marks a citation as deliberately naming this repository's own copy.
+ *
+ * The word rather than a notation, matching the three bodies that already
+ * spell it and the repair the plan settled on. A parser-visible syntax was the
+ * alternative and it invents a spelling for a handful of lines while leaving
+ * the shipped precedent unreadable.
+ */
+const QUALIFIER = /toolkit/i
+
+/** A backticked token, which is how every body spells a path it cites. */
+const TOKEN = /`([^`\s]+)`/g
+
+/**
+ * A path a reader could open, which is the only kind worth measuring.
+ *
+ * Requires an extension and a separator, and admits no `<`, `$`, or `*`. A
+ * body writes `.claude/context/<domain>.md` to name a shape rather than a
+ * file, and `${CLAUDE_SKILL_DIR}/../../standards/markdown.md` to resolve
+ * against the plugin root, which is self-contained by construction.
+ */
+const CONCRETE = /^[.A-Za-z0-9_][A-Za-z0-9._/-]*\.[a-z]{1,4}$/
+
+export interface Citation {
+  readonly file: string
+  /** One-based, matching the `file:line` form a reader clicks. */
+  readonly line: number
+  readonly path: string
+  readonly qualified: boolean
+}
+
+/** Why a scan produced no corpus, which is never the same as a clean one. */
+export type ReachRefusal = 'no-skills'
+
+export type ReachReport =
+  | {
+      readonly kind: 'measured'
+      /** Files opened, so a report can state what the verdict covers. */
+      readonly bodies: number
+      readonly qualified: readonly Citation[]
+      readonly unqualified: readonly Citation[]
+    }
+  | { readonly kind: 'refused'; readonly reason: ReachRefusal }
+
+export function isQualified(line: string): boolean {
+  return QUALIFIER.test(line)
+}
+
+/**
+ * Every path a seed lands on in a target, spelled the way a body would cite it.
+ *
+ * Read off the seed tree rather than listed, so a seed added to any stack
+ * clears its own citations without this module being edited. Dotfiles are in
+ * scope because the whole seeded context corpus sits under `.claude/`.
+ */
+export function readReceivedPaths(root: string): Set<string> {
+  const toolingRoot = join(root, 'tooling')
+  if (!existsSync(toolingRoot)) return new Set()
+
+  const received = new Set<string>()
+  for (const path of new Bun.Glob('*/seeds/**/*').scanSync({
+    cwd: toolingRoot,
+    onlyFiles: true,
+    dot: true,
+  })) {
+    const posix = path.replaceAll('\\', '/')
+    received.add(posix.replace(/^[^/]+\/seeds\//, ''))
+  }
+  return received
+}
+
+/**
+ * Whether a cited path is this repository's own rather than the reader's.
+ *
+ * A seeded path is disowned twice over: under its own name, and under the
+ * folder spelling it takes once a target splits the entry. A domain that
+ * outgrows one file becomes `<domain>/`, which is still the entry the seed
+ * delivered, so reporting the split form would fail a target for growing.
+ */
+export function isToolkitOwned(path: string, received: Set<string>): boolean {
+  if (received.has(path)) return false
+
+  for (const seeded of received) {
+    const stem = seeded.replace(/\.md$/, '')
+    if (stem !== seeded && path.startsWith(`${stem}/`)) return false
+  }
+
+  return AUTHORING_ROOTS.some((prefix) => path.startsWith(prefix))
+}
+
+/**
+ * Every toolkit-owned path one shipped file cites, with the line's verdict.
+ *
+ * Existence is not checked here. A body may name a path this repository once
+ * held, and separating the shape test from the disk read is what lets the
+ * shape be tested without a tree on disk.
+ */
+export function citationsIn(
+  file: string,
+  text: string,
+  received: Set<string>,
+): Citation[] {
+  const citations: Citation[] = []
+
+  for (const [index, line] of text.split('\n').entries()) {
+    const qualified = isQualified(line)
+
+    for (const match of line.matchAll(TOKEN)) {
+      const path = match[1]
+      if (!CONCRETE.test(path) || !path.includes('/')) continue
+      if (!isToolkitOwned(path, received)) continue
+
+      citations.push({ file, line: index + 1, path, qualified })
+    }
+  }
+
+  return citations
+}
+
+/**
+ * Reads every shipped body for a path its reader cannot open.
+ *
+ * A citation of a path this repository does not hold is dropped rather than
+ * reported. The measure asks whether a claim true here is false in a target,
+ * and a path true in neither is a different defect that `aitk context audit`
+ * already reports against its own corpus.
+ */
+export function scanReach(root: string): ReachReport {
+  const skillsRoot = join(root, SHIPPED_SKILLS)
+  if (!existsSync(skillsRoot)) return { kind: 'refused', reason: 'no-skills' }
+
+  const received = readReceivedPaths(root)
+  const files = [
+    ...new Bun.Glob('**/*.md').scanSync({ cwd: skillsRoot, onlyFiles: true }),
+  ].sort()
+
+  const qualified: Citation[] = []
+  const unqualified: Citation[] = []
+
+  for (const file of files) {
+    const posix = file.replaceAll('\\', '/')
+    const text = readFileSync(join(skillsRoot, file), 'utf8')
+
+    for (const citation of citationsIn(
+      `${SHIPPED_SKILLS.replaceAll('\\', '/')}/${posix}`,
+      text,
+      received,
+    )) {
+      if (!existsSync(join(root, citation.path))) continue
+
+      if (citation.qualified) qualified.push(citation)
+      else unqualified.push(citation)
+    }
+  }
+
+  return { kind: 'measured', bodies: files.length, qualified, unqualified }
+}

package/src/cli.ts

@@ -28,6 +28,7 @@ import { register as sessions } from '@/commands/sessions'
 import { register as audits } from '@/commands/audits'
 import { register as secrets } from '@/commands/secrets'
 import { register as deps } from '@/commands/deps'
+import { register as labels } from '@/commands/labels'
 import { register as upgrade } from '@/commands/upgrade'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
 import { palette } from '@/ui'
@@ -67,6 +68,7 @@ function showHelp(): void {
     `${GREY}│${NC}    sessions [cmd]     ${GREY}# Resolve live sessions to worktree and branch (list)${NC}`,
     `${GREY}│${NC}    secrets [cmd]      ${GREY}# Read the shipped tree for credential-shaped values (scan)${NC}`,
     `${GREY}│${NC}    deps [cmd]         ${GREY}# Read the resolved dependency set for advisories (audit)${NC}`,
+    `${GREY}│${NC}    labels [cmd]       ${GREY}# Read a changed set against the pull request label map (audit)${NC}`,
     `${GREY}│${NC}    audits [cmd]       ${GREY}# Run every health check as one set (run, list)${NC}`,
     `${GREY}│${NC}    upgrade            ${GREY}# Reinstall the CLI globally with the manager that installed it${NC}`,
     `${GREY}│${NC}`,
@@ -110,6 +112,7 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk sessions list --json`,
     `${GREY}│${NC}    aitk secrets scan --json`,
     `${GREY}│${NC}    aitk deps audit --json`,
+    `${GREY}│${NC}    aitk labels audit --json`,
     `${GREY}│${NC}    aitk audits run --json`,
     `${GREY}│${NC}    aitk upgrade --json`,
     `${GREY}└${NC}`,
@@ -156,6 +159,7 @@ records(program)
 sessions(program)
 secrets(program)
 deps(program)
+labels(program)
 audits(program)
 upgrade(program)
 

package/src/commands/claude.ts

@@ -23,6 +23,11 @@ import {
 } from '@/claude/skills-audit'
 import { type DriftReport, readDrift } from '@/claude/skills-drift'
 import { listSkills } from '@/claude/skills-list'
+import {
+  type ReachRefusal,
+  type ReachReport,
+  scanReach,
+} from '@/claude/skills-reach'
 import {
   planSettings,
   readSettings,
@@ -70,6 +75,10 @@ interface SkillsDriftOptions {
   readonly json?: boolean
 }
 
+interface SkillsReachOptions {
+  readonly json?: boolean
+}
+
 const SEEDED_FILES: readonly string[] = [
   'ARCHITECTURE.md',
   'REQUIREMENTS.md',
@@ -160,15 +169,15 @@ export function register(program: Command): void {
 
   const skills = claude
     .command('skills')
-    .description('Plugin skill catalog (list, audit, drift)')
-    .argument('[subcommand]', "One of 'list', 'audit', or 'drift'")
+    .description('Plugin skill catalog (list, audit, drift, reach)')
+    .argument('[subcommand]', "One of 'list', 'audit', 'drift', or 'reach'")
     .helpOption('-h, --help', 'Show this help message')
     .action((subcommand: string | undefined) => {
       intro('aitk claude')
       logError(
         subcommand === undefined
-          ? "Missing subcommand. Use 'list', 'audit', or 'drift'."
-          : `Unknown subcommand: ${subcommand}. Use 'list', 'audit', or 'drift'.`,
+          ? "Missing subcommand. Use 'list', 'audit', 'drift', or 'reach'."
+          : `Unknown subcommand: ${subcommand}. Use 'list', 'audit', 'drift', or 'reach'.`,
       )
       outro()
       process.exitCode = 1
@@ -260,6 +269,42 @@ export function register(program: Command): void {
     .action(async (ref: string, opts: SkillsDriftOptions) => {
       process.exitCode = await runSkillsDrift(ref, opts)
     })
+
+  skills
+    .command('reach')
+    .description('Report shipped bodies citing a path no target receives')
+    .argument('[path]', 'Repository root, defaulting to the current directory')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Scope:',
+        '  Every markdown file under claude/skills/, which is the tree that',
+        '  installs into a target. A cited path counts when it sits under an',
+        '  authoring root no install channel delivers and this repository',
+        '  holds it. A path under src/, scripts/, or bare docs/ names the',
+        "  reader's own tree and is not measured.",
+        '',
+        'Exit codes:',
+        '  0  every citation names the toolkit as the owner',
+        '  1  refused, with the reason on stderr',
+        '  2  at least one citation is unqualified',
+        '',
+        'Reports rather than gates. A toolkit-scoped instruction is sometimes',
+        'meant for a session in this repository, so the verdict is a reading',
+        'and the repair is to name the owner in the sentence.',
+        '',
+        'Examples:',
+        '  aitk claude skills reach',
+        '  aitk claude skills reach --json',
+        '',
+      ].join('\n'),
+    )
+    .action((path: string | undefined, opts: SkillsReachOptions) => {
+      process.exitCode = runSkillsReach(path, opts)
+    })
 }
 
 function succeed(message: string): number {
@@ -567,6 +612,80 @@ function reportSkew(skew: SkewReport): void {
   else logInfo(describeSkew(skew))
 }
 
+/** What a reader does about the one way the corpus fails to build. */
+const REACH_REFUSALS: Record<ReachRefusal, string> = {
+  'no-skills':
+    'No claude/skills/ here, so this tree ships no plugin body to measure.',
+}
+
+/**
+ * Measures the cwd rather than the toolkit root, matching the audit and drift
+ * verbs, so a linked worktree reads its own branch instead of `main`.
+ */
+function runSkillsReach(
+  path: string | undefined,
+  opts: SkillsReachOptions,
+): number {
+  const root = resolve(path ?? process.cwd())
+  const report = scanReach(root)
+
+  if (report.kind === 'refused') {
+    frameError(REACH_REFUSALS[report.reason])
+    if (opts.json) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          reason: report.reason,
+          message: REACH_REFUSALS[report.reason],
+        })}\n`,
+      )
+    }
+    return 1
+  }
+
+  intro('aitk claude skills reach')
+  reportReach(report)
+  outro()
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        bodies: report.bodies,
+        qualified: report.qualified,
+        unqualified: report.unqualified,
+      })}\n`,
+    )
+  }
+
+  return report.unqualified.length === 0 ? 0 : 2
+}
+
+/**
+ * States the corpus on every run, including the clean one. A count of what
+ * failed reads as a verdict on the catalog unless the run also says how many
+ * bodies it opened and how many citations it already accepted.
+ */
+function reportReach(report: Extract<ReachReport, { kind: 'measured' }>): void {
+  logStep('Corpus')
+  logInfo(
+    `${plural(report.bodies, 'shipped file')} read, ${plural(report.qualified.length, 'citation')} already naming the toolkit as owner`,
+  )
+
+  logStep('Unqualified citations')
+  if (report.unqualified.length === 0) {
+    logInfo('Every toolkit-owned path a shipped body cites names its owner.')
+    return
+  }
+
+  logWarn(plural(report.unqualified.length, 'citation'))
+  pipeOutput(
+    report.unqualified
+      .map((citation) => `${citation.file}:${citation.line}  ${citation.path}`)
+      .join('\n'),
+  )
+}
+
 /**
  * States the bound on every run, including the run that names nothing. A report
  * listing only what moved reads as a verdict on what a session holds, and the

package/src/commands/labels.ts

@@ -0,0 +1,166 @@
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import { type LabelAuditRefusal, auditLabels } from '@/labels/audit'
+import { MAP_REL } from '@/labels/map'
+import { intro, logInfo, logStep, logWarn, outro, plural } from '@/ui'
+
+interface AuditOptions {
+  readonly base?: string
+  readonly root?: string
+  readonly json?: boolean
+}
+
+/** What a reader does about each way the audit produced no reading. */
+const REFUSALS: Record<LabelAuditRefusal, string> = {
+  // An answer rather than a fault. A project declaring no map is labelled
+  // silently by design, so a refusal reading as a break would make the map
+  // mandatory for every target.
+  'no-map': `No ${MAP_REL} here, so this project labels nothing and declares no surfaces to cover.`,
+  'unreadable-map': `${MAP_REL} is not valid TOML, so no row could be read.`,
+  'no-domains': `${MAP_REL} carries no usable row under [domains], so every path would read as uncovered.`,
+  'no-base': 'No base resolves against the trunk. Fetch origin or pass --base.',
+  'bad-base':
+    'The ref passed to --base resolves to no commit here. Pass one this tree carries.',
+  'unreadable-changes':
+    'git could not list what this branch changed, so the set is unknown.',
+}
+
+export function register(program: Command): void {
+  const labels = program
+    .command('labels')
+    .description('Resolve a changed set against the pull request label map')
+    .helpOption('-h, --help', 'Show this help message')
+
+  labels
+    .command('audit')
+    .description(
+      'Report the labels a changed set earns and the paths no row reaches',
+    )
+    .argument(
+      '[paths...]',
+      'Changed set to read, defaulting to the branch range',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--base <ref>', 'Far side of the range, defaulting to the trunk')
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        `Reads ${MAP_REL} and matches it prefix-anchored, which is the rule the`,
+        "map's own census was measured against. It reports and never gates,",
+        'because whether an uncovered surface deserves a label is a judgment.',
+        '',
+        'What it separates:',
+        '  uncovered  a surface no row reaches, which is a gap wanting a row',
+        '  declined   a path a [declined] row names, which is a decision already taken',
+        '',
+        'What it does not measure:',
+        '  a prefix reaching no path, which is the map going stale from the other',
+        '  side and a second measure rather than this one',
+        '',
+        'Exit codes:',
+        '  0  every changed path is labelled or declined',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  at least one changed path is reached by no row',
+        '',
+        'Examples:',
+        '  aitk labels audit',
+        '  aitk labels audit --json',
+        '  aitk labels audit --base origin/main',
+        '  aitk labels audit src/cli.ts docs/index.md --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (paths: string[], opts: AuditOptions) => {
+      process.exitCode = await runAudit(paths, opts)
+    })
+}
+
+async function runAudit(paths: string[], opts: AuditOptions): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  const report = await auditLabels(root, {
+    base: opts.base,
+    ...(paths.length > 0 && { paths }),
+  })
+
+  intro('aitk labels audit')
+
+  // The frame renders on stderr in both modes and the record goes to stdout
+  // alone, so an operator reading the terminal sees the refusal rather than a
+  // command that appeared to do nothing.
+  if (report.kind === 'refused') {
+    logStep('Refused')
+    logWarn(REFUSALS[report.reason])
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          reason: report.reason,
+          message: REFUSALS[report.reason],
+        })}\n`,
+      )
+    }
+    return 1
+  }
+
+  const { coverage } = report
+
+  logStep('Scope')
+  logInfo(
+    report.base === undefined
+      ? `${plural(report.changed.length, 'path')} supplied by the caller`
+      : `${plural(report.changed.length, 'path')} changed since ${report.base.slice(0, 8)}`,
+  )
+
+  logStep('Labels')
+  logInfo(
+    coverage.labels.length === 0
+      ? 'this set earns no label'
+      : coverage.labels.join(', '),
+  )
+
+  // Named rather than counted into the uncovered line. A path somebody decided
+  // against wants nothing done, and folding it in would ask for a row that was
+  // already refused.
+  logStep('Declined')
+  if (coverage.declined.length === 0) {
+    logInfo('no changed path is deliberately unlabelled')
+  } else {
+    for (const entry of coverage.declined) {
+      logInfo(`${entry.path}: ${entry.reason}`)
+    }
+  }
+
+  logStep(coverage.uncovered.length === 0 ? 'Covered' : 'Uncovered')
+  if (coverage.uncovered.length === 0) {
+    logInfo('every changed path is reached by a row')
+  } else {
+    logWarn(
+      `${plural(coverage.uncovered.length, 'path')} reached by no row. Give each a prefix on the row that owns its subject, or a [declined] row with the reason it earns none.`,
+    )
+    for (const path of coverage.uncovered) logWarn(path)
+  }
+
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        ...(report.base !== undefined && { base: report.base }),
+        changed: report.changed,
+        labels: coverage.labels,
+        declined: coverage.declined,
+        uncovered: coverage.uncovered,
+      })}\n`,
+    )
+  }
+
+  return coverage.uncovered.length === 0 ? 0 : 2
+}

package/src/commands/sync.ts

@@ -162,6 +162,19 @@ function renderCheck(report: CheckReport): void {
     for (const name of report.newSkills) logInfo(name)
   }
 
+  // Warned where `newSkills` is noted, because a new skill loads live and needs
+  // nothing run while a rule reaches the target only when someone installs it.
+  // No sync closes any of this, so the remedy names the install command.
+  if (report.newRules.length > 0) {
+    logStep('New rules, never installed')
+    for (const name of report.newRules) logWarn(name)
+    // Names the stack as the reader's to supply, since no target records one
+    // and `--add` layers onto a resolved stack rather than standing in for it.
+    logInfo(
+      'Run `aitk gov install <stack>`, naming the stack yourself since no target records it. Add `--add <rule>` to take one.',
+    )
+  }
+
   renderUnclaimed(report)
   renderMigrations(report)