@praneeth_54/agentdoctor 0.2.0-beta → 1.0.0

package/CHANGELOG.md

@@ -7,10 +7,112 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Notes
+
+- Owner release sequence for `1.0.0`: `npm publish` → `git tag v1.0.0` → GitHub Release → then bump Action `version` default `0.3.0-beta` → `1.0.0` (only after npm serves `1.0.0`).
+- Project Brain V1 remains a parallel laboratory under `src/core/understanding/brain` and is excluded from the published npm pack. Docs: [docs/project-brain.md](docs/project-brain.md).
+
+## [1.0.0] — 2026-08-12
+
+First production release: Scan → Fix → Verify → CI contract frozen for v1.
+
+### Added
+
+- Claude Code safe-context Fix writer: `agentdoctor fix` appends allowlisted
+  `permissions.deny` Read rules to `.claude/settings.json` for
+  `context/generated-directory` and `context/large-log-file` when Claude Code is
+  configured (alongside existing Cursor `.cursorignore` fixes).
+- Codex safe-context Fix writer: `agentdoctor fix` merges allowlisted filesystem
+  `deny` keys into `.codex/config.toml` permission profiles for the same safe
+  context findings when Codex is detected. Skips when `sandbox_mode` is set or
+  `default_permissions` selects a built-in `:…` profile.
+- GitHub Action / CLI CI policy enforcement: `minimum-score` / `--min-score`,
+  `fail-on-severity` / `--fail-on-severity`, `fail-on-rule` / `--fail-on-rule`,
+  `fail-on-new` / `--fail-on-new`, `verify-baseline`, `json-output`, `summary` /
+  `--summary`, and `annotations` / `--annotations`. Action `version: workspace`
+  runs the checked-out `dist/cli` for local CI.
+- Guided Next steps on failed `scan` / `fix` / `verify` terminal output, and on
+  GitHub Step Summary when a policy gate fails — shortest path back to green
+  (reproduce → fix or explain → verify).
+- Windows CI quality job (Node 20) and Windows-safe Fix/Action overwrite writes.
+- Action smoke coverage for `fail-on-rule`, `verify-baseline`, and baseline
+  symlink escape rejection.
+
+### Fixed
+
+- `instructions/missing-path-reference` also resolves non-`./` paths relative to the
+  instruction file directory (monorepo package docs), while root-level instruction
+  files still require repository-root paths. Corpus-100: 121 → 88 findings for this
+  rule (−33); other rules unchanged.
+- `context/generated-directory` and `context/large-log-file` honor Claude Code Read
+  deny exclusions when computing `affectedAgents`, so Fix → Verify clears Claude
+  context findings after a deny rule is applied.
+- The same rules honor Codex filesystem deny keys in `.codex/config.toml` when
+  computing `affectedAgents`.
+- Action writes the JSON report even when a policy gate fails (exit `1`), so
+  artifacts remain available for triage.
+- `--min-score` / Action `minimum-score` fail when no supported agents are
+  configured (`agentSecurityAnalysis: limited`) instead of passing on a vacuous 100.
+- Terminal readiness prints `n/a` when analysis is limited (no agents).
+- Agentless first scan no longer shows a green “No agent-configuration findings”
+  success line; it tells the user to add Cursor / Claude Code / Codex config and
+  re-run.
+- Invalid `--min-score` values exit `2` (usage) instead of `3` (internal).
+- Codex Fix refuses invalid `.codex/config.toml` during planning (same as Claude
+  invalid JSON) instead of silently skipping Codex and writing Cursor-only fixes.
+- Codex Fix refuses unrecognizable / invalid `.codex/config.toml` content instead of
+  appending permission profiles into garbage TOML.
+- `agentdoctor fix` exits `2` when confirmation is cancelled (non-TTY without `--yes`)
+  or when Fix refuses invalid settings / cannot write due to permissions.
+- `scan --ci` now fails (exit `1`) when any **critical** finding exists. Omit `--ci` for
+  report-only scans. The GitHub Action stays report-only unless policy inputs are set
+  (it no longer passes a bare `--ci`).
+- Discovery keeps oversized log/dump-like paths as size metadata so
+  `context/large-log-file` flags files above the content-read limit (previously silent
+  false negatives for the largest logs).
+- Action `verify-baseline` re-checks workspace containment after `realpath` so a
+  workspace-relative symlink cannot escape to an outside file.
+- Fix writers and Action report overwrite use Windows-safe replace (rename cannot
+  overwrite an existing destination on Windows).
+
+### Compatibility
+
+- CLI + JSON + rule ID contracts frozen for v1 (see [docs/compatibility.md](docs/compatibility.md))
+- Action `version` input default remains `0.3.0-beta` until `1.0.0` is published to npm;
+  pin `1.0.0` or use `version: workspace` after the release is cut
+
+## [0.3.0-beta] — 2026-08-07
+
+Minor beta: completes the Scan → Fix → Verify CLI loop and corrects release-facing honesty.
+
+### Added
+
+- `agentdoctor verify` — re-scan and compare against a prior `scan --json` baseline
+  (`fixed` / `remaining` / `new` / `unchanged`). Supports `--json`, `--ci` (fails on new
+  findings), `--baseline`, and `--min-score`. Completes the Scan → Fix → Verify CLI loop.
+- Terminal summary prints overall readiness (`N/100`); category/agent scores remain in JSON.
+
+### Fixed
+
+- `agentdoctor scan --json` (and `--ci` / `--verbose` / `--min-score` on the `scan`
+  subcommand) now honor flags correctly. Overlapping root/subcommand options are read via
+  Commander `optsWithGlobals()`, so CI scripts using `scan … --json` receive JSON instead of
+  a terminal report.
+- `instructions/missing-path-reference` no longer treats Go/npm module imports
+  (`github.com/…`, `@scope/pkg`), Go stdlib paths (`io/ioutil`), glob patterns, code tokens
+  (`try/finally`), or bare build roots (`dist/`) as missing local paths.
+- `agentdoctor fix` now reports skip reasons for review/manual findings instead of an empty
+  “no applicable fixes” message with no explanation.
+- Sample/test/example paths and env templates no longer inflate security/context false positives.
+
+### Compatibility
+
+- Default Action `version` input is `0.3.0-beta` (pin CI smoke to last published until npm ships)
+- Fix remains Cursor `.cursorignore` safe-context only; security findings stay review/manual
+
 ### Planned
 
-- Safe automatic fixes
-- Terminal readiness line and GitHub Action score-gate inputs (deferred; see scoring.md v2+)
+- GitHub Action score-gate inputs (deferred; see scoring.md v2+)
 
 ## [0.2.0-beta] — 2026-08-02
 
@@ -143,7 +245,9 @@ First public beta.
 - Not a complete secret scanner
 - Git “tracked secret” detection deferred
 
-[Unreleased]: https://github.com/pranee54/AgentDoctor/compare/v0.2.0-beta...HEAD
+[Unreleased]: https://github.com/pranee54/AgentDoctor/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/pranee54/AgentDoctor/releases/tag/v1.0.0
+[0.3.0-beta]: https://github.com/pranee54/AgentDoctor/releases/tag/v0.3.0-beta
 [0.2.0-beta]: https://github.com/pranee54/AgentDoctor/releases/tag/v0.2.0-beta
 [0.1.4-beta]: https://github.com/pranee54/AgentDoctor/releases/tag/v0.1.4-beta
 [0.1.3-beta]: https://github.com/pranee54/AgentDoctor/releases/tag/v0.1.3-beta

package/README.md

@@ -1,6 +1,6 @@
 # AgentDoctor
 
-[![npm](https://img.shields.io/npm/v/@praneeth_54/agentdoctor)](https://www.npmjs.com/package/@praneeth_54/agentdoctor)
+[![npm](https://img.shields.io/npm/v/@praneeth_54/agentdoctor?label=npm)](https://www.npmjs.com/package/@praneeth_54/agentdoctor)
 [![npm downloads](https://img.shields.io/npm/dm/@praneeth_54/agentdoctor)](https://www.npmjs.com/package/@praneeth_54/agentdoctor)
 [![CI](https://img.shields.io/github/actions/workflow/status/pranee54/AgentDoctor/ci.yml?branch=main&label=CI)](https://github.com/pranee54/AgentDoctor/actions)
 [![Node](https://img.shields.io/node/v/@praneeth_54/agentdoctor)](https://nodejs.org)
@@ -16,7 +16,7 @@ AgentDoctor is a local CLI that inspects project-level AI coding agent setup —
 npx @praneeth_54/agentdoctor
 ```
 
-Public beta (`0.1.x-beta`). Deterministic readiness scores ship in JSON; automatic fixes are not available yet.
+Public release (`1.0.0`). Scan → Fix → Verify → CI. Deterministic scores in the terminal and JSON.
 
 ---
 
@@ -24,12 +24,12 @@ Public beta (`0.1.x-beta`). Deterministic readiness scores ship in JSON; automat
 
 ![AgentDoctor scanning a repository and reporting coding-agent security findings](docs/images/cli-scan.png)
 
-_Real scan of the included `insecure-agent-project` fixture using AgentDoctor v0.2.0-beta._
+_Real scan of the included `insecure-agent-project` fixture using AgentDoctor v1.0.0._
 
 ```text
 $ npx @praneeth_54/agentdoctor
 
-🩺 AgentDoctor v0.2.0-beta
+🩺 AgentDoctor v1.0.0
 
 Scanning repository...
 
@@ -71,10 +71,11 @@ Summary
   1 warning
   0 info
 
-Scoring: not included in this release
+  Readiness: 13/100
+  Category and agent scores: agentdoctor scan --json
 ```
 
-Abbreviated text example from the same fixture for accessibility and search. Secret values are never printed.
+Abbreviated text example from the same fixture for accessibility and search. Secret values are never printed. Re-run the scan if counts change.
 
 ---
 
@@ -99,7 +100,7 @@ Manually reviewing all of that across Cursor, Claude Code, and Codex is slow and
 | ESLint          | Source code                      |
 | **AgentDoctor** | **AI coding agent environments** |
 
-AgentDoctor analyzes configuration. It does not run agents, call an LLM, or modify your repository in this release.
+AgentDoctor analyzes configuration. It does not run agents or call an LLM. `agentdoctor fix` may append safe context exclusions (Cursor `.cursorignore`, Claude Code Read deny rules, and Codex filesystem deny keys); it does not rewrite secrets, credentials, or security modes such as `bypassPermissions`.
 
 ---
 
@@ -139,8 +140,9 @@ You get deterministic findings with:
 - evidence paths
 - affected agents when exposure claims are supported
 - conservative recommendations
+- readiness score (`scores.overall` in JSON; overall line in the terminal)
 
-Automatic repair is **not** included in this beta. Findings tell you what to review; you decide what to change.
+Safe context exclusions (Cursor / Claude Code / Codex) can be applied with `agentdoctor fix`. Security and review findings stay manual — Fix explains why and does not invent unsafe edits.
 
 ---
 
@@ -152,10 +154,10 @@ Automatic repair is **not** included in this beta. Findings tell you what to rev
 npx @praneeth_54/agentdoctor
 ```
 
-Pin a beta version when you need a fixed install:
+Pin a version when you need a fixed install:
 
 ```bash
-npx @praneeth_54/agentdoctor@0.2.0-beta
+npx @praneeth_54/agentdoctor@1.0.0
 ```
 
 ### Global (optional)
@@ -165,12 +167,33 @@ npm install -g @praneeth_54/agentdoctor
 agentdoctor
 ```
 
+### Scan → Fix → Verify
+
+```bash
+# 1. Scan (save a baseline for Verify)
+npx @praneeth_54/agentdoctor scan . --json > agentdoctor-report.json
+
+# 2. Fix safe context exclusions (preview first with --dry-run)
+npx @praneeth_54/agentdoctor fix . --dry-run
+npx @praneeth_54/agentdoctor fix . -y
+
+# 3. Verify against the baseline
+npx @praneeth_54/agentdoctor verify . --baseline agentdoctor-report.json
+```
+
+`fix` writes safe context exclusions for Cursor (`.cursorignore`), Claude Code
+(`permissions.deny` Read rules in `.claude/settings.json`), and Codex (filesystem `deny`
+keys under a permissions profile in `.codex/config.toml`) for findings such as unignored
+`build/` or large logs. Review/manual security findings are listed as skipped — address those
+yourself, then re-run `verify`.
+
 ### Common commands
 
 ```bash
 agentdoctor .
-agentdoctor . --json
-agentdoctor . --verbose
+agentdoctor scan . --json
+agentdoctor fix . --dry-run
+agentdoctor verify . --ci --baseline agentdoctor-report.json
 agentdoctor explain security/env-file-exposure
 agentdoctor doctor
 ```
@@ -184,10 +207,11 @@ npm install @praneeth_54/agentdoctor
 ```
 
 ```ts
-import { scan } from "@praneeth_54/agentdoctor";
+import { scan, verify, buildFixPlan, applyFixPlan } from "@praneeth_54/agentdoctor";
 
 const result = await scan({ cwd: process.cwd() });
 console.log(result.summary);
+console.log(result.scores?.overall);
 console.log(result.agentSecurityAnalysis); // "full" | "limited"
 ```
 
@@ -259,10 +283,14 @@ steps:
 
   - name: Audit coding-agent configuration
     id: agentdoctor
-    uses: pranee54/AgentDoctor@v0.2.0-beta
+    uses: pranee54/AgentDoctor@v1.0.0
     with:
       path: .
+      version: "1.0.0"
       output-file: agentdoctor-report.json
+      minimum-score: "70"
+      fail-on-severity: critical
+      summary: "true"
 
   - name: Upload AgentDoctor report
     uses: actions/upload-artifact@v4
@@ -271,10 +299,13 @@ steps:
       path: ${{ steps.agentdoctor.outputs.report-path }}
 ```
 
-The action installs the published `@praneeth_54/agentdoctor@0.2.0-beta` package, runs it with
-`--ci --json`, and writes the report inside the checked-out workspace. It sets up Node.js 20
-for the CLI. The optional `version` input accepts an exact npm version or the `latest` / `beta`
-dist-tag.
+Policy inputs: `minimum-score`, `fail-on-severity`, `fail-on-rule`, `fail-on-new`,
+`verify-baseline`, `summary`, `annotations`. The Action stays report-only until you set a
+policy input. Explicitly set `version: "1.0.0"` after npm publish (the Action default remains
+`0.3.0-beta` until that post-publish bump). For local CI against this repo, use
+`version: workspace` after `npm run build`. The action installs `@praneeth_54/agentdoctor`,
+runs scan (or `verify` when `verify-baseline` is set) with `--json`, and writes the report
+inside the workspace.
 
 ### CLI
 
@@ -282,43 +313,49 @@ Use JSON directly in other CI systems:
 
 ```bash
 # Report-only (exit 0 even when findings exist; scores still in JSON)
+npx @praneeth_54/agentdoctor --json
+
+# Fail when any critical finding exists
 npx @praneeth_54/agentdoctor --ci --json
 
-# Fail CI when overall readiness is below 70
+# Fail when overall readiness is below 70 (with --ci also fails on criticals)
 npx @praneeth_54/agentdoctor --ci --json --min-score 70
+
+# Fail on warning-or-higher (overrides the default critical gate from --ci)
+npx @praneeth_54/agentdoctor --ci --json --fail-on-severity warning
 ```
 
-`--ci` runs non-interactively and does **not** apply an implicit score threshold.
-Use `--min-score N` (with or without `--ci`) to fail with exit code `1` when
-`scores.overall < N`.
+`--ci` fails when any **critical** finding exists. Override the severity floor with
+`--fail-on-severity`, and use `--min-score` / `--fail-on-rule` for additional gates.
+Omit `--ci` for report-only JSON (exit `0` even when findings exist).
 
 Exit codes: [docs/exit-codes.md](docs/exit-codes.md). Compatibility promises: [docs/compatibility.md](docs/compatibility.md).
 
 ### Readiness scoring
 
 Scans populate `scoringAvailable: true` and a deterministic `scores` object
-(overall, categories, agents). The terminal report does not render a readiness line yet;
-scores are available in JSON (`--json`).
+(overall, categories, agents). The terminal prints overall readiness; category and agent
+scores are in JSON (`--json`).
 
 `--min-score N` is enforced by the CLI. Details (weights, security caps, threshold rules,
 and deferred v2 items): [docs/scoring.md](docs/scoring.md).
 
 ---
 
-## Beta limitations
+## Known limitations
 
-Honest limits of the current public beta:
+Honest limits of v1:
 
-| Limitation                          | Status                                                          |
-| ----------------------------------- | --------------------------------------------------------------- |
-| Terminal readiness line             | Scores ship in JSON only; terminal does not print N/100 yet     |
-| GitHub Action score gates           | Action remains `--ci --json` report-only (no `min-score` input) |
-| Automatic fixes (`agentdoctor fix`) | Stub only — does not modify files                               |
-| Secret-content scanning             | Filename / config heuristics only                               |
-| Detection style                     | Intentionally conservative; false security findings are avoided |
-| Agent coverage                      | Cursor, Claude Code, Codex project configs                      |
+| Limitation                  | Status                                                                          |
+| --------------------------- | ------------------------------------------------------------------------------- |
+| Automatic fixes             | Safe Cursor / Claude Code / Codex context exclusions only                       |
+| Security findings           | Review/manual — Fix does not rewrite secrets or security modes                  |
+| Secret-content scanning     | Filename / config heuristics only                                               |
+| Detection style             | Intentionally conservative; false security findings are avoided                 |
+| Agent coverage              | Cursor, Claude Code, Codex project configs                                      |
+| Missing-path residual noise | Broad path-lattice expansion deferred; instruction-directory resolution shipped |
 
-See [CHANGELOG.md](CHANGELOG.md) and [docs/release-notes-v0.2.0-beta.md](docs/release-notes-v0.2.0-beta.md).
+See [CHANGELOG.md](CHANGELOG.md) and [docs/compatibility.md](docs/compatibility.md).
 
 ---
 
@@ -367,6 +404,20 @@ node dist/cli/index.js ./fixtures/clean-configured-project
 
 ---
 
+## Project Brain (separate laboratory capability)
+
+AgentDoctor V1 ships the **safety** product: Scan → Fix → Verify → Policy → CI.
+
+A parallel **Project Brain** engineering layer lives under `src/core/understanding/` (durable local claims, evidence, snapshots, query/trace/delta). It is:
+
+- **not** part of the published npm package (`tsconfig.build` excludes it)
+- **not** wired into the public CLI
+- documented in [docs/project-brain.md](docs/project-brain.md)
+
+See [PROJECT_AUDIT.txt](PROJECT_AUDIT.txt) and [RELEASE_CHECKLIST.txt](RELEASE_CHECKLIST.txt).
+
+---
+
 ## Next steps
 
 - **Try it:** `npx @praneeth_54/agentdoctor`

package/dist/agents/inspect.js

@@ -23,11 +23,29 @@ export async function inspectRepoFile(root, relativePath, maxFileSizeBytes = DEF
         };
     }
     try {
-        const lstat = await fs.lstat(absolutePath);
-        const isSymlink = lstat.isSymbolicLink();
-        if (isSymlink) {
-            const real = await fs.realpath(absolutePath);
-            if (!isPathInsideRoot(root, real)) {
+        // Open first, then inspect via the same handle (avoids TOCTOU with prior lstat/stat).
+        const handle = await fs.open(absolutePath, "r");
+        try {
+            const lstat = await fs.lstat(absolutePath);
+            const isSymlink = lstat.isSymbolicLink();
+            if (isSymlink) {
+                const real = await fs.realpath(absolutePath);
+                if (!isPathInsideRoot(root, real)) {
+                    return {
+                        relativePath: normalizedRelative,
+                        absolutePath,
+                        exists: true,
+                        readable: false,
+                        sizeBytes: 0,
+                        empty: true,
+                        isSymlink: true,
+                        text: null,
+                        error: "Symlink target is outside repository root",
+                    };
+                }
+            }
+            const stat = await handle.stat();
+            if (!stat.isFile()) {
                 return {
                     relativePath: normalizedRelative,
                     absolutePath,
@@ -35,64 +53,53 @@ export async function inspectRepoFile(root, relativePath, maxFileSizeBytes = DEF
                     readable: false,
                     sizeBytes: 0,
                     empty: true,
-                    isSymlink: true,
+                    isSymlink,
                     text: null,
-                    error: "Symlink target is outside repository root",
+                    error: "Not a regular file",
                 };
             }
-        }
-        const stat = await fs.stat(absolutePath);
-        if (!stat.isFile()) {
-            return {
-                relativePath: normalizedRelative,
-                absolutePath,
-                exists: true,
-                readable: false,
-                sizeBytes: 0,
-                empty: true,
-                isSymlink,
-                text: null,
-                error: "Not a regular file",
-            };
-        }
-        const sizeBytes = Number(stat.size);
-        if (sizeBytes === 0) {
+            const sizeBytes = Number(stat.size);
+            if (sizeBytes === 0) {
+                return {
+                    relativePath: normalizedRelative,
+                    absolutePath,
+                    exists: true,
+                    readable: true,
+                    sizeBytes: 0,
+                    empty: true,
+                    isSymlink,
+                    text: "",
+                };
+            }
+            if (sizeBytes > maxFileSizeBytes) {
+                return {
+                    relativePath: normalizedRelative,
+                    absolutePath,
+                    exists: true,
+                    readable: false,
+                    sizeBytes,
+                    empty: false,
+                    isSymlink,
+                    text: null,
+                    error: "File exceeds max size limit",
+                };
+            }
+            const text = await handle.readFile("utf8");
+            const trimmedEmpty = text.trim().length === 0;
             return {
                 relativePath: normalizedRelative,
                 absolutePath,
                 exists: true,
                 readable: true,
-                sizeBytes: 0,
-                empty: true,
-                isSymlink,
-                text: "",
-            };
-        }
-        if (sizeBytes > maxFileSizeBytes) {
-            return {
-                relativePath: normalizedRelative,
-                absolutePath,
-                exists: true,
-                readable: false,
                 sizeBytes,
-                empty: false,
+                empty: trimmedEmpty,
                 isSymlink,
-                text: null,
-                error: "File exceeds max size limit",
+                text,
             };
         }
-        const text = await fs.readFile(absolutePath, "utf8");
-        const trimmedEmpty = text.trim().length === 0;
-        return {
-            relativePath: normalizedRelative,
-            absolutePath,
-            exists: true,
-            readable: true,
-            sizeBytes,
-            empty: trimmedEmpty,
-            isSymlink,
-            text,
-        };
+        finally {
+            await handle.close();
+        }
     }
     catch (error) {
         const message = error instanceof Error ? error.message : "Unable to read file";

package/dist/cli/commands/doctor.js

@@ -15,7 +15,7 @@ export async function runDoctorCommand() {
     lines.push(`  ${symbolOk()} Core scan API available`);
     lines.push("");
     lines.push(colors.dim("Environment looks ready."));
-    lines.push(colors.dim("Automatic fixes are not available yet."));
+    lines.push(colors.dim("Run agentdoctor scan → fix → verify to complete the readiness loop."));
     lines.push("");
     process.stdout.write(lines.join("\n"));
     return EXIT_CODES.SUCCESS;

package/dist/cli/commands/explain.js

@@ -39,9 +39,9 @@ export async function runExplainCommand(ruleId) {
     lines.push("");
     lines.push(colors.bold("Can AgentDoctor safely fix it?"));
     lines.push(rule.fixability === "safe"
-        ? "  Potentially yes. Conservative auto-fix is planned but not applied today."
+        ? "  Yes for Cursor (`.cursorignore`), Claude Code (Read deny in `.claude/settings.json`), and Codex (filesystem deny in `.codex/config.toml`)."
         : rule.fixability === "review"
-            ? "  Only with review. Automatic fixes are not applied today."
+            ? "  No — requires human review. Fix reports why and leaves the file unchanged."
             : rule.fixability === "manual"
                 ? "  No automatic fix. Manual remediation required."
                 : "  No fix available.");

package/dist/cli/commands/fix.d.ts

@@ -1,8 +1,10 @@
 import { type ExitCode } from "../../types/index.js";
-/**
- * Safe automatic fixes are not implemented yet.
- */
-export declare function runFixCommand(options: {
+export interface FixCommandOptions {
+    targetPath?: string;
     dryRun?: boolean;
     yes?: boolean;
-}): Promise<ExitCode>;
+}
+/**
+ * Safe Repository Mutation — apply allowlisted agent-config exclusions.
+ */
+export declare function runFixCommand(options: FixCommandOptions): Promise<ExitCode>;

package/dist/cli/commands/fix.js

@@ -1,19 +1,80 @@
 import { EXIT_CODES } from "../../types/index.js";
+import { isDirectory } from "../../utils/fs.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { applyFixPlan, readClaudeSettings, readCodexConfig, readCursorignore, } from "../../core/fix/apply.js";
+import { buildFixPlan } from "../../core/fix/plan.js";
+import { renderFixPlanTerminal } from "../../core/fix/render.js";
+import { runFix } from "../../core/fix/run.js";
+import { scan } from "../../core/scanner/scan.js";
 import { colors } from "../../utils/colors.js";
 /**
- * Safe automatic fixes are not implemented yet.
+ * Safe Repository Mutation — apply allowlisted agent-config exclusions.
  */
 export async function runFixCommand(options) {
-    const lines = [];
-    lines.push("");
-    lines.push(colors.bold("AgentDoctor fix"));
-    lines.push("");
-    if (options.dryRun) {
-        lines.push("  Dry-run mode requested.");
+    const target = resolveRepoRoot(options.targetPath ?? process.cwd());
+    if (!(await isDirectory(target))) {
+        console.error(`Error: not a directory: ${target}`);
+        return EXIT_CODES.USAGE_ERROR;
     }
-    lines.push("  Fix mode is not implemented yet.");
-    lines.push("  No files were modified.");
-    lines.push("");
-    process.stdout.write(lines.join("\n"));
-    return EXIT_CODES.SUCCESS;
+    const dryRun = options.dryRun === true;
+    const yes = options.yes === true;
+    try {
+        if (dryRun) {
+            const result = await scan({ cwd: target });
+            const plan = await buildFixPlan(result);
+            const cursorContent = await readCursorignore(plan.root);
+            const claudeSettingsContent = await readClaudeSettings(plan.root);
+            const codexConfigContent = await readCodexConfig(plan.root);
+            const applyResult = await applyFixPlan(plan, { dryRun: true });
+            process.stdout.write(renderFixPlanTerminal(plan, {
+                dryRun: true,
+                cursorContent,
+                claudeSettingsContent,
+                codexConfigContent,
+                applyResult,
+            }));
+            return EXIT_CODES.SUCCESS;
+        }
+        const { plan, applyResult, cancelled } = await runFix({
+            cwd: target,
+            dryRun: false,
+            yes,
+        });
+        if (cancelled) {
+            process.stdout.write("\n  Cancelled. No files were modified.\n\n");
+            return EXIT_CODES.USAGE_ERROR;
+        }
+        const cursorContentAfter = await readCursorignore(plan.root);
+        const claudeSettingsAfter = await readClaudeSettings(plan.root);
+        const codexConfigAfter = await readCodexConfig(plan.root);
+        process.stdout.write(renderFixPlanTerminal(plan, {
+            dryRun: false,
+            cursorContent: cursorContentAfter,
+            claudeSettingsContent: claudeSettingsAfter,
+            codexConfigContent: codexConfigAfter,
+            applyResult,
+        }));
+        if (applyResult.writtenFiles.length > 0) {
+            const after = await scan({ cwd: target });
+            const remainingSafeContext = after.findings.filter((f) => f.fixability === "safe" &&
+                (f.ruleId === "context/generated-directory" || f.ruleId === "context/large-log-file"));
+            process.stdout.write(colors.dim(`  Re-scan: ${remainingSafeContext.length} safe context finding(s) remain.\n\n`));
+        }
+        return EXIT_CODES.SUCCESS;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Error: ${message}`);
+        if (isFixConfigOrPermissionError(message)) {
+            return EXIT_CODES.USAGE_ERROR;
+        }
+        return EXIT_CODES.INTERNAL_ERROR;
+    }
+}
+function isFixConfigOrPermissionError(message) {
+    return (message.includes("refusing") ||
+        message.includes("not valid JSON") ||
+        message.includes("EACCES") ||
+        message.includes("EPERM") ||
+        message.includes("permission denied"));
 }

package/dist/cli/commands/scan.d.ts

@@ -1,3 +1,4 @@
+import { type PolicyOptions } from "../../core/policy/evaluate.js";
 import { type ExitCode } from "../../types/index.js";
 export interface ScanCommandOptions {
     targetPath?: string;
@@ -5,6 +6,10 @@ export interface ScanCommandOptions {
     ci?: boolean;
     verbose?: boolean;
     minScore?: number;
+    failOnSeverity?: PolicyOptions["failOnSeverity"];
+    failOnRules?: string[];
+    summary?: boolean;
+    annotations?: boolean;
 }
 export declare function runScanCommand(options: ScanCommandOptions): Promise<ExitCode>;
 export declare function resolveTargetArgument(pathArg: string | undefined, cwd?: string): string;