@erclx/aitk 0.31.0 → 0.32.0

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

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

package/docs/agents.md

@@ -391,11 +391,13 @@ Exit codes are `0` for a clean run, `1` for a refusal, and `2` for an unresolved
 
 ### What each check reports
 
-Length and depth quote their checkpoints from `.claude/standards/context.md`: roughly 150 lines for an entry, roughly 40 for a run of lines no heading breaks. Depth measures the longest such run rather than everything under one `##`, skips fenced blocks so a markdown example does not read as three headings, and exempts a run whose lines are all list items at one indent. Runs count blank lines, which the standard leaves open, so a hand reader who drops them lands a line or two lower. The report states the convention on every run.
+Length and depth quote their checkpoints from `.claude/standards/context.md`: roughly 150 rendered lines for an entry, roughly 40 for a run no heading breaks. Depth measures the longest such run rather than everything under one `##`, skips fenced blocks so a markdown example does not read as three headings, and exempts a run whose lines are all list items at one indent averaging under 130 characters. The weight condition is what separates a scannable catalog of one-liners from a stack of paragraph-bullets, which reach the same count and read nothing alike.
+
+Both checks count 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. Measuring one checkpoint in each unit would put an entry length beside a run length that mean different things. Their exclusions still differ: the file measure counts fenced blocks and frontmatter, while the run measure skips a fence so an example cannot break the run around it. A reference-heavy entry therefore ranks by its examples, which the length legend states on every run. Runs count blank lines, which the standard leaves open, so a hand reader who drops them lands a line or two lower. Both sections state the width on every run, since a number in rendered lines cannot be reproduced without it.
 
 The table check reports a catalog that grows a row per shipped thing, not a table count. A fixed comparison table never reflows, so its size costs nothing. A table qualifies at six or more body rows whose first column mostly carries a path, command, or link, which is what separates a catalog from a comparison without reading the prose.
 
-The provenance check reports the markers narrating how a domain reached its shape rather than describing what it is: a date, a change number, or a release label. The standard admits a rejected alternative and the reasoning that killed it while refusing the provenance attached to it, so a marker names a line to read rather than a line to delete. Findings group by entry and sort left to right within a line, since what a reader acts on is which file to open. Fenced blocks are excluded, which keeps a pinned version in an install command from reading as a claim the entry makes. Frontmatter is excluded with them, since every check reads the body alone, and that is what keeps a diagram entry's dated `verified` stamp a record of its last check rather than a marker to settle.
+The provenance check reports the markers narrating how a domain reached its shape rather than describing what it is: a date, a change number, or a release label. The standard admits a rejected alternative and the reasoning that killed it while refusing the provenance attached to it, so a marker names a line to read rather than a line to delete. Findings group by entry and sort left to right within a line, since what a reader acts on is which file to open. Fenced blocks are excluded, which keeps a pinned version in an install command from reading as a claim the entry makes. Frontmatter is excluded with them, since the content checks read the body alone, and that is what keeps a diagram entry's dated `verified` stamp a record of its last check rather than a marker to settle. Length is the exception, counting the whole file, so a reader applying the 150-rendered-line checkpoint against the body alone lands a few lines under what the tool reports.
 
 Index drift compares an index against its siblings in both directions. An entry the index does not link is invisible to a session choosing what to open, and a linked name resolving to nothing sends one to a path that opens nothing.
 

package/package.json

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

package/src/commands/context.ts

@@ -4,6 +4,8 @@ import {
   type EntryReport,
   LENGTH_CHECKPOINT,
   measureFolders,
+  PEER_BULLET_CHECKPOINT,
+  RENDER_WIDTH,
   RUN_CHECKPOINT,
 } from '@/context/audit'
 import { auditCitations, type CitationReport } from '@/context/citations'
@@ -160,6 +162,8 @@ async function runAudit(
           lines: LENGTH_CHECKPOINT,
           run: RUN_CHECKPOINT,
           runCountsBlankLines: true,
+          renderWidth: RENDER_WIDTH,
+          peerBullet: PEER_BULLET_CHECKPOINT,
         },
       })}\n`,
     )
@@ -241,6 +245,12 @@ function reportCitations(report: ScannedCitations): void {
 
 function reportLength(entries: readonly EntryReport[]): void {
   logStep('Length')
+  logInfo(
+    `Entries measure rendered lines at ${RENDER_WIDTH} columns, counting frontmatter and fenced blocks.`,
+  )
+  logInfo(
+    'A reference-heavy entry therefore ranks by its examples, which the depth check excludes.',
+  )
 
   const over = entries
     .filter((entry) => entry.lines > LENGTH_CHECKPOINT)
@@ -253,20 +263,29 @@ function reportLength(entries: readonly EntryReport[]): void {
 
   logWarn(`${over.length} past the ${LENGTH_CHECKPOINT}-line checkpoint`)
   pipeOutput(
-    over.map((entry) => `${entry.rel}  ${entry.lines} lines`).join('\n'),
+    over
+      .map((entry) => `${entry.rel}  ${entry.lines} rendered lines`)
+      .join('\n'),
   )
 }
 
 /**
- * Names the blank-line convention on every run.
+ * Names the render width and the blank-line convention on every run.
  *
  * The standard settles heading level and fenced blocks and stops there, so a
  * hand reader who drops blank lines lands a line or two below this number.
- * Stating it is what keeps the two measurements reconcilable.
+ * Stating both is what keeps the two measurements reconcilable, and the width
+ * matters more than the blank lines because a number counted in rendered lines
+ * cannot be reproduced without it.
  */
 function reportDepth(entries: readonly EntryReport[]): void {
   logStep('Depth')
-  logInfo('Runs count blank lines. Fenced blocks and peer lists are excluded.')
+  logInfo(
+    `Runs measure rendered lines at ${RENDER_WIDTH} columns and count blank lines.`,
+  )
+  logInfo(
+    `Fenced blocks are excluded, and so are peer lists averaging under ${PEER_BULLET_CHECKPOINT} characters a bullet.`,
+  )
 
   const over = entries
     .filter((entry) => entry.longestRun > RUN_CHECKPOINT)
@@ -282,7 +301,7 @@ function reportDepth(entries: readonly EntryReport[]): void {
     over
       .map(
         (entry) =>
-          `${entry.rel}:${entry.longestRunLine}  ${entry.longestRun} lines unbroken`,
+          `${entry.rel}:${entry.longestRunLine}  ${entry.longestRun} rendered lines unbroken`,
       )
       .join('\n'),
   )

package/src/context/audit.ts

@@ -6,6 +6,27 @@ import type { AuditedFolder } from '@/context/folders'
 export const LENGTH_CHECKPOINT = 150
 export const RUN_CHECKPOINT = 40
 
+/**
+ * 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.
+ * The common terminal and diff width is the reproducible choice, and the report
+ * legend states it so a reader can arrive at the same number by hand.
+ */
+export const RENDER_WIDTH = 80
+
+/**
+ * Characters a bullet averages before its list stops reading as a set of peers.
+ *
+ * The exemption below covers a flat catalog of one-liners and a stack of
+ * paragraphs equally, and only the first is navigable. Measured across this
+ * corpus the two shapes separate with nothing between roughly 100 and 170
+ * characters a bullet, so the midpoint splits the population rather than a
+ * continuum. It is a checkpoint like the two above, not a cap.
+ */
+export const PEER_BULLET_CHECKPOINT = 130
+
 /**
  * A table this size or larger whose first column mostly names artifacts reads
  * as a catalog that grows a row per shipped thing, which is the shape the
@@ -56,7 +77,20 @@ export interface ProvenanceFinding {
 
 export interface EntryReport {
   readonly rel: string
+  /**
+   * Rendered lines across the whole file, counting frontmatter and fenced
+   * blocks. Both this and `longestRun` measure in the same unit, since the two
+   * checkpoints they feed sit in one section of the standard and a reader
+   * compares them.
+   *
+   * The exclusions differ on purpose. `longestRun` skips a fence so an example
+   * cannot break the run around it, and a file measure has no run to protect.
+   * Excluding fences here would change which entries report by one and would
+   * not reach the case that motivates it: the most fenced entry in the corpus
+   * runs 20 percent fenced and sits past the checkpoint either way.
+   */
   readonly lines: number
+  /** Rendered lines at `RENDER_WIDTH`, not source lines. */
   readonly longestRun: number
   /** First line of the longest run, or 0 when the entry has no run at all. */
   readonly longestRunLine: number
@@ -90,24 +124,44 @@ function bodyLines(source: string): BodyLine[] {
  *
  * Every non-blank line has to be a list item at one indent. Prose mixed into
  * the run or a nested level inside it ends the exemption, because either one
- * means the block is no longer a flat set a reader can skim.
+ * means the block is no longer a flat set a reader can skim. Bullet count says
+ * nothing on its own, since a catalog of one-liners and a wall of paragraphs
+ * reach the same count and read nothing alike, so the average bullet is what
+ * decides whether the set is still skimmable.
  */
-function isPeerList(run: readonly BodyLine[]): boolean {
+function isScannablePeerList(run: readonly BodyLine[]): boolean {
   const indents = new Set<number>()
+  let items = 0
+  let characters = 0
 
   for (const line of run) {
-    if (line.text.trim() === '') continue
+    const text = line.text.trim()
+    if (text === '') continue
 
     const match = line.text.match(LIST_ITEM)
     if (!match) return false
     indents.add(match[1].length)
+    items++
+    characters += text.length
   }
 
-  return indents.size === 1
+  if (indents.size !== 1) return false
+
+  return characters / items < PEER_BULLET_CHECKPOINT
 }
 
 /**
- * Measures the longest run of lines no heading breaks.
+ * Height a source line occupies once wrapped.
+ *
+ * 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.
+ */
+function renderedHeight(text: string): number {
+  return Math.max(1, Math.ceil(text.length / RENDER_WIDTH))
+}
+
+/**
+ * Measures the longest run of lines no heading breaks, in rendered lines.
  *
  * Fenced blocks are skipped rather than treated as breaks, per the standard:
  * they leave the count without ending the run, so prose either side of an
@@ -116,6 +170,11 @@ function isPeerList(run: readonly BodyLine[]): boolean {
  * between signposts and a blank line is distance like any other. A hand reader
  * measuring without them lands one or two lines lower, which the report legend
  * states.
+ *
+ * Height is what a reader travels, and source lines only stand in for it while
+ * lines stay short. An entry authored one line per bullet puts a paragraph on
+ * each, so a block of fifteen bullets measures as fifteen and renders past
+ * sixty. Wrapping every line at a stated width is what closes that gap.
  */
 function longestRun(lines: readonly BodyLine[]): {
   length: number
@@ -132,9 +191,16 @@ function longestRun(lines: readonly BodyLine[]): {
     // two headings rather than a stretch a reader travels, so it never counts.
     const first = run.find((line) => line.text.trim() !== '')
 
-    if (first && run.length > longest && !isPeerList(run)) {
-      longest = run.length
-      longestLine = first.number
+    if (first && !isScannablePeerList(run)) {
+      const height = run.reduce(
+        (sum, line) => sum + renderedHeight(line.text),
+        0,
+      )
+
+      if (height > longest) {
+        longest = height
+        longestLine = first.number
+      }
     }
     run = []
   }
@@ -260,7 +326,10 @@ export function measureEntry(rel: string, source: string): EntryReport {
 
   return {
     rel,
-    lines: source.replace(/\n$/, '').split('\n').length,
+    lines: source
+      .replace(/\n$/, '')
+      .split('\n')
+      .reduce((sum, text) => sum + renderedHeight(text), 0),
     longestRun: run.length,
     longestRunLine: run.line,
     catalogTables: catalogTables(lines),

package/standards/context.md

@@ -100,9 +100,10 @@ Only the `development` entry carries this section. It is not a general-purpose h
 ## Length
 
 - Aim for one entry per domain. There is no hard cap. Length is a symptom, not the defect.
-- Past roughly 150 lines, check three things before adding more: whether the entry still covers a single domain, whether it has filled with content `ls` or `--help` reproduces, and whether it has accumulated the history of its own changes. Fix whichever is true rather than trimming to hit a number.
-- Past roughly 40 lines with no heading of any level breaking them, add a subheading at the seam. Measure the longest such run rather than everything under one `##`, and exclude fenced code blocks. The number is a checkpoint like the 150 above, not a cap.
-- Exempt a block whose lines are all list items at one level. A long list of peers is already navigable, and a subheading dropped into it splits a set that belongs together. Mixing prose with the list, or nesting levels inside it, ends the exemption.
+- Past roughly 150 rendered lines, check three things before adding more: whether the entry still covers a single domain, whether it has filled with content `ls` or `--help` reproduces, and whether it has accumulated the history of its own changes. Fix whichever is true rather than trimming to hit a number.
+- Past roughly 40 rendered lines with no heading of any level breaking them, add a subheading at the seam. Measure the longest such run rather than everything under one `##`, and exclude fenced code blocks. The number is a checkpoint like the 150 above, not a cap.
+- Both checkpoints count rendered lines, so wrap each source line at 80 columns and sum the heights. Source lines undercount an entry authored one line per bullet, where a block of fifteen paragraph-bullets occupies fifteen lines and renders past sixty. Counting the two checkpoints in different units would put a file measured one way beside a run measured another.
+- Exempt a block whose lines are all list items at one level averaging under roughly 130 characters. A flat list of short peers is already navigable, and a subheading dropped into it splits a set that belongs together. Bullet count says nothing on its own, since a catalog of one-liners and a stack of paragraphs reach the same count and read nothing alike, so weight is what decides. Mixing prose with the list, or nesting levels inside it, ends the exemption at any weight.
 - Never cut a `## Decisions` or `## Gotchas` entry to shorten a file. Cut a `## Layout` or `## CLI` section instead.
 - Split into a folder (`.claude/context/<domain>/<sub-area>.md`) when a domain has three or more sub-areas that do not fit cleanly in one file. That split is the natural ceiling.
 - Keep a split domain's `index.md` generated. The catalog body is rewritten on every regen, so the domain's own overview and layout belong in a sibling file rather than in it, and the `subtitle` is what names the file to start with.