@erclx/aitk 0.29.0 → 0.30.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.29.0",
+  "version": "0.30.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents.md

@@ -80,7 +80,7 @@ Full help: `aitk <command> --help`.
 | `aitk transcripts <url>` | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                          |
 | `aitk tasks archive`     | Move a shipped task off the board, clear its ordering row, and regenerate the index            |
 | `aitk comments scan`     | Measure comment density by language and comment kind, with a trend recomputed from git         |
-| `aitk context audit`     | Report entry length, depth, cited-path resolution, and index drift in the context folders      |
+| `aitk context audit`     | Report entry length, depth, cited-path resolution, provenance, and index drift                 |
 | `aitk capture [source]`  | Render HTML capture sources to PNG, toolkit-only and absent from an installed package          |
 
 ### Domain commands
@@ -387,7 +387,7 @@ aitk context audit --folder context,diagrams
 
 Scope defaults to `context`, `diagrams`, and `wireframes`, and a folder the project does not carry is skipped rather than reported. A domain that outgrew one file and split into `<domain>/` is audited as its own folder, so a split entry measures at the same grain as a flat one.
 
-Exit codes are `0` for a clean run, `1` for a refusal, and `2` for an unresolved citation. Only the citation check sets a failing code. Length, depth, table, and index findings print and return `0`, because each is a judgment threshold and failing a push on one would make the check something to route around.
+Exit codes are `0` for a clean run, `1` for a refusal, and `2` for an unresolved citation. Only the citation check sets a failing code. Length, depth, table, provenance, and index findings print and return `0`, because each is a judgment and failing a push on one would make the check something to route around.
 
 ### What each check reports
 
@@ -395,6 +395,8 @@ Length and depth quote their checkpoints from `.claude/standards/context.md`: ro
 
 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.
+
 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.
 
 ### The citation gate

package/package.json

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

package/src/commands/context.ts

@@ -45,7 +45,9 @@ export function register(program: Command): void {
 
   context
     .command('audit')
-    .description('Report entry length, depth, citations, and index drift')
+    .description(
+      'Report entry length, depth, citations, provenance, and index drift',
+    )
     .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')
     .option('--json', 'Add a machine-readable record on stdout')
@@ -61,7 +63,7 @@ export function register(program: Command): void {
         '  2  a cited path did not resolve',
         '',
         'Only unresolved citations set a failing exit code. Length, depth,',
-        'table, and index findings are advisory.',
+        'table, provenance, and index findings are advisory.',
         '',
         'Examples:',
         '  aitk context audit',
@@ -134,6 +136,7 @@ async function runAudit(
     reportLength(entries)
     reportDepth(entries)
     reportTables(entries)
+    reportProvenance(entries)
     reportDrift(drift)
     outro()
   }
@@ -303,6 +306,46 @@ function reportTables(entries: readonly EntryReport[]): void {
   pipeOutput(candidates.join('\n'))
 }
 
+/**
+ * Groups by entry rather than listing every marker.
+ *
+ * The two entries carrying most of a corpus's markers carry them a dozen at a
+ * time, and a flat list of those buries the entries holding one. What a reader
+ * acts on is which file to open, so the count sits beside the name and the
+ * lines follow it.
+ */
+function reportProvenance(entries: readonly EntryReport[]): void {
+  logStep('Provenance')
+  logInfo('Fenced blocks are excluded. A marker is a judgment, never a defect.')
+
+  const carrying = entries
+    .filter((entry) => entry.provenance.length > 0)
+    .sort((a, b) => b.provenance.length - a.provenance.length)
+
+  if (carrying.length === 0) {
+    logInfo('No entry narrates a change.')
+    return
+  }
+
+  const total = carrying.reduce(
+    (sum, entry) => sum + entry.provenance.length,
+    0,
+  )
+  logWarn(
+    `${plural(total, 'marker')} across ${carrying.length} ${carrying.length === 1 ? 'entry' : 'entries'}`,
+  )
+  pipeOutput(
+    carrying
+      .map(
+        (entry) =>
+          `${entry.rel}  ${plural(entry.provenance.length, 'marker')}\n${entry.provenance
+            .map((found) => `  :${found.line}  ${found.kind}  ${found.text}`)
+            .join('\n')}`,
+      )
+      .join('\n'),
+  )
+}
+
 function reportDrift(drift: readonly FolderDrift[]): void {
   logStep('Index drift')
 

package/src/context/audit.ts

@@ -25,11 +25,35 @@ const TABLE_ROW = /^\s*\|/
 const TABLE_SEPARATOR = /^\s*\|[\s:|-]+\|\s*$/
 const NAMED_CELL = /`[^`]+`|\[[^\]]+\]\([^)]+\)/
 
+/**
+ * Spellings of how the domain reached its shape rather than what it is now.
+ *
+ * The standard admits a rejected alternative and its reasoning while refusing
+ * the provenance attached to it, and these three are what a session reaches for
+ * when it records the second: when a change landed, which change carried it,
+ * and which release labelled it. A marker is a judgment rather than a defect,
+ * so this is measured and reported and never gates.
+ */
+const PROVENANCE: readonly { kind: ProvenanceKind; pattern: RegExp }[] = [
+  { kind: 'date', pattern: /\b\d{4}-\d{2}-\d{2}\b/g },
+  { kind: 'change', pattern: /#\d{3,}\b/g },
+  { kind: 'release', pattern: /\bv\d+\.\d+(?:\.\d+)?\b/g },
+]
+
+export type ProvenanceKind = 'date' | 'change' | 'release'
+
 export interface TableFinding {
   readonly line: number
   readonly rows: number
 }
 
+export interface ProvenanceFinding {
+  readonly line: number
+  readonly kind: ProvenanceKind
+  /** The marker as written, so a report names what to go and look at. */
+  readonly text: string
+}
+
 export interface EntryReport {
   readonly rel: string
   readonly lines: number
@@ -37,6 +61,7 @@ export interface EntryReport {
   /** First line of the longest run, or 0 when the entry has no run at all. */
   readonly longestRunLine: number
   readonly catalogTables: readonly TableFinding[]
+  readonly provenance: readonly ProvenanceFinding[]
 }
 
 interface BodyLine {
@@ -191,6 +216,44 @@ function catalogTables(lines: readonly BodyLine[]): TableFinding[] {
   return findings
 }
 
+/**
+ * Finds the markers narrating a change rather than describing the domain.
+ *
+ * Fenced blocks are skipped for the same reason the table scan skips them: a
+ * sample command or a fixture inside an example is content the entry displays
+ * rather than a claim it makes, and a version pinned in an install line is the
+ * ordinary shape of one.
+ */
+function provenance(lines: readonly BodyLine[]): ProvenanceFinding[] {
+  // Scanning one pattern at a time emits a line's markers grouped by kind, so
+  // the column is carried out of the match and sorted on. Without it a line
+  // holding a date and two change numbers reports them in an order the reader
+  // cannot find by scanning left to right.
+  const found: { finding: ProvenanceFinding; column: number }[] = []
+  let fenced = false
+
+  for (const line of lines) {
+    if (FENCE.test(line.text)) {
+      fenced = !fenced
+      continue
+    }
+    if (fenced) continue
+
+    for (const { kind, pattern } of PROVENANCE) {
+      for (const match of line.text.matchAll(pattern)) {
+        found.push({
+          finding: { line: line.number, kind, text: match[0] },
+          column: match.index,
+        })
+      }
+    }
+  }
+
+  return found
+    .sort((a, b) => a.finding.line - b.finding.line || a.column - b.column)
+    .map((each) => each.finding)
+}
+
 export function measureEntry(rel: string, source: string): EntryReport {
   const lines = bodyLines(source)
   const run = longestRun(lines)
@@ -201,6 +264,7 @@ export function measureEntry(rel: string, source: string): EntryReport {
     longestRun: run.length,
     longestRunLine: run.line,
     catalogTables: catalogTables(lines),
+    provenance: provenance(lines),
   }
 }
 

package/standards/context.md

@@ -94,11 +94,13 @@ Only the `development` entry carries this section. It is not a general-purpose h
 - Tutorials or human onboarding. Those go in `docs/` if a public audience exists.
 - Generated content (API references). Generate, do not write by hand.
 - Anything already in `.claude/REQUIREMENTS.md` or `.claude/ARCHITECTURE.md`.
+- The history of how the domain reached its current shape. An entry describes the repository as it stands, so a change number, release label, or date attached to a change goes wherever the project tracks work.
+- A rejected alternative's provenance, which is the same rule at the one place the section above admits history. Keep what was tried and why it lost. Cut who tried it and when.
 
 ## Length
 
 - Aim for one entry per domain. There is no hard cap. Length is a symptom, not the defect.
-- Past roughly 150 lines, check two things before adding more: whether the entry still covers a single domain, and whether it has filled with content `ls` or `--help` reproduces. Fix whichever is true rather than trimming to hit a number.
+- 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.
 - Never cut a `## Decisions` or `## Gotchas` entry to shorten a file. Cut a `## Layout` or `## CLI` section instead.