@erclx/aitk 1.2.0 → 1.3.0

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

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

package/docs/agents/commands.md

@@ -37,7 +37,8 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk teach resource`      | Record sources and leads in a workspace, repeating `--read` or `--lead` as `<title>=<url>` (`--json`)                                     |
 | `aitk teach glossary`      | Add terms to a workspace glossary alphabetically, repeating `--term <term>=<definition>` (`--json`)                                       |
 | `aitk records validate`    | Report a session record or a standard against the standard governing it, per kind (`--json`)                                              |
-| `aitk records push`        | Commit the eight backed record folders and push them to a private records remote (`--json`)                                               |
+| `aitk records size`        | Report what each record folder holds and how much of it is recent, heaviest first (`--json`)                                              |
+| `aitk records push`        | Commit the nine backed record folders and push them to a private records remote (`--json`)                                                |
 | `aitk records pull`        | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)                                   |
 | `aitk sessions list`       | Resolve live sessions to the worktree and branch each holds, filtered by `--branch` (`--json`)                                            |
 | `aitk comments scan`       | Measure comment density by language and comment kind, with a trend recomputed from git                                                    |

package/docs/agents/index.md

@@ -21,7 +21,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Markdown audit](markdown-audit.md): Running the audit over any markdown path, where its bans and checkpoints are read from, what each check reports, and why the ban half gates while the structural half reports
 - [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
-- [Records](records.md): Validating the session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, backing the folders to a private remote, and which root each kind defaults to
+- [Records](records.md): Validating the session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
 - [Sandbox](sandbox.md): Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills
 - [Scripting](scripting.md): The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
 - [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, the liveness confidence field, the unresolved reasons, and what the read depends on

package/docs/agents/records.md

@@ -1,6 +1,6 @@
 ---
 title: Records
-description: Validating the session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, backing the folders to a private remote, and which root each kind defaults to
+description: Validating the session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
 ---
 
 # Records
@@ -72,6 +72,34 @@ aitk records validate plans --json | jq -r '.findings[] | "\(.kind): \(.subject)
 
 For the shapes each check enforces, see `.claude/standards/plan.md`, `.claude/standards/groundwork.md`, `.claude/standards/intake.md`, `.claude/standards/memory.md`, and `.claude/standards/standard.md`.
 
+## Size
+
+`aitk records size` reports what each record folder holds and how much of it is recent. It reads the nine backed folders named under Push and pull, plus `.claude/.tmp`, and it gates nothing.
+
+```bash
+aitk records size
+aitk records size --json
+```
+
+| Option          | Behavior                                      |
+| --------------- | --------------------------------------------- |
+| `--json`        | Add a machine-readable record on stdout       |
+| `--root <path>` | Project root, defaulting to the main worktree |
+
+The table carries one row per folder that exists, heaviest first, with the file count, the bytes, a count for each growth window, and the dates of the least and most recently written file. Those dates render in the machine's local time, which is the calendar day whoever wrote the file was living in, and the reading is per-machine already. Folders that do not exist are named on one line below it rather than printed as rows of zeros. The record a `--json` call emits carries every folder either way, each with a `present` flag, so a caller reading the record gets a stable set of keys and can tell an absent folder from one the reading skipped.
+
+Ordering by weight is what makes the reading worth taking. A folder listed alphabetically hides behind its neighbors, and the row a reader came for is the one that grew.
+
+The reading carries two windows rather than one, at 7 and 30 days. A single window cannot separate a folder growing steadily from one that took a single batch: a folder whose 7-day count is most of its 30-day count moved in one pass, and one where the two are proportional is growing at a rate.
+
+Nothing fails on a number here. A record folder has no correct size, so the reading is a number to notice rather than a threshold to gate, and the point of the verb is that the next reading is taken by a command instead of by someone remembering to count the folder. The memory pen went from 44 entries to 236 between two readings taken by hand two weeks apart, which is the measurement this replaces.
+
+`.claude/.tmp` is read here and skipped by a backup, because deletable without loss is not the same as empty. The routing handoffs and the memory archive both sit there and both accumulate. `.claude/.records.git` stays out because it is the backup history rather than a record, and `.claude/worktrees/` stays out because each entry is a checkout of the project with its own removal verb, and one of them outweighs every record folder combined.
+
+The window counts read `mtime`, so what they report is a file written inside the window rather than one created there. An entry edited long after it landed reads as recent, which overstates growth and never understates it, and these folders are append-mostly so the two readings agree on nearly every file. The one reading that is wrong rather than early is a machine restored by `aitk records pull`, which resets the work tree hard and re-dates every file it writes, so a window taken there counts the restore. Nothing on the filesystem separates the two, since a restored file is new by every stamp it carries.
+
+Exit codes: `0` the reading completed, `1` refused. The one refusal is `no-folder`, raised when the root holds no `.claude` directory at all.
+
 ## Push and pull
 
 `aitk records push` commits the backed record folders to a private remote and pushes them. `aitk records pull` fetches the other direction and writes them back. Both take `--json` and `--root` the way `validate` does, and both exit `0` on agreement and `1` on a refusal.
@@ -82,9 +110,9 @@ aitk records push --json
 aitk records pull
 ```
 
-The backed folders are `groundwork`, `intake`, `memory`, `plans`, `plans-archive`, `review`, `task-archive`, and `tasks`, all under `.claude/`. They are the gitignored Claude group minus `.claude/.tmp`, which is deletable without loss, and `.claude/worktrees/`, whose contents belong to the project repository already. The list is a constant rather than configuration, matching the four folder names `validate` hardcodes.
+The backed folders are `groundwork`, `intake`, `memory`, `plans`, `plans-archive`, `review`, `task-archive`, `tasks`, and `teach`, all under `.claude/`. They are the gitignored Claude group minus `.claude/.tmp`, which is deletable without loss, and `.claude/worktrees/`, whose contents belong to the project repository already. The list is a constant rather than configuration, matching the four folder names `validate` hardcodes.
 
-Records are gitignored by design, so the history lives in a second git directory at `.claude/.records.git` with `.claude/` as its work tree. Every path stays where it is, which is what a separate checkout could not do. The verbs stage the eight folders by explicit pathspec with `--force`, so nothing outside them can enter the index however the ignore rules read, and the project working tree and its index are never touched.
+Records are gitignored by design, so the history lives in a second git directory at `.claude/.records.git` with `.claude/` as its work tree. Every path stays where it is, which is what a separate checkout could not do. The verbs stage the nine folders by explicit pathspec with `--force`, so nothing outside them can enter the index however the ignore rules read, and the project working tree and its index are never touched.
 
 ### Setup
 
@@ -113,7 +141,7 @@ Point it at a private repository, and at one that is not a remote of the project
 | `local-ahead`       | `pull` found local commits that never reached the origin                             |
 | `git-failed`        | A git call failed, with its stderr in the message                                    |
 
-The two `pull` refusals exist because the directions are not symmetric. A push only adds, while a pull onto a machine holding work that never left it would discard that work. Resolve either by running `push` first, or by moving the local folders aside. A machine holding none of the eight has nothing to lose, so a restore onto a fresh checkout runs straight through.
+The two `pull` refusals exist because the directions are not symmetric. A push only adds, while a pull onto a machine holding work that never left it would discard that work. Resolve either by running `push` first, or by moving the local folders aside. A machine holding none of the nine has nothing to lose, so a restore onto a fresh checkout runs straight through.
 
 ### When it runs
 

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "1.2.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/records/size.ts

@@ -0,0 +1,260 @@
+import { existsSync, type Stats } from 'node:fs'
+import { readdir, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import { BACKED_FOLDERS } from '@/records/backup'
+
+/**
+ * The folders a size reading covers, relative to `.claude/`.
+ *
+ * It is the backed set plus `.tmp`, which a backup skips because it is
+ * deletable without loss and a reading covers because deletable is not the same
+ * as empty: the routing handoffs and the memory archive both sit there and both
+ * accumulate. `.records.git` stays out because it is the backup history rather
+ * than a record, and `worktrees/` stays out because each entry there is a
+ * checkout of the enclosing repository with its own removal verb, and one of
+ * them outweighs every record folder combined.
+ */
+export const SIZED_FOLDERS = [...BACKED_FOLDERS, '.tmp'] as const
+
+/**
+ * The windows a reading reports, in days.
+ *
+ * There are two rather than one, because a single window cannot separate a
+ * folder that grows steadily from one that took a single batch. A folder whose
+ * 7-day count is most of its 30-day count moved in one pass, and one where the
+ * two are proportional is growing at a rate.
+ */
+export const GROWTH_WINDOWS = [7, 30] as const
+
+const DAY_MS = 24 * 60 * 60 * 1000
+
+export interface WindowCount {
+  readonly days: number
+  readonly files: number
+}
+
+export interface FolderSize {
+  /** Relative to `.claude/`, which is the name a reader opens. */
+  readonly folder: string
+  readonly present: boolean
+  readonly files: number
+  readonly bytes: number
+  /** `YYYY-MM-DD` of the least and most recently modified file, absent when the folder holds none. */
+  readonly oldest?: string
+  readonly newest?: string
+  readonly touched: readonly WindowCount[]
+}
+
+export interface SizeReport {
+  readonly ok: true
+  readonly root: string
+  readonly folders: readonly FolderSize[]
+  readonly files: number
+  readonly bytes: number
+}
+
+export const SIZE_REFUSALS = ['no-folder'] as const
+
+export type SizeRefusal = (typeof SIZE_REFUSALS)[number]
+
+export interface SizeRefused {
+  readonly ok: false
+  readonly reason: SizeRefusal
+  readonly message: string
+}
+
+export type SizeOutcome = SizeReport | SizeRefused
+
+interface Walked {
+  files: number
+  bytes: number
+  oldest?: number
+  newest?: number
+  touched: number[]
+}
+
+/**
+ * Renders the calendar date the writer saw, which is the local one.
+ *
+ * `toISOString` renders in UTC, so a file written after 17:00 at `-0700` dates
+ * to the following day and a reader comparing the column against their own
+ * memory of writing it finds the two disagree. The reading is per-machine
+ * already, since these folders are gitignored and hold whatever that disk holds,
+ * so a local date is the answer consistent with the rest of the report.
+ */
+function day(ms: number): string {
+  const at = new Date(ms)
+  const month = String(at.getMonth() + 1).padStart(2, '0')
+  const date = String(at.getDate()).padStart(2, '0')
+  return `${at.getFullYear()}-${month}-${date}`
+}
+
+/**
+ * Adds one file to the running totals.
+ *
+ * The window counts read `mtime`, so what they report is a file written inside
+ * the window rather than one created there. An entry edited long after it
+ * landed counts as recent, which overstates growth and never understates it.
+ * That is the safe direction for a number whose whole job is to be noticed, and
+ * these folders are append-mostly, so the two readings agree on nearly every
+ * file.
+ *
+ * The one reading that is wrong rather than early is a machine restored by
+ * `aitk records pull`, which resets the work tree hard and re-dates every file
+ * it writes. A window taken there counts the restore. Nothing separates the two
+ * from the filesystem, since a restored file is new by every stamp it carries,
+ * so the caveat is published rather than corrected.
+ */
+function absorb(into: Walked, bytes: number, mtime: number, now: number): void {
+  into.files += 1
+  into.bytes += bytes
+  into.oldest = into.oldest === undefined ? mtime : Math.min(into.oldest, mtime)
+  into.newest = into.newest === undefined ? mtime : Math.max(into.newest, mtime)
+
+  GROWTH_WINDOWS.forEach((days, index) => {
+    if (now - mtime <= days * DAY_MS) into.touched[index] += 1
+  })
+}
+
+/**
+ * Reads one entry, or undefined when it left between the listing and the read.
+ *
+ * These folders are written by whatever sessions are running, so a path listed
+ * a moment ago can be gone by the time it is read. A vanished file is a file
+ * the folder no longer holds, which is the answer the count wants, and letting
+ * `ENOENT` out would fail the whole reading over one deleted scratch file.
+ * Every other error propagates, since a permission or IO failure would
+ * undercount with nothing said.
+ */
+async function readSize(path: string): Promise<Stats | undefined> {
+  try {
+    return await stat(path)
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined
+    throw error
+  }
+}
+
+/**
+ * Walks one folder, counting files and never following a symlink.
+ *
+ * `isFile()` answers false for a link, so a folder holding one reports it
+ * nowhere rather than counting whatever sits behind it. The corpus symlinks
+ * point out of `.claude/` and into the authoring roots, where a second reading
+ * of the same bytes would be the wrong answer twice over.
+ */
+async function walk(dir: string, into: Walked, now: number): Promise<void> {
+  const entries = await readdir(dir, { withFileTypes: true }).catch(
+    (error: NodeJS.ErrnoException) => {
+      if (error.code === 'ENOENT') return []
+      throw error
+    },
+  )
+
+  for (const entry of entries) {
+    const path = join(dir, entry.name)
+
+    if (entry.isDirectory()) {
+      await walk(path, into, now)
+      continue
+    }
+    if (!entry.isFile()) continue
+
+    const info = await readSize(path)
+    if (info) absorb(into, info.size, info.mtimeMs, now)
+  }
+}
+
+async function measure(
+  root: string,
+  folder: string,
+  now: number,
+): Promise<FolderSize> {
+  const path = join(root, '.claude', folder)
+  const empty = GROWTH_WINDOWS.map((days) => ({ days, files: 0 }))
+
+  if (!existsSync(path)) {
+    return { folder, present: false, files: 0, bytes: 0, touched: empty }
+  }
+
+  const walked: Walked = {
+    files: 0,
+    bytes: 0,
+    touched: GROWTH_WINDOWS.map(() => 0),
+  }
+  await walk(path, walked, now)
+
+  return {
+    folder,
+    present: true,
+    files: walked.files,
+    bytes: walked.bytes,
+    oldest: walked.oldest === undefined ? undefined : day(walked.oldest),
+    newest: walked.newest === undefined ? undefined : day(walked.newest),
+    touched: GROWTH_WINDOWS.map((days, index) => ({
+      days,
+      files: walked.touched[index],
+    })),
+  }
+}
+
+/**
+ * Reports what each record folder holds and how much of it is recent.
+ *
+ * Every folder is reported whether or not it exists, since a caller reading the
+ * record wants a stable set of keys, and a folder absent from the output is
+ * indistinguishable from one the reading skipped.
+ *
+ * `now` is a parameter rather than a call inside the walk so a test can pin the
+ * windows against fixture timestamps.
+ */
+export async function sizeRecords(
+  root: string,
+  now: number = Date.now(),
+): Promise<SizeOutcome> {
+  if (!existsSync(join(root, '.claude'))) {
+    return {
+      ok: false,
+      reason: 'no-folder',
+      message: `No .claude directory at ${root}, so there are no record folders to read.`,
+    }
+  }
+
+  // Each folder is walked independently, and the report is ordered by the
+  // caller rather than by arrival, so `Promise.all` keeps the input order while
+  // the ten walks overlap.
+  const folders = await Promise.all(
+    SIZED_FOLDERS.map((folder) => measure(root, folder, now)),
+  )
+
+  return {
+    ok: true,
+    root,
+    folders,
+    files: folders.reduce((total, entry) => total + entry.files, 0),
+    bytes: folders.reduce((total, entry) => total + entry.bytes, 0),
+  }
+}
+
+const UNITS = ['B', 'K', 'M', 'G'] as const
+
+/**
+ * Renders a byte count at three significant figures or fewer.
+ *
+ * The reading is a prompt to go and look rather than an accounting figure, so
+ * an exact byte count buys nothing and costs a reader the comparison between
+ * two rows.
+ */
+export function formatBytes(bytes: number): string {
+  let value = bytes
+  let unit = 0
+
+  while (value >= 1024 && unit < UNITS.length - 1) {
+    value /= 1024
+    unit += 1
+  }
+
+  const rendered =
+    unit === 0 || value >= 10 ? Math.round(value) : value.toFixed(1)
+  return `${rendered}${UNITS[unit]}`
+}