@buresmi7/agent-doc-rules-docs-duplicates 0.8.2

package/README.md

@@ -0,0 +1,97 @@
+# Docs AI Review
+
+`@buresmi7/agent-doc-rules-docs-duplicates` provides Codex-backed documentation review.
+It checks likely semantic duplicates and can review Markdown sentences for
+style issues.
+
+## Install
+
+```bash
+pnpm add -D @buresmi7/agent-doc-rules-docs-duplicates
+```
+
+## Command
+
+```bash
+agent-doc-rules-docs-duplicates check
+agent-doc-rules-docs-duplicates style
+```
+
+`check` and `duplicates` run semantic duplicate review. `style` runs AI review
+for Markdown sentences.
+
+The command resolves the bundled `@openai/codex` binary from this package. It
+does not rely on `codex` being present in `PATH`.
+
+Default model settings for both AI checks:
+
+- model: `gpt-5-nano`
+- reasoning effort: `low`
+
+`gpt-5-nano` is the default because duplicate review is a classification task
+and OpenAI positions the nano GPT-5 variant as the fastest, lowest-cost GPT-5
+option for tasks such as summarization and classification.
+
+Use `--model <model>` or `agent-doc-rules.config.json` when your Codex account
+does not expose the default model.
+
+## Flow
+
+1. Parse Markdown prose into text units.
+2. Skip code blocks, short noise, and `references/` directories by default.
+3. Build candidates with normalized exact matching, shingle overlap, word
+   overlap, and string similarity.
+4. Remove candidates that match configured `ignorePairs`.
+5. Send only candidate pairs to Codex.
+6. Map structured Codex JSON to `fail`, `warn`, and `ok`.
+
+`fail` returns a non-zero exit code. Warning-only results return zero.
+
+## Style Review
+
+Style review parses Markdown into sentence units, sends only those units to
+Codex, and asks for `fail` or `warn` findings. It is meant for judgment calls
+such as unclear workflow names, vague AI-like phrasing, long sentences, or
+sentences that are understandable but need a maintainer rewrite.
+
+Use deterministic wording checks for known banned terms. Use AI style review
+when the question depends on the sentence.
+
+## Config
+
+Duplicate settings live under `docs.duplicates` in the root
+`agent-doc-rules.config.json`. Command-line flags take precedence.
+
+```json
+{
+  "docs": {
+    "duplicates": {
+      "includeReferences": false,
+      "ignorePairs": [
+        {
+          "left": "^e2e/",
+          "right": "^e2e/",
+          "reason": "E2E fixtures intentionally repeat scenario facts."
+        }
+      ],
+      "warnScore": 0.78,
+      "failScore": 0.92,
+      "model": "gpt-5-nano",
+      "reasoningEffort": "low"
+    },
+    "style": {
+      "includeReferences": false,
+      "maxUnits": 80,
+      "model": "gpt-5-nano",
+      "reasoningEffort": "low"
+    }
+  }
+}
+```
+
+The duplicate-review workflow is derived from the earlier `meta-work`
+documentation maintenance workflow, where deterministic duplicate candidates
+were reviewed separately from Markdown and link checks.
+
+See the skill package [Config Reference](../agent-doc-rules-skill/docs/config-reference.md)
+for shared include, exclude, wording, and AI style settings.

package/bin/agent-doc-rules-docs-duplicates.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { main } from '../src/cli.mjs';
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error(error.stack ?? error.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@buresmi7/agent-doc-rules-docs-duplicates",
+  "version": "0.8.2",
+  "private": false,
+  "description": "Semantic documentation duplicate checker powered by Codex",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "agent-doc-rules-docs-duplicates": "bin/agent-doc-rules-docs-duplicates.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@openai/codex": "^0.142.0",
+    "fast-glob": "^3.3.3",
+    "mdast-util-to-string": "^4.0.0",
+    "remark-parse": "^11.0.0",
+    "sentence-splitter": "^5.0.1",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.0.0"
+  }
+}

package/src/candidates.mjs

@@ -0,0 +1,175 @@
+export function findCandidatePairs(units, {
+  includeSameFile = false,
+  ignorePairs = [],
+  warnScore = 0.78,
+  maxCandidates = 50,
+} = {}) {
+  const threshold = Math.min(warnScore, 0.72);
+  const pairIgnores = normalizeIgnorePairs(ignorePairs);
+  const candidates = [];
+
+  for (let leftIndex = 0; leftIndex < units.length; leftIndex += 1) {
+    for (let rightIndex = leftIndex + 1; rightIndex < units.length; rightIndex += 1) {
+      const left = units[leftIndex];
+      const right = units[rightIndex];
+
+      if (!includeSameFile && left.file === right.file) {
+        continue;
+      }
+
+      if (isIgnoredPair(left.file, right.file, pairIgnores)) {
+        continue;
+      }
+
+      const score = scorePair(left, right);
+
+      if (score.score >= threshold || score.reason === 'normalized exact match') {
+        candidates.push({
+          id: `DUP-${candidates.length + 1}`,
+          score: score.score,
+          reason: score.reason,
+          left: pickUnit(left),
+          right: pickUnit(right),
+        });
+      }
+    }
+  }
+
+  return candidates
+    .sort((left, right) => right.score - left.score)
+    .slice(0, maxCandidates)
+    .map((candidate, index) => ({
+      ...candidate,
+      id: `DUP-${index + 1}`,
+    }));
+}
+
+export function normalizeIgnorePairs(ignorePairs = []) {
+  return ignorePairs.map((entry) => {
+    if (!entry?.left || !entry?.right) {
+      throw new Error('Duplicate ignore pairs must include left and right regex strings.');
+    }
+
+    return {
+      left: new RegExp(entry.left),
+      right: new RegExp(entry.right),
+    };
+  });
+}
+
+export function isIgnoredPair(leftFile, rightFile, ignorePairs = []) {
+  return ignorePairs.some((entry) => (
+    (entry.left.test(leftFile) && entry.right.test(rightFile))
+    || (entry.left.test(rightFile) && entry.right.test(leftFile))
+  ));
+}
+
+export function scorePair(left, right) {
+  if (left.normalized === right.normalized) {
+    return { score: 1, reason: 'normalized exact match' };
+  }
+
+  const shingle = jaccard(shingles(left.words, 4), shingles(right.words, 4));
+  const wordOverlap = overlap(left.words, right.words);
+  const charDice = diceCoefficient(left.normalized, right.normalized);
+  const score = Math.max(shingle, wordOverlap * 0.96, charDice * 0.9);
+
+  if (shingle >= wordOverlap && shingle >= charDice) {
+    return { score, reason: 'high shingle overlap' };
+  }
+
+  if (wordOverlap >= charDice) {
+    return { score, reason: 'high word overlap' };
+  }
+
+  return { score, reason: 'high string similarity' };
+}
+
+function pickUnit(unit) {
+  return {
+    file: unit.file,
+    line: unit.line,
+    text: unit.text,
+  };
+}
+
+function shingles(words, size) {
+  if (words.length < size) {
+    return new Set(words);
+  }
+
+  const result = new Set();
+
+  for (let index = 0; index <= words.length - size; index += 1) {
+    result.add(words.slice(index, index + size).join(' '));
+  }
+
+  return result;
+}
+
+function jaccard(left, right) {
+  if (left.size === 0 || right.size === 0) {
+    return 0;
+  }
+
+  let intersection = 0;
+
+  for (const value of left) {
+    if (right.has(value)) {
+      intersection += 1;
+    }
+  }
+
+  return intersection / (left.size + right.size - intersection);
+}
+
+function overlap(leftWords, rightWords) {
+  const left = new Set(leftWords);
+  const right = new Set(rightWords);
+  const smaller = left.size < right.size ? left : right;
+  const larger = left.size < right.size ? right : left;
+
+  if (smaller.size === 0) {
+    return 0;
+  }
+
+  let intersection = 0;
+
+  for (const word of smaller) {
+    if (larger.has(word)) {
+      intersection += 1;
+    }
+  }
+
+  return intersection / smaller.size;
+}
+
+function diceCoefficient(left, right) {
+  const leftPairs = bigrams(left);
+  const rightPairs = bigrams(right);
+
+  if (leftPairs.size === 0 || rightPairs.size === 0) {
+    return 0;
+  }
+
+  let intersection = 0;
+
+  for (const pair of leftPairs) {
+    if (rightPairs.has(pair)) {
+      intersection += 1;
+    }
+  }
+
+  return (2 * intersection) / (leftPairs.size + rightPairs.size);
+}
+
+function bigrams(text) {
+  const normalized = text.replace(/\s+/g, ' ');
+  const result = new Set();
+
+  for (let index = 0; index < normalized.length - 1; index += 1) {
+    result.add(normalized.slice(index, index + 2));
+  }
+
+  return result;
+}

package/src/check.mjs

@@ -0,0 +1,113 @@
+import { findCandidatePairs } from './candidates.mjs';
+import { runCodexClassifier } from './codex.mjs';
+import { loadMarkdownUnits } from './markdown.mjs';
+
+export async function checkDuplicates(options, deps = {}) {
+  const loadUnits = deps.loadMarkdownUnits ?? loadMarkdownUnits;
+  const classifyCandidates = deps.classifyCandidates ?? runCodexClassifier;
+  const { files, units } = await loadUnits(options);
+  const candidates = findCandidatePairs(units, options);
+
+  if (candidates.length === 0) {
+    return {
+      code: 0,
+      files,
+      units,
+      candidates,
+      reviews: [],
+      report: formatReport({ files, units, candidates, reviews: [] }),
+    };
+  }
+
+  const rawResult = await classifyCandidates(candidates, options);
+  const reviews = normalizeReviews({ candidates, rawResult, options });
+  const failCount = reviews.filter((review) => review.status === 'fail').length;
+
+  return {
+    code: failCount > 0 ? 1 : 0,
+    files,
+    units,
+    candidates,
+    reviews,
+    report: formatReport({ files, units, candidates, reviews }),
+  };
+}
+
+export function normalizeReviews({ candidates, rawResult, options }) {
+  const byId = new Map((rawResult.matches ?? []).map((match) => [match.id, match]));
+
+  return candidates.map((candidate) => {
+    const match = byId.get(candidate.id);
+
+    if (!match) {
+      return {
+        ...candidate,
+        status: 'warn',
+        duplicateScore: candidate.score,
+        reviewReason: 'Codex did not classify this candidate.',
+      };
+    }
+
+    const duplicateScore = Number(match.score);
+    const status = normalizeStatus(match.status)
+      ?? (Number.isFinite(duplicateScore) ? statusFromScore(duplicateScore, options) : 'warn');
+
+    return {
+      ...candidate,
+      status,
+      duplicateScore: Number.isFinite(duplicateScore) ? duplicateScore : candidate.score,
+      reviewReason: match.reason,
+    };
+  });
+}
+
+export function formatReport({ files, units, candidates, reviews }) {
+  const lines = [
+    'Docs semantic duplicate check',
+    `Files: ${files.length}`,
+    `Text units: ${units.length}`,
+    `Candidates: ${candidates.length}`,
+  ];
+
+  if (candidates.length === 0) {
+    lines.push('No semantic duplicate candidates found.');
+    return `${lines.join('\n')}\n`;
+  }
+
+  const grouped = {
+    fail: reviews.filter((review) => review.status === 'fail'),
+    warn: reviews.filter((review) => review.status === 'warn'),
+    ok: reviews.filter((review) => review.status === 'ok'),
+  };
+
+  for (const status of ['fail', 'warn']) {
+    for (const review of grouped[status]) {
+      lines.push('');
+      lines.push(`[${status}] ${review.id} score=${review.duplicateScore.toFixed(2)}`);
+      lines.push(`${review.left.file}:${review.left.line}`);
+      lines.push(`${review.right.file}:${review.right.line}`);
+      lines.push(review.reviewReason);
+    }
+  }
+
+  lines.push('');
+  lines.push(`Summary: ${grouped.fail.length} fail, ${grouped.warn.length} warn, ${grouped.ok.length} ok`);
+
+  return `${lines.join('\n')}\n`;
+}
+
+function statusFromScore(score, { warnScore, failScore }) {
+  if (score >= failScore) {
+    return 'fail';
+  }
+
+  if (score >= warnScore) {
+    return 'warn';
+  }
+
+  return 'ok';
+}
+
+function normalizeStatus(status) {
+  return ['fail', 'warn', 'ok'].includes(status) ? status : null;
+}

package/src/cli.mjs

@@ -0,0 +1,120 @@
+import { checkDuplicates } from './check.mjs';
+import { resolveDuplicateOptions, resolveStyleOptions } from './config.mjs';
+import { checkStyle } from './style.mjs';
+
+export async function main(argv = process.argv.slice(2)) {
+  const parsed = parseArgs(argv);
+
+  if (parsed.help) {
+    console.log(usage());
+    return;
+  }
+
+  const options = parsed.command === 'style'
+    ? await resolveStyleOptions(parsed)
+    : await resolveDuplicateOptions(parsed);
+  const result = parsed.command === 'style'
+    ? await checkStyle(options)
+    : await checkDuplicates(options);
+  process.stdout.write(result.report);
+
+  if (result.code !== 0) {
+    process.exitCode = result.code;
+  }
+}
+
+export function parseArgs(argv) {
+  const [command, ...rest] = argv;
+
+  if (!command || command === '--help' || command === '-h') {
+    return { command: 'check', help: true };
+  }
+
+  if (!['check', 'duplicates', 'style'].includes(command)) {
+    throw new Error(`Unknown command: ${command}`);
+  }
+
+  const parsed = {
+    command,
+    include: [],
+    exclude: [],
+  };
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+
+    if (arg === '--root') {
+      parsed.root = readValue(rest, ++index, arg);
+    } else if (arg === '--include') {
+      parsed.include.push(readValue(rest, ++index, arg));
+    } else if (arg === '--exclude') {
+      parsed.exclude.push(readValue(rest, ++index, arg));
+    } else if (arg === '--config') {
+      parsed.configPath = readValue(rest, ++index, arg);
+    } else if (arg === '--include-references') {
+      parsed.includeReferences = true;
+    } else if (arg === '--include-same-file') {
+      parsed.includeSameFile = true;
+    } else if (arg === '--warn-score') {
+      parsed.warnScore = Number(readValue(rest, ++index, arg));
+    } else if (arg === '--fail-score') {
+      parsed.failScore = Number(readValue(rest, ++index, arg));
+    } else if (arg === '--min-words') {
+      parsed.minWords = Number(readValue(rest, ++index, arg));
+    } else if (arg === '--min-chars') {
+      parsed.minChars = Number(readValue(rest, ++index, arg));
+    } else if (arg === '--max-candidates') {
+      parsed.maxCandidates = Number(readValue(rest, ++index, arg));
+    } else if (arg === '--max-units') {
+      parsed.maxUnits = Number(readValue(rest, ++index, arg));
+    } else if (arg === '--model') {
+      parsed.model = readValue(rest, ++index, arg);
+    } else if (arg === '--reasoning-effort') {
+      parsed.reasoningEffort = readValue(rest, ++index, arg);
+    } else if (arg === '--codex-bin') {
+      parsed.codexBin = readValue(rest, ++index, arg);
+    } else if (arg === '--help' || arg === '-h') {
+      parsed.help = true;
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  return parsed;
+}
+
+function readValue(args, index, option) {
+  const value = args[index];
+
+  if (!value || value.startsWith('--')) {
+    throw new Error(`Missing value for ${option}`);
+  }
+
+  return value;
+}
+
+function usage() {
+  return `Usage: agent-doc-rules-docs-duplicates <command> [options]
+
+Commands:
+  check         Run semantic duplicate review. Same as duplicates.
+  duplicates    Run semantic duplicate review.
+  style         Run AI style review for Markdown sentences.
+
+Options:
+  --root <dir>                  Repository root. Defaults to current directory.
+  --include <glob>              Include Markdown glob. Repeatable.
+  --exclude <glob>              Exclude glob. Repeatable.
+  --config <path>               Config file. Defaults to agent-doc-rules.config.json.
+  --include-references          Include files in references/ directories.
+  --include-same-file           Compare units from the same file.
+  --warn-score <number>         Score threshold for warnings.
+  --fail-score <number>         Score threshold for failures.
+  --min-words <number>          Minimum words per prose unit.
+  --min-chars <number>          Minimum characters per prose unit.
+  --max-candidates <number>     Maximum candidate pairs sent to Codex.
+  --max-units <number>          Maximum sentence units sent to Codex for style review.
+  --model <model>               Codex model. Defaults to gpt-5-nano.
+  --reasoning-effort <effort>   Codex reasoning effort. Defaults to low.
+  --codex-bin <path>            Override Codex binary for local debugging.`;
+}

package/src/codex.mjs

@@ -0,0 +1,333 @@
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+
+export const codexOutputSchema = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    matches: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          id: { type: 'string' },
+          score: { type: 'number', minimum: 0, maximum: 1 },
+          status: { type: 'string', enum: ['fail', 'warn', 'ok'] },
+          reason: { type: 'string' },
+        },
+        required: ['id', 'score', 'status', 'reason'],
+      },
+    },
+  },
+  required: ['matches'],
+};
+
+export const styleOutputSchema = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          id: { type: 'string' },
+          status: { type: 'string', enum: ['fail', 'warn', 'ok'] },
+          category: {
+            type: 'string',
+            enum: ['unclear', 'idiom', 'vague', 'ai-voice', 'too-long', 'passive', 'ok'],
+          },
+          issue: { type: 'string' },
+          suggestion: { type: 'string' },
+          confidence: { type: 'number', minimum: 0, maximum: 1 },
+        },
+        required: ['id', 'status', 'category', 'issue', 'suggestion', 'confidence'],
+      },
+    },
+  },
+  required: ['findings'],
+};
+
+export async function runCodexClassifier(candidates, {
+  root,
+  model,
+  reasoningEffort,
+  codexBin,
+} = {}) {
+  const tempDir = await mkdtemp(join(tmpdir(), 'docs-duplicates-codex-'));
+  const schemaFile = join(tempDir, 'schema.json');
+  const outputFile = join(tempDir, 'last-message.json');
+
+  try {
+    await writeFile(schemaFile, JSON.stringify(codexOutputSchema, null, 2));
+    const prompt = buildCodexPrompt(candidates);
+    const invocation = buildCodexInvocation({
+      root,
+      model,
+      reasoningEffort,
+      codexBin,
+      schemaFile,
+      outputFile,
+    });
+
+    await runCodex(invocation, prompt);
+    return parseCodexResponse(await readFile(outputFile, 'utf8'));
+  } finally {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+export async function runCodexStyleReviewer(units, {
+  root,
+  model,
+  reasoningEffort,
+  codexBin,
+} = {}) {
+  const tempDir = await mkdtemp(join(tmpdir(), 'docs-style-codex-'));
+  const schemaFile = join(tempDir, 'schema.json');
+  const outputFile = join(tempDir, 'last-message.json');
+
+  try {
+    await writeFile(schemaFile, JSON.stringify(styleOutputSchema, null, 2));
+    const prompt = buildStylePrompt(units);
+    const invocation = buildCodexInvocation({
+      root,
+      model,
+      reasoningEffort,
+      codexBin,
+      schemaFile,
+      outputFile,
+    });
+
+    await runCodex(invocation, prompt);
+    return parseCodexResponse(await readFile(outputFile, 'utf8'));
+  } finally {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+export function buildCodexPrompt(candidates) {
+  const formattedCandidates = candidates.map((candidate) => `## ${candidate.id}
+
+Heuristic score: ${candidate.score.toFixed(3)}
+Heuristic reason: ${candidate.reason}
+
+Left: ${candidate.left.file}:${candidate.left.line}
+${candidate.left.text}
+
+Right: ${candidate.right.file}:${candidate.right.line}
+${candidate.right.text}`).join('\n\n');
+
+  return `You are reviewing a small list of possible duplicate documentation passages.
+
+Classify only the candidate pairs shown below. Do not inspect the repository or
+invent additional pairs.
+
+Use these labels:
+
+- fail: the passages repeat the same durable rule, fact, or procedure and one
+  should be deduplicated.
+- warn: the passages overlap enough for a maintainer to review, but the
+  duplication may be acceptable.
+- ok: the passages are not a meaningful duplicate.
+
+Use warn, not fail, when repetition appears intentional in README summaries,
+templates, E2E fixtures, E2E criteria, reference indexes, or short routing
+pointers.
+
+Return JSON matching the provided schema. Use score as duplicate confidence from
+0.0 to 1.0.
+
+# Candidate Pairs
+
+${formattedCandidates}`;
+}
+
+export function buildStylePrompt(units) {
+  const formattedUnits = units.map((unit) => `## ${unit.id}
+
+Location: ${unit.file}:${unit.line}
+${unit.text}`).join('\n\n');
+
+  return `You are reviewing repository documentation sentence by sentence.
+
+Review only the sentences listed below. Do not inspect the repository and do not
+invent findings for text that is not shown.
+
+Use these labels:
+
+- fail: the sentence has a clear style problem that should block documentation
+  changes, such as an unclear idiom, metaphorical workflow name, vague AI-like
+  phrasing, or wording that makes the task hard to understand.
+- warn: the sentence is understandable but a maintainer should consider a
+  clearer rewrite.
+- ok: the sentence is clear enough for repository documentation.
+
+Prefer concrete wording. Be strict about workflow, process, and section names
+that sound clever but do not explain the task. Do not flag paths, commands,
+package names, code identifiers, or necessary technical terms.
+
+Return only findings that are fail or warn. If every sentence is ok, return an
+empty findings array. Use confidence from 0.0 to 1.0.
+
+# Sentences
+
+${formattedUnits}`;
+}
+
+export function buildCodexInvocation({
+  root,
+  model,
+  reasoningEffort,
+  codexBin,
+  schemaFile,
+  outputFile,
+}) {
+  const args = [
+    'exec',
+    '--skip-git-repo-check',
+    '--ephemeral',
+    '--ignore-rules',
+    '--sandbox',
+    'read-only',
+    '--model',
+    model,
+    '--config',
+    `model_reasoning_effort=${JSON.stringify(reasoningEffort)}`,
+    '--output-schema',
+    schemaFile,
+    '--output-last-message',
+    outputFile,
+    '--color',
+    'never',
+    '--cd',
+    root,
+    '-',
+  ];
+
+  if (codexBin) {
+    return { command: codexBin, args };
+  }
+
+  return {
+    command: process.execPath,
+    args: [resolveCodexBin(), ...args],
+  };
+}
+
+export function resolveCodexBin() {
+  for (const packageJsonPath of resolvePackageJsonPaths('@openai/codex')) {
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    const bin = typeof packageJson.bin === 'string'
+      ? packageJson.bin
+      : packageJson.bin?.codex;
+
+    if (!bin) {
+      continue;
+    }
+
+    const binPath = join(dirname(packageJsonPath), bin);
+
+    if (existsSync(binPath)) {
+      return binPath;
+    }
+  }
+
+  throw new Error('@openai/codex does not expose a codex binary.');
+}
+
+export function resolvePackageJsonPaths(packageName) {
+  const packageJsonPaths = [];
+
+  try {
+    packageJsonPaths.push(require.resolve(`${packageName}/package.json`));
+  } catch (error) {
+    if (error.code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
+      throw error;
+    }
+  }
+
+  if (packageJsonPaths.length > 0) {
+    return [...new Set(packageJsonPaths)];
+  }
+
+  let directory = dirname(require.resolve(packageName));
+
+  while (true) {
+    const candidate = join(directory, 'package.json');
+
+    if (existsSync(candidate)) {
+      const packageJson = JSON.parse(readFileSync(candidate, 'utf8'));
+
+      if (packageJson.name === packageName) {
+        packageJsonPaths.push(candidate);
+      }
+    }
+
+    const parent = dirname(directory);
+
+    if (parent === directory) {
+      break;
+    }
+
+    directory = parent;
+  }
+
+  return [...new Set(packageJsonPaths)];
+}
+
+export function parseCodexResponse(text) {
+  const trimmed = text.trim();
+
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
+
+    if (fenced) {
+      return JSON.parse(fenced[1]);
+    }
+
+    throw new Error('Codex did not return valid duplicate-check JSON.');
+  }
+}
+
+function runCodex({ command, args }, prompt) {
+  return new Promise((resolve, reject) => {
+    let stdout = '';
+    let stderr = '';
+    const child = spawn(command, args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: {
+        ...process.env,
+        NO_COLOR: process.env.NO_COLOR ?? '1',
+      },
+    });
+
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        const detail = [stderr.trim(), stdout.trim()].filter(Boolean).join('\n');
+        reject(new Error(`Codex duplicate review failed with exit code ${code ?? 1}.\n${detail}`));
+      }
+    });
+
+    child.stdin.end(prompt);
+  });
+}

package/src/config.mjs

@@ -0,0 +1,94 @@
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, resolve } from 'node:path';
+import {
+  defaultConfigFile,
+  defaultExclude,
+  defaultInclude,
+  duplicateDefaults,
+  styleDefaults,
+} from './defaults.mjs';
+
+export async function loadDocsConfig({ root = process.cwd(), configPath } = {}) {
+  const resolvedRoot = resolve(root);
+  const resolvedConfigPath = configPath
+    ? resolvePath(resolvedRoot, configPath)
+    : resolve(resolvedRoot, defaultConfigFile);
+
+  try {
+    const raw = await readFile(resolvedConfigPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed.docs ?? parsed;
+  } catch (error) {
+    if (error.code === 'ENOENT' && !configPath) {
+      return {};
+    }
+
+    throw error;
+  }
+}
+
+export async function resolveDuplicateOptions(flags = {}) {
+  const root = resolve(flags.root ?? process.cwd());
+  const config = await loadDocsConfig({ root, configPath: flags.configPath });
+  const duplicateConfig = config.duplicates ?? {};
+
+  return {
+    root,
+    include: chooseArray(flags.include, duplicateConfig.include, config.include, defaultInclude),
+    exclude: chooseArray(flags.exclude, duplicateConfig.exclude, config.exclude, defaultExclude),
+    includeReferences: flags.includeReferences ?? duplicateConfig.includeReferences ?? duplicateDefaults.includeReferences,
+    includeSameFile: flags.includeSameFile ?? duplicateConfig.includeSameFile ?? duplicateDefaults.includeSameFile,
+    ignorePairs: chooseArray(duplicateConfig.ignorePairs, duplicateDefaults.ignorePairs),
+    warnScore: chooseNumber(flags.warnScore, duplicateConfig.warnScore, duplicateDefaults.warnScore),
+    failScore: chooseNumber(flags.failScore, duplicateConfig.failScore, duplicateDefaults.failScore),
+    minWords: chooseNumber(flags.minWords, duplicateConfig.minWords, duplicateDefaults.minWords),
+    minChars: chooseNumber(flags.minChars, duplicateConfig.minChars, duplicateDefaults.minChars),
+    maxCandidates: chooseNumber(flags.maxCandidates, duplicateConfig.maxCandidates, duplicateDefaults.maxCandidates),
+    model: flags.model ?? duplicateConfig.model ?? duplicateDefaults.model,
+    reasoningEffort: flags.reasoningEffort ?? duplicateConfig.reasoningEffort ?? duplicateDefaults.reasoningEffort,
+    codexBin: flags.codexBin ?? duplicateConfig.codexBin,
+  };
+}
+
+export async function resolveStyleOptions(flags = {}) {
+  const root = resolve(flags.root ?? process.cwd());
+  const config = await loadDocsConfig({ root, configPath: flags.configPath });
+  const styleConfig = config.style ?? {};
+
+  return {
+    root,
+    include: chooseArray(flags.include, styleConfig.include, config.include, defaultInclude),
+    exclude: chooseArray(flags.exclude, styleConfig.exclude, config.exclude, defaultExclude),
+    includeReferences: flags.includeReferences ?? styleConfig.includeReferences ?? styleDefaults.includeReferences,
+    minWords: chooseNumber(flags.minWords, styleConfig.minWords, styleDefaults.minWords),
+    minChars: chooseNumber(flags.minChars, styleConfig.minChars, styleDefaults.minChars),
+    maxUnits: chooseNumber(flags.maxUnits, styleConfig.maxUnits, styleDefaults.maxUnits),
+    model: flags.model ?? styleConfig.model ?? styleDefaults.model,
+    reasoningEffort: flags.reasoningEffort ?? styleConfig.reasoningEffort ?? styleDefaults.reasoningEffort,
+    codexBin: flags.codexBin ?? styleConfig.codexBin,
+  };
+}
+
+function chooseArray(...candidates) {
+  for (const candidate of candidates) {
+    if (Array.isArray(candidate) && candidate.length > 0) {
+      return candidate;
+    }
+  }
+
+  return [];
+}
+
+function chooseNumber(...candidates) {
+  for (const candidate of candidates) {
+    if (candidate !== undefined && candidate !== null && !Number.isNaN(Number(candidate))) {
+      return Number(candidate);
+    }
+  }
+
+  return undefined;
+}
+
+function resolvePath(root, path) {
+  return isAbsolute(path) ? path : resolve(root, path);
+}

package/src/defaults.mjs

@@ -0,0 +1,43 @@
+export const defaultInclude = [
+  '*.md',
+  'docs/**/*.md',
+  '**/AGENTS.md',
+  '.agents/skills/**/*.md',
+  'packages/**/*.md',
+  'rules/**/*.md',
+  '.codex/**/*.md',
+];
+
+export const defaultExclude = [
+  'node_modules/**',
+  '.git/**',
+  'dist/**',
+  'coverage/**',
+  '.tmp/**',
+  'repos/**',
+  'worktrees/**',
+];
+
+export const defaultConfigFile = 'agent-doc-rules.config.json';
+
+export const duplicateDefaults = {
+  includeReferences: false,
+  includeSameFile: false,
+  ignorePairs: [],
+  warnScore: 0.78,
+  failScore: 0.92,
+  minWords: 6,
+  minChars: 40,
+  maxCandidates: 50,
+  model: 'gpt-5-nano',
+  reasoningEffort: 'low',
+};
+
+export const styleDefaults = {
+  includeReferences: false,
+  minWords: 6,
+  minChars: 40,
+  maxUnits: 80,
+  model: 'gpt-5-nano',
+  reasoningEffort: 'low',
+};

package/src/markdown.mjs

@@ -0,0 +1,148 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import fastGlob from 'fast-glob';
+import { toString } from 'mdast-util-to-string';
+import { split } from 'sentence-splitter';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+import { visit } from 'unist-util-visit';
+
+export async function resolveDuplicateFiles({ root, include, exclude, includeReferences = false }) {
+  const files = await fastGlob(include, {
+    cwd: root,
+    dot: true,
+    ignore: expandExcludePatterns(exclude),
+    onlyFiles: true,
+    unique: true,
+  });
+
+  return files
+    .filter((file) => file.endsWith('.md'))
+    .filter((file) => includeReferences || !hasPathSegment(file, 'references'))
+    .sort((left, right) => left.localeCompare(right));
+}
+
+export async function loadMarkdownUnits(options) {
+  const files = await resolveDuplicateFiles(options);
+  const units = [];
+
+  for (const file of files) {
+    const content = await readFile(join(options.root, file), 'utf8');
+    units.push(...extractMarkdownUnits({
+      file,
+      content,
+      minWords: options.minWords,
+      minChars: options.minChars,
+    }));
+  }
+
+  return { files, units };
+}
+
+export function extractMarkdownUnits({ file, content, minWords = 6, minChars = 40 }) {
+  const tree = unified().use(remarkParse).parse(content);
+  const units = [];
+
+  visit(tree, ['heading', 'paragraph'], (node) => {
+    if (node.type === 'paragraph' && isMarkdownTableBlock(sliceNodeContent(content, node))) {
+      return;
+    }
+
+    const text = normalizeWhitespace(toString(node));
+
+    for (const sentence of splitIntoUnits(text)) {
+      const normalized = normalizeForDuplicateCheck(sentence);
+      const words = normalized.split(' ').filter(Boolean);
+
+      if (isUsefulUnit({ text: sentence, normalized, words, minWords, minChars })) {
+        units.push({
+          id: `${file}:${node.position?.start?.line ?? 1}:${units.length + 1}`,
+          file,
+          line: node.position?.start?.line ?? 1,
+          text: sentence,
+          normalized,
+          words,
+        });
+      }
+    }
+  });
+
+  return units;
+}
+
+export function normalizeForDuplicateCheck(text) {
+  return normalizeWhitespace(text)
+    .toLowerCase()
+    .replace(/[`*_~[\](){}#>.,:;!?'"“”‘’]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function splitIntoUnits(text) {
+  const sentences = split(text)
+    .filter((node) => node.type === 'Sentence')
+    .map((node) => normalizeWhitespace(node.raw))
+    .filter(Boolean);
+
+  return sentences.length > 0 ? sentences : [text];
+}
+
+function isUsefulUnit({ text, normalized, words, minWords, minChars }) {
+  if (normalized.length < minChars || words.length < minWords) {
+    return false;
+  }
+
+  const alphaNumericCount = (text.match(/[a-z0-9]/gi) ?? []).length;
+  return alphaNumericCount / Math.max(text.length, 1) >= 0.45;
+}
+
+function sliceNodeContent(content, node) {
+  const start = node.position?.start?.offset;
+  const end = node.position?.end?.offset;
+
+  if (!Number.isInteger(start) || !Number.isInteger(end)) {
+    return '';
+  }
+
+  return content.slice(start, end);
+}
+
+function isMarkdownTableBlock(raw) {
+  const lines = raw
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  if (lines.length < 2) {
+    return false;
+  }
+
+  const allPipeRows = lines.every((line) => line.startsWith('|') && line.endsWith('|') && line.split('|').length >= 4);
+  if (!allPipeRows) {
+    return false;
+  }
+
+  return lines.some((line) => /^\|\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)+\|$/.test(line));
+}
+
+function normalizeWhitespace(text) {
+  return text.replace(/\s+/g, ' ').trim();
+}
+
+function hasPathSegment(file, segment) {
+  return file.split(/[\\/]/).includes(segment);
+}
+
+function expandExcludePatterns(exclude) {
+  const expanded = [];
+
+  for (const pattern of exclude) {
+    expanded.push(pattern);
+
+    if (!pattern.startsWith('**/') && !pattern.startsWith('/')) {
+      expanded.push(`**/${pattern}`);
+    }
+  }
+
+  return [...new Set(expanded)];
+}

package/src/style.mjs

@@ -0,0 +1,93 @@
+import { runCodexStyleReviewer } from './codex.mjs';
+import { loadMarkdownUnits } from './markdown.mjs';
+
+export async function checkStyle(options, deps = {}) {
+  const loadUnits = deps.loadMarkdownUnits ?? loadMarkdownUnits;
+  const reviewStyle = deps.reviewStyle ?? runCodexStyleReviewer;
+  const { files, units } = await loadUnits(options);
+  const reviewUnits = units.slice(0, options.maxUnits);
+
+  if (reviewUnits.length === 0) {
+    return {
+      code: 0,
+      files,
+      units,
+      reviewUnits,
+      findings: [],
+      report: formatStyleReport({ files, units, reviewUnits, findings: [] }),
+    };
+  }
+
+  const rawResult = await reviewStyle(reviewUnits, options);
+  const findings = normalizeStyleFindings({ reviewUnits, rawResult });
+  const failCount = findings.filter((finding) => finding.status === 'fail').length;
+
+  return {
+    code: failCount > 0 ? 1 : 0,
+    files,
+    units,
+    reviewUnits,
+    findings,
+    report: formatStyleReport({ files, units, reviewUnits, findings }),
+  };
+}
+
+export function normalizeStyleFindings({ reviewUnits, rawResult }) {
+  const unitsById = new Map(reviewUnits.map((unit) => [unit.id, unit]));
+
+  return (rawResult.findings ?? [])
+    .filter((finding) => ['fail', 'warn'].includes(finding.status))
+    .map((finding) => {
+      const unit = unitsById.get(finding.id);
+
+      return {
+        id: finding.id,
+        status: finding.status,
+        category: finding.category,
+        issue: finding.issue,
+        suggestion: finding.suggestion,
+        confidence: Number(finding.confidence),
+        file: unit?.file ?? 'unknown',
+        line: unit?.line ?? 1,
+        text: unit?.text ?? '',
+      };
+    });
+}
+
+export function formatStyleReport({ files, units, reviewUnits, findings }) {
+  const lines = [
+    'Docs AI style review',
+    `Files: ${files.length}`,
+    `Text units: ${units.length}`,
+    `Reviewed units: ${reviewUnits.length}`,
+  ];
+
+  if (findings.length === 0) {
+    lines.push('No AI style findings.');
+    return `${lines.join('\n')}\n`;
+  }
+
+  const grouped = {
+    fail: findings.filter((finding) => finding.status === 'fail'),
+    warn: findings.filter((finding) => finding.status === 'warn'),
+  };
+
+  for (const status of ['fail', 'warn']) {
+    for (const finding of grouped[status]) {
+      lines.push('');
+      lines.push(`[${status}] ${finding.id} confidence=${formatConfidence(finding.confidence)} category=${finding.category}`);
+      lines.push(`${finding.file}:${finding.line}`);
+      lines.push(`Issue: ${finding.issue}`);
+      lines.push(`Suggestion: ${finding.suggestion}`);
+    }
+  }
+
+  lines.push('');
+  lines.push(`Summary: ${grouped.fail.length} fail, ${grouped.warn.length} warn`);
+
+  return `${lines.join('\n')}\n`;
+}
+
+function formatConfidence(confidence) {
+  return Number.isFinite(confidence) ? confidence.toFixed(2) : 'n/a';
+}