@erclx/aitk 0.64.0 → 0.64.1

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.64.0",
+  "version": "0.64.1",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents/context-audit-checks.md

@@ -19,7 +19,7 @@ It reports rather than gates by default, the closer call because a missing secti
 
 ## Length
 
-Length quotes its checkpoint from `.claude/standards/context.md`: roughly 150 rendered lines for an entry. It counts rendered lines rather than source lines, wrapping each line at 80 columns and summing the heights. Entries here are authored one line per bullet, so a block of fifteen paragraph-bullets occupies fifteen source lines and renders past sixty, which source counting cannot see. The measure counts fenced blocks and frontmatter, so a reference-heavy entry ranks by its examples, which the legend states on every run alongside the width, since a number in rendered lines cannot be reproduced without it.
+Length quotes its checkpoint from `.claude/standards/context.md`: roughly 150 rendered lines for an entry. It counts rendered lines rather than source lines, wrapping each line at 80 columns and summing the heights. A line is wrapped at the width it renders at, so a link counts as its anchor text and a backticked path counts whole. That moves 2 of the 48 entries measured, `extensions.md` by 2 lines and `governance.md` by 1, because an entry cites a path in backticks rather than as a link. Entries here are authored one line per bullet, so a block of fifteen paragraph-bullets occupies fifteen source lines and renders past sixty, which source counting cannot see. The measure counts fenced blocks and frontmatter, so a reference-heavy entry ranks by its examples, which the legend states on every run alongside the width, since a number in rendered lines cannot be reproduced without it.
 
 Depth and bullet weight are quoted from `.claude/standards/markdown.md`, which states both over every markdown file rather than over a context entry, so `aitk markdown audit` measures them and this command no longer does. They share `renderedHeight` with the length measure, since the two checkpoints sit in one section of that standard and a reader compares them. What the split costs is that a session wanting both numbers for one entry runs two commands, and what it buys is that either number can be had for a file in a folder this audit refuses to resolve.
 

package/docs/agents/markdown-audit.md

@@ -41,13 +41,21 @@ Deriving the spellings rather than pattern-matching a suffix is what keeps `exer
 
 Frontmatter, fenced blocks, inline code spans, and link destinations are excluded. Without the code-span exclusion each standard would report its own backticked examples, and without the link exclusion a semicolon in a query string would report as prose no rewrite can fix.
 
+A banned word is bounded on a word character or a hyphen either side. A plain word boundary sits after a hyphen, so a banned word ending a hyphenated compound reported from inside one, and a compound is a single word to the reader who wrote it.
+
+A banned spelling keeps the plain word boundary, hyphens included. The two bans target different things: a word ban targets the word, so reading a compound as one word is correct, while a spelling ban targets the orthography inside it, which sits in `behaviour-driven` as plainly as it sits alone.
+
 Two ban shapes stay unmeasured and the report says so on every run. A phrase ban carries a placeholder standing in for the rest of the sentence, so no literal match reaches it, and every rule under `## Voice` is a judgment. A report listing hits without naming those would read as a verdict on the whole standard.
 
 ### Bullets, paragraphs, and depth
 
 Bullet weight and depth are the checks that moved off `aitk context audit`, unchanged in what they measure. A top-level bullet reports past roughly 400 characters with continuation lines folded in and nested items left out. A run of lines no heading breaks reports past roughly 40 rendered lines, measured at 80 columns, skipping fenced blocks and exempting a flat peer list averaging under 130 characters a bullet and a run that is entirely table rows.
 
-The paragraph check is new and measures both halves of one rule. `markdown.md` caps a paragraph at four sentences, and a sentence cap on its own is satisfied by writing fewer and longer ones: measured across 2906 paragraphs, 344 sit inside four sentences and past 400 characters, and the heaviest runs 1159 characters in two. The standard therefore states a weight beside the sentence cap, and the verb reads it as its own checkpoint.
+Every weight and depth measure counts the text a reader is shown. A link reduces to its anchor text and an autolink drops whole, since no reader is shown either destination. A backticked path stays counted, which is where these measures part from the ban scan above: that one blanks a code span so a standard quoting its own banned character does not report itself, and discounting the same span here would under-report a paragraph carrying several. One file holds both span sets and each answers its own question.
+
+A code span is walked around rather than through, so a path quoting link or angle-bracket syntax keeps the width the page gives it. Masking inside one takes back the decision to count it, and the placeholders this toolkit writes are where that shows.
+
+The paragraph check is new and measures both halves of one rule. `markdown.md` caps a paragraph at four sentences, and a sentence cap on its own is satisfied by writing fewer and longer ones: measured across 3374 paragraphs, 486 sit inside four sentences and past 400 characters, and the heaviest of those runs 1121 characters. The standard therefore states a weight beside the sentence cap, and the verb reads it as its own checkpoint.
 
 The paragraph weight and the bullet weight are the same number today because the two shapes measure one population, sharing a median near 170 characters with no gap behind either candidate. They are separate checkpoints in the standard and separate patterns in the parser, so retuning one leaves the other where it is.
 
@@ -59,7 +67,9 @@ Exit codes are `0` for a completed run and `1` for a refusal. Every finding repo
 
 A banned character is a fact rather than a judgment, which is the test that would ordinarily make it gate. What holds it back is that gating on day one against a corpus never checked mechanically fails loudly on work nobody has had a chance to fix. The order is to land the verb reporting, measure the corpus once, fix what it finds, and turn the gate on as its own change. Bullet, paragraph, and depth weight are judgments and stay advisory under any later gate.
 
-Measured across 443 files on the day this shipped: 9 word hits, no character or spelling hits, 109 heavy bullets, 610 heavy paragraphs, and 42 files carrying a run past the depth checkpoint. The ban count is what a gate would have to hold at zero, and it is the only one of the five a gate should ever read.
+Measured across 444 files once the weight measures moved to visible text: 8 word hits, no character or spelling hits, 119 heavy bullets, 615 heavy paragraphs, and 40 files carrying a run past the depth checkpoint. The ban count is what a gate would have to hold at zero, and it is the only one of the five a gate should ever read.
+
+Masking took 7 of the 493 weight-only paragraphs and 4 of the 44 files under their checkpoints, and no bullet at all. The first corpus triage put those at 31 paragraphs and 2 bullets, and neither reproduces: a code span is walked around, so a backticked path holding an angle-bracket placeholder keeps the width the page gives it, and both bullets the triage counted were that shape.
 
 ## What it does not cover
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.64.0",
+  "version": "0.64.1",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/markdown/scan.ts

@@ -23,6 +23,17 @@ const CODE_SPAN = /(`+)(?:(?!\1).)*\1/g
 const LINK_DESTINATION = /\]\([^)]*\)/g
 const AUTOLINK = /<[^>\s]+>/g
 
+/**
+ * A whole inline link, capturing the anchor text a reader is shown.
+ *
+ * `LINK_DESTINATION` covers the span both measures drop and this covers the
+ * brackets only the weight measure drops, which a reader is no more shown than
+ * the destination. The narrower pattern still runs after this one, since a link
+ * wrapped across two source lines puts its opening bracket on a line this one
+ * never matches.
+ */
+const LINK = /\[([^\]]*)\]\([^)]*\)/g
+
 export interface BodyLine {
   readonly number: number
   readonly text: string
@@ -128,16 +139,81 @@ export function maskDisplayed(text: string): string {
     .replace(AUTOLINK, blank)
 }
 
+/**
+ * Drops the spans a reader is never shown, returning the text they read.
+ *
+ * This is what a weight measure counts, and it is deliberately not
+ * `maskDisplayed`. That one holds each span's width so a ban finding can name a
+ * column, which leaves behind the very characters a weight measure exists to
+ * discount. The two also disagree on the span set: a backticked path is text a
+ * reader reads and stays counted here, while the ban scan blanks it so a
+ * standard quoting its own banned character does not report itself. One file
+ * therefore holds two answers to what a reader sees, each correct for its own
+ * measure, and collapsing them into one helper breaks whichever loses.
+ *
+ * A code span is walked around rather than through, since keeping it counted
+ * and then dropping spans from inside it takes back the decision. The
+ * placeholders this repository writes are the case: a reader is shown all of
+ * `.claude/context/<domain>.md` and the autolink pattern reaches the angle
+ * brackets in the middle of it.
+ */
+export function visibleText(text: string): string {
+  const drop = (segment: string): string =>
+    segment
+      .replace(LINK, '$1')
+      .replace(LINK_DESTINATION, '')
+      .replace(AUTOLINK, '')
+
+  let visible = ''
+  let read = 0
+
+  for (const span of text.matchAll(CODE_SPAN)) {
+    visible += drop(text.slice(read, span.index)) + span[0]
+    read = span.index + span[0].length
+  }
+
+  return visible + drop(text.slice(read))
+}
+
 function escape(term: string): string {
   return term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
 
+/**
+ * Bounds a banned word on a word character or a hyphen either side.
+ *
+ * `\b` sits after a hyphen, so a banned word ending a hyphenated compound
+ * reports from inside it: `allows` came back out of `auto-allows`. A compound
+ * is one word to a reader, and the ban is on the word rather than on a morpheme
+ * of it. Stripping hyphens before matching was the alternative and it joins the
+ * compound into a token neither half reaches.
+ *
+ * A spelling ban takes `wordBoundary` instead. This is not that rule with a
+ * wider fence, since the two bans target different things.
+ */
+function bannedWord(term: string): RegExp {
+  return new RegExp(`(?<![\\w-])${escape(term)}(?![\\w-])`, 'gi')
+}
+
+/**
+ * Bounds a banned spelling on a word character alone, hyphens included.
+ *
+ * A word ban targets the word, so a compound reading as one word is correct.
+ * A spelling ban targets the orthography inside it, and a compound is exactly
+ * where the orthography still sits: `behaviour-driven` carries the banned
+ * spelling as plainly as `behaviour` does, and rejecting a hyphen here would
+ * leave the usual spelling of that phrase unreported.
+ */
+function bannedSpelling(term: string): RegExp {
+  return new RegExp(`\\b${escape(term)}\\b`, 'gi')
+}
+
 /**
  * Finds every banned term outside a fence, a code span, and a link.
  *
- * A word ban matches on word boundaries and either casing, since the standard
- * states each in lowercase and bans the word rather than a spelling of it. This
- * is what separates the check from the pattern that produced most of the
+ * A word ban matches in either casing, since the standard states each in
+ * lowercase and bans the word rather than a spelling of it. A closed set of
+ * whole words separates the check from the pattern that produced most of the
  * intake's false positives: `exercises` and `promises` end in the banned
  * suffix and are not the banned words, and a closed set never reaches them.
  */
@@ -151,12 +227,12 @@ export function scanBans(
     ...bans.words.map((term) => ({
       kind: 'word' as const,
       term,
-      pattern: new RegExp(`\\b${escape(term)}\\b`, 'gi'),
+      pattern: bannedWord(term),
     })),
     ...bans.spellings.map((term) => ({
       kind: 'spelling' as const,
       term,
-      pattern: new RegExp(`\\b${escape(term)}\\b`, 'gi'),
+      pattern: bannedSpelling(term),
     })),
   ]
 

package/src/markdown/structure.ts

@@ -1,4 +1,4 @@
-import type { BodyLine } from '@/markdown/scan'
+import { type BodyLine, visibleText } from '@/markdown/scan'
 
 const HEADING = /^#{1,6}\s/
 const LIST_ITEM = /^(\s*)([-*+]|\d+\.)\s+/
@@ -143,9 +143,13 @@ export function parseCheckpoints(markdown: string): Checkpoints {
  *
  * A blank line renders as the gap it is rather than as nothing, which keeps it
  * the distance the source measure already counted it as.
+ *
+ * The width is measured against what renders, since a rendered line shows a
+ * link's anchor text rather than its destination and a source measure
+ * over-counts exactly where this rule cares how far a reader travels.
  */
 export function renderedHeight(text: string, width = RENDER_WIDTH): number {
-  return Math.max(1, Math.ceil(text.length / width))
+  return Math.max(1, Math.ceil(visibleText(text).length / width))
 }
 
 /**
@@ -173,7 +177,7 @@ function isScannablePeerList(
     if (!match) return false
     indents.add(match[1].length)
     items++
-    characters += text.length
+    characters += visibleText(text).length
   }
 
   if (indents.size !== 1) return false
@@ -297,10 +301,13 @@ export function heavyBullets(
     const item = line.text.match(LIST_ITEM)
     const text = line.text.trim()
 
+    // Structure is read off the raw line and only the weight is masked. A line
+    // carrying nothing but an autolink has no visible text at all, and reading
+    // its masked form as blank would close the bullet it continues.
     if (item) {
       close()
       if (item[1].length === 0) {
-        open = { line: line.number, characters: text.length }
+        open = { line: line.number, characters: visibleText(text).length }
       }
       continue
     }
@@ -312,7 +319,11 @@ export function heavyBullets(
 
     // The joining space a wrapped line would have carried, so folding two
     // source lines measures what one unwrapped line would have.
-    if (open) open = { ...open, characters: open.characters + text.length + 1 }
+    if (open)
+      open = {
+        ...open,
+        characters: open.characters + visibleText(text).length + 1,
+      }
   }
 
   close()
@@ -353,16 +364,13 @@ export function heavyParagraphs(
     if (block.length > 0) {
       const text = block.map((line) => line.text.trim()).join(' ')
       const sentences = countSentences(text)
+      const characters = visibleText(text).length
 
       if (
         sentences > checkpoints.sentences ||
-        text.length > checkpoints.paragraph
+        characters > checkpoints.paragraph
       ) {
-        findings.push({
-          line: block[0].number,
-          sentences,
-          characters: text.length,
-        })
+        findings.push({ line: block[0].number, sentences, characters })
       }
     }
     block = []