@erclx/aitk 0.106.0 → 0.107.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.106.0",
+  "version": "0.107.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -39,6 +39,12 @@ A line is wrapped at the width it renders at, so a link counts as its anchor tex
 
 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.
 
+Every entry past the checkpoint carries the three questions the standard asks of it rather than a count alone: whether it still covers one domain, whether it has filled with content `ls` or `--help` reproduces, and whether it has accumulated the history of its own changes. The checkpoint is not a cap, so the count is not the finding. What a reader acts on is which question came back true, and the standard directs the fix at that rather than at the number.
+
+Only the third is mechanical, and it is the provenance check already reported below, so the length finding cites that count rather than measuring it again. An entry outside the governed folder reads open there too, since provenance is scoped to the standard stating it and a clean list there is a scan that never ran. The other two stay open beside every entry, because whether a domain is still one domain is a judgment about its subject and recognizing reproduced content needs a reader who knows what those commands emit. Omitting them would read as an entry nothing found rather than one nothing checked.
+
+It reports and never gates, which the standard settles rather than the usual judgment-against-fact line: there is no hard cap, so an entry that answers all three and is still long is a correct outcome. The JSON record carries the joined findings as `length`, each with a `causes` array in the standard's order, and the jurisdiction the join reads as `entries[].governed`. That flag is what parts a provenance list measured and empty from one never scanned, which the count alone cannot say. The join is published rather than left to a consumer, since deriving it means restating which question the provenance count answers.
+
 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.
 
 ## Tables

package/package.json

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

package/src/commands/context.ts

@@ -3,6 +3,10 @@ import type { Command } from 'commander'
 import {
   type EntryReport,
   governsContent,
+  type LengthCause,
+  type LengthFinding,
+  lengthFindings,
+  type LengthQuestion,
   LENGTH_CHECKPOINT,
   matchesSiblings,
   measureFolders,
@@ -200,6 +204,7 @@ async function runAudit(
       )
   const drift = gateOnly ? [] : await auditIndexes(folders)
   const sections = gateOnly ? [] : missingSections(root, folders, entries)
+  const length = gateOnly ? undefined : lengthFindings(entries)
 
   if (gateOnly) {
     reportGate(citations)
@@ -209,7 +214,7 @@ async function runAudit(
     reportCitations(citations, cited)
     reportReferenceForm(entries, folders)
     reportSections(sections, folders)
-    reportLength(entries)
+    reportLength(length ?? [])
     reportTables(entries)
     reportProvenance(entries, folders)
     reportNarration(entries, folders, narration)
@@ -234,6 +239,16 @@ async function runAudit(
           unresolved: citations.unresolved,
         },
         entries,
+        // The join is published rather than left to a consumer, since deriving
+        // it from `entries` means restating which question the provenance count
+        // answers, and one wrong restatement is a cause reported against the
+        // wrong entry.
+        //
+        // Absent rather than empty under `--citations-only`, for the reason
+        // `checkpoints.narration` below carries. That mode measures no entry,
+        // so an empty array here reads as a corpus with nothing past the
+        // checkpoint rather than as a run that never looked.
+        length,
         missingSections: sections,
         indexDrift: drift,
         checkpoints: {
@@ -475,7 +490,32 @@ function reportSections(
   )
 }
 
-function reportLength(entries: readonly EntryReport[]): void {
+/** How each question reads in the report, in the standard's own order. */
+const QUESTION_LABEL: Record<LengthQuestion, string> = {
+  domain: 'one domain',
+  reproduced: 'reproduced content',
+  history: 'own history',
+}
+
+function readCause(cause: LengthCause): string {
+  const label = QUESTION_LABEL[cause.question]
+
+  if (cause.state === 'unanswered') return `${label}: open`
+  if (cause.state === 'no') return `${label}: no`
+
+  return `${label}: yes, ${plural(cause.markers ?? 0, 'marker')}`
+}
+
+/**
+ * Names each entry past the checkpoint with the three questions the standard
+ * asks of it, rather than a count a reader has to cross-reference by eye.
+ *
+ * The checkpoint is not a cap, so the legend says what the list is for. An
+ * entry that answers all three and is still long is a correct outcome under a
+ * standard stating there is no hard cap, and a run reporting success as a
+ * smaller count would have adopted the number the standard declines.
+ */
+function reportLength(over: readonly LengthFinding[]): void {
   logStep('Length')
   logInfo(
     `Entries measure rendered lines at ${RENDER_WIDTH} columns, counting frontmatter and fenced blocks.`,
@@ -484,19 +524,26 @@ function reportLength(entries: readonly EntryReport[]): void {
     'A reference-heavy entry therefore ranks by its examples, which the depth check in `aitk markdown audit` excludes.',
   )
 
-  const over = entries
-    .filter((entry) => entry.lines > LENGTH_CHECKPOINT)
-    .sort((a, b) => b.lines - a.lines)
-
   if (over.length === 0) {
     logInfo(`No entry past the ${LENGTH_CHECKPOINT}-line checkpoint.`)
     return
   }
 
   logWarn(`${over.length} past the ${LENGTH_CHECKPOINT}-line checkpoint`)
+  logInfo(
+    'The checkpoint is not a cap. Each entry carries the three questions the standard asks past it, and the fix goes to whichever is true.',
+  )
+  logInfo(
+    'Own history is answered from the provenance markers below. The other two are judgments no measure settles, so they stay open for a reader.',
+  )
   pipeOutput(
     over
-      .map((entry) => `${entry.rel}  ${entry.lines} rendered lines`)
+      .map(
+        (finding) =>
+          `${finding.rel}  ${finding.lines} rendered lines\n  ${finding.causes
+            .map(readCause)
+            .join('  ')}`,
+      )
       .join('\n'),
   )
 }

package/src/context/audit.ts

@@ -166,6 +166,52 @@ export interface EntryReport {
    * exempt from owing sections rather than from being well formed.
    */
   readonly stub: boolean
+  /**
+   * Whether a content rule reached this entry, which is what parts an empty
+   * `provenance` list that was measured from one that was never scanned. The
+   * length finding reads it, since reporting a clean history for an entry
+   * outside the governed folder answers a question nothing asked.
+   */
+  readonly governed: boolean
+}
+
+/**
+ * The three questions `standards/context.md` asks of an entry past the
+ * checkpoint, in the order it states them.
+ *
+ * The standard calls no entry over the checkpoint wrong. It asks 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, then directs a fix at whichever is true. A report naming the count
+ * alone leaves all three unasked, which is why the finding carries them.
+ */
+export type LengthQuestion = 'domain' | 'reproduced' | 'history'
+
+/**
+ * What the audit can say about one question for one entry.
+ *
+ * `unanswered` is a state rather than an omission. Two of the three questions
+ * are judgments no measure settles, and dropping them would read as an entry
+ * nothing found rather than one nothing checked.
+ */
+export type QuestionState = 'yes' | 'no' | 'unanswered'
+
+export interface LengthCause {
+  readonly question: LengthQuestion
+  readonly state: QuestionState
+  /**
+   * Markers behind a `yes`, and absent wherever nothing was counted. It cites
+   * the provenance finding rather than restating it, so the two sections of the
+   * report describe the same measurement once.
+   */
+  readonly markers?: number
+}
+
+export interface LengthFinding {
+  readonly rel: string
+  readonly lines: number
+  /** One entry per question in `LengthQuestion` order, never empty. */
+  readonly causes: readonly LengthCause[]
 }
 
 export interface SectionFinding {
@@ -481,9 +527,52 @@ export function measureEntry(
     bareReferences: bareReferences(lines, siblings),
     sections: governsContent ? declaredSections(lines) : [],
     stub: isStubSeed(source),
+    governed: governsContent,
   }
 }
 
+/**
+ * Names each entry past the checkpoint with the standard's three questions
+ * answered as far as anything measures them.
+ *
+ * Only accumulated history is mechanical, and it is already measured by the
+ * provenance check, so this joins that count rather than counting again. The
+ * other two are read by a person: whether an entry still covers one domain is a
+ * judgment about its subject, and recognizing content `ls` or `--help`
+ * reproduces needs a reader who knows what those emit.
+ *
+ * An entry outside the governed folder has no measured question at all, since
+ * provenance is scoped to the standard stating it, and reporting `no` there
+ * would answer from a scan that never ran.
+ *
+ * Sorted longest first, which is the order the report already printed and the
+ * order the questions are worth asking in.
+ */
+export function lengthFindings(
+  entries: readonly EntryReport[],
+): LengthFinding[] {
+  return entries
+    .filter((entry) => entry.lines > LENGTH_CHECKPOINT)
+    .sort((a, b) => b.lines - a.lines)
+    .map((entry) => ({
+      rel: entry.rel,
+      lines: entry.lines,
+      causes: [
+        { question: 'domain', state: 'unanswered' },
+        { question: 'reproduced', state: 'unanswered' },
+        historyCause(entry),
+      ] satisfies LengthCause[],
+    }))
+}
+
+function historyCause(entry: EntryReport): LengthCause {
+  if (!entry.governed) return { question: 'history', state: 'unanswered' }
+
+  return entry.provenance.length > 0
+    ? { question: 'history', state: 'yes', markers: entry.provenance.length }
+    : { question: 'history', state: 'no' }
+}
+
 /**
  * Measures every entry in the audited folders. A generated `index.md` is not
  * among them, since its body is rewritten on every regen and no checkpoint