@erclx/aitk 0.101.0 → 0.103.0

package/src/commands/markdown.ts

@@ -1,14 +1,19 @@
 import { readFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
-import { type BanReport, banReport, loadStandards } from '@/markdown/bans'
+import { BAN_SETS, emptyBanSets } from '@/markdown/bans'
 import { resolveMarkdown } from '@/markdown/files'
 import { isGating } from '@/markdown/gate'
-import { type BanFinding, bodyLines, scanBans } from '@/markdown/scan'
 import {
+  type BanFinding,
+  type BanSets,
+  bodyLines,
+  scanBans,
+} from '@/markdown/scan'
+import {
+  CHECKPOINTS,
   type Checkpoints,
   measureStructure,
-  parseCheckpoints,
   type StructureReport,
 } from '@/markdown/structure'
 import {
@@ -21,8 +26,19 @@ import {
   plural,
 } from '@/ui'
 
+const EXIT_REFUSED = 1
 const EXIT_GATE = 2
 
+/**
+ * A set shipped empty, so the run measured a corpus against nothing.
+ *
+ * Distinct from `EXIT_REFUSED` because the two want different responses. A
+ * refusal means no corpus was built and a push stage is right to skip, while an
+ * empty set means the corpus was walked and nothing was looked for, which is a
+ * defect in the build and has to fail.
+ */
+const EXIT_UNUSABLE = 3
+
 interface AuditCommandOptions {
   readonly json?: boolean
 }
@@ -58,6 +74,7 @@ export function register(program: Command): void {
         '  0  the audit completed with no gating finding',
         '  1  refused, with the reason on stderr',
         '  2  a banned character, word, or spelling is present',
+        '  3  a shipped ban set is empty, so the run measured nothing',
         '',
         'A ban hit is a fact and gates unconditionally. Bullet, paragraph, and',
         'depth weight are judgments a reader settles, so all three report and',
@@ -68,12 +85,11 @@ export function register(program: Command): void {
         'where the token is genuinely an identifier under discussion, which is',
         'what markdown.md reserves the span for.',
         '',
-        'Bans and checkpoints are read from markdown.md and prose.md, resolved',
-        'under .claude/standards/, then standards/, then the corpus inside the',
-        'aitk package, so a project that installed neither is still measured.',
-        'The report names the copy it read. No folder has to resolve and no',
-        'index.md has to exist, so .claude/rules/, governance/, and snippets/',
-        'are in reach.',
+        'Bans and checkpoints ship with the aitk package rather than being read',
+        'out of a standards file, so a project that installed no standards is',
+        'measured the same as one that did. markdown.md and prose.md still state',
+        'every rule for a reader. No folder has to resolve and no index.md has',
+        'to exist, so .claude/rules/, governance/, and snippets/ are in reach.',
         '',
         'Examples:',
         '  aitk markdown audit',
@@ -110,9 +126,9 @@ async function runAudit(
     )
   }
 
-  const standards = await loadStandards(root)
-  const bans = banReport(standards)
-  const checkpoints = parseCheckpoints(standards.markdown?.text ?? '')
+  const bans = BAN_SETS
+  const empty = emptyBanSets(bans)
+  const checkpoints = CHECKPOINTS
 
   const reports: FileReport[] = await Promise.all(
     scope.files.map(async (rel) => {
@@ -127,7 +143,7 @@ async function runAudit(
 
   intro('aitk markdown audit')
   reportScope(scope.files, scope.unmatched)
-  reportBans(reports, bans)
+  reportBans(reports, bans, empty)
   reportBullets(reports, checkpoints)
   reportParagraphs(reports, checkpoints)
   reportDepth(reports, checkpoints)
@@ -143,8 +159,7 @@ async function runAudit(
           characters: bans.characters,
           words: bans.words,
           spellings: bans.spellings,
-          sources: bans.sources,
-          missingStandards: bans.missing,
+          emptySets: empty,
         },
         checkpoints: {
           run: checkpoints.run,
@@ -153,7 +168,6 @@ async function runAudit(
           paragraph: checkpoints.paragraph,
           sentences: checkpoints.sentences,
           renderWidth: checkpoints.renderWidth,
-          fellBack: checkpoints.fellBack,
         },
         entries: reports.map((report) => ({
           path: report.rel,
@@ -167,6 +181,10 @@ async function runAudit(
     )
   }
 
+  // An empty set finds nothing and would exit clean, which reports a corpus
+  // nobody checked as a corpus carrying no violation.
+  if (empty.length > 0) return EXIT_UNUSABLE
+
   const gating = isGating({
     bans: reports.flatMap((report) => report.bans),
     structure: reports.map((report) => report.structure),
@@ -180,7 +198,7 @@ function refuse(message: string): number {
   logStep('Refused')
   logWarn(message)
   outro()
-  return 1
+  return EXIT_REFUSED
 }
 
 function reportScope(
@@ -203,18 +221,22 @@ function reportScope(
  * the sentence and every voice rule is a judgment, so a report listing hits
  * without naming those would read as a verdict on the whole standard.
  */
-function reportBans(reports: readonly FileReport[], bans: BanReport): void {
+function reportBans(
+  reports: readonly FileReport[],
+  bans: BanSets,
+  empty: readonly string[],
+): void {
   logStep('Bans')
 
-  if (bans.missing.length > 0) {
+  if (empty.length > 0) {
     logWarn(
-      `Not measured. Found no copy of: ${bans.missing.join(', ')}. Looked under .claude/standards/, then standards/, then the aitk package.`,
+      `Not measured. The shipped set is empty for: ${empty.join(', ')}. The sets ship with the aitk package, so an empty one is a defect in the build rather than a missing install.`,
     )
-    if (bans.sources.length === 0) return
+    return
   }
 
   logInfo(
-    `${plural(bans.characters.length, 'character')}, ${plural(bans.words.length, 'word')}, and ${plural(bans.spellings.length, 'spelling')} read from ${bans.sources.join(' and ')}`,
+    `${plural(bans.characters.length, 'character')}, ${plural(bans.words.length, 'word')}, and ${plural(bans.spellings.length, 'spelling')} shipped with the aitk package`,
   )
   logInfo(
     'Frontmatter, fenced blocks, code spans, and link destinations are excluded.',
@@ -379,12 +401,6 @@ function reportDepth(
     'A run that is entirely table rows is excluded too, since a heading inside a table splits the table rather than the run.',
   )
 
-  if (checkpoints.fellBack.length > 0) {
-    logWarn(
-      `Read no number from the standard for: ${checkpoints.fellBack.join(', ')}. Measured against the shipped default instead.`,
-    )
-  }
-
   const over = reports
     .filter((report) => report.structure.longestRun > checkpoints.run)
     .sort((a, b) => b.structure.longestRun - a.structure.longestRun)

package/src/commands/tasks.ts

@@ -104,7 +104,7 @@ export function register(program: Command): void {
         '',
         'Checks:',
         '  every Run now row points at a plan file that resolves',
-        '  every row maps to a task file and every task file to a row',
+        '  every task file carries a board row or a backlog line, never both',
         '  no task carries more than one row',
         '  no two Run now rows touch the same file',
         '',
@@ -450,12 +450,14 @@ function reportValidation(
     intro('aitk tasks validate')
     logStep('Board')
     logInfo(
-      `${outcome.rows} row(s) across the readiness groups, ${outcome.tasks} task file(s)`,
+      `${outcome.rows} row(s) across the readiness groups, ${outcome.backlog} backlog line(s), ${outcome.tasks} task file(s)`,
     )
 
     logStep(outcome.findings.length === 0 ? 'Clean' : 'Findings')
     if (outcome.findings.length === 0) {
-      logInfo('every row resolves, maps one to one, and touches its own files')
+      logInfo(
+        'every row resolves, every task sits on one surface, and each touches its own files',
+      )
     } else {
       for (const finding of outcome.findings) logWarn(describe(finding))
     }
@@ -481,6 +483,7 @@ function reportValidation(
         ok: true,
         root,
         rows: outcome.rows,
+        backlog: outcome.backlog,
         tasks: outcome.tasks,
         findings: outcome.findings,
         untested: outcome.untested,

package/src/markdown/bans.ts

@@ -1,233 +1,94 @@
-import { readFile } from 'node:fs/promises'
-import { linesOutsideFences } from '@/markdown/scan'
-import { resolveStandard } from '@/standards/read'
+import type { BanSets } from '@/markdown/scan'
 
 /**
- * Headings the two standards state their closed sets under.
+ * Single characters `markdown.md` bans under `## Punctuation`.
  *
- * Each standard says where its own bans sit and points at the other for the
- * rest, so discovery anchors on the heading rather than on a bullet's position.
- * A section renamed empties the set loudly at the report's legend, where a
- * position-based read would narrow the check and still print a count.
+ * The parenthetical-aside ban in that section is absent because it quotes a
+ * whole clause, and a literal match built from a clause reports the compliant
+ * text and reaches none of the violations.
  */
-export const WORD_BAN_HEADING = '## Language'
-export const CHARACTER_BAN_HEADING = '## Punctuation'
-
-/** Bullet lead-ins the two closed sets are stated behind. */
-const BAN_LEAD = '- Do not use '
-const SPELLING_LEAD = '- Use American English spelling'
-
-const BACKTICKED = /`([^`]+)`/g
-const WORD = /^[a-z]+$/
-const SUFFIX = /^-[a-z]+$/
-
-export interface BanReport {
-  /** Single characters the mechanics standard bans outright. */
-  readonly characters: readonly string[]
-  /** Single lowercase words the prose standard bans outright. */
-  readonly words: readonly string[]
-  /** Spellings derived from the prose standard's own examples. */
-  readonly spellings: readonly string[]
-  /**
-   * Paths of the standards read, in the order read. Repo-relative for a project
-   * copy, and spelled under `<aitk>/` for the package copy, so a reader can
-   * tell which root answered without joining a path that resolves nowhere.
-   */
-  readonly sources: readonly string[]
-  /**
-   * Standards that resolved under none of the roots. Absent is a distinct state
-   * from empty: a scan with no terms finds nothing, and reporting that as a
-   * clean file claims the prose passed when nothing was looked for.
-   */
-  readonly missing: readonly string[]
-}
-
-function section(markdown: string, heading: string): string[] {
-  const lines = linesOutsideFences(markdown)
-  const start = lines.findIndex((line) => line.trim() === heading)
-  if (start === -1) return []
-
-  const body = lines.slice(start + 1)
-  const end = body.findIndex((line) => line.startsWith('## '))
-
-  return end === -1 ? body : body.slice(0, end)
-}
-
-function backticked(line: string): string[] {
-  return [...line.matchAll(BACKTICKED)].map((match) => match[1].trim())
-}
+const CHARACTERS = ['—', ';'] as const
 
 /**
- * Pulls the single lowercase words out of the `Do not use` bullets.
+ * Single lowercase words `prose.md` bans under `## Language`.
  *
- * A multi-word term is left out rather than matched loosely. The standard bans
- * a pattern like `It's not X, it's Y` with a placeholder standing in for the
- * rest of the sentence, and no literal match reaches it, so the phrase bans
- * stay a reader's judgment and the report names them as unmeasured.
+ * A multi-word ban is absent by the same test the character set applies. The
+ * standard bans a pattern like `It's not X, it's Y` with a placeholder standing
+ * in for the rest of the sentence, so no literal match reaches it and the
+ * phrase bans stay a reader's judgment.
  */
-export function parseWordBans(markdown: string): string[] {
-  const terms: string[] = []
-
-  for (const line of section(markdown, WORD_BAN_HEADING)) {
-    if (!line.startsWith(BAN_LEAD)) continue
-    for (const term of backticked(line)) {
-      if (WORD.test(term) && !terms.includes(term)) terms.push(term)
-    }
-  }
-
-  return terms
-}
+const WORDS = [
+  'seamless',
+  'robust',
+  'powerful',
+  'revolutionary',
+  'enhanced',
+  'allows',
+  'leverage',
+  'simply',
+  'just',
+  'easily',
+  'quickly',
+  'very',
+  'really',
+] as const
 
 /**
- * Pulls the single non-alphanumeric characters out of the `Do not use` bullets.
+ * British spellings of the American examples `prose.md` lists.
  *
- * Width is what separates the two ban classes in that section. The character
- * bans are stated as one glyph each, and the parenthetical-aside ban quotes a
- * whole clause, which is a shape no literal match should be built from.
- */
-export function parseCharacterBans(markdown: string): string[] {
-  const terms: string[] = []
-
-  for (const line of section(markdown, CHARACTER_BAN_HEADING)) {
-    if (!line.startsWith(BAN_LEAD)) continue
-    for (const term of backticked(line)) {
-      if (
-        term.length === 1 &&
-        !/[a-z0-9]/i.test(term) &&
-        !terms.includes(term)
-      ) {
-        terms.push(term)
-      }
-    }
-  }
-
-  return terms
-}
-
-/**
- * Derives the banned spellings by applying the standard's own suffix rules to
- * the standard's own examples.
+ * The set is carried whole rather than derived from a suffix rule, because a
+ * suffix pattern run over prose produced 46 of the 58 false positives measured
+ * during intake: `exercises`, `promises`, and `revised` all end in `-ise` and
+ * none is a British spelling. Matching whole words reaches none of them.
  *
- * The spelling rule is stated as a preference with examples rather than as a
- * closed set, and a suffix pattern run over prose is what produced 46 of the
- * 58 false positives measured during intake: `exercises`, `promises`, and
- * `revised` all end in `-ise` and none is a British spelling. Transforming the
- * listed American words into their British forms yields a closed set that
- * matches whole words and reaches none of them, and an example added to the
- * standard extends the check without a code edit.
+ * `analyse` is absent because the standard's example is `analyze`, which ends
+ * in `-yze` rather than the `-ize` its rule states. The set records what the
+ * standard reaches rather than what a reader would extend it to, so adding the
+ * spelling here would widen the check past the prose it answers to.
  */
-export function parseSpellingBans(markdown: string): string[] {
-  const line = section(markdown, WORD_BAN_HEADING).find((each) =>
-    each.startsWith(SPELLING_LEAD),
-  )
-  if (!line) return []
-
-  const terms = backticked(line)
-  const suffixes = terms.filter((term) => SUFFIX.test(term))
-  const examples = terms.filter((term) => WORD.test(term))
-
-  // Stated as `preferred` over `banned`, so the run of suffix terms pairs off
-  // in order. An odd count means the sentence was rewritten into a shape this
-  // cannot read, and pairing what is there would invent a rule from half of it.
-  if (suffixes.length === 0 || suffixes.length % 2 !== 0) return []
-
-  const pairs: { preferred: string; banned: string }[] = []
-  for (let index = 0; index < suffixes.length; index += 2) {
-    pairs.push({
-      preferred: suffixes[index].slice(1),
-      banned: suffixes[index + 1].slice(1),
-    })
-  }
-
-  const spellings: string[] = []
-  for (const example of examples) {
-    const pair = pairs.find((each) => example.endsWith(each.preferred))
-    if (!pair) continue
-
-    const banned = `${example.slice(0, -pair.preferred.length)}${pair.banned}`
-    if (!spellings.includes(banned)) spellings.push(banned)
-  }
-
-  return spellings
-}
-
-export interface StandardText {
-  /** Path of the copy read, so a report says which root won. */
-  readonly source: string
-  readonly text: string
-}
-
-export interface Standards {
-  readonly markdown: StandardText | undefined
-  readonly prose: StandardText | undefined
-  /**
-   * Standards that resolved under none of the roots. Absent is a distinct state
-   * from empty: a scan with no terms finds nothing, and reporting that as a
-   * clean file claims the prose passed when nothing was looked for.
-   */
-  readonly missing: readonly string[]
-}
-
-async function loadStandard(
-  root: string,
-  name: string,
-): Promise<StandardText | undefined> {
-  const resolved = resolveStandard(root, name)
-  if (!resolved) return undefined
-
-  return {
-    source: resolved.source,
-    text: await readFile(resolved.path, 'utf8'),
-  }
-}
+const SPELLINGS = [
+  'organise',
+  'summarise',
+  'recognise',
+  'behaviour',
+  'colour',
+  'centre',
+] as const
 
 /**
- * Finds both standards, so one read serves the ban sets and the checkpoints.
+ * The three closed sets the audit measures, owned here rather than harvested
+ * from the standards stating them.
+ *
+ * Parsing the prose was the alternative and it put a parser contract on two
+ * documents authored for people, which the prose standard had to carry a
+ * paragraph of its own to protect. The sets are a prior an author already
+ * knows rather than a filter: measured at `60fc97bf` on 2026-08-19, these 21
+ * terms ran across 483 markdown files for a clean exit, and every one of the
+ * 70 occurrences of a banned word sat inside the ban list itself or inside an
+ * example demonstrating the ban.
  *
- * The texts are returned rather than the parsed sets alone because
- * `structure.ts` reads its numbers out of the same `markdown.md`, and a second
- * loader would open the file twice and could resolve a different root than
- * this one did.
+ * The set is closed rather than extensible. Enumeration cannot close the gap
+ * it aims at, and each addition costs a false-positive class, since `just`,
+ * `allows`, and `very` have honest uses no literal match separates. A project
+ * wanting its own vocabulary is asking for a different feature than this one.
  */
-export async function loadStandards(root: string): Promise<Standards> {
-  const [markdown, prose] = await Promise.all([
-    loadStandard(root, 'markdown.md'),
-    loadStandard(root, 'prose.md'),
-  ])
-
-  return {
-    markdown,
-    prose,
-    missing: [
-      markdown ? undefined : 'markdown.md',
-      prose ? undefined : 'prose.md',
-    ].filter((name): name is string => name !== undefined),
-  }
+export const BAN_SETS: BanSets = {
+  characters: CHARACTERS,
+  words: WORDS,
+  spellings: SPELLINGS,
 }
 
 /**
- * Reads both closed sets out of the standards stating them.
+ * Names any set that arrived empty, so a run measuring nothing says so.
  *
- * Holding the lists in code was the alternative and it puts the bans in two
- * places, where an author adding a banned word gets no enforcement until
- * someone edits TypeScript. The trade is a reader of prose that a reformat can
- * break, which `bans.test.ts` answers by asserting the parsed sets against the
- * shipped standards.
+ * Empty is not the same state as finding no hit. A scan with no terms reports
+ * a clean file having looked for nothing, which is the silence the audit
+ * refused to ship back when a standard could go missing. The sets ship with
+ * the package now, so the only way one empties is an edit to this file, and
+ * the guard is what keeps that edit loud rather than quiet.
  */
-export function banReport(standards: Standards): BanReport {
-  const { markdown, prose } = standards
-
-  return {
-    characters: markdown ? parseCharacterBans(markdown.text) : [],
-    words: prose ? parseWordBans(prose.text) : [],
-    spellings: prose ? parseSpellingBans(prose.text) : [],
-    sources: [markdown?.source, prose?.source].filter(
-      (source): source is string => source !== undefined,
-    ),
-    missing: standards.missing,
-  }
-}
-
-export async function loadBans(root: string): Promise<BanReport> {
-  return banReport(await loadStandards(root))
+export function emptyBanSets(sets: BanSets = BAN_SETS): string[] {
+  return (['characters', 'words', 'spellings'] as const).filter(
+    (name) => sets[name].length === 0,
+  )
 }

package/src/markdown/structure.ts

@@ -24,30 +24,17 @@ const BLOCKQUOTE = /^\s*>/
  */
 const SENTENCE_END = /[.!?]["'’”)\]]*(?=\s+(?:["'“(\[]*[A-Z]|`)|\s*$)/g
 
-const NUMBER_WORDS: Record<string, number> = {
-  one: 1,
-  two: 2,
-  three: 3,
-  four: 4,
-  five: 5,
-  six: 6,
-  seven: 7,
-  eight: 8,
-  nine: 9,
-  ten: 10,
-}
-
 /**
- * Checkpoints as `standards/markdown.md` states them today.
+ * Checkpoints the structural measures run against.
  *
- * These are the fallback rather than the definition. Each is read out of the
- * standard per run, and this stands in for one the standard no longer states in
- * a shape the reader recognizes, so a rewording degrades a number rather than
- * the whole check. The report's legend names every checkpoint that fell back,
- * because a stale number quietly measuring the wrong thing is the failure mode
- * a silent default would ship.
+ * These are the definition rather than a fallback. Reading each number out of
+ * the sentence `standards/markdown.md` states it in was the alternative, and it
+ * put a parser contract on a document authored for people, where a rewording
+ * degraded a number and the report had to carry a legend saying which one. The
+ * standard still states every number for a reader, and moving one is an edit to
+ * both.
  */
-export const DEFAULT_CHECKPOINTS = {
+export const CHECKPOINTS = {
   run: 40,
   peerBullet: 130,
   bullet: 400,
@@ -56,15 +43,13 @@ export const DEFAULT_CHECKPOINTS = {
   renderWidth: 80,
 } as const
 
-export type CheckpointName = keyof typeof DEFAULT_CHECKPOINTS
-
 /**
  * Columns a source line wraps at when rendered.
  *
  * Nothing in this repository sets a line width and entries are authored one
  * line per bullet, so the rendered width is the viewer's rather than the file's.
  */
-export const RENDER_WIDTH: number = DEFAULT_CHECKPOINTS.renderWidth
+export const RENDER_WIDTH: number = CHECKPOINTS.renderWidth
 
 export interface Checkpoints {
   readonly run: number
@@ -73,8 +58,6 @@ export interface Checkpoints {
   readonly paragraph: number
   readonly sentences: number
   readonly renderWidth: number
-  /** Names that fell back, so the report can say which number is not the standard's. */
-  readonly fellBack: readonly CheckpointName[]
 }
 
 export interface BulletFinding {
@@ -99,51 +82,6 @@ export interface StructureReport {
   readonly heavyParagraphs: readonly ParagraphFinding[]
 }
 
-const PATTERNS: Record<CheckpointName, RegExp> = {
-  run: /Past roughly (\d+) rendered lines/,
-  peerBullet: /averaging under roughly (\d+) characters/,
-  bullet: /Past roughly (\d+) characters in one top-level bullet/,
-  paragraph: /Past roughly (\d+) characters in one paragraph/,
-  sentences: /Keep paragraphs to ([a-z]+|\d+) sentences or fewer/,
-  renderWidth: /wrapping each source line at (\d+) columns/,
-}
-
-/**
- * Reads each checkpoint out of the standard stating it.
- *
- * A number held in code is a second place the rule lives, and the two drift
- * silently because nothing compares them. What this buys is that raising a
- * checkpoint is an edit to the sentence a reader is pointed at, and what it
- * costs is a reader of prose, which is bounded by falling back per checkpoint
- * rather than per file.
- */
-export function parseCheckpoints(markdown: string): Checkpoints {
-  const fellBack: CheckpointName[] = []
-
-  const read = (name: CheckpointName): number => {
-    const match = markdown.match(PATTERNS[name])
-    const raw = match?.[1]
-    const value = raw ? (NUMBER_WORDS[raw] ?? Number(raw)) : Number.NaN
-
-    if (!Number.isFinite(value) || value <= 0) {
-      fellBack.push(name)
-      return DEFAULT_CHECKPOINTS[name]
-    }
-
-    return value
-  }
-
-  return {
-    run: read('run'),
-    peerBullet: read('peerBullet'),
-    bullet: read('bullet'),
-    paragraph: read('paragraph'),
-    sentences: read('sentences'),
-    renderWidth: read('renderWidth'),
-    fellBack,
-  }
-}
-
 /**
  * Height a source line occupies once wrapped.
  *

package/src/tasks/archive.ts

@@ -9,11 +9,16 @@ const PLANS_DIR = join('.claude', 'plans')
 
 /**
  * Siblings that sit on the board without being tasks: the generated index, the
- * hand-maintained ordering, and a handoff a session wrote before the file took
- * one name per session. `validate` reads the same list, so neither verb can
- * count a sibling as a task the other does not.
+ * hand-maintained ordering, the unordered backlog beside it, and a handoff a
+ * session wrote before the file took one name per session. `validate` reads the
+ * same list, so neither verb can count a sibling as a task the other does not.
  */
-export const RESERVED_STEMS = ['index', 'priority', 'session'] as const
+export const RESERVED_STEMS = [
+  'index',
+  'priority',
+  'backlog',
+  'session',
+] as const
 
 /** The pre-compaction handoff takes one file per session, so its stems vary. */
 const SESSION_MAP_PREFIX = 'session-'