add doc-agent

.github/scripts/doc-agent/.gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+*.log
+.env
+.env.local
+doc-review-report.md
+doc-review-comments.json

.github/scripts/doc-agent/README.md

@@ -0,0 +1,101 @@
+# doc-agent
+
+Automated documentation agent for the xrpld C++ codebase. Built on the
+Claude Agent SDK.
+
+## What it does
+
+Two modes:
+
+- **document** — Add Doxygen `/** */` documentation to a C++ file or
+  directory. The agent reads the file, related tests, and module skill
+  context, then writes documentation comments per the project standards in
+  `docs/DOCUMENTATION_STANDARDS.md`.
+- **review** — Given a git diff range, detect documentation drift. Used by
+  the `doc-review` GitHub Action and locally for testing.
+
+## Requirements
+
+- Node.js >= 20
+- `ANTHROPIC_API_KEY` environment variable
+- Tools the agent uses: `git`, `gh` (for `--pr`)
+
+## Install
+
+```sh
+cd .github/scripts/doc-agent
+npm install
+```
+
+## Build and lint
+
+```sh
+npm run typecheck     # type check without emitting
+npm run build         # compile to dist/
+npm run lint          # biome lint
+npm run format        # biome format --write
+npm run check         # lint + format check (read-only)
+npm run check:fix     # lint + format + fix
+```
+
+## Usage
+
+```sh
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# Document a single file
+npm run document include/xrpl/basics/base_uint.h
+
+# Document an entire module
+npm run document include/xrpl/basics/
+
+# Review a git range
+npm run review develop..HEAD
+
+# Review a PR
+npm run review -- --pr 1234
+```
+
+When invoked outside the xrpld repo, set `XRPLD_ROOT` to the path of the
+checkout you want to operate on.
+
+## Outputs
+
+The `review` mode writes two files in the current directory:
+
+- `doc-review-report.md` — markdown summary, posted as the PR comment
+- `doc-review-comments.json` — array of inline review comments, posted
+  individually on the PR diff
+
+## Layout
+
+```
+doc-agent/
+├── package.json
+├── tsconfig.json
+├── biome.json
+├── prompts/
+│   ├── document-file.md     # System prompt for documentation mode
+│   └── review-diff.md       # System prompt for review mode
+└── src/
+    ├── index.ts             # CLI entry point
+    ├── config.ts            # Paths, model, module-skill map
+    ├── prompt-loader.ts     # Loads prompts + module skill context
+    ├── document.ts          # Document mode
+    ├── review.ts            # Review mode
+    └── types.ts             # Shared types
+```
+
+## Module skills
+
+The agent injects per-module context from `docs/skills/soul/*.md` into its
+system prompt based on the file path being processed. The mapping lives in
+`src/config.ts` (`MODULE_SKILL_MAP`).
+
+## Notes
+
+- Prompts live in markdown files, not source, so they can be edited without
+  touching code.
+- The `document` mode uses `permissionMode: 'acceptEdits'` so the agent
+  writes directly to the target files. Run against a clean git tree so you
+  can review and revert if needed.

.github/scripts/doc-agent/biome.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": false,
+    "ignore": ["dist", "node_modules"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100,
+    "lineEnding": "lf"
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "trailingCommas": "all",
+      "semicolons": "always",
+      "arrowParentheses": "always"
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "correctness": {
+        "noUnusedVariables": "error",
+        "noUnusedImports": "error",
+        "useExhaustiveDependencies": "error"
+      },
+      "style": {
+        "useConst": "error",
+        "useTemplate": "error",
+        "useImportType": "error",
+        "useExportType": "error",
+        "noNonNullAssertion": "warn"
+      },
+      "suspicious": {
+        "noExplicitAny": "error",
+        "noConsoleLog": "off"
+      },
+      "complexity": {
+        "noUselessTypeConstraint": "error",
+        "useArrowFunction": "error",
+        "useLiteralKeys": "off"
+      }
+    }
+  },
+  "organizeImports": {
+    "enabled": true
+  }
+}

.github/scripts/doc-agent/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "xrpld-doc-agent",
+  "version": "0.1.0",
+  "description": "Automated documentation agent for the xrpld C++ codebase. Uses the Claude Agent SDK to generate Doxygen documentation and detect doc drift on PRs.",
+  "type": "module",
+  "private": true,
+  "bin": {
+    "doc-agent": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "document": "tsx src/index.ts document",
+    "review": "tsx src/index.ts review",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome lint src",
+    "format": "biome format --write src",
+    "check": "biome check src",
+    "check:fix": "biome check --write src"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.1.10"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

.github/scripts/doc-agent/prompts/document-file.md

@@ -0,0 +1,63 @@
+You are documenting C++ code in the xrpld (XRP Ledger daemon) codebase.
+
+Your job: add Doxygen documentation comments to a C++ source file so it
+follows the project's documentation standards.
+
+## Documentation Standards
+
+Read `docs/DOCUMENTATION_STANDARDS.md` for the full specification. Key rules:
+
+- Use `/** ... */` Javadoc-style Doxygen comments (dominant pattern in the
+  codebase)
+- For multi-line comments, prefix each line with ` * ` (space, asterisk, space)
+- Document every public class, struct, function, and enum
+- Document public methods with `@param`, `@return`, `@throw`/`@throws`, `@note`
+- Continuation lines for `@param` descriptions indent 4 spaces from the `*`
+- Document `.cpp` files only where the algorithm or invariant is non-obvious
+- `JAVADOC_AUTOBRIEF = YES` — the first sentence is automatically the brief,
+  so `@brief` is optional
+
+## Quality Rules
+
+- **Never paraphrase the signature.** `/** Returns the account ID. */` on
+  `AccountID getAccountID()` is worse than no doc.
+- **Document behavior, invariants, and the WHY.** What does this function do
+  in terms a developer can use? What can go wrong? What's the contract?
+- **Read the implementation before writing the doc.** Don't guess what the
+  function does — read it.
+- **Cross-reference test files** to find edge cases worth documenting in
+  `@note` tags.
+- **Be terse.** Target 2-5 lines for classes, 1-3 for functions, plus tag
+  lines. If you need a multi-paragraph essay, the code probably needs help.
+- **Wrong docs are worse than no docs.** If you're not sure what the code
+  does, say so — don't invent.
+
+## Module Context
+
+Before you start, read the relevant skill file in `docs/skills/soul/` for
+the module you're working on. These capture per-module conventions, key
+classes, and gotchas:
+
+- `basics`, `crypto`, `json`, `beast` — foundation utilities
+- `protocol` — STObject, SField, Serializer, TER codes, Features, Keylets
+- `ledger` — ReadView/ApplyView, state tables, payment sandbox
+- `tx` / `transactors` — transaction pipeline
+- `consensus`, `peering`, `nodestore`, `shamap`, `rpc` — see `docs/skills/soul/`
+
+## Process
+
+1. Read the target file completely
+2. Read the corresponding skill file in `docs/skills/soul/` if one applies
+3. Identify entities that need documentation (public classes, structs,
+   public methods, free functions in headers, enums)
+4. For each entity: read the implementation (and tests if helpful), then
+   write a Doxygen comment that captures behavior and intent
+5. Use the Edit tool to add the comments to the file
+6. Do NOT modify code logic — only add documentation
+7. Do NOT add documentation to entities that don't need it (private members
+   with obvious purpose, simple getters where the name is self-explanatory)
+
+When you finish, summarize:
+- How many entities you documented
+- Any entities you skipped and why
+- Any code patterns you discovered that should be added to a skill file

.github/scripts/doc-agent/prompts/review-diff.md

@@ -0,0 +1,55 @@
+You are reviewing a pull request to the xrpld (XRP Ledger daemon) codebase
+for documentation drift.
+
+Your job: given a git diff, determine whether the changes invalidate
+existing Doxygen documentation comments, or introduce new public API
+surface that lacks documentation.
+
+## Rules
+
+- Only flag REAL semantic drift: changed behavior, new parameters, removed
+  functionality, changed return values, new error conditions, changed
+  invariants.
+- Do NOT flag cosmetic changes (whitespace, formatting, internal renames
+  that don't change semantics).
+- Do NOT suggest docs for private implementation details unless the logic
+  is genuinely non-obvious.
+- Do NOT paraphrase function signatures. Good docs explain WHY and what
+  BEHAVIOR — not what the code literally does.
+- Be terse: 1-3 sentences per finding.
+
+## Process
+
+1. For each changed file, get the git diff and the current file content
+2. Read existing doc comments on the modified entities
+3. For each modified entity, ask:
+   - Did behavior change in a way the docs miss?
+   - Did parameters or return values change?
+   - Are there new error conditions?
+   - Did the contract / invariant change?
+   - Is this a NEW public API surface with no docs?
+4. Read the module's skill file in `docs/skills/soul/` for context
+5. Read related tests if it helps you understand the change
+6. Output findings as structured JSON (see below)
+
+## Output Format
+
+```json
+{
+  "summary": "One-paragraph summary of doc state for this PR",
+  "issues": [
+    {
+      "file": "include/xrpl/protocol/Payment.h",
+      "line": 42,
+      "severity": "warning" | "suggestion",
+      "message": "Brief description of the doc issue",
+      "suggested_doc": "Optional: suggested doc comment text"
+    }
+  ]
+}
+```
+
+- `severity: warning` = doc is now incorrect / misleading
+- `severity: suggestion` = new code lacks docs, would be nice to add
+
+If no issues found, return `{"summary": "Documentation is up to date.", "issues": []}`.

.github/scripts/doc-agent/src/config.ts

@@ -0,0 +1,77 @@
+/**
+ * Shared configuration for doc-agent.
+ *
+ * Paths are resolved relative to the doc-agent directory so the tool works
+ * regardless of where it's invoked from.
+ */
+
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/** Absolute path to the doc-agent root (parent of src/). */
+export const AGENT_DIR: string = resolve(__dirname, '..');
+
+/** Absolute path to the prompts directory. */
+export const PROMPTS_DIR: string = resolve(AGENT_DIR, 'prompts');
+
+/**
+ * Absolute path to the xrpld repo root.
+ *
+ * Defaults to three levels up from doc-agent (which lives at
+ * .github/scripts/doc-agent/). Override with the XRPLD_ROOT env var when
+ * running against a different checkout.
+ */
+export const XRPLD_ROOT: string = process.env['XRPLD_ROOT'] ?? resolve(AGENT_DIR, '..', '..', '..');
+
+/** Model used for documentation generation and review. */
+export const MODEL: string = process.env['DOC_AGENT_MODEL'] ?? 'claude-opus-4-7';
+
+/** Absolute path to the skills directory inside the xrpld repo. */
+export const SKILLS_DIR: string = resolve(XRPLD_ROOT, 'docs', 'skills');
+
+/**
+ * Map module path prefixes to their skill file name in docs/skills/soul/.
+ *
+ * Used to inject module-specific context into the agent's system prompt
+ * when documenting or reviewing code in that module.
+ */
+export const MODULE_SKILL_MAP: Readonly<Record<string, string | null>> = {
+  'src/libxrpl/basics/': null,
+  'src/libxrpl/crypto/': 'cryptography.md',
+  'src/libxrpl/json/': null,
+  'src/libxrpl/beast/': null,
+  'src/libxrpl/protocol/': 'protocol.md',
+  'src/libxrpl/ledger/': 'ledger.md',
+  'src/libxrpl/tx/': 'transactors.md',
+  'src/libxrpl/nodestore/': 'nodestore.md',
+  'src/libxrpl/shamap/': 'shamap.md',
+  'src/libxrpl/rdb/': 'sql.md',
+  'src/xrpld/consensus/': 'consensus.md',
+  'src/xrpld/overlay/': 'peering.md',
+  'src/xrpld/peerfinder/': 'peering.md',
+  'src/xrpld/rpc/': 'rpc.md',
+  'include/xrpl/crypto/': 'cryptography.md',
+  'include/xrpl/protocol/': 'protocol.md',
+  'include/xrpl/ledger/': 'ledger.md',
+  'include/xrpl/tx/': 'transactors.md',
+  'include/xrpl/nodestore/': 'nodestore.md',
+  'include/xrpl/shamap/': 'shamap.md',
+};
+
+/**
+ * Resolve which skill file applies to a given source path.
+ *
+ * @param sourcePath - Path relative to the xrpld repo root
+ * @returns The skill file name, or null if no skill applies
+ */
+export function skillForPath(sourcePath: string): string | null {
+  for (const [prefix, skillFile] of Object.entries(MODULE_SKILL_MAP)) {
+    if (sourcePath.startsWith(prefix) || sourcePath.includes(`/${prefix}`)) {
+      return skillFile;
+    }
+  }
+  return null;
+}

.github/scripts/doc-agent/src/document.ts

@@ -0,0 +1,114 @@
+/**
+ * Document mode: add Doxygen docs to a file or all files in a directory.
+ */
+
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { MODEL, XRPLD_ROOT } from './config.js';
+import { loadSystemPrompt } from './prompt-loader.js';
+
+const CPP_EXTENSIONS: ReadonlySet<string> = new Set(['.h', '.hpp', '.cpp']);
+
+/**
+ * Recursively find all C++ source files under a target path.
+ *
+ * @param target - File or directory path (relative to xrpld root or absolute)
+ * @returns Absolute paths of all matching files
+ */
+function findCppFiles(target: string): string[] {
+  const absTarget = resolve(XRPLD_ROOT, target);
+  if (!existsSync(absTarget)) {
+    throw new Error(`Target does not exist: ${absTarget}`);
+  }
+
+  const stat = statSync(absTarget);
+  if (stat.isFile()) {
+    return [absTarget];
+  }
+
+  const results: string[] = [];
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (entry.isFile()) {
+        const dotIdx = entry.name.lastIndexOf('.');
+        if (dotIdx === -1) continue;
+        const ext = entry.name.slice(dotIdx);
+        if (CPP_EXTENSIONS.has(ext)) {
+          results.push(full);
+        }
+      }
+    }
+  };
+  walk(absTarget);
+  return results;
+}
+
+/**
+ * Document a single file by running the documentation agent against it.
+ */
+async function documentFile(absPath: string): Promise<void> {
+  const relPath = relative(XRPLD_ROOT, absPath);
+  console.log(`\n=== Documenting: ${relPath} ===`);
+
+  const systemPrompt = await loadSystemPrompt('document-file', relPath);
+  const userPrompt = `Add Doxygen documentation to: ${relPath}
+
+The file is rooted at ${XRPLD_ROOT}. Use the Read tool to read it, the Edit
+tool to add documentation, and Glob/Grep to find related tests or callers
+when needed.
+
+Do not modify any code logic — only add documentation comments.`;
+
+  const result = query({
+    prompt: userPrompt,
+    options: {
+      model: MODEL,
+      systemPrompt,
+      cwd: XRPLD_ROOT,
+      allowedTools: ['Read', 'Edit', 'Glob', 'Grep', 'Bash'],
+      permissionMode: 'acceptEdits',
+    },
+  });
+
+  for await (const message of result) {
+    if (message.type === 'assistant') {
+      const content = message.message?.content;
+      if (Array.isArray(content)) {
+        for (const block of content) {
+          if (block.type === 'text') {
+            process.stdout.write(block.text);
+          }
+        }
+      }
+    }
+    if (message.type === 'result') {
+      const cost = message.total_cost_usd?.toFixed(4) ?? '?';
+      const inTok = message.usage?.['input_tokens'] ?? 0;
+      const outTok = message.usage?.['output_tokens'] ?? 0;
+      console.log(`\n[Cost: $${cost}, Tokens: ${inTok}/${outTok}]`);
+    }
+  }
+}
+
+/**
+ * Document a file or every C++ file under a directory.
+ *
+ * @param target - File or directory path
+ */
+export async function documentTarget(target: string): Promise<void> {
+  const files = findCppFiles(target);
+  console.log(`Found ${files.length} C++ file(s) to document.`);
+
+  for (const file of files) {
+    try {
+      await documentFile(file);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(`Failed to document ${file}: ${message}`);
+    }
+  }
+}

.github/scripts/doc-agent/src/index.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * xrpld doc-agent CLI entry point.
+ *
+ * @example
+ *   doc-agent document src/libxrpl/basics/base_uint.h
+ *   doc-agent document include/xrpl/basics/
+ *   doc-agent review develop..HEAD
+ *   doc-agent review --pr 1234
+ */
+
+import { documentTarget } from './document.js';
+import { reviewDiff } from './review.js';
+
+const USAGE = `
+xrpld doc-agent
+
+Usage:
+  doc-agent document <file-or-directory>   Add Doxygen documentation
+  doc-agent review <base>..<head>          Detect doc drift in range
+  doc-agent review --pr <number>           Detect doc drift for a PR
+
+Environment:
+  ANTHROPIC_API_KEY  (required)  Anthropic API key
+  XRPLD_ROOT         (optional)  Path to xrpld repo root (default: repo root)
+  DOC_AGENT_MODEL    (optional)  Model override (default: claude-opus-4-7)
+`;
+
+function printUsageAndExit(code: number): never {
+  console.error(USAGE);
+  process.exit(code);
+}
+
+const HELP_MODES: ReadonlySet<string> = new Set(['help', '--help', '-h']);
+
+async function main(): Promise<void> {
+  const [mode, ...args] = process.argv.slice(2);
+
+  if (process.env['ANTHROPIC_API_KEY'] === undefined) {
+    console.error('ERROR: ANTHROPIC_API_KEY environment variable is required.');
+    process.exit(1);
+  }
+
+  if (mode === undefined || HELP_MODES.has(mode)) {
+    printUsageAndExit(0);
+  }
+
+  if (mode === 'document') {
+    const target = args[0];
+    if (target === undefined) printUsageAndExit(1);
+    await documentTarget(target);
+    return;
+  }
+
+  if (mode === 'review') {
+    if (args.length === 0) printUsageAndExit(1);
+    await reviewDiff(args);
+    return;
+  }
+
+  console.error(`Unknown mode: ${mode}`);
+  printUsageAndExit(1);
+}
+
+main().catch((err: unknown) => {
+  const message = err instanceof Error ? (err.stack ?? err.message) : String(err);
+  console.error('FATAL:', message);
+  process.exit(1);
+});

.github/scripts/doc-agent/src/prompt-loader.ts

@@ -0,0 +1,34 @@
+/**
+ * Loads system prompts and injects module-specific skill context.
+ */
+
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { PROMPTS_DIR, SKILLS_DIR, skillForPath } from './config.js';
+
+/**
+ * Load a system prompt from prompts/ and append the relevant module skill
+ * if one applies to the given source path.
+ *
+ * @param promptName - Base name of the prompt file (without .md extension)
+ * @param sourcePath - Path relative to the xrpld repo root
+ * @returns The fully-assembled system prompt
+ */
+export async function loadSystemPrompt(promptName: string, sourcePath: string): Promise<string> {
+  const basePromptPath = resolve(PROMPTS_DIR, `${promptName}.md`);
+  const basePrompt = await readFile(basePromptPath, 'utf8');
+
+  const skillFile = skillForPath(sourcePath);
+  if (skillFile === null) {
+    return basePrompt;
+  }
+
+  const skillPath = resolve(SKILLS_DIR, 'soul', skillFile);
+  if (!existsSync(skillPath)) {
+    return basePrompt;
+  }
+
+  const skill = await readFile(skillPath, 'utf8');
+  return `${basePrompt}\n\n## Module Skill (${skillFile})\n\n${skill}`;
+}

.github/scripts/doc-agent/src/review.ts

@@ -0,0 +1,222 @@
+/**
+ * Review mode: detect documentation drift in a git diff range.
+ *
+ * Used by the doc-review GitHub Action and locally for testing.
+ */
+
+import { execSync } from 'node:child_process';
+import { writeFile } from 'node:fs/promises';
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { MODEL, XRPLD_ROOT } from './config.js';
+import { loadSystemPrompt } from './prompt-loader.js';
+import type { FileReviewResult, GitRange, ReviewIssue, ReviewOutput } from './types.js';
+
+const MAX_DIFF_CHARS = 12_000;
+const TRACKED_PATH_PATTERN = /^(include|src\/libxrpl|src\/xrpld)\//;
+const CPP_FILE_PATTERN = /\.(h|hpp|cpp)$/;
+
+/**
+ * Parse the CLI arguments into a base..head git range.
+ *
+ * Accepts either:
+ *   - `base..head` (e.g. `develop..HEAD`)
+ *   - `--pr <number>` (resolves via `gh pr view`)
+ */
+function parseRangeArgs(args: readonly string[]): GitRange {
+  const first = args[0];
+  if (first === undefined) {
+    throw new Error('Expected range as base..head or --pr <number>');
+  }
+
+  if (first === '--pr') {
+    const pr = args[1];
+    if (pr === undefined) {
+      throw new Error('--pr requires a PR number');
+    }
+    const base = execSync(`gh pr view ${pr} --json baseRefOid -q .baseRefOid`, {
+      cwd: XRPLD_ROOT,
+    })
+      .toString()
+      .trim();
+    const head = execSync(`gh pr view ${pr} --json headRefOid -q .headRefOid`, {
+      cwd: XRPLD_ROOT,
+    })
+      .toString()
+      .trim();
+    return { base, head };
+  }
+
+  const match = first.match(/^([^.]+)\.\.([^.]+)$/);
+  if (match === null || match[1] === undefined || match[2] === undefined) {
+    throw new Error('Expected range as base..head or --pr <number>');
+  }
+  return { base: match[1], head: match[2] };
+}
+
+/**
+ * Get the list of C++ source files changed in the given git range,
+ * filtered to paths the doc-agent cares about.
+ */
+function getChangedCppFiles(range: GitRange): string[] {
+  const out = execSync(`git diff --name-only ${range.base}...${range.head}`, {
+    cwd: XRPLD_ROOT,
+  }).toString();
+
+  return out
+    .split('\n')
+    .filter((line) => line.length > 0)
+    .filter((file) => CPP_FILE_PATTERN.test(file))
+    .filter((file) => TRACKED_PATH_PATTERN.test(file));
+}
+
+/** Get the unified diff for a single file in the given range. */
+function getFileDiff(range: GitRange, file: string): string {
+  return execSync(`git diff ${range.base}...${range.head} -- "${file}"`, {
+    cwd: XRPLD_ROOT,
+    maxBuffer: 10 * 1024 * 1024,
+  }).toString();
+}
+
+/** Extract a JSON object from a possibly-fenced model response. */
+function extractJson(response: string): ReviewOutput | null {
+  const fenced = response.match(/```json\s*([\s\S]*?)```/);
+  const raw = fenced?.[1] ?? response.match(/(\{[\s\S]*\})/)?.[1];
+  if (raw === undefined) return null;
+  try {
+    return JSON.parse(raw) as ReviewOutput;
+  } catch {
+    return null;
+  }
+}
+
+/** Send one file's diff to the agent and parse the response. */
+async function reviewFile(range: GitRange, file: string): Promise<FileReviewResult | null> {
+  console.log(`\n=== Reviewing: ${file} ===`);
+  const diff = getFileDiff(range, file);
+  if (diff.trim().length === 0) return null;
+
+  const systemPrompt = await loadSystemPrompt('review-diff', file);
+  const userPrompt = `Review this diff for documentation drift:
+
+## File: ${file}
+
+## Diff
+\`\`\`
+${diff.slice(0, MAX_DIFF_CHARS)}
+\`\`\`
+
+Use the Read tool to inspect the current state of the file, related tests,
+or callers if needed. Output findings as JSON per the schema in the system
+prompt.`;
+
+  let response = '';
+  const result = query({
+    prompt: userPrompt,
+    options: {
+      model: MODEL,
+      systemPrompt,
+      cwd: XRPLD_ROOT,
+      allowedTools: ['Read', 'Glob', 'Grep', 'Bash'],
+      permissionMode: 'acceptEdits',
+    },
+  });
+
+  for await (const message of result) {
+    if (message.type === 'assistant') {
+      const content = message.message?.content;
+      if (Array.isArray(content)) {
+        for (const block of content) {
+          if (block.type === 'text') {
+            response += block.text;
+          }
+        }
+      }
+    }
+  }
+
+  const parsed = extractJson(response);
+  if (parsed === null) {
+    console.warn(`  No JSON output for ${file}, skipping`);
+    return null;
+  }
+
+  const issues: ReviewIssue[] = parsed.issues.map((issue) => ({
+    file: issue.file ?? file,
+    line: issue.line,
+    severity: issue.severity,
+    message: issue.message,
+    ...(issue.suggested_doc !== undefined && { suggestedDoc: issue.suggested_doc }),
+  }));
+
+  return { file, summary: parsed.summary, issues };
+}
+
+/** Build the markdown report posted to the PR. */
+function buildReport(fileCount: number, results: readonly FileReviewResult[]): string {
+  const issues = results.flatMap((r) => r.issues);
+  const warnings = issues.filter((i) => i.severity === 'warning').length;
+  const suggestions = issues.length - warnings;
+
+  const lines: string[] = ['## Documentation Review Report', ''];
+  lines.push(
+    issues.length === 0
+      ? 'No documentation issues found.'
+      : `Found **${issues.length}** issue(s) across **${fileCount}** changed file(s): ${warnings} warning(s), ${suggestions} suggestion(s).`,
+  );
+  lines.push('');
+
+  for (const result of results) {
+    if (result.issues.length === 0) continue;
+    lines.push(`### \`${result.file}\``, '', result.summary, '');
+    for (const issue of result.issues) {
+      const tag = issue.severity === 'warning' ? '**Warning:**' : '**Suggestion:**';
+      lines.push(`- ${tag} Line ${issue.line}: ${issue.message}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('---', '*Automated review by doc-agent.*');
+  return lines.join('\n');
+}
+
+/**
+ * Review the documentation drift introduced by a git range or PR.
+ *
+ * Writes two output files in the current working directory:
+ *   - doc-review-report.md (markdown summary for PR comment)
+ *   - doc-review-comments.json (inline review comments)
+ */
+export async function reviewDiff(args: readonly string[]): Promise<void> {
+  const range = parseRangeArgs(args);
+  console.log(`Reviewing range: ${range.base}...${range.head}`);
+
+  const files = getChangedCppFiles(range);
+  if (files.length === 0) {
+    console.log('No C++ files changed in this range.');
+    await writeFile('doc-review-report.md', '## Documentation Review\n\nNo C++ files changed.\n');
+    await writeFile('doc-review-comments.json', '[]');
+    return;
+  }
+
+  console.log(`Found ${files.length} changed C++ file(s).`);
+
+  const results: FileReviewResult[] = [];
+  for (const file of files) {
+    try {
+      const result = await reviewFile(range, file);
+      if (result !== null) results.push(result);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.warn(`  Review failed for ${file}: ${message}`);
+    }
+  }
+
+  const report = buildReport(files.length, results);
+  const allIssues = results.flatMap((r) => r.issues);
+
+  await writeFile('doc-review-report.md', report);
+  await writeFile('doc-review-comments.json', JSON.stringify(allIssues, null, 2));
+
+  console.log('\nReport: doc-review-report.md');
+  console.log(`Inline comments: doc-review-comments.json (${allIssues.length} issues)`);
+}

.github/scripts/doc-agent/src/types.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared type definitions for the doc-agent.
+ */
+
+export type Severity = 'warning' | 'suggestion';
+
+export interface ReviewIssue {
+  file: string;
+  line: number;
+  severity: Severity;
+  message: string;
+  suggestedDoc?: string;
+}
+
+export interface FileReviewResult {
+  file: string;
+  summary: string;
+  issues: ReviewIssue[];
+}
+
+export interface ReviewOutput {
+  summary: string;
+  issues: Array<{
+    file?: string;
+    line: number;
+    severity: Severity;
+    message: string;
+    suggested_doc?: string;
+  }>;
+}
+
+export interface GitRange {
+  base: string;
+  head: string;
+}
+
+export type AgentMode = 'document' | 'review';

.github/scripts/doc-agent/tsconfig.json

@@ -0,0 +1,39 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2023"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictBindCallApply": true,
+    "strictPropertyInitialization": true,
+    "noImplicitThis": true,
+    "alwaysStrict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "allowUnusedLabels": false,
+    "allowUnreachableCode": false,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}