@x6txy/ctxscope 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## Unreleased
+
+### Added
+
+- Added Agent Context Score to `ctxscope doctor`.
+- Added diagnostic line and column metadata where rules can locate the issue.
+- Added recommendations and safe fix metadata to diagnostics.
+- Added `ctxscope fix` with `--dry-run`, `--json`, and `--agent` support.
+- Added deterministic package manager normalization for context files when exactly one lockfile identifies the package manager.
+- Added exact duplicate paragraph removal.
+- Added `node:test` coverage for doctor metadata, scoring, and fix behavior.
+
+### Changed
+
+- Repositioned README around repairing stale agent instructions.
+- `CTX102` missing script references are recommendation-only and are not autofixed by default.
+
 ## 0.2.0 - 2026-06-21
 
 ### Added

package/README.md

@@ -1,30 +1,31 @@
 # ctxscope
 
-Inspect and lint coding-agent context files.
+Make AI coding agents follow the right repository instructions.
 
-`ctxscope` helps you see and lint the instructions your coding agents may read before they start working: `AGENTS.md`, `CLAUDE.md`, `SKILL.md`, OpenCode skills, Cursor rules, and GitHub Copilot instructions.
+`ctxscope` finds and fixes stale, conflicting, duplicated, and wasteful instructions across `AGENTS.md`, `CLAUDE.md`, `SKILL.md`, OpenCode skills, Cursor rules, and GitHub Copilot instructions.
 
-It answers the first questions every agent-heavy repo eventually has:
+It answers the questions every agent-heavy repo eventually has:
 
 - What context files exist?
 - How much context do they add?
 - Which agent is each file probably for?
-- Which files are suspiciously large, empty, duplicated, or stale?
+- Which files are suspiciously large, stale, duplicated, or wrong?
 - Which context problems should fail CI?
+- Which problems can be fixed safely right now?
 
 ## Install
 
 Run without installing:
 
 ```bash
-npx @x6txy/ctxscope scan
+npx @x6txy/ctxscope doctor
 ```
 
 Or install globally:
 
 ```bash
 npm install -g @x6txy/ctxscope
-ctxscope scan
+ctxscope doctor
 ```
 
 ## Usage
@@ -32,13 +33,16 @@ ctxscope scan
 ```bash
 ctxscope --help
 ctxscope --version
-ctxscope init
-ctxscope scan [path]
-ctxscope scan --agent <all|codex|opencode|claude|generic>
-ctxscope scan --json
-ctxscope doctor [path]
-ctxscope doctor --ci
-ctxscope doctor --json
+  ctxscope init
+  ctxscope scan [path]
+  ctxscope scan --agent <all|codex|opencode|claude|generic>
+  ctxscope scan --json
+  ctxscope doctor [path]
+  ctxscope doctor --ci
+  ctxscope doctor --json
+  ctxscope fix [path]
+  ctxscope fix --dry-run
+  ctxscope fix --json
 ```
 
 Examples:
@@ -50,28 +54,57 @@ ctxscope scan --agent codex
 ctxscope scan --agent opencode --json
 ctxscope init
 ctxscope doctor --ci
+ctxscope fix --dry-run
+ctxscope fix
 ```
 
 ## Output
 
 ```text
-ctxscope scan
+ctxscope doctor
 
 Agent   all
 Target  /repo
+Status  fail
 
-Files (3)
-Path                               Tokens  Agents
-.opencode/skills/backend/SKILL.md      ~6  opencode, generic
-AGENTS.md                             ~13  codex, opencode, claude, generic
-src/AGENTS.md                          ~3  codex, opencode, claude, generic
+Agent Context Score  64/100
+  Correctness  56
+  Freshness    90
+  Efficiency   76
+  Consistency  78
+  Coverage     100
 
 Summary
-  3 files, ~22 tokens, 4 warnings
+  4 files, ~9,200 tokens, 2 errors, 3 warnings
+  Run ctxscope fix to apply 1 safe fix.
+
+Errors (2)
+ERROR CTX101  AGENTS.md:18
+  conflicting package managers: npm, pnpm
+  Fix: Normalize package manager commands
 
-Warnings (4)
-WARN CTX002  AGENTS.md
-  heading "testing" appears in 2 context files
+ERROR CTX102  AGENTS.md:24
+  references missing package script: test:e2e
+  Recommendation: remove the command or replace it with an existing package.json script
+```
+
+`ctxscope fix` applies only deterministic safe fixes:
+
+```text
+ctxscope fix
+
+Target  /repo
+Mode    write
+
+Summary
+  Agent Context Score  64 -> 82
+  Applied 1 safe fix
+  Skipped 1 fix
+  Saved ~420 tokens per session
+
+Applied (1)
+CTX101  AGENTS.md
+  Normalize package manager commands to pnpm
 ```
 
 ## Supported Agents
@@ -119,6 +152,8 @@ ctxscope doctor --json
 
 `--ci` exits with code `1` when any diagnostic has severity `error`.
 
+`doctor` also reports Agent Context Score, line numbers, safe fix hints, and recommendations.
+
 Example output:
 
 ```text
@@ -130,15 +165,37 @@ Status  fail
 
 Summary
   4 files, ~9,200 tokens, 2 errors, 1 warnings
+  Run ctxscope fix to apply 1 safe fix.
 
 Errors (2)
-ERROR CTX101  AGENTS.md
+ERROR CTX101  AGENTS.md:18
   conflicting package managers: npm, pnpm
+  Fix: Normalize package manager commands
 
-ERROR CTX102  AGENTS.md
+ERROR CTX102  AGENTS.md:24
   references missing package script: test:e2e
+  Recommendation: remove the command or replace it with an existing package.json script
 ```
 
+## Fix
+
+Use `fix` to apply deterministic repairs:
+
+```bash
+ctxscope fix --dry-run
+ctxscope fix
+ctxscope fix --json
+```
+
+Safe v0.3 autofixes:
+
+- Normalize package manager command prefixes when exactly one lockfile identifies the repo package manager.
+- Remove exact duplicate paragraphs after the first occurrence.
+
+Recommendation-only in v0.3:
+
+- `CTX102` missing package script references are not autofixed because replacing commands can break workflows.
+
 ## Config
 
 Create a default config:
@@ -207,9 +264,9 @@ Shape:
 ## Limitations
 
 - Token counts are estimates: `ceil(character_count / 4)`.
-- v0.2 is discovery-based, not real session tracing.
+- ctxscope is discovery-based, not real session tracing.
 - Semantic checks are intentionally conservative. They inspect explicit commands and context text, not model behavior.
-- `diff` and `trace` are future commands.
+- `trace`, GitHub Actions, AI fixes, and dashboards are future work.
 
 ## License
 

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { readFileSync as readFileSync6 } from "fs";
+import { readFileSync as readFileSync7 } from "fs";
 
 // src/config.ts
 import { existsSync, readFileSync } from "fs";
@@ -235,7 +235,11 @@ function createDiagnostic(input, config) {
     code: input.code,
     severity,
     path: input.path,
-    message: input.message
+    message: input.message,
+    line: input.line,
+    column: input.column,
+    recommendation: input.recommendation,
+    fix: input.fix
   };
 }
 function sortDiagnostics(diagnostics) {
@@ -245,6 +249,29 @@ function sortDiagnostics(diagnostics) {
   });
 }
 
+// src/locations.ts
+function locationFromOffset(content, offset) {
+  const safeOffset = Math.max(0, Math.min(offset, content.length));
+  let line = 1;
+  let column = 1;
+  for (let index = 0; index < safeOffset; index += 1) {
+    if (content[index] === "\n") {
+      line += 1;
+      column = 1;
+    } else {
+      column += 1;
+    }
+  }
+  return { line, column };
+}
+function firstRegexLocation(content, pattern) {
+  const match = pattern.exec(content);
+  if (!match || match.index === void 0) {
+    return void 0;
+  }
+  return locationFromOffset(content, match.index);
+}
+
 // src/warnings.ts
 var MARKER_PATTERN = /\b(TODO|FIXME|OBSOLETE)\b/i;
 var MARKDOWN_LINK_PATTERN = /(?<!!)\[[^\]\n]+\]\(([^)]+)\)/g;
@@ -282,11 +309,15 @@ function collectFileDiagnostics(input, config) {
     }, config));
   }
   if (MARKER_PATTERN.test(content)) {
+    const location = firstRegexLocation(content, new RegExp(MARKER_PATTERN.source, MARKER_PATTERN.flags));
     pushDiagnostic(diagnostics, createDiagnostic({
       code: "CTX005",
       defaultSeverity: "warn",
       path: file.path,
-      message: "contains TODO, FIXME, or obsolete markers"
+      message: "contains TODO, FIXME, or obsolete markers",
+      line: location == null ? void 0 : location.line,
+      column: location == null ? void 0 : location.column,
+      recommendation: "remove stale TODO, FIXME, or obsolete instructions from agent context"
     }, config));
   }
   diagnostics.push(...collectStaleLinkDiagnostics(input.absolutePath, file.path, content, config));
@@ -346,29 +377,55 @@ function collectStaleLinkDiagnostics(absolutePath, displayPath, content, config)
         code: "CTX003",
         defaultSeverity: "warn",
         path: displayPath,
-        message: `links to missing file: ${href}`
+        message: `links to missing file: ${href}`,
+        line: match.index === void 0 ? void 0 : locationFromOffset(content, match.index).line,
+        column: match.index === void 0 ? void 0 : locationFromOffset(content, match.index).column,
+        recommendation: "remove the stale link or update it to an existing file"
       }, config));
     }
   }
   return diagnostics;
 }
 function collectRepeatedParagraphDiagnostics(displayPath, content, config) {
-  const paragraphs = content.split(/\n\s*\n/).map((paragraph) => paragraph.trim().replace(/\s+/g, " ")).filter((paragraph) => paragraph.length >= 40);
+  const paragraphs = collectParagraphs(content);
   const seen = /* @__PURE__ */ new Set();
   for (const paragraph of paragraphs) {
-    if (seen.has(paragraph)) {
+    if (seen.has(paragraph.normalized)) {
+      const location = locationFromOffset(content, paragraph.offset);
       const diagnostic = createDiagnostic({
         code: "CTX006",
         defaultSeverity: "warn",
         path: displayPath,
-        message: "contains a repeated paragraph"
+        message: "contains a repeated paragraph",
+        line: location.line,
+        column: location.column,
+        fix: {
+          title: "Remove repeated paragraph",
+          kind: "delete",
+          safe: true
+        }
       }, config);
       return diagnostic ? [diagnostic] : [];
     }
-    seen.add(paragraph);
+    seen.add(paragraph.normalized);
   }
   return [];
 }
+function collectParagraphs(content) {
+  var _a;
+  const paragraphs = [];
+  const pattern = /(^|\n)([^\S\r\n]*\S[\s\S]*?)(?=\n\s*\n|$)/g;
+  for (const match of content.matchAll(pattern)) {
+    const raw = match[2] ?? "";
+    const trimmedStart = raw.search(/\S/);
+    const offset = (match.index ?? 0) + (((_a = match[1]) == null ? void 0 : _a.length) ?? 0) + Math.max(trimmedStart, 0);
+    const normalized = raw.trim().replace(/\s+/g, " ");
+    if (normalized.length >= 40) {
+      paragraphs.push({ normalized, offset });
+    }
+  }
+  return paragraphs;
+}
 function shouldSkipLink(href) {
   return href.startsWith("http://") || href.startsWith("https://") || href.startsWith("mailto:") || href.startsWith("#");
 }
@@ -428,13 +485,14 @@ function collectBudgetDiagnostics(scan, config) {
     code: "CTX105",
     defaultSeverity: "error",
     path: scan.target,
-    message: `total context is ~${scan.totalTokens} tokens, budget is ${config.maxTokens}`
+    message: `total context is ~${scan.totalTokens} tokens, budget is ${config.maxTokens}`,
+    recommendation: "remove duplicated or low-value instructions, or raise maxTokens in ctxscope.config.json"
   }, config);
   return diagnostic ? [diagnostic] : [];
 }
 
 // src/rules/package-manager.ts
-import { readFileSync as readFileSync4, statSync as statSync3 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync4, statSync as statSync3 } from "fs";
 import { dirname as dirname3, resolve as resolve5 } from "path";
 var PACKAGE_MANAGER_PATTERNS = [
   ["npm", /\bnpm\s+(?:run\s+)?[a-z0-9:_-]+\b/i],
@@ -442,22 +500,46 @@ var PACKAGE_MANAGER_PATTERNS = [
   ["yarn", /\byarn\s+(?:run\s+)?[a-z0-9:_-]+\b/i],
   ["bun", /\bbun\s+(?:run\s+)?[a-z0-9:_-]+\b/i]
 ];
+var LOCKFILES = [
+  ["pnpm", "pnpm-lock.yaml"],
+  ["npm", "package-lock.json"],
+  ["yarn", "yarn.lock"],
+  ["bun", "bun.lock"],
+  ["bun", "bun.lockb"]
+];
 function collectPackageManagerDiagnostics(target, files, config) {
   const root = getScanRoot2(target);
   const mentions = files.flatMap((file) => collectPackageManagerMentions(root, file));
   const managers = [...new Set(mentions.map((mention) => mention.manager))].sort();
+  const lockfileManager = detectPackageManagerFromLockfiles(root);
   if (managers.length < 2) {
     return [];
   }
   const involvedPaths = [...new Set(mentions.map((mention) => mention.path))].sort();
-  const diagnostics = involvedPaths.map((path) => createDiagnostic({
-    code: "CTX101",
-    defaultSeverity: "error",
-    path,
-    message: `conflicting package managers: ${managers.join(", ")}`
-  }, config)).filter((diagnostic) => diagnostic !== null);
+  const diagnostics = involvedPaths.map((path) => {
+    const mention = mentions.find((candidate) => candidate.path === path);
+    return createDiagnostic({
+      code: "CTX101",
+      defaultSeverity: "error",
+      path,
+      message: `conflicting package managers: ${managers.join(", ")}`,
+      line: mention == null ? void 0 : mention.line,
+      column: mention == null ? void 0 : mention.column,
+      recommendation: "use one package manager consistently in agent instructions",
+      fix: lockfileManager ? {
+        title: "Normalize package manager commands",
+        kind: "replace",
+        safe: true
+      } : void 0
+    }, config);
+  }).filter((diagnostic) => diagnostic !== null);
   return sortDiagnostics(diagnostics);
 }
+function detectPackageManagerFromLockfiles(root) {
+  const detected = LOCKFILES.filter(([, lockfile]) => existsSync3(resolve5(root, lockfile))).map(([manager]) => manager);
+  const unique = [...new Set(detected)];
+  return unique.length === 1 ? unique[0] ?? null : null;
+}
 function collectPackageManagerMentions(root, file) {
   if (file.skippedBinary) {
     return [];
@@ -466,8 +548,9 @@ function collectPackageManagerMentions(root, file) {
   const content = readFileSync4(absolutePath, "utf8");
   const mentions = [];
   for (const [manager, pattern] of PACKAGE_MANAGER_PATTERNS) {
-    if (pattern.test(content)) {
-      mentions.push({ manager, path: file.path });
+    const location = firstRegexLocation(content, new RegExp(pattern.source, pattern.flags));
+    if (location) {
+      mentions.push({ manager, path: file.path, line: location.line, column: location.column });
     }
   }
   return mentions;
@@ -479,7 +562,7 @@ function getScanRoot2(target) {
 }
 
 // src/rules/package-scripts.ts
-import { existsSync as existsSync3, readFileSync as readFileSync5, statSync as statSync4 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync5, statSync as statSync4 } from "fs";
 import { dirname as dirname4, resolve as resolve6 } from "path";
 var SCRIPT_PATTERNS = [
   /\bnpm\s+run\s+([a-z0-9:_-]+)\b/gi,
@@ -509,7 +592,10 @@ function collectPackageScriptDiagnostics(target, files, config) {
       code: "CTX102",
       defaultSeverity: "error",
       path: mention.path,
-      message: `references missing package script: ${mention.script}`
+      message: `references missing package script: ${mention.script}`,
+      line: mention.line,
+      column: mention.column,
+      recommendation: "remove the command or replace it with an existing package.json script"
     }, config);
     if (diagnostic) {
       diagnostics.push(diagnostic);
@@ -529,7 +615,8 @@ function collectScriptMentions(root, file) {
     for (const match of content.matchAll(pattern)) {
       const script = match[1];
       if (script) {
-        mentions.push({ path: file.path, script });
+        const location = locationFromOffset(content, match.index ?? 0);
+        mentions.push({ path: file.path, script, line: location.line, column: location.column });
       }
     }
   }
@@ -537,7 +624,7 @@ function collectScriptMentions(root, file) {
 }
 function readPackageScripts(root) {
   const packageJsonPath = resolve6(root, "package.json");
-  if (!existsSync3(packageJsonPath)) {
+  if (!existsSync4(packageJsonPath)) {
     return null;
   }
   const parsed = JSON.parse(readFileSync5(packageJsonPath, "utf8"));
@@ -549,6 +636,39 @@ function getScanRoot3(target) {
   return stat.isDirectory() ? absoluteTarget : dirname4(absoluteTarget);
 }
 
+// src/score.ts
+var CATEGORY_RULES = {
+  correctness: ["CTX101", "CTX102"],
+  freshness: ["CTX003", "CTX005"],
+  efficiency: ["CTX001", "CTX006", "CTX105"],
+  consistency: ["CTX002", "CTX101"],
+  coverage: []
+};
+function calculateContextScore(scan, diagnostics, config) {
+  const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error").length;
+  const warnings = diagnostics.filter((diagnostic) => diagnostic.severity === "warn").length;
+  const budgetPenalty = scan.totalTokens > config.maxTokens ? Math.min(Math.ceil((scan.totalTokens - config.maxTokens) / config.maxTokens * 20), 20) : 0;
+  const duplicationPenalty = Math.min(diagnostics.filter((diagnostic) => diagnostic.code === "CTX006").length * 8, 16);
+  const overall = clampScore(100 - Math.min(errors * 18, 54) - Math.min(warnings * 6, 30) - budgetPenalty - duplicationPenalty);
+  return {
+    overall,
+    correctness: categoryScore(diagnostics, CATEGORY_RULES.correctness),
+    freshness: categoryScore(diagnostics, CATEGORY_RULES.freshness),
+    efficiency: clampScore(categoryScore(diagnostics, CATEGORY_RULES.efficiency) - budgetPenalty - duplicationPenalty),
+    consistency: categoryScore(diagnostics, CATEGORY_RULES.consistency),
+    coverage: scan.files.length === 0 ? 70 : 100
+  };
+}
+function categoryScore(diagnostics, codes) {
+  const relevant = diagnostics.filter((diagnostic) => codes.includes(diagnostic.code));
+  const errors = relevant.filter((diagnostic) => diagnostic.severity === "error").length;
+  const warnings = relevant.filter((diagnostic) => diagnostic.severity === "warn").length;
+  return clampScore(100 - Math.min(errors * 22, 66) - Math.min(warnings * 10, 40));
+}
+function clampScore(score) {
+  return Math.max(0, Math.min(100, Math.round(score)));
+}
+
 // src/doctor.ts
 function runDoctor(target, agent, config) {
   const scan = scanContext(target, agent, config);
@@ -570,14 +690,159 @@ function runDoctor(target, agent, config) {
       warnings,
       errors
     },
+    score: calculateContextScore(scan, diagnostics, config),
     files: scan.files,
     diagnostics
   };
 }
 
+// src/fix.ts
+import { readFileSync as readFileSync6, statSync as statSync5, writeFileSync } from "fs";
+import { dirname as dirname5, resolve as resolve7 } from "path";
+function runFix(options, config) {
+  const root = getScanRoot4(options.target);
+  const before = runDoctor(options.target, options.agent, config);
+  const skipped = collectSkippedFixes(before);
+  const edits = collectSafeEdits(root, before.files);
+  const applied = [];
+  for (const edit of edits) {
+    applied.push({
+      code: edit.code,
+      path: edit.path,
+      title: edit.title,
+      dryRun: options.dryRun
+    });
+    if (!options.dryRun) {
+      writeFileSync(resolve7(root, edit.path), edit.content);
+    }
+  }
+  const after = options.dryRun ? before : runDoctor(options.target, options.agent, config);
+  return {
+    target: options.target,
+    applied,
+    skipped,
+    before,
+    after
+  };
+}
+function collectSafeEdits(root, files) {
+  const edits = /* @__PURE__ */ new Map();
+  for (const edit of collectPackageManagerEdits(root, files)) {
+    edits.set(edit.path, edit);
+  }
+  for (const edit of collectDuplicateParagraphEdits(root, files)) {
+    const current = edits.get(edit.path);
+    edits.set(edit.path, current ? { ...edit, content: removeDuplicateParagraphs(current.content) } : edit);
+  }
+  return [...edits.values()];
+}
+function collectPackageManagerEdits(root, files) {
+  const packageManager = detectPackageManagerFromLockfiles(root);
+  if (!packageManager) {
+    return [];
+  }
+  return files.flatMap((file) => {
+    if (file.skippedBinary) {
+      return [];
+    }
+    const absolutePath = resolve7(root, file.path);
+    const content = readFileSync6(absolutePath, "utf8");
+    const next = normalizePackageManagerCommands(content, packageManager);
+    return next === content ? [] : [{
+      code: "CTX101",
+      path: file.path,
+      title: `Normalize package manager commands to ${packageManager}`,
+      content: next
+    }];
+  });
+}
+function collectDuplicateParagraphEdits(root, files) {
+  return files.flatMap((file) => {
+    if (file.skippedBinary) {
+      return [];
+    }
+    const absolutePath = resolve7(root, file.path);
+    const content = readFileSync6(absolutePath, "utf8");
+    const next = removeDuplicateParagraphs(content);
+    return next === content ? [] : [{
+      code: "CTX006",
+      path: file.path,
+      title: "Remove repeated paragraph",
+      content: next
+    }];
+  });
+}
+function collectSkippedFixes(before) {
+  return before.diagnostics.filter((diagnostic) => diagnostic.code === "CTX102").map((diagnostic) => ({
+    code: diagnostic.code,
+    path: diagnostic.path,
+    title: "Replace missing package script reference",
+    reason: "missing package script replacements are recommendations only in v0.3"
+  }));
+}
+function normalizePackageManagerCommands(content, packageManager) {
+  return content.replace(/\b(npm|pnpm|yarn|bun)\s+(run\s+)?([a-z0-9:_-]+)\b/gi, (match, current, runPrefix, command) => {
+    const lowerCommand = command.toLowerCase();
+    if (current.toLowerCase() === packageManager && commandFormMatches(packageManager, runPrefix, lowerCommand)) {
+      return match;
+    }
+    if (["install", "add", "remove"].includes(lowerCommand)) {
+      return `${packageManager} ${command}`;
+    }
+    if (["exec", "dlx", "create", "init"].includes(lowerCommand)) {
+      return match;
+    }
+    if (packageManager === "npm") {
+      return `npm run ${command}`;
+    }
+    if (packageManager === "bun") {
+      return `bun run ${command}`;
+    }
+    return `${packageManager} ${command}`;
+  });
+}
+function removeDuplicateParagraphs(content) {
+  const parts = content.split(/(\n\s*\n)/);
+  const seen = /* @__PURE__ */ new Set();
+  const kept = [];
+  for (let index = 0; index < parts.length; index += 1) {
+    const part = parts[index] ?? "";
+    if (index % 2 === 1) {
+      kept.push(part);
+      continue;
+    }
+    const normalized = part.trim().replace(/\s+/g, " ");
+    if (normalized.length >= 40 && seen.has(normalized)) {
+      if (kept.length > 0 && /^\n\s*\n$/.test(kept[kept.length - 1] ?? "")) {
+        kept.pop();
+      }
+      continue;
+    }
+    if (normalized.length >= 40) {
+      seen.add(normalized);
+    }
+    kept.push(part);
+  }
+  return kept.join("");
+}
+function commandFormMatches(packageManager, runPrefix, command) {
+  if (["install", "add", "remove", "exec", "dlx", "create", "init"].includes(command)) {
+    return !runPrefix;
+  }
+  if (packageManager === "npm" || packageManager === "bun") {
+    return Boolean(runPrefix);
+  }
+  return !runPrefix;
+}
+function getScanRoot4(target) {
+  const absoluteTarget = resolve7(target);
+  const stat = statSync5(absoluteTarget);
+  return stat.isDirectory() ? absoluteTarget : dirname5(absoluteTarget);
+}
+
 // src/init.ts
-import { existsSync as existsSync4, writeFileSync } from "fs";
-import { resolve as resolve7 } from "path";
+import { existsSync as existsSync5, writeFileSync as writeFileSync2 } from "fs";
+import { resolve as resolve8 } from "path";
 var InitError = class extends Error {
   constructor(message) {
     super(message);
@@ -585,11 +850,11 @@ var InitError = class extends Error {
   }
 };
 function initConfig(cwd = process.cwd()) {
-  const path = resolve7(cwd, CONFIG_FILE_NAME);
-  if (existsSync4(path)) {
+  const path = resolve8(cwd, CONFIG_FILE_NAME);
+  if (existsSync5(path)) {
     throw new InitError(`${CONFIG_FILE_NAME} already exists`);
   }
-  writeFileSync(path, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}
+  writeFileSync2(path, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}
 `, "utf8");
   return { path };
 }
@@ -627,6 +892,7 @@ function formatHumanDoctorResult(result) {
   const sections = [
     colors.bold(colors.cyan("ctxscope doctor")),
     formatDoctorMeta(result),
+    formatDoctorScore(result),
     formatDoctorSummary(result),
     formatDoctorDiagnostics(result)
   ];
@@ -638,15 +904,43 @@ function formatJsonDoctorResult(result) {
     target: result.target,
     status: result.status,
     summary: result.summary,
+    score: result.score,
     files: result.files,
     diagnostics: result.diagnostics
   }, null, 2);
 }
+function formatHumanFixResult(result) {
+  const sections = [
+    colors.bold(colors.cyan("ctxscope fix")),
+    formatFixMeta(result),
+    formatFixSummary(result),
+    formatAppliedFixes(result),
+    formatSkippedFixes(result)
+  ];
+  return sections.filter(Boolean).join("\n\n");
+}
+function formatJsonFixResult(result) {
+  return JSON.stringify({
+    target: result.target,
+    applied: result.applied,
+    skipped: result.skipped,
+    before: result.before,
+    after: result.after
+  }, null, 2);
+}
 function formatWarning(warning) {
+  var _a;
   const severity = colorSeverity(warning);
   const code = warning.severity === "error" ? colors.red(warning.code) : colors.yellow(warning.code);
-  return `${severity} ${code}  ${warning.path}
-  ${colors.dim(warning.message)}`;
+  const location = warning.line === void 0 ? warning.path : `${warning.path}:${warning.line}`;
+  const details = [colors.dim(warning.message)];
+  if ((_a = warning.fix) == null ? void 0 : _a.safe) {
+    details.push(`${colors.dim("Fix:")} ${warning.fix.title}`);
+  } else if (warning.recommendation) {
+    details.push(`${colors.dim("Recommendation:")} ${warning.recommendation}`);
+  }
+  return `${severity} ${code}  ${location}
+  ${details.join("\n  ")}`;
 }
 function colorSeverity(diagnostic) {
   return diagnostic.severity === "error" ? colors.red(diagnostic.severity.toUpperCase()) : colors.yellow(diagnostic.severity.toUpperCase());
@@ -707,8 +1001,33 @@ function formatDoctorSummary(result) {
     result.summary.errors > 0 ? colors.red(`${result.summary.errors} errors`) : null,
     result.summary.warnings > 0 ? colors.yellow(`${result.summary.warnings} warnings`) : null
   ].filter(Boolean).join(", ");
+  const safeFixes = result.diagnostics.filter((diagnostic) => {
+    var _a;
+    return (_a = diagnostic.fix) == null ? void 0 : _a.safe;
+  }).length;
+  const fixLine = safeFixes > 0 ? `
+  Run ctxscope fix to apply ${safeFixes} safe ${safeFixes === 1 ? "fix" : "fixes"}.` : "";
   return `${colors.bold("Summary")}
-  ${formatNumber(result.summary.files)} files, ~${formatNumber(result.summary.totalTokens)} tokens, ${diagnosticLabel}`;
+  ${formatNumber(result.summary.files)} files, ~${formatNumber(result.summary.totalTokens)} tokens, ${diagnosticLabel}${fixLine}`;
+}
+function formatDoctorScore(result) {
+  return [
+    `${colors.bold("Agent Context Score")}  ${scoreColor(result.score.overall)(`${result.score.overall}/100`)}`,
+    `  Correctness  ${scoreColor(result.score.correctness)(String(result.score.correctness))}`,
+    `  Freshness    ${scoreColor(result.score.freshness)(String(result.score.freshness))}`,
+    `  Efficiency   ${scoreColor(result.score.efficiency)(String(result.score.efficiency))}`,
+    `  Consistency  ${scoreColor(result.score.consistency)(String(result.score.consistency))}`,
+    `  Coverage     ${scoreColor(result.score.coverage)(String(result.score.coverage))}`
+  ].join("\n");
+}
+function scoreColor(score) {
+  if (score >= 80) {
+    return colors.green;
+  }
+  if (score >= 60) {
+    return colors.yellow;
+  }
+  return colors.red;
 }
 function formatDoctorDiagnostics(result) {
   if (result.diagnostics.length === 0) {
@@ -727,6 +1046,44 @@ ${warnings.map(formatWarning).join("\n")}`);
   }
   return sections.join("\n\n");
 }
+function formatFixMeta(result) {
+  const dryRun = result.applied.some((fix) => fix.dryRun);
+  return [
+    `${colors.dim("Target")}  ${result.target}`,
+    `${colors.dim("Mode")}    ${dryRun ? "dry-run" : "write"}`
+  ].join("\n");
+}
+function formatFixSummary(result) {
+  const beforeScore = result.before.score.overall;
+  const afterScore = result.after.score.overall;
+  const beforeTokens = result.before.summary.totalTokens;
+  const afterTokens = result.after.summary.totalTokens;
+  const savedTokens = Math.max(0, beforeTokens - afterTokens);
+  const action = result.applied.some((fix) => fix.dryRun) ? "Would apply" : "Applied";
+  return [
+    `${colors.bold("Summary")}`,
+    `  Agent Context Score  ${scoreColor(afterScore)(`${beforeScore} -> ${afterScore}`)}`,
+    `  ${action} ${result.applied.length} safe ${result.applied.length === 1 ? "fix" : "fixes"}`,
+    `  Skipped ${result.skipped.length} ${result.skipped.length === 1 ? "fix" : "fixes"}`,
+    `  Saved ~${formatNumber(savedTokens)} tokens per session`
+  ].join("\n");
+}
+function formatAppliedFixes(result) {
+  if (result.applied.length === 0) {
+    return "";
+  }
+  return `${colors.bold(result.applied.some((fix) => fix.dryRun) ? "Would Apply" : "Applied")} ${colors.dim(`(${result.applied.length})`)}
+${result.applied.map((fix) => `${fix.code}  ${fix.path}
+  ${colors.dim(fix.title)}`).join("\n")}`;
+}
+function formatSkippedFixes(result) {
+  if (result.skipped.length === 0) {
+    return "";
+  }
+  return `${colors.bold("Skipped")} ${colors.dim(`(${result.skipped.length})`)}
+${result.skipped.map((fix) => `${fix.code}  ${fix.path}
+  ${colors.dim(`${fix.title}: ${fix.reason}`)}`).join("\n")}`;
+}
 function formatTokenCell(tokens, skippedBinary) {
   return skippedBinary ? "binary" : `~${formatNumber(tokens)}`;
 }
@@ -744,7 +1101,7 @@ var SUPPORTED_AGENTS = ["all", "codex", "opencode", "claude", "generic"];
 function getVersion() {
   try {
     const packageJson = JSON.parse(
-      readFileSync6(new URL("../package.json", import.meta.url), "utf8")
+      readFileSync7(new URL("../package.json", import.meta.url), "utf8")
     );
     return packageJson.version ?? "0.0.0";
   } catch {
@@ -762,17 +1119,20 @@ Usage:
   ctxscope init
   ctxscope scan [path] [--agent <agent>] [--json]
   ctxscope doctor [path] [--agent <agent>] [--json] [--ci]
+  ctxscope fix [path] [--agent <agent>] [--dry-run] [--json]
 
 Commands:
   init                 Create ctxscope.config.json.
   scan                 Discover coding-agent context files for a path.
   doctor               Lint coding-agent context files.
+  fix                  Apply safe deterministic context fixes.
 
 Options:
   --agent <agent>      Agent profile: all, codex, opencode, claude, generic.
                        Default: all.
   --json               Print machine-readable JSON.
   --ci                 Exit 1 when doctor finds errors.
+  --dry-run            Show fixes without writing files.
   -h, --help           Show this help message.
   -v, --version        Show the package version.
 `);
@@ -870,6 +1230,48 @@ function parseDoctorOptions(args) {
   }
   return options;
 }
+function parseFixOptions(args) {
+  const options = {
+    agent: "all",
+    dryRun: false,
+    json: false,
+    target: "."
+  };
+  let targetSet = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--help" || arg === "-h") {
+      printHelp();
+      process.exit(0);
+    }
+    if (arg === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+    if (arg === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (arg === "--agent") {
+      options.agent = parseAgent(args[index + 1]);
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--agent=")) {
+      options.agent = parseAgent(arg.slice("--agent=".length));
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      fail(`unknown option '${arg}'`);
+    }
+    if (targetSet) {
+      fail(`unexpected extra path '${arg}'`);
+    }
+    options.target = arg;
+    targetSet = true;
+  }
+  return options;
+}
 function runScan(options) {
   const config = loadConfig();
   const result = scanContext(options.target, options.agent, config);
@@ -891,6 +1293,15 @@ function runDoctorCommand(options) {
     process.exit(1);
   }
 }
+function runFixCommand(options) {
+  const config = loadConfig();
+  const result = runFix(options, config);
+  if (options.json) {
+    console.log(formatJsonFixResult(result));
+    return;
+  }
+  console.log(formatHumanFixResult(result));
+}
 function runInitCommand() {
   const result = initConfig();
   console.log(`Created ${result.path}`);
@@ -941,6 +1352,17 @@ function main(argv) {
     }
     return;
   }
+  if (command === "fix") {
+    try {
+      runFixCommand(parseFixOptions(args));
+    } catch (error) {
+      if (error instanceof ConfigError) {
+        fail(error.message);
+      }
+      throw error;
+    }
+    return;
+  }
   fail(`unknown command '${command}'`);
 }
 main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x6txy/ctxscope",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Inspect and lint coding-agent context files",
   "type": "module",
   "keywords": [
@@ -32,6 +32,7 @@
   ],
   "scripts": {
     "build": "tsup src/cli.ts --format esm --clean",
+    "test": "pnpm build && tsup test/*.test.ts --format esm --platform node --out-dir dist-test --clean && node --test dist-test/*.test.js",
     "prepack": "pnpm build"
   },
   "engines": {