@erclx/aitk 0.100.0 → 0.102.0

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/records/validate.ts

@@ -3,6 +3,14 @@ import { readdir, readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { linesOutsideFences } from '@/markdown/scan'
+import {
+  TEACH_GLOSSARY,
+  TEACH_MISSION,
+  TEACH_RECORDS,
+  TEACH_REFERENCE,
+  TEACH_RESOURCES,
+  WORKSPACE_NAME,
+} from '@/teach/workspace'
 
 export const RECORD_KINDS = [
   'plans',
@@ -568,14 +576,7 @@ async function checkDump(dir: string, slug: string): Promise<Finding[]> {
   return [...findings, ...perCluster.flat()]
 }
 
-const TEACH_MISSION = 'MISSION.md'
-const TEACH_RESOURCES = 'RESOURCES.md'
-const TEACH_GLOSSARY = 'GLOSSARY.md'
-const TEACH_REFERENCE = 'reference'
-const TEACH_RECORDS = 'learning-records'
-
 const TEACH_SUCCESS = /^##[ \t]+Success looks like[ \t]*$/
-const WORKSPACE_NAME = /^\d{2}-[a-z0-9]+(-[a-z0-9]+)*$/
 const NUMBERED_RECORD = /^\d{4}-[a-z0-9]+(-[a-z0-9]+)*\.md$/
 /**
  * A kebab slug that does not open with an ordinal. The lookahead rejects a

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-'

package/src/tasks/validate.ts

@@ -9,6 +9,7 @@ import {
 } from '@/tasks/archive'
 
 const ORDERING_FILE = 'priority.md'
+const BACKLOG_FILE = 'backlog.md'
 
 /**
  * The readiness headings `.claude/standards/tasks.md` fixes. The names are the
@@ -60,6 +61,16 @@ export interface Untested {
   readonly message: string
 }
 
+/**
+ * A backlog line, which carries a pointer and nothing else. The backlog is
+ * explicitly unordered, so a line has no position to read and no columns to
+ * resolve.
+ */
+export interface BacklogRow {
+  readonly label: string
+  readonly stem: string | undefined
+}
+
 export interface BoardRow {
   readonly group: BoardGroup
   readonly label: string
@@ -74,6 +85,7 @@ export interface BoardRow {
 export interface ValidateReport {
   readonly ok: true
   readonly rows: number
+  readonly backlog: number
   readonly tasks: number
   readonly findings: readonly Finding[]
   readonly untested: readonly Untested[]
@@ -91,6 +103,10 @@ export function orderingPath(root: string): string {
   return join(tasksDir(root), ORDERING_FILE)
 }
 
+export function backlogPath(root: string): string {
+  return join(tasksDir(root), BACKLOG_FILE)
+}
+
 /**
  * Pulls the target out of a markdown link, which is how both the `Task` and the
  * `Plan` column spell their pointer. A cell carrying prose instead of a link
@@ -225,6 +241,39 @@ export function readBoard(text: string): {
   return { rows, groups }
 }
 
+/**
+ * Parses the backlog into one row per bullet carrying a link. The backlog is a
+ * flat list rather than a table, so there is no header to resolve and no group
+ * to sit under, and a bullet holding prose instead of a pointer is skipped.
+ *
+ * Skipping it rather than reporting it is what keeps the intro paragraph and
+ * any explanatory bullet out of the findings. The task that bullet meant to
+ * name is still accounted for, because a stem no line reaches is reported by
+ * `checkMapping` as carrying no row on either surface.
+ */
+export function readBacklog(text: string): readonly BacklogRow[] {
+  const rows: BacklogRow[] = []
+
+  for (const line of text.split('\n')) {
+    if (!/^\s*[-*]\s/.test(line)) continue
+
+    const target = linkTarget(line)
+    if (!target) continue
+
+    // A pointer carrying a directory names something other than a sibling task,
+    // the way `citedStem` reads the same shape on the board.
+    const path = target.split('#')[0] ?? ''
+    if (path.includes('/')) continue
+
+    const stem = stemOf(path)
+    if (stem && isReservedStem(stem)) continue
+
+    rows.push({ label: linkText(line) || line.trim(), stem })
+  }
+
+  return rows
+}
+
 async function listTaskStems(dir: string): Promise<string[]> {
   const entries = await readdir(dir)
 
@@ -247,13 +296,44 @@ function resolves(target: string, dir: string, root: string): boolean {
   return existsSync(resolve(dir, path)) || existsSync(resolve(root, path))
 }
 
+/**
+ * Accounts every task file against both surfaces the board spans. A task sits
+ * on `priority.md` when it would plausibly be planned soon and on `backlog.md`
+ * otherwise, so a file reached by neither is the dropped one this reports and a
+ * file reached by both claims two contradictory things about itself.
+ */
 function checkMapping(
   rows: readonly BoardRow[],
+  backlog: readonly BacklogRow[],
   stems: readonly string[],
   dir: string,
 ): Finding[] {
   const findings: Finding[] = []
   const seen = new Map<string, number>()
+  const listed = new Set<string>()
+
+  for (const row of backlog) {
+    if (!row.stem) {
+      findings.push({
+        kind: 'task-unresolved',
+        group: undefined,
+        subject: row.label,
+        message: 'is a backlog line naming no task file.',
+      })
+      continue
+    }
+
+    listed.add(row.stem)
+
+    if (!existsSync(join(dir, `${row.stem}.md`))) {
+      findings.push({
+        kind: 'task-unresolved',
+        group: undefined,
+        subject: row.stem,
+        message: 'has a backlog line and no task file.',
+      })
+    }
+  }
 
   for (const row of rows) {
     if (!row.stem) {
@@ -287,15 +367,26 @@ function checkMapping(
         message: `carries ${count} rows. A task belongs to exactly one group.`,
       })
     }
+
+    if (listed.has(stem)) {
+      findings.push({
+        kind: 'row-duplicated',
+        group: undefined,
+        subject: stem,
+        message:
+          'carries a row on the board and a line on the backlog. A task sits on one surface.',
+      })
+    }
   }
 
   for (const stem of stems) {
-    if (!seen.has(stem)) {
+    if (!seen.has(stem) && !listed.has(stem)) {
       findings.push({
         kind: 'row-missing',
         group: undefined,
         subject: stem,
-        message: 'is a task file with no row on the board.',
+        message:
+          'is a task file with no row on the board and no line on the backlog.',
       })
     }
   }
@@ -547,11 +638,19 @@ export async function validateBoard(root: string): Promise<ValidateOutcome> {
     )
   }
 
+  // An absent backlog reads as empty rather than refusing. A project that has
+  // never needed the second surface keeps every task on the board, which is the
+  // one-to-one mapping this check ran before the backlog existed.
+  const backlogFile = backlogPath(root)
+  const backlog = existsSync(backlogFile)
+    ? readBacklog(await readFile(backlogFile, 'utf8'))
+    : []
+
   const stems = await listTaskStems(dir)
   const parked = await checkParked(rows, root)
 
   const findings = [
-    ...checkMapping(rows, stems, dir),
+    ...checkMapping(rows, backlog, stems, dir),
     ...checkPlans(rows, dir, root),
     ...checkCollisions(rows),
     ...parked.findings,
@@ -560,6 +659,7 @@ export async function validateBoard(root: string): Promise<ValidateOutcome> {
   return {
     ok: true,
     rows: rows.length,
+    backlog: backlog.length,
     tasks: stems.length,
     findings,
     untested: parked.untested,