@erclx/aitk 0.36.0 → 0.37.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.36.0",
+  "version": "0.37.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, bullet weight, cited-path resolution, provenance, and index drift  |
+| `aitk context audit`     | Report required sections, length, depth, bullet weight, cited paths, provenance, and drift     |
 | `aitk capture [source]`  | Render HTML capture sources to PNG, toolkit-only and absent from an installed package          |
 
 ### Domain commands
@@ -387,10 +387,16 @@ 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, bullet weight, 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.
+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. Required-section, length, depth, bullet weight, 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
 
+The required-section check reports what does not declare `## Overview` and `## Layout`, the two sections `.claude/standards/context.md` marks required. The list is held in code beside the numeric checkpoints rather than parsed out of the standard, so it fails on a defect rather than on a rewrite of the wording around it. A heading at any level counts, because a domain that split into a folder carries its overview in a sibling named `overview.md` where the section is the `#` title and an `##` beneath it would repeat the filename. Matching exactly is what keeps `## Layout catalog` from satisfying `Layout`.
+
+Which unit answers depends on the folder. Entries of the folder named under `.claude/` are one domain each, so each answers for itself and a finding names the entry. Entries of a folder a domain split into describe that one domain between them, so any sibling answers and a finding names the folder. Holding a split folder to the rule per file would report every child beside its `overview.md`, and rolling the named folder up would let one conforming entry stand in for every other domain sitting next to it.
+
+It reports rather than gates, the closer call because a missing section reads more like a fact than the other judgments. What settles it is that the standard sanctions omitting `## Layout` from a domain owning no paths in the repo, and no measure separates that from an entry that forgot it. A domain covering only external tools is that case, and it reports on every run. The JSON record carries the findings as `missingSections` and the list as `checkpoints.requiredSections`.
+
 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.
@@ -401,7 +407,7 @@ The table check reports a catalog that grows a row per shipped thing, not a tabl
 
 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.
 
-The provenance and bullet-weight checks cover `.claude/context/` alone, while length, depth, and the table finding reach every audited folder. The rule is stated in `.claude/standards/context.md`, which opens its scope by handing diagrams and wireframes to `diagrams.md` and `wireframes.md`, and the sibling standards do not restate it. A marker reported in a diagram entry would cite a rule that entry's own standard routes elsewhere. The split is between kinds of rule rather than kinds of folder, and what decides it is whether the remedy is actionable rather than what the check measures. Subdividing a run and splitting a file mean something in any entry, so length and depth generalize. Moving an incident out of a bullet and keeping the decision means nothing in a folder whose entries declare no decisions, which is why bullet weight narrows despite measuring a distance like the two that do not. The scoping key is the folder an entry was audited under, so `--folder` still reaches a folder the default list does not carry, and a domain split into `context/<sub-area>/` is governed as `context`. Every run states the reach, including a run where no audited folder is the governed one. The JSON record carries it as `checkpoints.provenanceFolder` and a per-folder `governsContent`.
+The provenance, bullet-weight, and required-section checks cover `.claude/context/` alone, while length, depth, and the table finding reach every audited folder. The rule is stated in `.claude/standards/context.md`, which opens its scope by handing diagrams and wireframes to `diagrams.md` and `wireframes.md`, and the sibling standards do not restate it. A marker reported in a diagram entry would cite a rule that entry's own standard routes elsewhere. The split is between kinds of rule rather than kinds of folder, and what decides it is whether the remedy is actionable rather than what the check measures. Subdividing a run and splitting a file mean something in any entry, so length and depth generalize. Moving an incident out of a bullet and keeping the decision means nothing in a folder whose entries declare no decisions, which is why bullet weight narrows despite measuring a distance like the two that do not. Required sections narrow for a plainer reason: the names are the context standard's own, and neither sibling standard states a required section at all. The scoping key is the folder an entry was audited under, so `--folder` still reaches a folder the default list does not carry, and a domain split into `context/<sub-area>/` is governed as `context`. Every run states the reach, including a run where no audited folder is the governed one. The JSON record carries it as `checkpoints.provenanceFolder` and a per-folder `governsContent`.
 
 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.36.0",
+  "version": "0.37.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/commands/context.ts

@@ -6,10 +6,13 @@ import {
   governsContent,
   LENGTH_CHECKPOINT,
   measureFolders,
+  missingSections,
   PEER_BULLET_CHECKPOINT,
   PROVENANCE_FOLDER,
   RENDER_WIDTH,
+  REQUIRED_SECTIONS,
   RUN_CHECKPOINT,
+  type SectionFinding,
 } from '@/context/audit'
 import { auditCitations, type CitationReport } from '@/context/citations'
 import {
@@ -51,7 +54,7 @@ export function register(program: Command): void {
   context
     .command('audit')
     .description(
-      'Report entry length, depth, bullet weight, citations, provenance, and index drift',
+      'Report required sections, entry length, depth, bullet weight, citations, provenance, and index drift',
     )
     .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')
@@ -67,8 +70,8 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr',
         '  2  a cited path did not resolve',
         '',
-        'Only unresolved citations set a failing exit code. Length, depth,',
-        'bullet, table, provenance, and index findings are advisory.',
+        'Only unresolved citations set a failing exit code. Section, length,',
+        'depth, bullet, table, provenance, and index findings are advisory.',
         '',
         'Examples:',
         '  aitk context audit',
@@ -131,6 +134,7 @@ async function runAudit(
 
   const entries = gateOnly ? [] : await measureFolders(root, folders)
   const drift = gateOnly ? [] : await auditIndexes(folders)
+  const sections = gateOnly ? [] : missingSections(root, folders, entries)
 
   if (gateOnly) {
     reportGate(citations)
@@ -138,6 +142,7 @@ async function runAudit(
     intro('aitk context audit')
     reportScope(folders)
     reportCitations(citations)
+    reportSections(sections, folders)
     reportLength(entries)
     reportDepth(entries)
     reportBullets(entries, folders)
@@ -162,6 +167,7 @@ async function runAudit(
           unresolved: citations.unresolved,
         },
         entries,
+        missingSections: sections,
         indexDrift: drift,
         checkpoints: {
           lines: LENGTH_CHECKPOINT,
@@ -171,6 +177,7 @@ async function runAudit(
           peerBullet: PEER_BULLET_CHECKPOINT,
           bullet: BULLET_CHECKPOINT,
           provenanceFolder: PROVENANCE_FOLDER,
+          requiredSections: REQUIRED_SECTIONS,
         },
       })}\n`,
     )
@@ -250,6 +257,49 @@ function reportCitations(report: ScannedCitations): void {
   )
 }
 
+/**
+ * Names the path each finding belongs to, which is an entry in the folder named
+ * under `.claude/` and the folder itself in a domain split across one. States
+ * the reach on every run for the reason the provenance report does.
+ *
+ * This prints ahead of the four readability measures because a missing section
+ * asks whether the entry is the right shape at all, which precedes asking
+ * whether it has grown too long.
+ */
+function reportSections(
+  missing: readonly SectionFinding[],
+  folders: readonly AuditedFolder[],
+): void {
+  logStep('Sections')
+
+  const governed = folders.filter(governsContent)
+  if (governed.length === 0) {
+    logInfo(
+      `Out of scope. The list is stated in the standard governing .claude/${PROVENANCE_FOLDER}/, and no audited folder is that one.`,
+    )
+    return
+  }
+
+  logInfo(
+    `Covers .claude/${PROVENANCE_FOLDER}/ alone, whose standard requires ${REQUIRED_SECTIONS.join(' and ')}.`,
+  )
+  logInfo(
+    'A heading at any level counts. Each entry answers for itself, except in a domain split across a folder, where a sibling answers for the rest.',
+  )
+
+  if (missing.length === 0) {
+    logInfo('Every entry declares each required section.')
+    return
+  }
+
+  logWarn(`${plural(missing.length, 'path')} short a required section`)
+  pipeOutput(
+    missing
+      .map((found) => `${found.rel}  missing: ${found.missing.join(', ')}`)
+      .join('\n'),
+  )
+}
+
 function reportLength(entries: readonly EntryReport[]): void {
   logStep('Length')
   logInfo(

package/src/context/audit.ts

@@ -50,9 +50,25 @@ export const CATALOG_ROW_CHECKPOINT = 6
 /** Share of first cells that must name an artifact for a table to qualify. */
 const CATALOG_NAMED_RATIO = 0.6
 
+/**
+ * Sections `standards/context.md` marks required, in the order it states them.
+ *
+ * The list is held here rather than read out of the standard, the way the four
+ * checkpoints above quote their numbers. A parser over the standard's prose
+ * would decide which sections are required from the wording around them, so it
+ * fails on a rewrite of that wording rather than on a defect in an entry.
+ *
+ * These names do not generalize the way a length threshold does, which is why
+ * the measure is scoped to the folder `governsContent` names. A diagram entry
+ * declares a heading per kind and a wireframe entry per screen, and neither
+ * sibling standard states a required section at all.
+ */
+export const REQUIRED_SECTIONS: readonly string[] = ['Overview', 'Layout']
+
 const FRONTMATTER = /^---\n[\s\S]*?\n---\n?/
 const FENCE = /^\s*(```|~~~)/
 const HEADING = /^#{1,6}\s/
+const HEADING_TEXT = /^#{1,6}\s+(.+?)\s*$/
 const LIST_ITEM = /^(\s*)([-*+]|\d+\.)\s+/
 const TABLE_ROW = /^\s*\|/
 const TABLE_SEPARATOR = /^\s*\|[\s:|-]+\|\s*$/
@@ -144,6 +160,23 @@ export interface EntryReport {
   readonly provenance: readonly ProvenanceFinding[]
   /** Empty for the same reason `provenance` is, and under the same folder. */
   readonly heavyBullets: readonly BulletFinding[]
+  /**
+   * Required sections this entry declares, in the standard's order, and empty
+   * outside the folder whose standard names them. What the folder is short of
+   * is `missingSections`, since one entry answers for its siblings.
+   */
+  readonly sections: readonly string[]
+}
+
+export interface SectionFinding {
+  /**
+   * Repo-relative path of whatever owes the sections: the entry itself in the
+   * folder named under `.claude/`, and the folder in a domain split across
+   * one, since the split folder's entries answer for each other.
+   */
+  readonly rel: string
+  /** Required sections the path above does not declare, never empty. */
+  readonly missing: readonly string[]
 }
 
 interface BodyLine {
@@ -422,6 +455,38 @@ function provenance(lines: readonly BodyLine[]): ProvenanceFinding[] {
     .map((each) => each.finding)
 }
 
+/**
+ * Finds which required sections the entry declares.
+ *
+ * A heading at any level counts rather than the `##` the standard writes its
+ * examples at. A domain that split into a folder puts its overview in a sibling
+ * named for it, where the section is the `#` title and an `##` beneath it would
+ * repeat the file's own name. All three split folders in this repository are
+ * that shape, so matching `##` alone would report every one of them. Nothing is
+ * titled for a required section without being about it, so the looser match
+ * costs no precision.
+ *
+ * Fenced blocks are skipped for the reason the scans above skip them. A
+ * standard quoted inside an example declares nothing about the entry quoting it.
+ */
+function declaredSections(lines: readonly BodyLine[]): string[] {
+  const found = new Set<string>()
+  let fenced = false
+
+  for (const line of lines) {
+    if (FENCE.test(line.text)) {
+      fenced = !fenced
+      continue
+    }
+    if (fenced) continue
+
+    const match = line.text.match(HEADING_TEXT)
+    if (match && REQUIRED_SECTIONS.includes(match[1])) found.add(match[1])
+  }
+
+  return REQUIRED_SECTIONS.filter((section) => found.has(section))
+}
+
 /**
  * Measures one entry, scanning for provenance only when a standard claims it.
  *
@@ -448,6 +513,7 @@ export function measureEntry(
     catalogTables: catalogTables(lines),
     provenance: governsContent ? provenance(lines) : [],
     heavyBullets: governsContent ? heavyBullets(lines) : [],
+    sections: governsContent ? declaredSections(lines) : [],
   }
 }
 
@@ -484,3 +550,56 @@ export async function measureFolders(
 export function governsContent(folder: AuditedFolder): boolean {
   return folder.name === PROVENANCE_FOLDER
 }
+
+/**
+ * Names what does not declare the sections the standard requires.
+ *
+ * Which unit answers depends on what the folder is. A split folder's entries
+ * describe one domain between them and carry the overview and the layout in a
+ * sibling named for them, so any one of them answers and a per-file rule there
+ * would report every other child of all three shipped splits. The entries of
+ * the folder named under `.claude/` are one domain each, so each answers for
+ * itself. Rolling those up too was the first shape of this check, and it let a
+ * single sibling stand in for thirteen domains it says nothing about.
+ *
+ * The judgment sits in the caller because the split case needs the folder's
+ * other entries, which `measureFolders` holds and `measureEntry` does not. A
+ * folder with no entries of its own is a split parent holding an index and
+ * subfolders, and it has nothing to require a section of.
+ *
+ * The standard sanctions omitting `## Layout` from a domain owning no paths,
+ * which no measure can tell from an entry that forgot it. An entry of that
+ * shape therefore reports, which is a reason this is printed and never gated on.
+ */
+export function missingSections(
+  root: string,
+  folders: readonly AuditedFolder[],
+  entries: readonly EntryReport[],
+): SectionFinding[] {
+  const byRel = new Map(entries.map((entry) => [entry.rel, entry]))
+  const findings: SectionFinding[] = []
+
+  const shortOf = (declared: readonly string[]): string[] =>
+    REQUIRED_SECTIONS.filter((name) => !declared.includes(name))
+
+  for (const folder of folders) {
+    if (!governsContent(folder) || folder.entries.length === 0) continue
+
+    const reports = folder.entries
+      .map((path) => byRel.get(relative(root, path)))
+      .filter((entry) => entry !== undefined)
+
+    if (folder.nested) {
+      const missing = shortOf(reports.flatMap((entry) => entry.sections))
+      if (missing.length > 0) findings.push({ rel: folder.rel, missing })
+      continue
+    }
+
+    for (const entry of reports) {
+      const missing = shortOf(entry.sections)
+      if (missing.length > 0) findings.push({ rel: entry.rel, missing })
+    }
+  }
+
+  return findings
+}

package/src/context/folders.ts

@@ -30,6 +30,16 @@ export interface AuditedFolder {
   readonly indexPath: string
   /** Absolute paths of the folder's own entries, excluding its `index.md`. */
   readonly entries: readonly string[]
+  /**
+   * Whether this is a sub-area a domain split into rather than the folder
+   * named under `.claude/`.
+   *
+   * The entries of a split folder describe one domain between them, so a rule
+   * about what a domain declares is answered by the folder. The entries of the
+   * named folder are one domain each, and a rule answered by a sibling there
+   * would let one entry stand in for domains it says nothing about.
+   */
+  readonly nested: boolean
 }
 
 /**
@@ -91,6 +101,7 @@ export async function resolveFolders(
         rel: relative(root, each),
         indexPath: `${each}/${INDEX_FILE}`,
         entries: await readEntries(each),
+        nested: each !== dir,
       })
     }
   }

package/tooling/base/seeds/.claude/context/ci.md

@@ -5,7 +5,13 @@ description: GitHub Actions workflow triggers and checks
 
 # CI
 
-GitHub Actions workflow for this project.
+## Overview
+
+Owns the GitHub Actions workflow that gates a merge: which events start a run, and which checks have to pass before the branch can land. The checks call package scripts rather than defining commands of their own, so what each one runs is the development entry's subject.
+
+## Layout
+
+- `.github/workflows/` owns the workflow definitions a trigger below starts
 
 ## Triggers
 

package/tooling/base/seeds/.claude/context/development.md

@@ -5,7 +5,14 @@ description: Local dev workflow, scripts, and husky hooks
 
 # Development
 
-Local dev workflow for this project.
+## Overview
+
+Owns how the project runs on a developer machine: installing the toolchain, the scripts that verify a change, and the git hooks that run them before a commit or a push leaves. CI calls the same scripts from a workflow, which is the CI entry's subject.
+
+## Layout
+
+- `scripts/` owns the shell scripts the package scripts below call
+- `.husky/` owns the git hooks
 
 ## Setup
 

package/tooling/base/seeds/.claude/context/index.md

@@ -0,0 +1,11 @@
+---
+title: Context
+subtitle: Per-domain narrative loaded on demand
+---
+
+# Context
+
+Per-domain narrative loaded on demand
+
+- [CI](ci.md): GitHub Actions workflow triggers and checks
+- [Development](development.md): Local dev workflow, scripts, and husky hooks

package/tooling/claude/seeds/.claude/context/index.md

@@ -1,8 +0,0 @@
----
-title: Context
-subtitle: Per-domain narrative loaded on demand
----
-
-# Context
-
-Per-domain narrative loaded on demand