@praneeth_54/agentdoctor 0.3.0-beta → 1.1.0

package/CHANGELOG.md

@@ -7,6 +7,108 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Notes
+
+- Owner-only after this tree is green: `npm publish`, git tag `v1.1.0`, GitHub Release.
+  Do **not** auto-publish from CI agents.
+
+## [1.1.0] — 2026-08-13
+
+Minor release: Brain → MCP → Agent consumption for Project Brain (Safety V1 unchanged).
+
+### Added
+
+- Project Brain MCP bridge (`agentdoctor brain-mcp --root <path>`): STDIO MCP server
+  exposing evidence-backed Brain tools (`brain_overview`, `brain_query`, `brain_explain`,
+  `brain_trace`, `brain_claims`, `brain_evidence`, `brain_ownership`, `brain_risk`,
+  `brain_delta`, `brain_snapshot`) with provenance envelopes. Local-only; no API key.
+  Docs: [docs/mcp/brain-mcp.md](docs/mcp/brain-mcp.md). Examples: [examples/mcp/](examples/mcp/).
+  Demo: [docs/demo/brain-mcp-demo.md](docs/demo/brain-mcp-demo.md).
+  Validation: [validation/mcp-agent/](validation/mcp-agent/).
+
+### Changed
+
+- Build packaging now includes `src/core/understanding/**` and `src/mcp/**` so the
+  `brain-mcp` CLI command can run from `dist/` (Safety public API export remains
+  Scan/Fix/Verify-focused).
+- MCP tool descriptions explicitly mark READ vs CONTROLLED WRITE (`brain_snapshot` rebuild
+  only under `.agentdoctor/project-brain/`).
+
+### Notes
+
+- Product promise: help AI coding agents understand what is in a repository, what can be
+  trusted, and why. Not a generic coding assistant, not RAG, not chatbot memory.
+- Authenticated third-party agent LLM smoke (Cursor / Claude Code / Codex Q1–Q7) remains an
+  environment/auth gate; engineering MCP + Brain contracts pass without it.
+
+## [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 is `1.0.0` (bumped after npm published `@praneeth_54/agentdoctor@1.0.0`)
+
 ## [0.3.0-beta] — 2026-08-07
 
 Minor beta: completes the Scan → Fix → Verify CLI loop and corrects release-facing honesty.
@@ -171,7 +273,9 @@ First public beta.
 - Not a complete secret scanner
 - Git “tracked secret” detection deferred
 
-[Unreleased]: https://github.com/pranee54/AgentDoctor/compare/v0.3.0-beta...HEAD
+[Unreleased]: https://github.com/pranee54/AgentDoctor/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/pranee54/AgentDoctor/releases/tag/v1.1.0
+[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

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,9 @@ AgentDoctor is a local CLI that inspects project-level AI coding agent setup —
 npx @praneeth_54/agentdoctor
 ```
 
-Public beta (`0.3.0-beta`). Scan → Fix → Verify. Deterministic scores in the terminal and JSON.
+Public release track: Safety V1 (`1.0.0`) plus Project Brain MCP for agents (`1.1.0`).
+Scan → Fix → Verify → CI remains the Safety contract. Brain MCP helps agents understand
+what is in a repository, what can be trusted, and why — not a generic coding assistant.
 
 ---
 
@@ -24,12 +26,12 @@ Public beta (`0.3.0-beta`). Scan → Fix → Verify. Deterministic scores in the
 
 ![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.3.0-beta._
+_Real scan of the included `insecure-agent-project` fixture using AgentDoctor v1.0.0._
 
 ```text
 $ npx @praneeth_54/agentdoctor
 
-🩺 AgentDoctor v0.3.0-beta
+🩺 AgentDoctor v1.0.0
 
 Scanning repository...
 
@@ -100,7 +102,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 or call an LLM. `agentdoctor fix` may append safe Cursor ignore patterns; it does not rewrite security settings or credentials.
+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`.
 
 ---
 
@@ -142,7 +144,7 @@ You get deterministic findings with:
 - conservative recommendations
 - readiness score (`scores.overall` in JSON; overall line in the terminal)
 
-Safe Cursor context exclusions can be applied with `agentdoctor fix`. Security and review findings stay manual — Fix explains why and does not invent unsafe edits.
+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.
 
 ---
 
@@ -154,10 +156,10 @@ Safe Cursor context exclusions can be applied with `agentdoctor fix`. Security a
 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.3.0-beta
+npx @praneeth_54/agentdoctor@1.0.0
 ```
 
 ### Global (optional)
@@ -173,7 +175,7 @@ agentdoctor
 # 1. Scan (save a baseline for Verify)
 npx @praneeth_54/agentdoctor scan . --json > agentdoctor-report.json
 
-# 2. Fix safe Cursor context exclusions (preview first with --dry-run)
+# 2. Fix safe context exclusions (preview first with --dry-run)
 npx @praneeth_54/agentdoctor fix . --dry-run
 npx @praneeth_54/agentdoctor fix . -y
 
@@ -181,7 +183,11 @@ npx @praneeth_54/agentdoctor fix . -y
 npx @praneeth_54/agentdoctor verify . --baseline agentdoctor-report.json
 ```
 
-`fix` currently writes `.cursorignore` patterns for safe context findings (for example unignored `build/` or large logs). Review/manual security findings are listed as skipped — address those yourself, then re-run `verify`.
+`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
 
@@ -279,10 +285,14 @@ steps:
 
   - name: Audit coding-agent configuration
     id: agentdoctor
-    uses: pranee54/AgentDoctor@v0.3.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
@@ -291,10 +301,12 @@ steps:
       path: ${{ steps.agentdoctor.outputs.report-path }}
 ```
 
-The action installs the published `@praneeth_54/agentdoctor@0.3.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. The Action default `version` is `1.0.0`. 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
 
@@ -302,15 +314,21 @@ 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).
 
@@ -325,19 +343,18 @@ 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                                                              |
-| --------------------------- | ------------------------------------------------------------------- |
-| Automatic fixes             | Safe Cursor `.cursorignore` context exclusions only                 |
-| Claude Code / Codex writers | Not implemented — Fix skips with an explicit reason                 |
-| Security findings           | Review/manual — Fix does not rewrite secrets or permission settings |
-| GitHub Action score gates   | Action remains `--ci --json` report-only (no `min-score` input)     |
-| 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/compatibility.md](docs/compatibility.md).
 
@@ -362,7 +379,9 @@ Details: [docs/architecture.md](docs/architecture.md)
 | [docs/rules.md](docs/rules.md)                                     | Stable rule IDs                 |
 | [docs/exit-codes.md](docs/exit-codes.md)                           | Process exit codes              |
 | [docs/scoring.md](docs/scoring.md)                                 | Readiness scoring specification |
-| [docs/compatibility.md](docs/compatibility.md)                     | Beta compatibility promises     |
+| [docs/compatibility.md](docs/compatibility.md)                     | v1 compatibility promises       |
+| [docs/project-brain.md](docs/project-brain.md)                     | Project Brain understanding     |
+| [docs/mcp/brain-mcp.md](docs/mcp/brain-mcp.md)                     | Brain → MCP → Agent bridge      |
 | [docs/development.md](docs/development.md)                         | Local development               |
 | [docs/github-launch-checklist.md](docs/github-launch-checklist.md) | GitHub About / topics / launch  |
 | [ROADMAP.md](ROADMAP.md)                                           | Near- and medium-term plans     |
@@ -388,6 +407,20 @@ node dist/cli/index.js ./fixtures/clean-configured-project
 
 ---
 
+## Project Brain MCP (agent context)
+
+Evidence-backed repository understanding for agents (not a search MCP):
+
+```bash
+agentdoctor brain-mcp --root /absolute/path/to/project
+```
+
+Tools: overview, query, explain, trace, claims, evidence, ownership, risk, delta, snapshot.
+Local STDIO only — no API key, no upload. Docs: [docs/mcp/brain-mcp.md](docs/mcp/brain-mcp.md).
+Examples: [examples/mcp/](examples/mcp/).
+
+---
+
 ## 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/brain-mcp.d.ts

@@ -0,0 +1,9 @@
+export interface BrainMcpCommandOptions {
+    root: string;
+    buildIfMissing?: boolean;
+    generatedAt?: string;
+}
+/**
+ * Start Brain MCP over STDIO. Must not write protocol noise to stdout.
+ */
+export declare function runBrainMcpCommand(options: BrainMcpCommandOptions): Promise<number>;

package/dist/cli/commands/brain-mcp.js

@@ -0,0 +1,38 @@
+import { EXIT_CODES } from "../../types/index.js";
+import { BrainMcpError, runBrainMcpStdio } from "../../mcp/brain/index.js";
+/**
+ * Start Brain MCP over STDIO. Must not write protocol noise to stdout.
+ */
+export async function runBrainMcpCommand(options) {
+    try {
+        if (!options.root || options.root.trim().length === 0) {
+            process.stderr.write("Error: --root <path> is required (never scans process.cwd() implicitly)\n");
+            return EXIT_CODES.USAGE_ERROR;
+        }
+        await runBrainMcpStdio({
+            root: options.root,
+            buildIfMissing: options.buildIfMissing !== false,
+            ...(options.generatedAt !== undefined ? { generatedAt: options.generatedAt } : {}),
+            log: (message) => process.stderr.write(`${message}\n`),
+        });
+        // STDIO server runs until stdin closes; resolve when transport ends.
+        await new Promise((resolve) => {
+            const onClose = () => resolve();
+            process.stdin.on("end", onClose);
+            process.stdin.on("close", onClose);
+        });
+        return EXIT_CODES.SUCCESS;
+    }
+    catch (error) {
+        if (error instanceof BrainMcpError) {
+            process.stderr.write(`Error: ${error.message}\n`);
+            if (error.code === "invalid_root" || error.code === "invalid_argument") {
+                return EXIT_CODES.USAGE_ERROR;
+            }
+            return EXIT_CODES.INTERNAL_ERROR;
+        }
+        const message = error instanceof Error ? error.message : "brain-mcp failed";
+        process.stderr.write(`Error: ${message}\n`);
+        return EXIT_CODES.INTERNAL_ERROR;
+    }
+}

package/dist/cli/commands/explain.js

@@ -39,7 +39,7 @@ export async function runExplainCommand(ruleId) {
     lines.push("");
     lines.push(colors.bold("Can AgentDoctor safely fix it?"));
     lines.push(rule.fixability === "safe"
-        ? "  Yes for Cursor context exclusions (`agentdoctor fix`). Other agents may still need a manual step."
+        ? "  Yes for Cursor (`.cursorignore`), Claude Code (Read deny in `.claude/settings.json`), and Codex (filesystem deny in `.codex/config.toml`)."
         : rule.fixability === "review"
             ? "  No — requires human review. Fix reports why and leaves the file unchanged."
             : rule.fixability === "manual"

package/dist/cli/commands/fix.js

@@ -1,7 +1,7 @@
 import { EXIT_CODES } from "../../types/index.js";
 import { isDirectory } from "../../utils/fs.js";
 import { resolveRepoRoot } from "../../utils/path.js";
-import { applyFixPlan, readCursorignore } from "../../core/fix/apply.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";
@@ -23,10 +23,14 @@ export async function runFixCommand(options) {
             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;
@@ -38,27 +42,39 @@ export async function runFixCommand(options) {
         });
         if (cancelled) {
             process.stdout.write("\n  Cancelled. No files were modified.\n\n");
-            return EXIT_CODES.SUCCESS;
+            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,
         }));
-        // After apply, show a short re-scan hint / delta for Cursor-fixable rules
         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") &&
-                f.affectedAgents.includes("cursor"));
-            process.stdout.write(colors.dim(`  Re-scan: ${remainingSafeContext.length} Cursor-related safe context finding(s) remain.\n\n`));
+                (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;

package/dist/cli/commands/scan.js

@@ -1,10 +1,12 @@
 import path from "node:path";
+import { evaluateScanPolicy } from "../../core/policy/evaluate.js";
 import { scan } from "../../core/scanner/scan.js";
+import { emitGithubReports } from "../../reporters/github/emit.js";
 import { renderJsonReport } from "../../reporters/json/report.js";
 import { renderTerminalReport } from "../../reporters/terminal/report.js";
 import { EXIT_CODES } from "../../types/index.js";
-import { resolveRepoRoot } from "../../utils/path.js";
 import { isDirectory } from "../../utils/fs.js";
+import { resolveRepoRoot } from "../../utils/path.js";
 export async function runScanCommand(options) {
     const target = resolveRepoRoot(options.targetPath ?? process.cwd());
     if (!(await isDirectory(target))) {
@@ -24,13 +26,30 @@ export async function runScanCommand(options) {
                 verbose: options.verbose === true,
             }));
         }
-        if (options.minScore !== undefined && result.scores !== null) {
-            if (result.scores.overall < options.minScore) {
-                if (!options.json) {
-                    console.error(`\nCI check failed: overall score ${result.scores.overall} is below --min-score ${options.minScore}`);
+        const failOnSeverity = options.failOnSeverity ?? (options.ci === true ? "critical" : undefined);
+        const policy = {
+            ...(options.minScore !== undefined ? { minimumScore: options.minScore } : {}),
+            ...(failOnSeverity !== undefined ? { failOnSeverity } : {}),
+            ...(options.failOnRules && options.failOnRules.length > 0
+                ? { failOnRules: options.failOnRules }
+                : {}),
+        };
+        const violations = evaluateScanPolicy(result, policy);
+        await emitGithubReports({
+            mode: "scan",
+            findings: result.findings,
+            overallScore: result.scores?.overall ?? null,
+            violations,
+            summary: options.summary === true,
+            annotations: options.annotations === true,
+        });
+        if (violations.length > 0) {
+            if (!options.json) {
+                for (const violation of violations) {
+                    console.error(`\n${violation.message}`);
                 }
-                return EXIT_CODES.ISSUES_OR_THRESHOLD;
             }
+            return EXIT_CODES.ISSUES_OR_THRESHOLD;
         }
         return EXIT_CODES.SUCCESS;
     }