@sabaiway/agent-workflow-kit 1.0.0

package/references/scripts/archive-issues.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+// Rotate FIXED issues from docs/ai/known_issues.md → docs/ai/history/issues-resolved.md.
+//
+// Rule: an issue is archivable when
+//   - its heading is wrapped in ~~strikethrough~~  AND
+//   - its body contains `**Status:** ✅ FIXED (YYYY.MM.DD)` with a date older than CUTOFF_DAYS.
+// Issues marked FIXED without an explicit date are left untouched (conservative — agent
+// can re-evaluate and archive manually).
+//
+// Modes:
+//   (default)   append matching issues to history/issues-resolved.md, remove from known_issues.md
+//   --dry-run   print plan, no file changes
+//   --check     exit 1 if known_issues.md still has archivable issues
+//
+// CLI:
+//   --cutoff-days=N (default 14)
+//   --today=YYYY-MM-DD (default UTC today)
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve, relative, basename } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '..');
+
+const readProjectName = () => {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf8'));
+    if (pkg.name) return pkg.name;
+  } catch {
+    /* no package.json — fall back to repo dir basename */
+  }
+  return basename(ROOT);
+};
+const PROJECT_NAME = readProjectName();
+
+const KNOWN_ISSUES_PATH = resolve(ROOT, 'docs/ai/known_issues.md');
+const HISTORY_DIR = resolve(ROOT, 'docs/ai/history');
+const RESOLVED_PATH = resolve(HISTORY_DIR, 'issues-resolved.md');
+
+const DEFAULT_CUTOFF_DAYS = 14;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+const ISSUE_HEADING_RE = /^### (.+?)$/;
+const STRIKETHROUGH_RE = /^~~(.+)~~$/;
+const FIXED_WITH_DATE_RE = /\*\*Status:\*\*\s*✅\s*FIXED\s*\((\d{4})\.(\d{2})\.(\d{2})\)/;
+
+const parseArgs = (argv) => {
+  const flags = { dryRun: false, check: false };
+  const opts = { cutoffDays: DEFAULT_CUTOFF_DAYS, today: null };
+  for (const arg of argv.slice(2)) {
+    if (arg === '--dry-run') flags.dryRun = true;
+    else if (arg === '--check') flags.check = true;
+    else if (arg.startsWith('--cutoff-days=')) opts.cutoffDays = Number(arg.slice('--cutoff-days='.length));
+    else if (arg.startsWith('--today=')) opts.today = arg.slice('--today='.length);
+    else if (arg === '--help' || arg === '-h') {
+      console.log('Usage: archive-issues.mjs [--dry-run|--check] [--cutoff-days=N] [--today=YYYY-MM-DD]');
+      process.exit(0);
+    } else {
+      console.error(`Unknown argument: ${arg}`);
+      process.exit(2);
+    }
+  }
+  return { flags, opts };
+};
+
+export const parseKnownIssues = (text) => {
+  const fmMatch = text.match(/^(---\n[\s\S]*?\n---\n)/);
+  const frontmatter = fmMatch ? fmMatch[1] : '';
+  const body = text.slice(frontmatter.length);
+  const lines = body.split('\n');
+
+  const sections = [];
+  let current = { heading: null, lines: [] };
+  for (const line of lines) {
+    if (/^### /.test(line)) {
+      if (current.heading !== null || current.lines.length > 0) sections.push(current);
+      current = { heading: line, lines: [line] };
+    } else {
+      current.lines.push(line);
+    }
+  }
+  if (current.heading !== null || current.lines.length > 0) sections.push(current);
+  return { frontmatter, sections };
+};
+
+export const classifySection = (section, cutoffDate) => {
+  if (section.heading === null) return { kind: 'preamble' };
+  const headingMatch = ISSUE_HEADING_RE.exec(section.heading);
+  if (!headingMatch) return { kind: 'other' };
+  const title = headingMatch[1];
+  const stricken = STRIKETHROUGH_RE.exec(title);
+  if (!stricken) return { kind: 'open' };
+
+  const blockText = section.lines.join('\n');
+  const dateMatch = FIXED_WITH_DATE_RE.exec(blockText);
+  if (!dateMatch) return { kind: 'fixed-undated' };
+
+  const fixedDate = new Date(`${dateMatch[1]}-${dateMatch[2]}-${dateMatch[3]}T00:00:00Z`);
+  return fixedDate < cutoffDate ? { kind: 'archivable', fixedDate } : { kind: 'fixed-recent', fixedDate };
+};
+
+export const buildResolvedFile = (existing, newSections, todayStr) => {
+  const header = existing
+    ? existing
+    : `---\ntype: history\nlastUpdated: ${todayStr}\nscope: permanent\nstaleAfter: never\nowner: none\nmaxLines: 3500\n---\n\n# Resolved Issues — ${PROJECT_NAME}\n\n> Append-only archive of issues closed > 14 days ago. Sourced from \`../known_issues.md\`.\n\n---\n`;
+  const newBlocks = newSections.map((s) => s.lines.join('\n').replace(/\n+$/, '')).join('\n\n---\n\n');
+  if (!newBlocks) return header;
+  return `${header}\n${newBlocks}\n`;
+};
+
+const main = async () => {
+  const { flags, opts } = parseArgs(process.argv);
+  const today = opts.today
+    ? new Date(`${opts.today}T00:00:00Z`)
+    : new Date(new Date().toISOString().slice(0, 10) + 'T00:00:00Z');
+  const cutoffDate = new Date(today.getTime() - (opts.cutoffDays - 1) * MS_PER_DAY);
+  const todayStr = today.toISOString().slice(0, 10);
+
+  const text = await readFile(KNOWN_ISSUES_PATH, 'utf8');
+  const { frontmatter, sections } = parseKnownIssues(text);
+
+  const classified = sections.map((s) => ({ section: s, ...classifySection(s, cutoffDate) }));
+  const archivable = classified.filter((c) => c.kind === 'archivable');
+
+  if (flags.check) {
+    if (archivable.length > 0) {
+      console.error(`[archive-issues] FAIL: ${archivable.length} archivable issues found in known_issues.md.`);
+      for (const c of archivable) console.error(`  - ${c.section.heading.trim()}`);
+      console.error('Run the issues archive script (without --check) to rotate.');
+      process.exit(1);
+    }
+    console.log('[archive-issues] OK — no FIXED issues older than 14 days in known_issues.md.');
+    process.exit(0);
+  }
+
+  if (flags.dryRun) {
+    console.log('[archive-issues] DRY-RUN — no files will be changed.');
+    console.log(`  cutoffDate: ${cutoffDate.toISOString().slice(0, 10)}`);
+    console.log(`  total sections: ${sections.length}`);
+    console.log(`  archivable: ${archivable.length}`);
+    for (const c of archivable) console.log(`    - ${c.section.heading.trim()}`);
+    return;
+  }
+
+  if (archivable.length === 0) {
+    console.log('[archive-issues] nothing to archive.');
+    return;
+  }
+
+  await mkdir(HISTORY_DIR, { recursive: true });
+  const existing = existsSync(RESOLVED_PATH) ? await readFile(RESOLVED_PATH, 'utf8') : '';
+  const updatedResolved = buildResolvedFile(existing, archivable.map((c) => c.section), todayStr);
+  await writeFile(RESOLVED_PATH, updatedResolved, 'utf8');
+
+  const keptSections = classified.filter((c) => c.kind !== 'archivable').map((c) => c.section);
+  // Rebuild known_issues.md
+  const rebuilt = [
+    frontmatter.trim(),
+    '',
+    ...keptSections.map((s) => s.lines.join('\n').replace(/\n+$/, '')),
+    '',
+  ]
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim() + '\n';
+  await writeFile(KNOWN_ISSUES_PATH, rebuilt, 'utf8');
+
+  console.log(`[archive-issues] archived ${archivable.length} issue(s) to ${relative(ROOT, RESOLVED_PATH)}`);
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/references/scripts/archive-issues.test.mjs

@@ -0,0 +1,95 @@
+import { describe, it } from 'node:test';
+import { expect } from './_expect-shim.mjs';
+import {
+  parseKnownIssues,
+  classifySection,
+  buildResolvedFile,
+} from './archive-issues.mjs';
+
+const FM = '---\ntype: reference\nlastUpdated: 2026-05-24\nmaxLines: 240\n---\n';
+
+describe('parseKnownIssues', () => {
+  it('extracts frontmatter and each ### section', () => {
+    const text = `${FM}\n# Known Issues\n\n## High\n\n### Issue-001: foo\n\nbody one.\n\n### ~~Issue-002: bar~~\n\nbody two.\n`;
+    const parsed = parseKnownIssues(text);
+    expect(parsed.frontmatter).toBe(FM);
+    const issueSections = parsed.sections.filter((s) => s.heading !== null);
+    expect(issueSections).toHaveLength(2);
+    expect(issueSections[0].heading).toBe('### Issue-001: foo');
+  });
+
+  it('treats body before any ### as a preamble section', () => {
+    const text = `${FM}\n# Header\n\npreamble text\n\n### Issue-001: foo\n\nbody.\n`;
+    const parsed = parseKnownIssues(text);
+    expect(parsed.sections[0].heading).toBeNull();
+    expect(parsed.sections[0].lines.join('\n')).toContain('preamble text');
+  });
+});
+
+describe('classifySection', () => {
+  const cutoff = new Date('2026-05-20T00:00:00Z'); // 14 days before today=2026-05-24 ... actually let's use real cutoff math
+
+  it('returns preamble when heading is null', () => {
+    expect(classifySection({ heading: null, lines: [] }, cutoff).kind).toBe('preamble');
+  });
+
+  it('returns open when issue heading is not strikethrough', () => {
+    const section = {
+      heading: '### Issue-013: example open issue',
+      lines: ['### Issue-013: example open issue', '', '**Status:** Accepted'],
+    };
+    expect(classifySection(section, cutoff).kind).toBe('open');
+  });
+
+  it('returns archivable when strikethrough AND FIXED date older than cutoff', () => {
+    const section = {
+      heading: '### ~~Issue-001: example fixed feature~~',
+      lines: ['### ~~Issue-001: example fixed feature~~', '', '**Status:** ✅ FIXED (2026.04.10)'],
+    };
+    const result = classifySection(section, cutoff);
+    expect(result.kind).toBe('archivable');
+    expect(result.fixedDate.toISOString().slice(0, 10)).toBe('2026-04-10');
+  });
+
+  it('returns fixed-recent when strikethrough AND FIXED date newer than cutoff', () => {
+    const section = {
+      heading: '### ~~Issue-015: example recently-fixed item~~',
+      lines: ['### ~~Issue-015: example recently-fixed item~~', '', '**Status:** ✅ FIXED (2026.05.23)'],
+    };
+    expect(classifySection(section, cutoff).kind).toBe('fixed-recent');
+  });
+
+  it('returns fixed-undated when strikethrough has no FIXED date', () => {
+    const section = {
+      heading: '### ~~Issue-002: example undated-fixed item~~',
+      lines: ['### ~~Issue-002: example undated-fixed item~~', '', '**Status:** ✅ FIXED'],
+    };
+    expect(classifySection(section, cutoff).kind).toBe('fixed-undated');
+  });
+});
+
+describe('buildResolvedFile', () => {
+  it('writes new file with header + frontmatter when existing is empty', () => {
+    const result = buildResolvedFile(
+      '',
+      [{ heading: '### ~~Issue-001~~', lines: ['### ~~Issue-001~~', '', '**Status:** ✅ FIXED (2026.01.01)'] }],
+      '2026-05-24',
+    );
+    expect(result).toMatch(/^---\n/);
+    expect(result).toMatch(/maxLines: 3500/);
+    expect(result).toMatch(/# Resolved Issues/);
+    expect(result).toMatch(/### ~~Issue-001~~/);
+  });
+
+  it('appends new sections to existing content without re-emitting the header', () => {
+    const existing = '---\ntype: history\nlastUpdated: 2026-04-01\nmaxLines: 3500\n---\n\n# Resolved Issues\n\n### ~~Issue-000~~\n\nold body.\n';
+    const result = buildResolvedFile(
+      existing,
+      [{ heading: '### ~~Issue-099~~', lines: ['### ~~Issue-099~~', '', 'new body.'] }],
+      '2026-05-24',
+    );
+    expect(result.split('# Resolved Issues').length).toBe(2); // header appears exactly once
+    expect(result).toMatch(/### ~~Issue-099~~/);
+    expect(result).toMatch(/### ~~Issue-000~~/);
+  });
+});

package/references/scripts/check-docs-size.mjs

@@ -0,0 +1,353 @@
+#!/usr/bin/env node
+// Cap-validator for docs/ai/**/*.md.
+//
+// Reads YAML frontmatter from each file and verifies:
+//   - line count ≤ maxLines                                  (blocking error)
+//   - lastUpdated within staleAfter window (e.g. 7d, 30d)    (non-blocking warning)
+//
+// Modes:
+//   (default)        run validation, print report, exit 1 if any error
+//   --report          run validation, print full table, do not exit non-zero
+//   --write-index     run validation AND regenerate docs/ai/index.md from frontmatter
+//   --check-index     verify docs/ai/index.md is in sync with source frontmatter;
+//                     exit 1 (and print how to fix) if stale. Catches the silent
+//                     drift `--write-index` is supposed to prevent.
+//
+// CLI overrides:
+//   --today=YYYY-MM-DD (default today UTC) — useful for tests / reproducible runs
+//   --quiet            print only failures (and final summary)
+
+import { readFile, writeFile, readdir, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, resolve, relative, join, basename } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const ROOT = resolve(__dirname, '..');
+const DOCS_DIR = resolve(ROOT, 'docs/ai');
+const INDEX_PATH = resolve(DOCS_DIR, 'index.md');
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+// Project-name + footer links for the index are auto-discovered (no hardcoding):
+//   project name  ← package.json "name" (fallback: repo dir basename)
+//   hierarchical  ← every AGENTS.md / CLAUDE.md below the repo root
+//   on-demand     ← .agents/skills/*-{patterns,commands}/SKILL.md
+const DEFAULT_PROJECT_NAME = 'this project';
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'dist-ssr', 'coverage', 'build', '.next']);
+
+const walkForName = async (dir, name, acc = [], depth = 0) => {
+  if (depth > 6) return acc;
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      await walkForName(join(dir, entry.name), name, acc, depth + 1);
+    } else if (entry.isFile() && entry.name === name) {
+      acc.push(join(dir, entry.name));
+    }
+  }
+  return acc;
+};
+
+export const discoverMeta = async () => {
+  let projectName = basename(ROOT);
+  try {
+    const pkg = JSON.parse(await readFile(resolve(ROOT, 'package.json'), 'utf8'));
+    if (pkg.name) projectName = pkg.name;
+  } catch {
+    /* no package.json — keep dir basename */
+  }
+  const agentsFiles = await walkForName(ROOT, 'AGENTS.md');
+  const claudeFiles = await walkForName(ROOT, 'CLAUDE.md');
+  const rootAgents = resolve(ROOT, 'AGENTS.md');
+  const rootClaude = resolve(ROOT, 'CLAUDE.md');
+  // A subdir typically holds AGENTS.md plus a CLAUDE.md symlink to it — list each
+  // dir once (prefer AGENTS.md, drop its sibling CLAUDE.md alias).
+  const agentsDirs = new Set(agentsFiles.map((file) => dirname(resolve(file))));
+  const nestedFiles = [
+    ...agentsFiles.filter((file) => resolve(file) !== rootAgents),
+    ...claudeFiles.filter(
+      (file) => resolve(file) !== rootClaude && !agentsDirs.has(dirname(resolve(file))),
+    ),
+  ];
+  const hierarchicalLinks = nestedFiles
+    .map((file) => relative(ROOT, file))
+    .sort()
+    .map((rel) => `[\`${rel}\`](../../${rel})`);
+  let onDemandLinks = [];
+  try {
+    const skillDirs = await readdir(resolve(ROOT, '.agents/skills'), { withFileTypes: true });
+    onDemandLinks = skillDirs
+      .filter((dirent) => dirent.isDirectory() && /-(patterns|commands)$/.test(dirent.name))
+      .map((dirent) => dirent.name)
+      .sort()
+      .map((name) => `[\`${name}\`](../../.agents/skills/${name}/SKILL.md)`);
+  } catch {
+    /* no .agents/skills — omit the section */
+  }
+  return { projectName, hierarchicalLinks, onDemandLinks };
+};
+
+const parseArgs = (argv) => {
+  const flags = { report: false, writeIndex: false, checkIndex: false, quiet: false };
+  const opts = { today: null };
+  for (const arg of argv.slice(2)) {
+    if (arg === '--report') flags.report = true;
+    else if (arg === '--write-index') flags.writeIndex = true;
+    else if (arg === '--check-index') flags.checkIndex = true;
+    else if (arg === '--quiet') flags.quiet = true;
+    else if (arg.startsWith('--today=')) opts.today = arg.slice('--today='.length);
+    else if (arg === '--help' || arg === '-h') {
+      console.log(
+        'Usage: check-docs-size.mjs [--report|--write-index|--check-index] [--today=YYYY-MM-DD] [--quiet]',
+      );
+      process.exit(0);
+    } else {
+      console.error(`Unknown argument: ${arg}`);
+      process.exit(2);
+    }
+  }
+  return { flags, opts };
+};
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+
+export const parseFrontmatter = (text) => {
+  const match = text.match(FRONTMATTER_RE);
+  if (!match) return null;
+  const body = match[1];
+  const fields = {};
+  for (const line of body.split('\n')) {
+    const m = line.match(/^([a-zA-Z][a-zA-Z0-9_]*):\s*(.*)$/);
+    if (!m) continue;
+    fields[m[1]] = m[2].trim();
+  }
+  return fields;
+};
+
+export const parseStaleAfter = (value) => {
+  if (!value || value === 'never') return null;
+  const m = value.match(/^(\d+)d$/);
+  if (!m) return null;
+  return Number(m[1]);
+};
+
+const walkMarkdownFiles = async (dir) => {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await walkMarkdownFiles(full)));
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      files.push(full);
+    }
+  }
+  return files;
+};
+
+export const computeToday = (todayStr) =>
+  todayStr
+    ? new Date(`${todayStr}T00:00:00Z`)
+    : new Date(new Date().toISOString().slice(0, 10) + 'T00:00:00Z');
+
+export const inspectFile = async (filePath, today) => {
+  const text = await readFile(filePath, 'utf8');
+  const lineCount = text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
+  const fm = parseFrontmatter(text);
+  const rel = relative(ROOT, filePath);
+
+  if (!fm) {
+    return {
+      path: rel,
+      lineCount,
+      frontmatter: null,
+      errors: [`missing YAML frontmatter`],
+      warnings: [],
+    };
+  }
+
+  const errors = [];
+  const warnings = [];
+
+  const maxLines = fm.maxLines ? Number(fm.maxLines) : null;
+  if (maxLines === null || Number.isNaN(maxLines)) {
+    errors.push(`frontmatter missing maxLines`);
+  } else if (lineCount > maxLines) {
+    errors.push(`${lineCount} lines > maxLines ${maxLines}`);
+  }
+
+  const staleDays = parseStaleAfter(fm.staleAfter);
+  if (staleDays !== null && fm.lastUpdated) {
+    const updated = new Date(`${fm.lastUpdated}T00:00:00Z`);
+    if (!Number.isNaN(updated.getTime())) {
+      const ageDays = Math.floor((today.getTime() - updated.getTime()) / MS_PER_DAY);
+      if (ageDays > staleDays) {
+        warnings.push(`lastUpdated ${fm.lastUpdated} is ${ageDays}d old (staleAfter ${staleDays}d)`);
+      }
+    }
+  }
+
+  return { path: rel, lineCount, frontmatter: fm, errors, warnings };
+};
+
+const formatRow = (row) => {
+  const sizeCell = row.frontmatter?.maxLines
+    ? `${row.lineCount}/${row.frontmatter.maxLines}`
+    : `${row.lineCount}/?`;
+  const status = row.errors.length > 0 ? 'X' : row.warnings.length > 0 ? '!' : 'OK';
+  return { status, sizeCell, ...row };
+};
+
+const printReport = (rows, quiet) => {
+  const widths = {
+    status: 2,
+    path: Math.max(4, ...rows.map((r) => r.path.length)),
+    size: Math.max(9, ...rows.map((r) => r.sizeCell.length)),
+    type: Math.max(4, ...rows.map((r) => (r.frontmatter?.type ?? '').length)),
+    updated: 12,
+  };
+  const printable = quiet ? rows.filter((r) => r.errors.length || r.warnings.length) : rows;
+  if (printable.length > 0) {
+    console.log(
+      `${'S'.padEnd(widths.status)}  ${'PATH'.padEnd(widths.path)}  ${'SIZE/MAX'.padEnd(widths.size)}  ${'TYPE'.padEnd(widths.type)}  ${'UPDATED'.padEnd(widths.updated)}`,
+    );
+    for (const row of printable) {
+      console.log(
+        `${row.status.padEnd(widths.status)}  ${row.path.padEnd(widths.path)}  ${row.sizeCell.padEnd(widths.size)}  ${(row.frontmatter?.type ?? '').padEnd(widths.type)}  ${(row.frontmatter?.lastUpdated ?? '').padEnd(widths.updated)}`,
+      );
+      for (const err of row.errors) console.log(`     - ERROR  ${err}`);
+      for (const warn of row.warnings) console.log(`     - WARN   ${warn}`);
+    }
+  }
+};
+
+const INDEX_HEADER = `---
+type: reference
+lastUpdated: __TODAY__
+scope: permanent
+staleAfter: 30d
+owner: none
+maxLines: 80
+---
+
+# Memory Map — __PROJECT__ \`docs/ai/\`
+
+> **Auto-generated** — edit the source files' frontmatter, not this file. Regenerate after changes.
+> Layered context architecture:
+> **Always-loaded** — root \`AGENTS.md\` + this index.
+> **On-demand** — read a specific \`docs/ai/\` file when its "Read When" applies.
+> **Hierarchical** — subdirectory \`AGENTS.md\` files load when working in that folder.
+> **Archive** — \`history/recent.md\` (WARM) + \`history/condensed-index.md\` + per-month files.
+
+## Files
+
+`;
+
+const formatIndexRow = (row) => {
+  const fm = row.frontmatter ?? {};
+  const name = row.path.replace(/^docs\/ai\//, '');
+  const link = `[\`${name}\`](./${name})`;
+  return `| ${link} | ${fm.type ?? '—'} | ${row.lineCount}/${fm.maxLines ?? '—'} | ${fm.lastUpdated ?? '—'} | ${fm.staleAfter ?? '—'} |`;
+};
+
+// Pure index renderer — given inspected rows + the date to stamp in the header,
+// returns the exact bytes `docs/ai/index.md` should contain. Shared by
+// `--write-index` (writes it) and `--check-index` (diffs against on-disk).
+export const buildIndex = (rows, todayStr, meta = {}) => {
+  const projectName = meta.projectName ?? DEFAULT_PROJECT_NAME;
+  const onDemandLinks = meta.onDemandLinks ?? [];
+  const hierarchicalLinks = meta.hierarchicalLinks ?? [];
+  const sorted = [...rows].sort((a, b) => a.path.localeCompare(b.path));
+  const header = INDEX_HEADER.replace('__TODAY__', todayStr).replace('__PROJECT__', projectName);
+  const tableHeader = `| File | Type | Lines/Max | Updated | Stale after |\n|------|------|-----------|---------|-------------|`;
+  const tableRows = sorted
+    .filter((r) => r.path !== 'docs/ai/index.md')
+    .map(formatIndexRow)
+    .join('\n');
+  const onDemandSection =
+    onDemandLinks.length > 0
+      ? `\n\n## Skills (on-demand)\n\n${onDemandLinks.map((link) => `- ${link}`).join('\n')}`
+      : '';
+  const hierarchicalSection =
+    hierarchicalLinks.length > 0
+      ? `\n\n## Subdirectory \`AGENTS.md\` (hierarchical)\n\n${hierarchicalLinks.map((link) => `- ${link}`).join('\n')}`
+      : '';
+  return `${header}${tableHeader}\n${tableRows}${onDemandSection}${hierarchicalSection}\n`;
+};
+
+// Decides whether an on-disk index is in sync with the source frontmatter.
+// The index is regenerated in memory using the on-disk index's OWN `lastUpdated`
+// for the header, so a mere day-rollover (no content change) is NOT flagged —
+// only genuine drift in the file table (added/removed files, changed
+// type/cap/lastUpdated/staleAfter, or a changed line count) makes it stale.
+export const checkIndexFreshness = (rows, onDiskText, meta = {}) => {
+  if (onDiskText === null || onDiskText === undefined || onDiskText === '') {
+    return { fresh: false, expected: buildIndex(rows, 'unknown', meta) };
+  }
+  const fm = parseFrontmatter(onDiskText);
+  const headerDate = fm?.lastUpdated ?? 'unknown';
+  const expected = buildIndex(rows, headerDate, meta);
+  return { fresh: expected === onDiskText, expected };
+};
+
+const writeIndex = async (rows, today, meta) => {
+  const body = buildIndex(rows, today.toISOString().slice(0, 10), meta);
+  await writeFile(INDEX_PATH, body, 'utf8');
+};
+
+const main = async () => {
+  const { flags, opts } = parseArgs(process.argv);
+  const today = computeToday(opts.today);
+  const files = (await walkMarkdownFiles(DOCS_DIR)).sort();
+  const inspected = await Promise.all(files.map((f) => inspectFile(f, today)));
+  const rows = inspected.map(formatRow);
+
+  const meta = flags.writeIndex || flags.checkIndex ? await discoverMeta() : null;
+
+  if (flags.writeIndex) {
+    await writeIndex(rows, today, meta);
+    console.log(`Wrote ${relative(ROOT, INDEX_PATH)}`);
+    const after = await stat(INDEX_PATH);
+    if (after.size === 0) {
+      console.error('index.md was written empty');
+      process.exit(2);
+    }
+  }
+
+  if (flags.checkIndex) {
+    const onDisk = existsSync(INDEX_PATH) ? await readFile(INDEX_PATH, 'utf8') : null;
+    const { fresh } = checkIndexFreshness(rows, onDisk, meta);
+    if (!fresh) {
+      console.error(
+        `[check-docs-size] FAIL: ${relative(ROOT, INDEX_PATH)} is stale (out of sync with source frontmatter). Regenerate the index (--write-index) and commit the regenerated file.`,
+      );
+      process.exit(1);
+    }
+    console.log(
+      `[check-docs-size] OK — ${relative(ROOT, INDEX_PATH)} is in sync with source frontmatter.`,
+    );
+    return;
+  }
+
+  printReport(rows, flags.quiet);
+  const errorCount = rows.reduce((n, r) => n + r.errors.length, 0);
+  const warnCount = rows.reduce((n, r) => n + r.warnings.length, 0);
+  console.log(
+    `\n${rows.length} files inspected  —  ${errorCount} error(s), ${warnCount} warning(s)`,
+  );
+
+  if (errorCount > 0 && !flags.report) process.exit(1);
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) {
+  await main();
+}