@erclx/aitk 1.1.0 → 1.3.0

package/docs/ai-workflow.md

@@ -93,10 +93,12 @@ An execution that picks other than the suggestion rewrites the `- Suggested:` li
 
 `aitk records validate plans` reports where a plan and that standard disagree: a filename that is not `feature-<slug>.md`, a missing required section, a files-to-touch entry naming no file, and a question carrying a suggestion with no answer slot. The same verb takes `groundwork`, `intake`, `memory`, and `teach`, which are governed the same way and were unreachable for the same reason. Nothing fires it automatically, because all five folders are gitignored and every check the repository runs reads changed files from git. It reports and never writes, since the folders are per-machine scratch with no history to recover a wrong repair from.
 
-`aitk records push` carries these folders off the disk they live on, and `aitk records pull` brings them back. Eight of them are backed: `groundwork`, `intake`, `memory`, `plans`, `plans-archive`, `review`, `task-archive`, and `tasks`. The history lives in a second git directory at `.claude/.records.git` with `.claude/` as its work tree, so every path a task file cites stays where it is.
+`aitk records push` carries these folders off the disk they live on, and `aitk records pull` brings them back. Nine of them are backed: `groundwork`, `intake`, `memory`, `plans`, `plans-archive`, `review`, `task-archive`, `tasks`, and `teach`. The history lives in a second git directory at `.claude/.records.git` with `.claude/` as its work tree, so every path a task file cites stays where it is.
 
 A person points it at a private repository once and both verbs refuse until they have, and `push` refuses when that origin is also a remote of the project, since the payload is the memory pen and the groundwork trails. `.husky/post-merge` runs the push after its archive loop, on every merge rather than only on one that closed a task. See [records](agents/records.md) for the refusal table.
 
+`aitk records size` reports what each of these folders holds, heaviest first, along with `.claude/.tmp`. Each row carries the file count, the bytes, how many files were written in the last 7 and 30 days, and the dates of the least and most recently written one. Nothing fails on a number, because a record folder has no correct size. What the verb replaces is a reading somebody had to remember to take: the memory pen went from 44 entries to 236 between two counts made by hand a fortnight apart, and nothing reported the rate in between.
+
 A plan that ships is archived, never deleted. `aitk:claude-docs` moves it to `.claude/plans-archive/` and retargets the task file's `Plan:` line at the new location, so a completed task still leads to the reasoning behind it. Both folders are gitignored, which is why a deleted plan had no recovery path. A plan cited by more than one task stays put until the last of them closes, since moving it early would strand every other pointer.
 
 The sweep reads the whole board rather than the tasks the session touched. It is the one place the skill reaches past its own rule against editing a task file the session did not change, because a task that closed while an earlier run missed its archive is exactly what the sweep exists to clear. Reaching it is safe: the archive moves the plan and retargets the pointer in the same pass, so an untouched task ends up with a working link rather than a broken one.

package/docs/target-projects.md

@@ -88,11 +88,11 @@ Run `aitk tooling list --json` and `aitk gov list --json` to see the current cat
 
 `governance`, `standards`, and `wiki` are skippable:
 
-- `--skip governance`: leave `.claude/rules/` empty. Standards still install, so `.claude/standards/markdown.md` lands with nothing pointing at it and no coding standard loads on a file match. The preview names any `--add` rules the skip drops, and the run prints the `aitk gov install <stack> <path>` command to add rules afterward, carrying those extras so one paste restores what the skip declined.
-- `--skip standards`: leave standards out. The governance rules still reference `.claude/standards/`, so their authority lines resolve to nothing for a reader following the path. Toolkit skills are unaffected, since each falls back to the copy in its own plugin root. `aitk standards <name>` searches the corpus inside the CLI's own package behind both project roots, so it prints a standard in a project that skipped the install, and `aitk markdown audit` needs no standard at all, its ban sets and checkpoints shipping with the package as data. What the skip costs is the editable copy rather than the enforcement.
+- `--skip governance`: leave `.claude/rules/` empty, so no coding standard loads on a file match. Standards still install, and the installed copy is the first root `aitk standards <name>` resolves, so it stays the editable seed a project owns. The preview names any `--add` rules the skip drops, and the run prints the `aitk gov install <stack> <path>` command to add rules afterward, carrying those extras so one paste restores what the skip declined.
+- `--skip standards`: leave standards out. The governance rules are unaffected, since each authority line names `aitk standards <name>` and that command answers from the corpus inside the CLI's own package. Toolkit skills are unaffected too, each naming the copy in its own plugin root. `aitk standards <name>` searches the corpus inside the CLI's own package behind both project roots, so it prints a standard in a project that skipped the install, and `aitk markdown audit` needs no standard at all, its ban sets and checkpoints shipping with the package as data. What the skip costs is the editable copy rather than the enforcement.
 - `--skip wiki`: skip the `.claude/wiki/` scaffold. A target that already carries a root `wiki/` keeps it, since the verb reports that folder rather than migrating it.
 
-That standards fallback carries runtime behavior rather than reference prose alone, because the pre-publish scan and the branch-slug transform each have a standard of their own, `publish.md` and `slug.md`, cited by the skills that run them.
+The plugin corpus carries runtime behavior rather than reference prose alone, because the pre-publish scan and the branch-slug transform each have a standard of their own, `publish.md` and `slug.md`, cited by the skills that run them.
 
 ## Add a domain later
 

package/governance/rules/claude/501-markdown.md

@@ -8,7 +8,7 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/markdown.md` for headings, paragraph and list structure, code spans, punctuation, emphasis, file references, the banned words and spellings, and the wording of a `title` or `description`. It is the single source.
+- Follow the markdown standard for headings, paragraph and list structure, code spans, punctuation, emphasis, file references, the banned words and spellings, and the wording of a `title` or `description`. It is the single source. Read it with `aitk standards markdown`.
 - Read it before a substantial markdown edit. Do not work the banned words or characters from memory.
 - Run `aitk markdown audit <path>` after the edit, and rewrite the sentence carrying a hit rather than swapping the token for a near-synonym.
 - Voice, rhythm, and sentence construction are a separate topic. `500-prose` routes them.

package/governance/rules/claude/510-context.md

@@ -26,4 +26,4 @@ Do not put a sibling bullet's design in the past with one of these.
 
 ## Authority
 
-- Follow `.claude/standards/context.md` for entry shape: frontmatter, sections, length, and what goes in. It is the single source.
+- Follow the context standard for entry shape: frontmatter, sections, length, and what goes in. It is the single source. Read it with `aitk standards context`.

package/governance/rules/claude/520-wireframes.md

@@ -16,5 +16,5 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/wireframes.md` for layout and interaction intent: ASCII layout, region labels, variants, copy, and what moves to `.claude/context/`. It is the single source.
+- Follow the wireframes standard for layout and interaction intent: ASCII layout, region labels, variants, copy, and what moves to `.claude/context/`. It is the single source. Read it with `aitk standards wireframes`.
 - Read it before adding or revising a surface.

package/governance/rules/claude/530-requirements.md

@@ -16,4 +16,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/requirements.md` for what belongs in the problem, goals, non-goals, MVP features, tech stack, and constraints. It is the single source.
+- Follow the requirements standard for what belongs in the problem, goals, non-goals, MVP features, tech stack, and constraints. It is the single source. Read it with `aitk standards requirements`.

package/governance/rules/claude/540-architecture.md

@@ -18,4 +18,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/architecture.md` for the overview, named decision entries, and risks. It is the single source.
+- Follow the architecture standard for the overview, named decision entries, and risks. It is the single source. Read it with `aitk standards architecture`.

package/governance/rules/claude/550-design.md

@@ -16,4 +16,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/design.md` for visual intent, the token tables, and the render contract. It is the single source.
+- Follow the design standard for visual intent, the token tables, and the render contract. It is the single source. Read it with `aitk standards design`.

package/governance/rules/claude/555-tasks.md

@@ -16,5 +16,5 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/tasks.md` for filenames, frontmatter, what belongs, and the task file format. It is the single source.
+- Follow the tasks standard for filenames, frontmatter, what belongs, and the task file format. It is the single source. Read it with `aitk standards tasks`.
 - Never hand-edit `.claude/tasks/index.md`. A hook regenerates it from sibling frontmatter.

package/governance/rules/claude/556-groundwork.md

@@ -13,4 +13,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/groundwork.md` for reserved numbering, frontmatter and dating, what each required file holds, and the conventions a track keeps. It is the single source.
+- Follow the groundwork standard for reserved numbering, frontmatter and dating, what each required file holds, and the conventions a track keeps. It is the single source. Read it with `aitk standards groundwork`.

package/governance/rules/claude/557-intake.md

@@ -13,4 +13,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/intake.md` for the folder layout, frontmatter and dating, the item format, and retrieval. It is the single source.
+- Follow the intake standard for the folder layout, frontmatter and dating, the item format, and retrieval. It is the single source. Read it with `aitk standards intake`.

package/governance/rules/claude/558-plan.md

@@ -20,4 +20,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/plan.md` for the filename and slug, the required sections, the suggested-and-answer contract, and the lifecycle. It is the single source.
+- Follow the plan standard for the filename and slug, the required sections, the suggested-and-answer contract, and the lifecycle. It is the single source. Read it with `aitk standards plan`.

package/governance/rules/claude/559-memory.md

@@ -17,4 +17,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/memory.md` for the filename and type prefix, the frontmatter, the body shape per type, links between entries, and the lifecycle. It is the single source.
+- Follow the memory standard for the filename and type prefix, the frontmatter, the body shape per type, links between entries, and the lifecycle. It is the single source. Read it with `aitk standards memory`.

package/governance/rules/claude/560-diagrams.md

@@ -9,7 +9,7 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/diagrams.md` for Mermaid diagram layout, budgets, accessibility, verification, and explanation prose. It is the single source.
+- Follow the diagrams standard for Mermaid diagram layout, budgets, accessibility, verification, and explanation prose. It is the single source. Read it with `aitk standards diagrams`.
 - A diagram entry carries structure and flow, not implementation. Read the standard before adding or revising a kind.
 
 ## Scope

package/governance/rules/claude/561-teach.md

@@ -16,6 +16,6 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/teach.md` for the folder layout, ordinal naming, frontmatter, and the mission and learning-record formats. It is the single source.
+- Follow the teach standard for the folder layout, ordinal naming, frontmatter, and the mission and learning-record formats. It is the single source. Read it with `aitk standards teach`.
 - Read `references/glossary.md` inside the `claude-teach` skill for the glossary every workspace carries at its root. It is the single source for the entry shape, the ordering, and which terms the file carries. Read it rather than invoking the skill, which resumes a workspace and runs lessons.
 - Report it rather than proceeding silently when that file does not resolve. It ships with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have it.

package/governance/rules/claude/562-session.md

@@ -16,4 +16,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/session.md` for the filename and location, frontmatter, the core sections, and the write and read procedures. It is the single source.
+- Follow the session standard for the filename and location, frontmatter, the core sections, and the write and read procedures. It is the single source. Read it with `aitk standards session`.

package/governance/rules/claude/570-skill.md

@@ -20,4 +20,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/skill.md` for skill structure, frontmatter fields, invocation rules, and the shape a `REQUIREMENT.md` states. It is the single source.
+- Follow the skill standard for skill structure, frontmatter fields, invocation rules, and the shape a `REQUIREMENT.md` states. It is the single source. Read it with `aitk standards skill`.

package/governance/rules/claude/580-readme.md

@@ -16,4 +16,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/readme.md` for voice, structure, required and optional sections, heading hierarchy, badge classes, per-project-type content, and what to link out rather than inline. It is the single source.
+- Follow the readme standard for voice, structure, required and optional sections, heading hierarchy, badge classes, per-project-type content, and what to link out rather than inline. It is the single source. Read it with `aitk standards readme`.

package/governance/rules/claude/590-rule-authoring.md

@@ -19,5 +19,5 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/rule.md` for rule frontmatter, body shape, and voice. It is the single source.
+- Follow the rule-authoring standard for rule frontmatter, body shape, and voice. It is the single source. Read it with `aitk standards rule`.
 - Read it before writing or editing a rule. Do not work the shape from memory.

package/governance/rules/claude/591-standard-authoring.md

@@ -17,5 +17,5 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/standard.md` for a standard's frontmatter, shape, scope, and success criterion. It is the single source.
+- Follow the standard-authoring standard for a standard's frontmatter, shape, scope, and success criterion. It is the single source. Read it with `aitk standards standard`.
 - Read it before writing or editing a standard. Do not work the shape from memory.

package/package.json

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

package/src/cli.ts

@@ -61,7 +61,7 @@ function showHelp(): void {
     `${GREY}│${NC}    comments [cmd]     ${GREY}# Measure comment density and trend (scan)${NC}`,
     `${GREY}│${NC}    context [cmd]      ${GREY}# Report context folder health (audit)${NC}`,
     `${GREY}│${NC}    markdown [cmd]     ${GREY}# Report markdown against the attribute standards (audit)${NC}`,
-    `${GREY}│${NC}    records [cmd]      ${GREY}# Session records under .claude/ (validate, push, pull)${NC}`,
+    `${GREY}│${NC}    records [cmd]      ${GREY}# Session records under .claude/ (validate, size, push, pull)${NC}`,
     `${GREY}│${NC}    sessions [cmd]     ${GREY}# Resolve live sessions to worktree and branch (list)${NC}`,
     `${GREY}│${NC}    audits [cmd]       ${GREY}# Run every health check as one set (run, list)${NC}`,
     `${GREY}│${NC}    upgrade            ${GREY}# Reinstall the CLI globally with the manager that installed it${NC}`,
@@ -101,6 +101,7 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk context audit --json`,
     `${GREY}│${NC}    aitk markdown audit .claude/rules --json`,
     `${GREY}│${NC}    aitk records validate plans`,
+    `${GREY}│${NC}    aitk records size --json`,
     `${GREY}│${NC}    aitk records push --json`,
     `${GREY}│${NC}    aitk sessions list --json`,
     `${GREY}│${NC}    aitk audits run --json`,

package/src/commands/records.ts

@@ -1,11 +1,13 @@
 import type { Command } from 'commander'
+import { BACKED_FOLDERS, pullRecords, pushRecords } from '@/records/backup'
 import {
-  BACKED_FOLDERS,
-  type PullOutcome,
-  pullRecords,
-  type PushOutcome,
-  pushRecords,
-} from '@/records/backup'
+  type FolderSize,
+  formatBytes,
+  GROWTH_WINDOWS,
+  SIZED_FOLDERS,
+  type SizeOutcome,
+  sizeRecords,
+} from '@/records/size'
 import {
   type Finding,
   isRecordKind,
@@ -23,6 +25,7 @@ import {
   logWarn,
   outro,
   pipeOutput,
+  plural,
 } from '@/ui'
 import { currentWorktreeRoot, mainWorktreeRoot } from '@/worktree'
 
@@ -87,6 +90,41 @@ export function register(program: Command): void {
       process.exitCode = await runValidate(kind, opts)
     })
 
+  records
+    .command('size')
+    .description('Report what each record folder holds and how much is recent')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--root <path>', 'Project root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Folders read under .claude/:',
+        `  ${SIZED_FOLDERS.join(', ')}`,
+        '',
+        'Exit codes:',
+        '  0  the reading completed',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'It gates nothing. A record folder has no correct size, so the reading is',
+        'a number to notice rather than a threshold to fail, and a session takes it',
+        `by running this rather than by counting the folder. The ${GROWTH_WINDOWS.join(
+          ' and ',
+        )} day`,
+        'counts read mtime, so a file rewritten long after it landed reads as recent,',
+        'and a machine restored by records pull reads its whole tree as one week old.',
+        '',
+        'Examples:',
+        '  aitk records size',
+        '  aitk records size --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: BackupCommandOptions) => {
+      process.exitCode = await runSize(opts)
+    })
+
   records
     .command('push')
     .description(
@@ -149,6 +187,99 @@ function backupHelp(verb: 'push' | 'pull'): string {
   ].join('\n')
 }
 
+async function runSize(opts: BackupCommandOptions): Promise<number> {
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await sizeRecords(root)
+
+  if (!outcome.ok)
+    return reportRefusal('aitk records size', outcome, opts.json ?? false)
+
+  if (opts.json ?? false) {
+    process.stdout.write(`${JSON.stringify(outcome)}\n`)
+    return 0
+  }
+
+  reportSize(outcome)
+  return 0
+}
+
+/** Widest cell in the column, so a row lines up against the header as well. */
+function columnWidth(header: string, cells: readonly string[]): number {
+  return Math.max(header.length, ...cells.map((cell) => cell.length))
+}
+
+function sizeRow(entry: FolderSize): string[] {
+  return [
+    entry.folder,
+    String(entry.files),
+    formatBytes(entry.bytes),
+    ...entry.touched.map((window) => String(window.files)),
+    entry.oldest ?? '',
+    entry.newest ?? '',
+  ]
+}
+
+/**
+ * Renders the present folders as a table, heaviest first.
+ *
+ * The order is what makes the reading worth taking. A folder listed
+ * alphabetically hides behind its neighbors, and the one that grew is the row
+ * a reader came for, so it leads.
+ */
+function reportSize(outcome: Extract<SizeOutcome, { ok: true }>): void {
+  const present = outcome.folders
+    .filter((entry) => entry.present)
+    .toSorted((left, right) => right.files - left.files)
+  const absent = outcome.folders
+    .filter((entry) => !entry.present)
+    .map((entry) => entry.folder)
+
+  intro('aitk records size')
+  logStep('Folders')
+
+  if (present.length === 0) {
+    logInfo('none of the record folders exist yet')
+  } else {
+    const headers = [
+      'folder',
+      'files',
+      'size',
+      ...GROWTH_WINDOWS.map((days) => `${days}d`),
+      'oldest',
+      'newest',
+    ]
+    const rows = present.map(sizeRow)
+    const widths = headers.map((header, column) =>
+      columnWidth(
+        header,
+        rows.map((row) => row[column]),
+      ),
+    )
+
+    // The name column reads as a list and the rest as numbers, so one is
+    // left-aligned and the others are not.
+    const render = (cells: readonly string[]): string =>
+      cells
+        .map((cell, column) =>
+          column === 0
+            ? cell.padEnd(widths[column])
+            : cell.padStart(widths[column]),
+        )
+        .join('  ')
+        .trimEnd()
+
+    pipeOutput([render(headers), ...rows.map(render)].join('\n'))
+  }
+
+  if (absent.length > 0) logInfo(`absent: ${absent.join(', ')}`)
+
+  logStep('Total')
+  logInfo(
+    `${plural(outcome.files, 'file')}, ${formatBytes(outcome.bytes)} across ${plural(present.length, 'folder')}`,
+  )
+  outro()
+}
+
 async function runPush(opts: BackupCommandOptions): Promise<number> {
   const root = opts.root ?? (await mainWorktreeRoot())
   const outcome = await pushRecords(root)
@@ -197,9 +328,16 @@ async function runPull(opts: BackupCommandOptions): Promise<number> {
   return 0
 }
 
+/**
+ * Reports a refusal from any of the three verbs that carry one.
+ *
+ * The parameter is structural rather than the union of their outcome types,
+ * because the three refusal vocabularies are separate lists and naming them all
+ * here would grow with every verb added.
+ */
 function reportRefusal(
   banner: string,
-  outcome: Extract<PushOutcome | PullOutcome, { ok: false }>,
+  outcome: { readonly reason: string; readonly message: string },
   emitJson: boolean,
 ): number {
   if (emitJson) {

package/src/markdown/structure.ts

@@ -536,10 +536,45 @@ function measureParagraph(block: readonly BodyLine[]): CadenceFinding {
  * absence of something, so no addition to that set catches a paragraph whose
  * sentences are all one length. The measure stops at what is countable. A
  * sentence's grammatical shape and whether it carries a finite verb are the two
- * rules `write-human` states that this does not implement, because identifying
- * either needs a parse rather than a match, and an imperative or a heading
- * fragment would read as a defect. Reporting them wrong is worse than not
- * reporting them, since they name the exact failure this exists to measure.
+ * rules `write-human` states that this does not implement. Reporting them wrong
+ * is worse than not reporting them, since they name the exact failure this
+ * exists to measure.
+ *
+ * That was a prediction and it has now been measured, against two parsers
+ * rather than against the idea of one. Both ran over 11,389 paragraph sentences
+ * across 503 markdown files at `c7e92612` on 2026-08-20, and they disagree by
+ * a factor of four on a number one of them has to be wrong about.
+ *
+ * `compromise` reported 2 percent. It tags a fronted past participle as a
+ * finite past-tense verb, so all twelve of those sentences in
+ * `.claude/ARCHITECTURE.md` read as carrying one, eleven opening `Measured at`
+ * and one `Overturned by`, which is the exact shape the measure exists to
+ * catch. It is not even consistent with itself there: `Measured at` tags a verb
+ * and `Measured against` tags an adjective.
+ *
+ * `wink-pos-tagger` reported 9 percent and fixes that class, tagging the
+ * participle `VBN`. Roughly three quarters of what it flags is still wrong:
+ * hand-classifying every 21st of the 1,071 flagged sentences put 12 of 51
+ * genuinely verbless. Two classes split the other 39 almost evenly and neither
+ * is a tuning problem. Nineteen are imperatives, which this instructional
+ * corpus is full of and whose verb tags as a proper noun as often as a verb.
+ * Twenty are ordinary declaratives whose predicate is noun-ambiguous and tags
+ * as a noun outright, so `Each maps to a skill.` and `Nothing checks either
+ * one.` both report verbless. This corpus is built from exactly those words:
+ * reports, answers, checks, maps, holds, names, carries, records, measures.
+ *
+ * Separating them needs to know which token is the predicate, which is syntax
+ * rather than a tag. Neither tagger carries one and nothing was found worth
+ * taking for a number nothing gates on, so the rule the deferral set is met and
+ * still returns no: a parse was tried, twice, and neither produced a number
+ * worth printing beside two that hold.
+ *
+ * Where a shape sits is a different question and is already answered. A heading
+ * fragment, a list item, and a table cell are all legitimately verbless and
+ * none of them reaches this measure, because `paragraphBlocks` ends a paragraph
+ * on each. That exclusion is structural and needs no grammar. The imperative is
+ * the one that sits in paragraph prose, and it is what neither parser could
+ * separate out.
  *
  * A paragraph under the floor is skipped rather than scored. A two-sentence
  * configuration note has no spread worth reading, and the opener rule is