@erclx/aitk 3.7.0 → 3.9.0

package/src/audits/catalog.ts

@@ -1,5 +1,6 @@
 import type { ReachRefusal } from '@/claude/skills-reach'
 import type { AuditRefusal } from '@/deps/audit'
+import type { RestatedRefusal } from '@/gov/restated'
 import type { LabelAuditRefusal } from '@/labels/audit'
 import type { ValidateRefusal as RecordRefusal } from '@/records/validate'
 import type { ScanRefusal } from '@/secrets/scan'
@@ -356,6 +357,33 @@ function labelCoverageCounts(
   return allOf({ uncovered: lengthOf(root.uncovered) })
 }
 
+/**
+ * Reads the two classes that are findings, leaving the declared mirrors out.
+ *
+ * A mirror is an authoring root and its consumed copy, which duplicate on
+ * purpose, so folding them in would report a corpus getting worse every time a
+ * seed is kept in step with the file it is authored from. Same reasoning the
+ * label audit drops its declined rows on.
+ *
+ * The reach count is left out for a different reason. It counts how many
+ * surfaces an instruction reached rather than whether anything is wrong, and it
+ * moves in lockstep with the two retained here, so a baseline carrying it would
+ * report one movement twice.
+ */
+function restatedCounts(record: unknown): Record<string, number> | undefined {
+  const counts = asObject(asObject(record)?.counts)
+  if (counts === undefined) return undefined
+
+  return allOf({
+    contradictions:
+      typeof counts.contradictions === 'number'
+        ? counts.contradictions
+        : undefined,
+    repetitions:
+      typeof counts.repetitions === 'number' ? counts.repetitions : undefined,
+  })
+}
+
 function findingsOnly(record: unknown): Record<string, number> | undefined {
   const root = asObject(record)
   if (root === undefined) return undefined
@@ -548,6 +576,27 @@ export const AUDITS: readonly AuditSpec[] = [
     absentReasons: ['no-map'] satisfies LabelAuditRefusal[],
     counts: labelCoverageCounts,
   },
+  {
+    id: 'restated',
+    label: 'Restated instructions',
+    argv: ['gov', 'restated', '--json'],
+    // Reports rather than gates, on the split this file already draws. Whether
+    // a rule stated on two surfaces should be stated on one is a judgment the
+    // person owning the surface takes, and most restatements here are correct,
+    // so a push failing on one would fail on the ordinary case.
+    gatingExits: [],
+    corpus: 'tracked',
+    // Both reasons the sweep refuses for, and each is an absence rather than a
+    // break. A target holds neither the seed nor a shipped skills tree, 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. Same shape as the reach verb.
+    absentReasons: [
+      'no-instructions',
+      'no-surfaces',
+    ] satisfies RestatedRefusal[],
+    counts: restatedCounts,
+  },
   {
     id: 'deps',
     label: 'Dependency advisories',

package/src/claude/routing.ts

@@ -0,0 +1,283 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const CLAUDE_MD = 'CLAUDE.md'
+const RULES_DIR = join('.claude', 'rules')
+
+/** A backticked token, which is how the always-loaded file spells a path. */
+const TOKEN = /`([^`\s]+)`/g
+
+/**
+ * A path a reader could open. Admits no `$`, `*`, or `=`, so an assignment
+ * (`AITK_NON_INTERACTIVE=1`) and a variable are both excluded.
+ */
+const PATH_TOKEN = /^[.A-Za-z0-9_][A-Za-z0-9._/-]*$/
+
+/** A placeholder segment, which a shape carries and a real path does not. */
+const SHAPE = /<[^>]*>/
+
+/** An alphabetic extension, which separates `cspell.json` from `3.6.0`. */
+const EXTENSION = /\.[a-z]{2,5}$/
+
+/** Extensions a folder is probed with, so a glob narrowed by type still hits. */
+const PROBES = ['probe.md', 'probe.ts', 'probe.tsx', 'probe.sh', 'probe.json']
+
+export interface RuleGlobs {
+  /** Path under `.claude/rules/`, which is how a reader cites a rule. */
+  readonly rule: string
+  readonly globs: readonly string[]
+}
+
+export interface Section {
+  /** `Behavior` for an H2, `Behavior / Scope` for the H3 beneath it. */
+  readonly heading: string
+  /** The top-level bullet lines the heading owns, in reading order. */
+  readonly lines: readonly string[]
+}
+
+export interface SectionReport {
+  readonly heading: string
+  readonly bullets: number
+  /** Bullets naming at least one path, which is the reading this measures. */
+  readonly pathScoped: number
+  /** Path-scoped bullets whose named path some rule glob already reaches. */
+  readonly covered: number
+  /** Distinct named paths no rule glob reaches, in reading order. */
+  readonly uncovered: readonly string[]
+}
+
+/** Why a scan produced no reading, which is never the same as a clean one. */
+export type RoutingRefusal = 'no-claude-md' | 'no-rules'
+
+export type RoutingReport =
+  | {
+      readonly kind: 'measured'
+      readonly rules: number
+      readonly sections: readonly SectionReport[]
+    }
+  | { readonly kind: 'refused'; readonly reason: RoutingRefusal }
+
+/**
+ * Every distinct path one bullet names, in reading order.
+ *
+ * Naming a path is what this measures, not firing only on it. A bullet can
+ * name a folder and still apply every session, and one can fire on a path it
+ * never spells, so the count is a reading a person still has to judge.
+ */
+export function namedPaths(line: string): string[] {
+  const paths: string[] = []
+
+  for (const match of line.matchAll(TOKEN)) {
+    const token = concretePrefix(match[1])
+    if (token === undefined) continue
+    if (!PATH_TOKEN.test(token)) continue
+    if (!token.includes('/') && !EXTENSION.test(token)) continue
+    if (!paths.includes(token)) paths.push(token)
+  }
+
+  return paths
+}
+
+/**
+ * The openable part of a token, which for a shape is the folder above the
+ * placeholder.
+ *
+ * `.claude/context/<domain>.md` names `.claude/context/` and nothing narrower,
+ * so dropping the whole token would report the section that carries it as
+ * naming no path at all. A token whose placeholder sits in the first segment
+ * has no openable prefix and is dropped.
+ */
+function concretePrefix(token: string): string | undefined {
+  if (!SHAPE.test(token)) return token
+
+  const prefix = token.slice(0, token.indexOf('<'))
+  return prefix.endsWith('/') ? prefix : undefined
+}
+
+/**
+ * Splits the file into the sections a reader sees, counting top-level bullets.
+ *
+ * A nested bullet belongs to the one above it rather than to the section, and
+ * a fenced block holds example text rather than instruction, so neither is
+ * counted. A heading carrying no bullet is dropped, since the report answers
+ * how many bullets are path-scoped and a section with none answers nothing.
+ */
+export function splitSections(text: string): Section[] {
+  const sections: Section[] = []
+  let parent = ''
+  let heading: string | undefined
+  let lines: string[] = []
+  let fenced = false
+
+  const flush = (): void => {
+    if (heading !== undefined && lines.length > 0)
+      sections.push({ heading, lines })
+  }
+
+  const open = (next: string): void => {
+    flush()
+    heading = next
+    lines = []
+  }
+
+  for (const line of text.split('\n')) {
+    if (line.startsWith('```')) {
+      fenced = !fenced
+      continue
+    }
+    if (fenced) continue
+
+    const h2 = line.match(/^## (.+)$/)
+    if (h2) {
+      parent = h2[1]
+      open(parent)
+      continue
+    }
+
+    const h3 = line.match(/^### (.+)$/)
+    if (h3) {
+      open(parent === '' ? h3[1] : `${parent} / ${h3[1]}`)
+      continue
+    }
+
+    if (line.startsWith('- ')) lines.push(line)
+  }
+
+  flush()
+  return sections
+}
+
+/**
+ * Every path-scoped rule the tree installs, with the globs it declares.
+ *
+ * An always-on rule declares no `paths` and applies at the same priority as
+ * the always-loaded file, so it covers no path in particular and is skipped.
+ */
+export function readRuleGlobs(root: string): RuleGlobs[] {
+  const rulesRoot = join(root, RULES_DIR)
+  if (!existsSync(rulesRoot)) return []
+
+  const rules: RuleGlobs[] = []
+  const files = [
+    ...new Bun.Glob('**/*.md').scanSync({ cwd: rulesRoot, onlyFiles: true }),
+  ].sort()
+
+  for (const file of files) {
+    const text = readFileSync(join(rulesRoot, file), 'utf8')
+    const globs = [...frontmatter(text).matchAll(/^\s*-\s*'([^']+)'\s*$/gm)]
+      .map((match) => match[1])
+      .filter((glob) => glob.includes('*') || glob.includes('.'))
+
+    if (globs.length === 0) continue
+    rules.push({ rule: file.replaceAll('\\', '/'), globs })
+  }
+
+  return rules
+}
+
+/**
+ * The block between the opening and closing `---`, or nothing for a rule
+ * carrying no frontmatter.
+ *
+ * Bounding the read is what keeps a body bullet out of the glob list. A rule
+ * quoting a path in prose would otherwise register it as a scope the rule
+ * never declared, and the resulting coverage would be wrong with nothing
+ * reporting it.
+ */
+function frontmatter(text: string): string {
+  if (!text.startsWith('---\n')) return ''
+
+  const end = text.indexOf('\n---', 3)
+  return end === -1 ? '' : text.slice(4, end)
+}
+
+/**
+ * Whether a glob scopes itself to a location rather than to a file type.
+ *
+ * A glob opening `**` reaches every folder in the tree, so it answers that a
+ * file type is governed and never that a named path is. Counting one would
+ * report every markdown path covered by `501-markdown` and leave the column
+ * saying nothing a reader could act on.
+ */
+function isAnchored(glob: string): boolean {
+  return !glob.startsWith('**/')
+}
+
+/**
+ * The first rule scoping itself to a named path, or undefined for none.
+ *
+ * A folder is probed with a handful of extensions rather than matched as a
+ * literal, because a glob narrowed by file type reaches under the folder
+ * without ever matching the folder's own name.
+ */
+export function coveringRule(
+  path: string,
+  rules: readonly RuleGlobs[],
+): string | undefined {
+  const bare = path.replace(/\/+$/, '')
+  const candidates = [bare, ...PROBES.map((probe) => `${bare}/${probe}`)]
+
+  for (const { rule, globs } of rules) {
+    for (const glob of globs) {
+      if (!isAnchored(glob)) continue
+      const matcher = new Bun.Glob(glob)
+      if (candidates.some((candidate) => matcher.match(candidate))) return rule
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Reads the always-loaded file against the rules installed beside it.
+ *
+ * Measures the tree it is pointed at rather than the toolkit root, so a linked
+ * worktree reads its own branch and a target reads its own file.
+ */
+export function scanRouting(root: string): RoutingReport {
+  const file = join(root, CLAUDE_MD)
+  if (!existsSync(file)) return { kind: 'refused', reason: 'no-claude-md' }
+
+  const rules = readRuleGlobs(root)
+  if (rules.length === 0) return { kind: 'refused', reason: 'no-rules' }
+
+  const sections = splitSections(readFileSync(file, 'utf8')).map((section) =>
+    classify(section, rules),
+  )
+
+  return { kind: 'measured', rules: rules.length, sections }
+}
+
+/** Counts one section's bullets against the rules installed beside the file. */
+function classify(
+  section: Section,
+  rules: readonly RuleGlobs[],
+): SectionReport {
+  let pathScoped = 0
+  let covered = 0
+  const uncovered: string[] = []
+
+  for (const line of section.lines) {
+    const paths = namedPaths(line)
+    if (paths.length === 0) continue
+    pathScoped += 1
+
+    const reached = paths.filter(
+      (path) => coveringRule(path, rules) !== undefined,
+    )
+    if (reached.length > 0) covered += 1
+
+    for (const path of paths) {
+      if (reached.includes(path) || uncovered.includes(path)) continue
+      uncovered.push(path)
+    }
+  }
+
+  return {
+    heading: section.heading,
+    bullets: section.lines.length,
+    pathScoped,
+    covered,
+    uncovered,
+  }
+}

package/src/cli.ts

@@ -85,6 +85,7 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk sandbox git:commit`,
     `${GREY}│${NC}    aitk gov install react`,
     `${GREY}│${NC}    aitk gov sync ../my-app`,
+    `${GREY}│${NC}    aitk gov restated --json`,
     `${GREY}│${NC}    aitk standards markdown`,
     `${GREY}│${NC}    aitk snippets install base ../my-app`,
     `${GREY}│${NC}    aitk snippets sync ../my-app`,

package/src/commands/claude.ts

@@ -21,6 +21,11 @@ import {
   type SkillFinding,
   type SkillsAudit,
 } from '@/claude/skills-audit'
+import {
+  type RoutingRefusal,
+  type RoutingReport,
+  scanRouting,
+} from '@/claude/routing'
 import { type DriftReport, readDrift } from '@/claude/skills-drift'
 import { listSkills } from '@/claude/skills-list'
 import {
@@ -79,6 +84,10 @@ interface SkillsReachOptions {
   readonly json?: boolean
 }
 
+interface RoutingOptions {
+  readonly json?: boolean
+}
+
 const SEEDED_FILES: readonly string[] = [
   'ARCHITECTURE.md',
   'REQUIREMENTS.md',
@@ -91,7 +100,7 @@ const STATUSLINE = 'statusline-command.sh'
 export function register(program: Command): void {
   const claude = program
     .command('claude')
-    .description('Claude workflow (init, seeds, sync, setup)')
+    .description('Claude workflow (init, seeds, sync, setup, routing)')
     .helpOption('-h, --help', 'Show this help message')
     .addHelpText(
       'after',
@@ -167,6 +176,42 @@ export function register(program: Command): void {
       process.exitCode = await runSeedsList(opts)
     })
 
+  claude
+    .command('routing')
+    .description('Report per CLAUDE.md section how many bullets name a path')
+    .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 H2 and H3 in CLAUDE.md that owns at least one top-level',
+        '  bullet, counted against the path-scoped rules under .claude/rules/.',
+        '  A bullet is path-scoped here when it names a path, which is not the',
+        "  same as firing only on one. A rule's glob covers a named folder",
+        '  only when the glob is anchored to a location rather than to a file',
+        '  type, so **/*.md covers README.md and no folder at all.',
+        '',
+        'Exit codes:',
+        '  0  the file was read',
+        '  1  refused, with the reason on stderr',
+        '',
+        'Reports rather than gates. Whether a bullet belongs in a rule is the',
+        'judgment 592-claude-md states, and naming a path is evidence for it',
+        'rather than the answer.',
+        '',
+        'Examples:',
+        '  aitk claude routing',
+        '  aitk claude routing --json',
+        '',
+      ].join('\n'),
+    )
+    .action((path: string | undefined, opts: RoutingOptions) => {
+      process.exitCode = runRouting(path, opts)
+    })
+
   const skills = claude
     .command('skills')
     .description('Plugin skill catalog (list, audit, drift, reach)')
@@ -612,6 +657,90 @@ function reportSkew(skew: SkewReport): void {
   else logInfo(describeSkew(skew))
 }
 
+/** What a reader does about each way the reading cannot be taken. */
+const ROUTING_REFUSALS: Record<RoutingRefusal, string> = {
+  'no-claude-md': 'No CLAUDE.md here, so this tree has no always-loaded file.',
+  'no-rules':
+    'No path-scoped rules under .claude/rules/, so nothing covers a path yet.',
+}
+
+/**
+ * Measures the cwd rather than the toolkit root, matching the reach and drift
+ * verbs, so a linked worktree reads its own branch instead of `main`.
+ */
+function runRouting(path: string | undefined, opts: RoutingOptions): number {
+  const root = resolve(path ?? process.cwd())
+  const report = scanRouting(root)
+
+  if (report.kind === 'refused') {
+    frameError(ROUTING_REFUSALS[report.reason])
+    if (opts.json) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          reason: report.reason,
+          message: ROUTING_REFUSALS[report.reason],
+        })}\n`,
+      )
+    }
+    return 1
+  }
+
+  intro('aitk claude routing')
+  reportRouting(report)
+  outro()
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        rules: report.rules,
+        sections: report.sections,
+      })}\n`,
+    )
+  }
+
+  return 0
+}
+
+/**
+ * States the corpus on every run, so a section naming no path reads as
+ * measured rather than as skipped. A reader deciding what to cut needs the
+ * sections that stay as much as the ones that move.
+ */
+function reportRouting(
+  report: Extract<RoutingReport, { kind: 'measured' }>,
+): void {
+  const bullets = report.sections.reduce(
+    (total, section) => total + section.bullets,
+    0,
+  )
+  const pathScoped = report.sections.reduce(
+    (total, section) => total + section.pathScoped,
+    0,
+  )
+
+  logStep('Corpus')
+  logInfo(
+    `${plural(report.sections.length, 'section')} carrying ${plural(bullets, 'bullet')}, read against ${plural(report.rules, 'path-scoped rule')}`,
+  )
+
+  logStep('Sections')
+  logInfo(`${pathScoped} of ${bullets} bullets name a path`)
+  pipeOutput(
+    report.sections
+      .map(
+        (section) =>
+          `${section.pathScoped}/${section.bullets} path-scoped, ${section.covered} covered  ${section.heading}${
+            section.uncovered.length === 0
+              ? ''
+              : `  [uncovered: ${section.uncovered.join(', ')}]`
+          }`,
+      )
+      .join('\n'),
+  )
+}
+
 /** What a reader does about the one way the corpus fails to build. */
 const REACH_REFUSALS: Record<ReachRefusal, string> = {
   'no-skills':

package/src/commands/gov.ts

@@ -14,6 +14,15 @@ import {
   mergeExtraRules,
   resolveRules,
 } from '@/gov/stacks'
+import {
+  INSTRUCTIONS_REL,
+  type RestatedEntry,
+  type RestatedRefusal,
+  type RestatedReport,
+  readRestated,
+  SEED_REL,
+  SHIPPED_SKILLS_REL,
+} from '@/gov/restated'
 import {
   readSuperseded,
   SUPERSEDED_MARKER,
@@ -68,6 +77,17 @@ interface SupersededOptions {
   readonly json?: boolean
 }
 
+interface RestatedOptions {
+  readonly root?: string
+  readonly json?: boolean
+}
+
+/** What a reader does about each way the sweep produced no reading. */
+const RESTATED_REFUSALS: Record<RestatedRefusal, string> = {
+  'no-instructions': `No ${INSTRUCTIONS_REL} here, or it carries no bullet, so there is no instruction corpus to sweep.`,
+  'no-surfaces': `Neither ${SEED_REL} nor ${SHIPPED_SKILLS_REL}/ is here, so no second surface exists to match against.`,
+}
+
 export function register(program: Command): void {
   const gov = program
     .command('gov')
@@ -245,6 +265,146 @@ export function register(program: Command): void {
         process.exitCode = await runSuperseded(superseded, replacement, opts)
       },
     )
+
+  gov
+    .command('restated')
+    .description(
+      'Report every instruction the always-loaded file states that a second surface states too',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Tree to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        `Matches every bullet in ${INSTRUCTIONS_REL} against ${SEED_REL}`,
+        `and every ${SHIPPED_SKILLS_REL}/*/SKILL.md body. Matching is recall-first,`,
+        'keyed on distinctive tokens two statements share rather than on a phrase',
+        'they spell the same way, because the case this exists for was one rule',
+        'written three different ways.',
+        '',
+        'What it separates:',
+        '  mirror         a declared authoring-to-consumed pair, where repeating is the design',
+        '  repetition     two surfaces state one rule and neither is declared a copy',
+        '  contradiction  the prohibition falls on one surface alone, on a strong match',
+        '',
+        'The contradiction class is a polarity reading rather than a judgment',
+        'about meaning, so weigh each against the surfaces it names.',
+        '',
+        'What it does not measure:',
+        '  a rule stated in two skill bodies and never in the always-loaded file,',
+        '  since the bullets there are the subjects and the bodies are searched',
+        '',
+        'Exit codes:',
+        '  0  no instruction is restated outside a declared mirror',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  at least one instruction is restated outside a declared mirror',
+        '',
+        'Examples:',
+        '  aitk gov restated',
+        '  aitk gov restated --json',
+        '',
+      ].join('\n'),
+    )
+    .action((opts: RestatedOptions) => {
+      process.exitCode = runRestated(opts)
+    })
+}
+
+/**
+ * Reports and never gates, matching the two sweeps above. A restatement is
+ * legitimate more often than not, so failing a push on one would fail on the
+ * ordinary case and teach contributors to route around the stage.
+ */
+function runRestated(opts: RestatedOptions): number {
+  const root = resolve(opts.root ?? process.cwd())
+  const report = readRestated(root)
+  const emitJson = opts.json ?? false
+
+  if (report.kind === 'unreadable') {
+    intro('aitk gov restated')
+    logStep('Refused')
+    logWarn(RESTATED_REFUSALS[report.reason])
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          reason: report.reason,
+          message: RESTATED_REFUSALS[report.reason],
+        })}\n`,
+      )
+    }
+
+    return 1
+  }
+
+  reportRestated(report, root)
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ root, ...report })}\n`)
+  }
+
+  const findings = report.counts.contradictions + report.counts.repetitions
+  return findings > 0 ? 2 : 0
+}
+
+function describeEntry(entry: RestatedEntry): string[] {
+  const lines = [`${entry.subject.file}:${entry.subject.line}`]
+
+  for (const surface of entry.surfaces) {
+    lines.push(
+      `  [${surface.restatement}] ${surface.file}:${surface.line} via ${surface.anchors.join(', ')}`,
+    )
+  }
+
+  return lines
+}
+
+function reportRestated(
+  report: Extract<RestatedReport, { kind: 'measured' }>,
+  root: string,
+): void {
+  intro('aitk gov restated')
+
+  // A count of what matched reads as a verdict on the repository unless the run
+  // also says how wide the corpus behind it was.
+  logStep('Corpus')
+  logInfo(
+    `${report.corpus.instructions} instruction(s) against ${report.corpus.candidates} statement(s) from the seed and ${report.corpus.bodies} shipped body/bodies in ${root}`,
+  )
+  logInfo(
+    `matched on ${report.matcher.anchors} weighted anchor(s), dropping any token in more than ${report.matcher.common} statements`,
+  )
+
+  // Named rather than counted. A polarity split is the only class claiming a
+  // defect, and a reader weighing one has to reach both surfaces.
+  logStep(
+    report.counts.contradictions === 0 ? 'No contradiction' : 'Contradictions',
+  )
+  if (report.counts.contradictions === 0) {
+    logInfo('no restatement puts a prohibition on one surface alone')
+  } else {
+    for (const entry of report.restatements) {
+      const carries = entry.surfaces.some(
+        (surface) => surface.restatement === 'contradiction',
+      )
+      if (!carries) continue
+      for (const line of describeEntry(entry)) logWarn(line)
+    }
+  }
+
+  logStep('Restated')
+  logInfo(
+    `${report.counts.repetitions} repetition(s) outside a declared mirror, and ${report.counts.mirrors} on one`,
+  )
+  logInfo(
+    `${report.counts.threeSurface} instruction(s) reach three surfaces or more`,
+  )
+
+  outro()
 }
 
 /**