@erclx/aitk 0.101.0 → 0.103.0

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,

package/standards/glossary.md

@@ -0,0 +1,75 @@
+---
+title: Glossary reference
+description: Frontmatter, entry shape, ordering, and the rules deciding which terms a glossary carries
+---
+
+# Glossary reference
+
+Applies to a glossary, the file holding one entry per term a body of material defines. It changes whenever the material names a concept a reader cannot look up yet, and it is revised in place rather than appended to.
+
+## Scope
+
+Governs a glossary at `.claude/teach/<nn>-<topic>/GLOSSARY.md` and at whatever path a surface fixes for one it holds: its frontmatter, entry shape, ordering, grouping, and the rules deciding which terms it carries.
+
+Does not govern:
+
+- The folder a learning workspace lays out around its glossary, and the other files in it: `teach.md`
+- Which surface a glossary moves to once it leaves the material that produced it, which belongs to the surface driving that move
+- Voice and word choice: `prose.md`
+- Headings, punctuation, and file references: `markdown.md`
+
+## What a working glossary looks like
+
+A glossary works when a reader who meets a term in the material settles it here without opening the page that introduced it:
+
+- Which word does this material use for the concept, and which words does it deliberately not use?
+- What does the term mean, stated without leaning on the term itself?
+- Where does the term appear, so a reader can see it used rather than only defined?
+- Does every entry carry a term the material actually uses?
+
+A glossary failing these is non-conforming even when it satisfies every shape rule below.
+
+## Frontmatter
+
+- `title` (required): names the material the terms come from, in sentence case
+- `description` (required): one line naming what a reader gets from the entries
+
+## Entries
+
+- Write one entry per term, as a single bullet.
+- Lead the bullet with the term as a bolded span, then the definition in one or two sentences.
+- Define the term without using it. A definition that spends the term explains nothing to the reader who arrived not knowing it.
+- Name where the term first appears, so a reader can reach one use of it in context.
+- Keep an entry to the meaning. Worked detail belongs on the page that teaches the term.
+- Sort entries alphabetically, so a reader who knows only the word finds it without reading the file.
+
+## Which terms it carries
+
+- Add a term once the material has used it, never ahead of that. A glossary front-loaded with terms nothing has introduced is a syllabus rather than a reference.
+- Pick one word per concept and use that word everywhere. A glossary carrying two words for one thing hands the reader a choice it exists to remove.
+- List each rejected synonym as an alias to avoid inside the entry that won, so a reader arriving with the wrong word lands on the right one.
+- Use the glossary's own terms inside other definitions. A definition reaching for a synonym of a term defined two entries down teaches the reader a word the material does not use.
+- Revise an entry the material has moved under rather than adding a second one narrating the change.
+
+## Grouping
+
+- Keep a short glossary as one alphabetical list under the title. Grouping a handful of entries costs a heading per category and saves no lookup.
+- Group a glossary long enough that one list stops helping under `##` headings by category, sorted alphabetically within each. Roughly two screens of entries is the signal.
+- Name each category so a reader picks it from the term alone. A category a reader cannot predict makes the grouping a second thing to search.
+- State a departure from any rule above in the file itself, naming what it departs from and why. A glossary serving no single body of material is the case that produces one, since a term drawn from everywhere has no first appearance to name.
+
+## Template
+
+```markdown
+---
+title: <Material the terms come from>
+description: <one line naming what a reader gets from these entries>
+---
+
+# <Material the terms come from>
+
+<One line on which material these terms come from and when the file changes.>
+
+- **<Term>**: <the meaning in one or two sentences, written without using the term>. Avoid <rejected synonym>. First appears in `<page or lesson>`.
+- **<Term>**: <the meaning in one or two sentences, written without using the term>. First appears in `<page or lesson>`.
+```

package/standards/index.md

@@ -11,6 +11,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Context entry reference](context.md): Shape and content rules for .claude/context/<domain>.md entries
 - [Design reference](design.md): Shape and content rules for .claude/DESIGN.md
 - [Diagram reference](diagrams.md): Shape and content rules for .claude/diagrams/<kind>.md files
+- [Glossary reference](glossary.md): Frontmatter, entry shape, ordering, and the rules deciding which terms a glossary carries
 - [Groundwork reference](groundwork.md): Folder layout, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
 - [Intake reference](intake.md): Folder layout, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval
 - [Markdown reference](markdown.md): Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, and file references
@@ -26,6 +27,6 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Slug reference](slug.md): Transform from a git branch name to a slug, and the three responses to an empty result
 - [Standard reference](standard.md): Shape and content rules for authoring a standard
 - [Tasks reference](tasks.md): Folder layout, filename convention, readiness groups, and content rules for .claude/tasks/
-- [Teach reference](teach.md): Workspace layout, ordinal naming, frontmatter, and the mission, learning-record, and glossary formats for a learning workspace
+- [Teach reference](teach.md): Workspace layout, ordinal naming, frontmatter, and the mission and learning-record formats for a learning workspace
 - [Versioning reference](versioning.md): Phase label vs semver discipline across tasks, PRs, reviews, issues, commits, and tags
 - [Wireframe reference](wireframes.md): Shape and content rules for .claude/wireframes/<surface>.md files

package/standards/prose.md

@@ -51,8 +51,6 @@ Does not govern:
 
 The character bans sit in `markdown.md` under `## Punctuation` rather than here, because an em dash and a semicolon are typography and the bans here reach the words a sentence chooses and the claims it makes. A surface applying both reads both files.
 
-Illustrate a pattern ban with a multi-word phrase. An audit reading this section harvests the single lowercase backticked words out of every `- Do not use ` bullet into a literal ban set, so a one-word example bans that word everywhere it appears rather than banning the pattern it stands for. Both the toolkit command and the audit hook a project installs parse that shape, so the constraint holds wherever this file lands.
-
 ## Frontmatter descriptions
 
 When frontmatter carries a short `title` or `description` used for catalog display:

package/standards/tasks.md

@@ -13,7 +13,7 @@ The folder is gitignored. Board state changes when work ships rather than when a
 
 ## Scope
 
-Governs the task board under `.claude/tasks/`: folder layout, filenames, frontmatter, file format, origin lines, execution ordering, and archiving.
+Governs the task board under `.claude/tasks/`: folder layout, filenames, frontmatter, file format, origin lines, execution ordering, the backlog beside it, and archiving.
 
 Does not govern:
 
@@ -30,6 +30,7 @@ Does not govern:
 .claude/tasks/
 ├── index.md              ← generated, never hand-edited
 ├── priority.md           ← hand-maintained execution order
+├── backlog.md            ← unordered, what is not being scheduled
 ├── session-<slug>.md     ← optional, what a compaction is about to destroy
 ├── v09.0-sync-paths.md
 └── v13.0-toolkit-drift.md
@@ -37,7 +38,9 @@ Does not govern:
 
 One file per task is what keeps the board safe under parallel sessions. Two sessions working different tasks never write the same file, which matters because a gitignored board has no history to recover a clobbered write from.
 
-Siblings sit in the folder without being tasks, and each earns its place by being governed somewhere. `index.md` and `priority.md` are governed here. Every `session-` file is a pre-compaction handoff governed by `session.md`, and each is optional: a project whose sessions never approach a compaction carries none. Anything filtering the folder to tasks skips all of them, so a name outside the set is a task whatever it holds.
+Siblings sit in the folder without being tasks, and each earns its place by being governed somewhere. `index.md`, `priority.md`, and `backlog.md` are governed here. Every `session-` file is a pre-compaction handoff governed by `session.md`, and each is optional: a project whose sessions never approach a compaction carries none. Anything filtering the folder to tasks skips all of them, so a name outside the set is a task whatever it holds.
+
+`backlog.md` is optional too. A project small enough that every task it holds would be planned soon carries none, and the ordering rules below then describe the whole board.
 
 The handoff takes one file per session for the reason a task does. A single shared path puts two sessions closing near each other on one file that neither can watch the other write, and the loser leaves no trace on a board with no history behind it.
 
@@ -49,7 +52,7 @@ The `claude-tasks` skill creates and archives task files. `claude-docs` marks ou
 
 ## Ordering
 
-`priority.md` carries execution order and what each task is waiting on. The generated index sorts by filename and says nothing about order, so without this file board state gets reconstructed by hand every session. Why the order is what it is belongs in `.claude/ROADMAP.md`, which is committed because that rationale has no substitute record.
+`priority.md` carries execution order and what each task is waiting on. The generated index sorts by filename and says nothing about order, so without this file board state gets reconstructed by hand every session. Why one version sequences against another belongs in `.claude/ROADMAP.md`, which is committed because that rationale has no substitute record. Why a row sits where it does inside its group is stated on the row itself, in the column that already carries what the task is waiting on.
 
 Group tasks by readiness rather than by status, one row per task, under the columns each group fixes below. Keep it to links and blockers: tables, plus at most one sentence per section. A paragraph in `priority.md` is a defect whatever it says. Stating the shape this way is what lets a single diff fail, since a size cap only trips after the fact and every addition looks defensible on its own.
 
@@ -61,11 +64,15 @@ Readiness is three groups under fixed headings, `## Run now`, `## Up next`, and
 
 Each group fixes its own columns, which follow from the test above it rather than from preference. Neither half of the `## Run now` test is checkable without the file set and the plan sitting beside the task.
 
+Row position inside `## Needs a plan` is the order those tasks get planned in, top first. The three tests answer whether a task can start, which is mechanical, and none of them answers which task is worth starting, which is a judgment no column holds. Position is where that judgment is recorded, so the top row is the answer to what to plan next and a reader needs no other surface to get it. The other two groups take the same reading, and it costs them little, since a group holding what is already planned is short by construction.
+
+Position alone carries it, and no rank column exists. A number beside each row is a second thing to keep in step with the order it duplicates, and the file is edited by one session at a time, so the order the rows are written in is already unambiguous. State on each row why it sits where it does, in the same cell that carries what it is waiting on. A position with no stated reason is re-derived from memory by the next session, which is the failure the ordering replaces rather than moves.
+
 The `Waiting on` column under `## Up next` carries that reason in one of three forms. `## Needs a plan` states no file set at all, because a task with no plan has no bounded one to state. A group with no rows keeps its heading and its header row.
 
 Under `## Up next` a collision names the file held by the task already running, a sibling task names that task, and an external condition names both the condition and what would satisfy it. Naming what would satisfy it is what separates a blocked row from one nobody has examined, so a cell stating a condition with no way out of it fails the test. The header text is the contract the way the group names are, because anything reading the cell resolves the column by header rather than by position.
 
-`aitk tasks validate` reads those columns and reports where a row's claim and the tree disagree: a plan pointer resolving to no file, a row and a task file that do not map one to one, a task in two groups, and two `## Run now` rows touching a path in common. It also re-takes the two blocker kinds a command can settle, reporting a parked row whose cited task is archived or has closed every outcome and one whose cited file nothing under `## Run now` still holds. Both halves read a citation out of the cell rather than parsing it into fields, and a row citing neither is reported as untested, which is where the three kinds resting on a person's judgment land. Run it when the readiness claim is made rather than on a schedule, since the board is gitignored per-machine scratch and no shared moment exists to hang it on. It reports and never writes, so a session fixes the row it names.
+Under `## Needs a plan` the cell carries two halves and each takes one clause: what the task needs before it can be planned, then why it sits at this position. A cell running past that is the paragraph this file already deletes, arriving one row at a time rather than all at once, and the group is where it costs the most, since it holds the rows nobody has read recently and is the longest group on any board that needs a backlog at all.
 
 ```markdown
 ---
@@ -88,13 +95,47 @@ description: One line on what the board covers
 
 ## Needs a plan
 
-| Task                            | Waiting on                                     |
-| ------------------------------- | ---------------------------------------------- |
-| [vXX.Y <slug>](vXX.Y-<slug>.md) | <what the task needs before it can be planned> |
+| Task                            | Waiting on                                                     |
+| ------------------------------- | -------------------------------------------------------------- |
+| [vXX.Y <slug>](vXX.Y-<slug>.md) | <what it needs before it can be planned, and why it sits here> |
 ```
 
 The tests live here so the board does not carry them. Writing them as a sentence under each heading produces the paragraph the rule above deletes, and a criterion with no home gets restated from memory every time the board is touched.
 
+## The backlog
+
+A task sits on the board when it would plausibly be planned within the next few waves, and on `backlog.md` otherwise. The call is a judgment, so restate it whenever the board is swept rather than making it once: a backlogged task rises when the work in front of it lands or the world changes under it, and a board row falls to the backlog when it stops being near-term.
+
+A mechanical test over age or origin was the alternative and neither predicts what gets picked next, which is the judgment the ordering exists to carry. Leaving everything on the board is the other alternative, and it is what produces a group too long to rank, where the ordering means nothing because nobody can hold the whole list in one reading.
+
+What the split buys is that the board is short enough for its order to be read, and what it costs is a second surface to keep. That trade only pays while the backlog stays honest about what it is, which is why it carries no order, no groups, and no readiness claim.
+
+Nothing is deleted. A backlogged task keeps its file, its findings, and its frontmatter, and the backlog row is a pointer at that file. The folder is gitignored and has no history behind it, so a row dropped without landing somewhere readable is gone with nothing to recover it from.
+
+The backlog is a flat list of links under one heading, sorted by filename. Sorting mechanically is what keeps it from reading as a queue: the order is the same order the index already sorts in, so no position on it means anything.
+
+```markdown
+---
+title: Backlog
+description: One line on what the backlog holds
+---
+
+# Backlog
+
+Unordered. Nothing here is scheduled, and a task rises to `priority.md` when it becomes near-term.
+
+- [vXX.Y <slug>](vXX.Y-<slug>.md)
+- [vXX.Y <slug>](vXX.Y-<slug>.md)
+```
+
+Add no fourth readiness group in place of this file. The three group names are the contract, and a backlog is a separate surface rather than a group because it makes no readiness claim at all: it says nobody has scheduled the task, which is a fact about attention rather than about whether the work can start.
+
+## Validation
+
+`aitk tasks validate` reads the columns above and reports where a row's claim and the tree disagree: a plan pointer resolving to no file, a task file reached by neither surface, a task on both surfaces or in two groups, and two `## Run now` rows touching a path in common. It also re-takes the two blocker kinds a command can settle, reporting a parked row whose cited task is archived or has closed every outcome and one whose cited file nothing under `## Run now` still holds. Both halves read a citation out of the cell rather than parsing it into fields, and a row citing neither is reported as untested, which is where the three kinds resting on a person's judgment land. Run it when the readiness claim is made rather than on a schedule, since the board is gitignored per-machine scratch and no shared moment exists to hang it on. It reports and never writes, so a session fixes the row it names.
+
+A task file is accounted for when a row on `priority.md` or a line on `backlog.md` names it, and reported when neither does. One check across both surfaces is what lets a task move between them without the move looking like a dropped file, and a task named by both is reported for the same reason a task in two groups is: it claims two things about itself and only one of them can hold. A project carrying no `backlog.md` is read as an empty backlog rather than refused, which leaves the one-to-one mapping this check ran before the second surface existed.
+
 ## Filenames
 
 `vXX.Y-<slug>.md`, where the version is the phase label zero-padded to two digits and the slug is kebab-case.
@@ -195,7 +236,7 @@ The line is what lets a merge close its own task. Every merge on `main` is a squ
 - Architectural reasoning that outlives the task. A finding explains why this task is shaped as it is. A decision the system keeps after the task closes belongs in `.claude/ARCHITECTURE.md`.
 - Narrative of the session that produced the task. A finding states what constrains the task, so what was probed, what it cost, and who decided belongs in the groundwork folder the `Groundwork:` line names. A task with no groundwork folder cuts the narrative rather than relocating it, since the board is not the fallback destination for it.
 - "In progress" or "Blocked" headings. Note status inline on the outcome instead.
-- Sequencing rationale or which version is active. Those belong in `.claude/ROADMAP.md`, which is committed because that reasoning has no substitute record.
+- Sequencing rationale or which version is active. Why this task is planned before its neighbors goes on its row in `priority.md`, in the cell that already carries what it is waiting on. Why one version sequences against another belongs in `.claude/ROADMAP.md`, which is committed because that reasoning has no substitute record.
 
 ## Archiving
 
@@ -205,6 +246,8 @@ Two callers reach that command. The `claude-tasks` skill runs it inside a sessio
 
 One destination rather than a per-project choice is what lets the move happen without asking. It mirrors the plans archive at `.claude/plans-archive/` and stays gitignored, so an archived task does not start appearing in diffs. The cost is that the folder is unbacked, which is the same cost the plans archive already carries.
 
+The archive clears a row from `priority.md` and reads no other surface, which holds because a task reaches a merge by being planned and handed out, and both steps move it onto the board first. A task archived straight off the backlog therefore leaves its line standing, and the validator reports that line as naming a file that is gone rather than the board losing it silently.
+
 Archiving a task does not archive its plan. `claude-docs` owns the plans sweep and moves a plan only when the closing task is its last live citation. The archive clears the task's row from `priority.md` itself, since a shipped task left in the ordering reads as ready to hand a worker. It leaves prose naming the task alone for a person to resolve.
 
 The row is matched by the link in its first cell rather than by a pattern against the whole line. A row names the task it is about in the first cell, so a link anywhere after that is a reference, such as a blocker pointing at what it waits on. Matching the line would delete the referring task's row too, on a board that is gitignored and has nothing to recover it from.

package/standards/teach.md

@@ -1,6 +1,6 @@
 ---
 title: Teach reference
-description: Workspace layout, ordinal naming, frontmatter, and the mission, learning-record, and glossary formats for a learning workspace
+description: Workspace layout, ordinal naming, frontmatter, and the mission and learning-record formats for a learning workspace
 ---
 
 # Teach reference
@@ -11,10 +11,11 @@ The folder is gitignored. Its markdown half is written in a format the authoring
 
 ## Scope
 
-Governs a learning workspace under `.claude/teach/<nn>-<topic>/`: folder layout, ordinal naming, frontmatter, and the mission, learning-record, and glossary formats.
+Governs a learning workspace under `.claude/teach/<nn>-<topic>/`: folder layout, ordinal naming, frontmatter, and the mission and learning-record formats.
 
 Does not govern:
 
+- The frontmatter, entry shape, and ordering of the glossary the workspace holds: `glossary.md`
 - What a lesson teaches, how it sequences difficulty, and what makes one worth returning to, which belong to the surface driving the workspace
 - Where a durable page goes once it leaves the workspace, which belongs to the routing test the destination surface states
 - One question measured in depth before anyone can plan against it: `groundwork.md`
@@ -96,12 +97,9 @@ Record the wrong answer rather than the fact of an error. A wrong answer names t
 
 ## GLOSSARY.md
 
-One entry per term the subject defines, sorted alphabetically.
+Required in every workspace, holding one entry per term the subject defines. `glossary.md` fixes what an entry looks like, how the file orders and groups them, and which terms it carries, so this standard states only that the file exists and sits at the workspace root.
 
-- Lead each entry with the term as a bolded span, then the definition in one or two sentences
-- Define the term without using it
-- Name the lesson or reference page where the term first appears
-- Keep an entry to the meaning. Worked detail belongs on a reference page.
+Name the lesson or reference page a term first appears in as that standard requires. A workspace is the case it was written for, so a glossary here has a first appearance to name.
 
 ## RESOURCES.md
 

package/tooling/claude/seeds/.claude/hooks/standards-audit.sh

@@ -24,66 +24,62 @@ esac
 
 [ -f "$file" ] || exit 0
 
-# Read the closed-set word bans from the standard so the hook never carries a
-# second copy. Every "Do not use ... (`a`, `b`)" bullet contributes its
-# single-word backticked terms, which skips the multi-word and punctuation bans.
+# The audit verb owns the ban sets, so this hook carries no copy of them. The
+# awk this replaces parsed the word bans out of the project's own prose.md,
+# hardcoded the em-dash and semicolon, and reached none of the spellings, so a
+# British spelling passed at edit time and a corpus check caught it later with
+# nothing in between explaining the difference. A ban class added to the verb
+# now reaches this hook without an edit here.
 #
-# The word bans sit in prose.md and the em-dash and semicolon bans in
-# markdown.md, so this parses the first and hardcodes the second. A "Do not use"
-# bullet added to markdown.md is parsed by nothing and enforces silently.
-standard="${CLAUDE_PROJECT_DIR:-.}/.claude/standards/prose.md"
-words=""
+# The verb resolves its own paths under the cwd, so the project root is named
+# rather than inherited. The payload carries an absolute file path, which is
+# what lets the runner move without taking the argument out of reach.
+root="${CLAUDE_PROJECT_DIR:-.}"
+
+# A machine without the binary reports that nothing ran rather than exiting
+# clean. An edit nobody checked and an edit carrying no violation are the same
+# silence to a reader, so the enforcement a machine lacks is reported.
+#
+# A completed run always writes the record, and a refusal writes nothing, so an
+# empty one means the verb declined to measure rather than measured and found
+# nothing. It refuses outside a git repository, which is a project this hook can
+# be installed into, and reading the findings alone reports that as a clean file.
 unread=""
-if [ -f "$standard" ]; then
-  words=$(grep '^- Do not use ' "$standard" |
-    grep -o '`[^`]*`' |
-    tr -d '`' |
-    grep -x '[a-z][a-z]*' |
-    sort -u |
-    paste -sd '|' -)
+record=""
+if command -v aitk >/dev/null 2>&1; then
+  record=$(cd "$root" 2>/dev/null && aitk markdown audit "$file" --json 2>/dev/null) || true
+  [ -n "$record" ] || unread="record"
 else
-  # An absent standard empties the word list, and the awk below reads an empty
-  # list as nothing to look for rather than as nothing found. The path is kept
-  # so the report names what could not be read, since a file carrying no banned
-  # word and a file nobody checked produce the same silence otherwise.
-  unread="$standard"
+  unread="runner"
 fi
 
-hits=$(awk -v words="$words" '
-  BEGIN { if (words != "") banned = "(^|[^a-z])(" words ")([^a-z]|$)" }
-  /^```/ { in_code = !in_code; next }
-  in_code { next }
-  /—/ { print NR ": em-dash: " $0 }
-  /;/  { print NR ": semicolon: " $0 }
-  banned != "" {
-    prose = tolower($0)
-    gsub(/`[^`]*`/, "", prose)
-    found = ""
-    delete seen
-    while (match(prose, banned)) {
-      word = substr(prose, RSTART, RLENGTH)
-      gsub(/[^a-z]/, "", word)
-      if (word != "" && !(word in seen)) {
-        seen[word] = 1
-        found = found (found == "" ? "" : ", ") word
-      }
-      prose = substr(prose, RSTART + RLENGTH)
-    }
-    if (found != "") print NR ": banned word (" found "): " $0
-  }
-' "$file")
+# The record decides rather than the exit code, so a binary predating a ban
+# class still reports what it does measure. A refusal and an unparseable payload
+# both yield nothing, which is the same silence a clean file produces.
+hits=$(printf '%s' "$record" |
+  jq -r '.entries[]?.bans[]? | ":\(.line):\(.column + 1)  \(.kind)  \(.term)"' 2>/dev/null)
+
+# A set the verb shipped empty measures nothing and would report a clean file.
+# Reading the findings alone turns that narrowed check into a pass, so the field
+# is read beside them.
+empty=$(printf '%s' "$record" |
+  jq -r '[.bans.emptySets[]?] | join(", ")' 2>/dev/null)
 
-[ -z "$hits" ] && [ -z "$unread" ] && exit 0
+[ -z "$hits" ] && [ -z "$unread" ] && [ -z "$empty" ] && exit 0
 
 nl=$'\n'
 msg=""
 
-if [ -n "$unread" ]; then
-  msg=$(printf 'Standards-audit: no word ban checked in %s. Found no standard at %s, so only the character bans ran. Restore it with `aitk standards install`.' "$file" "$unread")
+if [ "$unread" = "runner" ]; then
+  msg=$(printf 'Standards-audit: nothing checked in %s. Found no `aitk` binary on PATH. Install one with `bun add -g @erclx/aitk`.' "$file")
+elif [ "$unread" = "record" ]; then
+  msg=$(printf 'Standards-audit: nothing checked in %s. `aitk markdown audit` returned no record, which it does when it declines to measure. It needs a git repository to build its corpus.' "$file")
+elif [ -n "$empty" ]; then
+  msg=$(printf 'Standards-audit: the shipped ban set is empty for %s, so %s was checked against a narrowed set. Reinstall the toolkit with `bun add -g @erclx/aitk`.' "$empty" "$file")
 fi
 
 if [ -n "$hits" ]; then
-  found=$(printf 'Standards-audit: prose.md and markdown.md violations in %s. Rewrite or restructure (do not lazy-swap).\n%s' "$file" "$hits")
+  found=$(printf 'Standards-audit: prose.md and markdown.md violations in %s. Rewrite the sentence (do not lazy-swap). A code span is the answer only where the token is genuinely an identifier under discussion.\n%s' "$file" "$hits")
   msg="${msg:+$msg$nl}$found"
 fi