@praneeth_54/agentdoctor 0.2.0-beta → 1.0.0

package/dist/core/rules/security/env-file-exposure.js

@@ -1,3 +1,6 @@
+import { claudeDeniesPath } from "../claude-deny.js";
+import { codexDeniesPath } from "../codex-deny.js";
+import { isSampleOrTestPath } from "../path-kind.js";
 const TEMPLATE_BASENAMES = new Set([".env.example", ".env.sample", ".env.template", ".env.dist"]);
 const BACKUP_BASENAMES = new Set([".env_backup", ".env_old", ".env_local"]);
 /**
@@ -10,11 +13,18 @@ export function classifyEnvBasename(base) {
         return null;
     }
     const lower = normalized.toLowerCase();
+    if (BACKUP_BASENAMES.has(lower)) {
+        return "backup";
+    }
     if (TEMPLATE_BASENAMES.has(lower)) {
         return "template";
     }
-    if (BACKUP_BASENAMES.has(lower)) {
-        return "backup";
+    // .env.local.example, .env.testing.example, .env.example.local, etc.
+    if (/\.(?:example|sample|template)(?:\.|$)/i.test(normalized)) {
+        return "template";
+    }
+    if (/\.env(?:\.[A-Za-z0-9_-]+)*\.(?:example|sample|template)$/i.test(normalized)) {
+        return "template";
     }
     if (lower === ".env") {
         return "runtime";
@@ -54,28 +64,6 @@ function agentsWithoutClearExclusion(context, relativePath) {
     }
     return affected;
 }
-async function claudeDeniesRead(context, relativePath) {
-    const settingsFiles = context.agents
-        .find((a) => a.id === "claude-code")
-        ?.configFiles.filter((f) => f.kind === "claude-settings" || f.kind === "claude-settings-local") ?? [];
-    for (const file of settingsFiles) {
-        const cached = await context.textCache.read(file.relativePath);
-        if (!cached.text)
-            continue;
-        const patterns = [
-            `Read(./${relativePath})`,
-            `Read(${relativePath})`,
-            `Read(/**/${relativePath.split("/").pop()})`,
-        ];
-        if (patterns.some((p) => cached.text.includes(p))) {
-            return true;
-        }
-        if (/"deny"\s*:\s*\[[^\]]*"Read"\s*[,\]]/.test(cached.text)) {
-            return true;
-        }
-    }
-    return false;
-}
 export const envFileExposureRule = {
     id: "security/env-file-exposure",
     title: "Sensitive environment file may enter agent context",
@@ -93,19 +81,11 @@ export const envFileExposureRule = {
             if (!kind) {
                 continue;
             }
+            if (isSampleOrTestPath(file.relativePath)) {
+                continue;
+            }
+            // Templates document variable names; they are not agent-readiness findings.
             if (kind === "template") {
-                findings.push({
-                    ruleId: "security/env-file-exposure",
-                    category: "security",
-                    severity: "info",
-                    title: "Environment template file present",
-                    message: `Environment template file detected at ${file.relativePath}`,
-                    whyItMatters: "Template env files are usually placeholders, but they can still document secret names. Filename classification only — contents were not inspected.",
-                    recommendation: "Keep templates free of real credentials. Prefer documenting variable names without values.",
-                    affectedAgents: [],
-                    evidence: { path: file.relativePath, detail: "template" },
-                    fixability: "review",
-                });
                 continue;
             }
             if (!agentsPresent) {
@@ -128,10 +108,15 @@ export const envFileExposureRule = {
             }
             let affected = agentsWithoutClearExclusion(context, file.relativePath);
             if (affected.includes("claude-code")) {
-                if (await claudeDeniesRead(context, file.relativePath)) {
+                if (await claudeDeniesPath(context, file.relativePath)) {
                     affected = affected.filter((a) => a !== "claude-code");
                 }
             }
+            if (affected.includes("codex")) {
+                if (await codexDeniesPath(context, file.relativePath)) {
+                    affected = affected.filter((a) => a !== "codex");
+                }
+            }
             if (affected.length === 0) {
                 continue;
             }
@@ -142,7 +127,7 @@ export const envFileExposureRule = {
                 title: "Sensitive environment file may enter agent context",
                 message: `Sensitive environment file detected and no relevant exclusion was found for: ${file.relativePath}`,
                 whyItMatters: "Environment files frequently hold API keys and credentials. If readable by an AI coding agent, those values may be included in prompts or logs.",
-                recommendation: "Add an agent-specific exclusion (for example .cursorignore or a Claude Code Read deny rule), keep the file out of version control, and rotate any credentials that may have been exposed.",
+                recommendation: "Add an agent-specific exclusion (for example .cursorignore, a Claude Code Read deny rule, or a Codex filesystem deny), keep the file out of version control, and rotate any credentials that may have been exposed.",
                 affectedAgents: affected,
                 evidence: {
                     path: file.relativePath,

package/dist/core/rules/security/private-key-file.js

@@ -1,3 +1,4 @@
+import { isSampleOrTestPath } from "../path-kind.js";
 const PRIVATE_KEY_PATTERNS = [
     { test: (b) => /^id_rsa$/i.test(b), label: "SSH private key" },
     { test: (b) => /^id_ed25519$/i.test(b), label: "SSH private key" },
@@ -40,6 +41,9 @@ export const privateKeyFileRule = {
         const findings = [];
         const affected = context.agents.filter((a) => a.detected || a.configured).map((a) => a.id);
         for (const file of context.discovery.files) {
+            if (isSampleOrTestPath(file.relativePath)) {
+                continue;
+            }
             const base = file.relativePath.split("/").pop() ?? file.relativePath;
             const label = classify(base);
             if (!label) {

package/dist/core/rules/text-cache.js

@@ -32,55 +32,61 @@ export class TextCache {
             return blocked;
         }
         try {
-            const stat = await fs.stat(absolute);
-            if (!stat.isFile()) {
-                const result = {
-                    relativePath: toPosixRelative(this.root, absolute),
-                    text: null,
-                    sizeBytes: 0,
-                    empty: true,
-                    binary: false,
-                    error: "Not a regular file",
-                };
-                this.cache.set(relativePath, result);
-                return result;
-            }
-            const sizeBytes = Number(stat.size);
-            if (sizeBytes > this.maxBytes) {
+            const handle = await fs.open(absolute, "r");
+            try {
+                const stat = await handle.stat();
+                if (!stat.isFile()) {
+                    const result = {
+                        relativePath: toPosixRelative(this.root, absolute),
+                        text: null,
+                        sizeBytes: 0,
+                        empty: true,
+                        binary: false,
+                        error: "Not a regular file",
+                    };
+                    this.cache.set(relativePath, result);
+                    return result;
+                }
+                const sizeBytes = Number(stat.size);
+                if (sizeBytes > this.maxBytes) {
+                    const result = {
+                        relativePath,
+                        text: null,
+                        sizeBytes,
+                        empty: false,
+                        binary: false,
+                        error: "File exceeds max read size",
+                    };
+                    this.cache.set(relativePath, result);
+                    return result;
+                }
+                const buffer = await handle.readFile();
+                if (looksBinary(buffer)) {
+                    const result = {
+                        relativePath,
+                        text: null,
+                        sizeBytes,
+                        empty: sizeBytes === 0,
+                        binary: true,
+                        error: "Binary file skipped",
+                    };
+                    this.cache.set(relativePath, result);
+                    return result;
+                }
+                const text = buffer.toString("utf8");
                 const result = {
                     relativePath,
-                    text: null,
+                    text,
                     sizeBytes,
-                    empty: false,
+                    empty: text.trim().length === 0,
                     binary: false,
-                    error: "File exceeds max read size",
                 };
                 this.cache.set(relativePath, result);
                 return result;
             }
-            const buffer = await fs.readFile(absolute);
-            if (looksBinary(buffer)) {
-                const result = {
-                    relativePath,
-                    text: null,
-                    sizeBytes,
-                    empty: sizeBytes === 0,
-                    binary: true,
-                    error: "Binary file skipped",
-                };
-                this.cache.set(relativePath, result);
-                return result;
+            finally {
+                await handle.close();
             }
-            const text = buffer.toString("utf8");
-            const result = {
-                relativePath,
-                text,
-                sizeBytes,
-                empty: text.trim().length === 0,
-                binary: false,
-            };
-            this.cache.set(relativePath, result);
-            return result;
         }
         catch (error) {
             const message = error instanceof Error ? error.message : "Unable to read file";

package/dist/core/verify/compare.d.ts

@@ -0,0 +1,29 @@
+import type { Finding, FindingEvidence, Severity } from "../../types/index.js";
+/** Stable subset of a finding for verify reports. */
+export interface VerifyFindingRef {
+    id: string;
+    ruleId: string;
+    severity: Severity;
+    title: string;
+    message: string;
+    evidence?: FindingEvidence;
+}
+export interface FindingCompareResult {
+    fixed: VerifyFindingRef[];
+    remaining: VerifyFindingRef[];
+    new: VerifyFindingRef[];
+    unchanged: VerifyFindingRef[];
+    summary: {
+        fixed: number;
+        remaining: number;
+        new: number;
+        unchanged: number;
+        before: number;
+        after: number;
+    };
+}
+export declare function toVerifyFindingRef(finding: Finding): VerifyFindingRef;
+/**
+ * Deterministic finding set comparison keyed by stable `Finding.id`.
+ */
+export declare function compareFindings(before: readonly Finding[], after: readonly Finding[]): FindingCompareResult;

package/dist/core/verify/compare.js

@@ -0,0 +1,56 @@
+export function toVerifyFindingRef(finding) {
+    const ref = {
+        id: finding.id,
+        ruleId: finding.ruleId,
+        severity: finding.severity,
+        title: finding.title,
+        message: finding.message,
+    };
+    if (finding.evidence !== undefined) {
+        ref.evidence = { ...finding.evidence };
+    }
+    return ref;
+}
+function sortRefs(refs) {
+    return [...refs].sort((a, b) => a.id.localeCompare(b.id));
+}
+/**
+ * Deterministic finding set comparison keyed by stable `Finding.id`.
+ */
+export function compareFindings(before, after) {
+    const beforeById = new Map(before.map((f) => [f.id, f]));
+    const afterById = new Map(after.map((f) => [f.id, f]));
+    const fixed = [];
+    const remaining = [];
+    const newly = [];
+    for (const [id, finding] of beforeById) {
+        if (!afterById.has(id)) {
+            fixed.push(toVerifyFindingRef(finding));
+        }
+        else {
+            remaining.push(toVerifyFindingRef(afterById.get(id)));
+        }
+    }
+    for (const [id, finding] of afterById) {
+        if (!beforeById.has(id)) {
+            newly.push(toVerifyFindingRef(finding));
+        }
+    }
+    const fixedSorted = sortRefs(fixed);
+    const remainingSorted = sortRefs(remaining);
+    const newSorted = sortRefs(newly);
+    return {
+        fixed: fixedSorted,
+        remaining: remainingSorted,
+        new: newSorted,
+        unchanged: remainingSorted,
+        summary: {
+            fixed: fixedSorted.length,
+            remaining: remainingSorted.length,
+            new: newSorted.length,
+            unchanged: remainingSorted.length,
+            before: before.length,
+            after: after.length,
+        },
+    };
+}

package/dist/core/verify/load-baseline.d.ts

@@ -0,0 +1,15 @@
+import type { Finding } from "../../types/index.js";
+declare const DEFAULT_BASELINE_NAMES: readonly ["agentdoctor-report.json", ".agentdoctor-baseline.json"];
+export interface LoadedBaseline {
+    path: string;
+    findings: Finding[];
+}
+/**
+ * Load findings from a prior `scan --json` report (or a bare `{ findings: [...] }` file).
+ */
+export declare function loadBaselineFindings(baselinePath: string): Promise<LoadedBaseline>;
+/**
+ * Resolve baseline path: explicit flag, else first default filename that exists under root.
+ */
+export declare function resolveBaselinePath(root: string, explicitBaseline?: string): Promise<string | undefined>;
+export { DEFAULT_BASELINE_NAMES };

package/dist/core/verify/load-baseline.js

@@ -0,0 +1,71 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const DEFAULT_BASELINE_NAMES = ["agentdoctor-report.json", ".agentdoctor-baseline.json"];
+function isFindingLike(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const record = value;
+    return (typeof record.id === "string" &&
+        typeof record.ruleId === "string" &&
+        typeof record.severity === "string" &&
+        typeof record.title === "string" &&
+        typeof record.message === "string");
+}
+/**
+ * Load findings from a prior `scan --json` report (or a bare `{ findings: [...] }` file).
+ */
+export async function loadBaselineFindings(baselinePath) {
+    const absolute = path.resolve(baselinePath);
+    let raw;
+    try {
+        raw = await fs.readFile(absolute, "utf8");
+    }
+    catch {
+        throw new Error(`baseline not found or unreadable: ${absolute}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`baseline is not valid JSON: ${absolute}`);
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error(`baseline JSON must be an object: ${absolute}`);
+    }
+    const findingsUnknown = parsed.findings;
+    if (!Array.isArray(findingsUnknown)) {
+        throw new Error(`baseline JSON must include a findings array: ${absolute}`);
+    }
+    const findings = [];
+    for (const item of findingsUnknown) {
+        if (!isFindingLike(item)) {
+            throw new Error(`baseline contains an invalid finding entry: ${absolute}`);
+        }
+        findings.push(item);
+    }
+    return { path: absolute, findings };
+}
+/**
+ * Resolve baseline path: explicit flag, else first default filename that exists under root.
+ */
+export async function resolveBaselinePath(root, explicitBaseline) {
+    if (explicitBaseline) {
+        return path.isAbsolute(explicitBaseline)
+            ? explicitBaseline
+            : path.resolve(root, explicitBaseline);
+    }
+    for (const name of DEFAULT_BASELINE_NAMES) {
+        const candidate = path.join(root, name);
+        try {
+            await fs.access(candidate);
+            return candidate;
+        }
+        catch {
+            // try next
+        }
+    }
+    return undefined;
+}
+export { DEFAULT_BASELINE_NAMES };

package/dist/core/verify/verify.d.ts

@@ -0,0 +1,26 @@
+import type { Scores, ScanResult } from "../../types/index.js";
+import { type FindingCompareResult } from "./compare.js";
+export interface VerifyOptions {
+    cwd?: string;
+    /** Path to a prior scan JSON report. Defaults to agentdoctor-report.json if present. */
+    baselinePath?: string;
+    verbose?: boolean;
+}
+export interface VerifyResult extends FindingCompareResult {
+    version: string;
+    repositoryRoot: string;
+    baselinePath: string;
+    after: ScanResult;
+    scores: Scores | null;
+    scoringAvailable: boolean;
+    timing: {
+        totalMs: number;
+        scanMs: number;
+        compareMs: number;
+    };
+}
+/**
+ * Re-scan the repository and compare against a prior scan JSON baseline.
+ * Reuses the public `scan()` pipeline — no duplicated rule engine.
+ */
+export declare function verify(options?: VerifyOptions): Promise<VerifyResult>;

package/dist/core/verify/verify.js

@@ -0,0 +1,40 @@
+import { PACKAGE_VERSION } from "../../constants.js";
+import { scan } from "../scanner/scan.js";
+import { compareFindings } from "./compare.js";
+import { loadBaselineFindings, resolveBaselinePath } from "./load-baseline.js";
+/**
+ * Re-scan the repository and compare against a prior scan JSON baseline.
+ * Reuses the public `scan()` pipeline — no duplicated rule engine.
+ */
+export async function verify(options = {}) {
+    const totalStarted = performance.now();
+    const cwd = options.cwd ?? process.cwd();
+    const resolvedBaseline = await resolveBaselinePath(cwd, options.baselinePath);
+    if (!resolvedBaseline) {
+        throw new Error("No verify baseline found. Run `agentdoctor scan --json > agentdoctor-report.json`, apply fixes, then re-run verify.");
+    }
+    const baseline = await loadBaselineFindings(resolvedBaseline);
+    const scanStarted = performance.now();
+    const after = await scan({
+        cwd,
+        verbose: options.verbose ?? false,
+    });
+    const scanMs = Math.round(performance.now() - scanStarted);
+    const compareStarted = performance.now();
+    const compared = compareFindings(baseline.findings, after.findings);
+    const compareMs = Math.round(performance.now() - compareStarted);
+    return {
+        version: PACKAGE_VERSION,
+        repositoryRoot: after.repository.root,
+        baselinePath: baseline.path,
+        ...compared,
+        after,
+        scores: after.scores,
+        scoringAvailable: after.scoringAvailable,
+        timing: {
+            totalMs: Math.round(performance.now() - totalStarted),
+            scanMs,
+            compareMs,
+        },
+    };
+}

package/dist/discovery/files.js

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { DEFAULT_IGNORE_DIRECTORIES, DEFAULT_MAX_FILE_SIZE_BYTES } from "../constants.js";
 import { isPathInsideRoot, toPosixRelative } from "../utils/path.js";
+import { isLogLikePath } from "./log-like.js";
 /**
  * Walk the repository without blindly reading every file.
  * Skips common generated/dependency directories and records permission errors.
@@ -70,14 +71,18 @@ export async function discoverFiles(options) {
             }
             try {
                 const stat = await fs.lstat(absolutePath);
-                if (stat.size > maxFileSizeBytes) {
+                const sizeBytes = Number(stat.size);
+                // Oversized binaries stay skipped (content reads already refuse them).
+                // Log/dump-like paths are kept as metadata so context/large-log-file
+                // can flag the worst offenders instead of silently missing them.
+                if (sizeBytes > maxFileSizeBytes && !isLogLikePath(relativePath)) {
                     filesSkippedOversized += 1;
                     continue;
                 }
                 files.push({
                     absolutePath,
                     relativePath,
-                    sizeBytes: Number(stat.size),
+                    sizeBytes,
                     isSymlink,
                 });
             }

package/dist/discovery/log-like.d.ts

@@ -0,0 +1,2 @@
+/** Path looks like a log/dump that can pollute agent context (size-only rules). */
+export declare function isLogLikePath(relativePath: string): boolean;

package/dist/discovery/log-like.js

@@ -0,0 +1,7 @@
+const LOG_LIKE = /\.(log|out|dump)$/i;
+const HEAVY_NAME = /(^|\/)(debug|trace|coverage-final|chrome-devtools|heapdump)/i;
+/** Path looks like a log/dump that can pollute agent context (size-only rules). */
+export function isLogLikePath(relativePath) {
+    const base = relativePath.split("/").pop() ?? relativePath;
+    return LOG_LIKE.test(base) || HEAVY_NAME.test(relativePath);
+}

package/dist/index.d.ts

@@ -1,8 +1,18 @@
 export { scan } from "./core/scanner/scan.js";
+export { verify } from "./core/verify/verify.js";
+export { compareFindings } from "./core/verify/compare.js";
 export { PACKAGE_VERSION } from "./constants.js";
 export type { ScanOptions, ScanResult, RepositoryInfo, Finding, FindingsSummary, Scores, AgentPresence, AgentDetectionResult, AgentSecurityAnalysisMode, CliOptions, ExitCode, } from "./types/index.js";
+export type { VerifyResult, VerifyOptions } from "./core/verify/verify.js";
+export type { VerifyFindingRef, FindingCompareResult } from "./core/verify/compare.js";
 export { EXIT_CODES } from "./types/index.js";
 export { agentRegistry } from "./agents/registry.js";
 export { detectAgents } from "./agents/detect-agents.js";
 export { ruleRegistry, getRuleById } from "./core/rules/registry.js";
 export { runRules } from "./core/rules/run-rules.js";
+export { buildFixPlan } from "./core/fix/plan.js";
+export { applyFixPlan } from "./core/fix/apply.js";
+export { runFix } from "./core/fix/run.js";
+export { evaluatePolicy, evaluateScanPolicy, evaluateVerifyPolicy, parseFailOnRules, parseSeverityGate, } from "./core/policy/evaluate.js";
+export type { PolicyOptions, PolicyViolation, PolicyViolationCode, PolicyInput, } from "./core/policy/evaluate.js";
+export type { FixPlan, FixAction, FixApplyResult } from "./core/fix/types.js";

package/dist/index.js

@@ -1,7 +1,13 @@
 export { scan } from "./core/scanner/scan.js";
+export { verify } from "./core/verify/verify.js";
+export { compareFindings } from "./core/verify/compare.js";
 export { PACKAGE_VERSION } from "./constants.js";
 export { EXIT_CODES } from "./types/index.js";
 export { agentRegistry } from "./agents/registry.js";
 export { detectAgents } from "./agents/detect-agents.js";
 export { ruleRegistry, getRuleById } from "./core/rules/registry.js";
 export { runRules } from "./core/rules/run-rules.js";
+export { buildFixPlan } from "./core/fix/plan.js";
+export { applyFixPlan } from "./core/fix/apply.js";
+export { runFix } from "./core/fix/run.js";
+export { evaluatePolicy, evaluateScanPolicy, evaluateVerifyPolicy, parseFailOnRules, parseSeverityGate, } from "./core/policy/evaluate.js";

package/dist/reporters/github/annotations.d.ts

@@ -0,0 +1,8 @@
+import type { Finding } from "../../types/index.js";
+/**
+ * GitHub Actions workflow commands for file annotations.
+ * Emitted to stderr so `--json` stdout stays pure JSON.
+ *
+ * @see https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions
+ */
+export declare function renderGithubAnnotations(findings: Finding[]): string;

package/dist/reporters/github/annotations.js

@@ -0,0 +1,42 @@
+/**
+ * GitHub Actions workflow commands for file annotations.
+ * Emitted to stderr so `--json` stdout stays pure JSON.
+ *
+ * @see https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions
+ */
+export function renderGithubAnnotations(findings) {
+    const lines = [];
+    for (const finding of findings) {
+        lines.push(formatAnnotation(finding));
+    }
+    return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+}
+function formatAnnotation(finding) {
+    const level = annotationLevel(finding.severity);
+    const properties = [];
+    const file = finding.evidence?.path?.replace(/\\/g, "/");
+    if (file) {
+        properties.push(`file=${escapeProperty(file)}`);
+    }
+    if (finding.evidence?.line !== undefined && Number.isFinite(finding.evidence.line)) {
+        properties.push(`line=${finding.evidence.line}`);
+    }
+    properties.push(`title=${escapeProperty(`${finding.ruleId}: ${finding.title}`)}`);
+    const message = escapeMessage(`${finding.message} (${finding.ruleId})`);
+    const props = properties.length > 0 ? ` ${properties.join(",")}` : "";
+    return `::${level}${props}::${message}`;
+}
+function annotationLevel(severity) {
+    return severity === "critical" ? "error" : severity === "warning" ? "warning" : "notice";
+}
+function escapeProperty(value) {
+    return value
+        .replace(/%/g, "%25")
+        .replace(/\r/g, "%0D")
+        .replace(/\n/g, "%0A")
+        .replace(/:/g, "%3A")
+        .replace(/,/g, "%2C");
+}
+function escapeMessage(value) {
+    return value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+}

package/dist/reporters/github/emit.d.ts

@@ -0,0 +1,23 @@
+import type { PolicyViolation } from "../../core/policy/evaluate.js";
+import type { Finding } from "../../types/index.js";
+export interface GithubReportOptions {
+    summary?: boolean;
+    annotations?: boolean;
+}
+export declare function emitGithubReports(options: {
+    mode: "scan" | "verify";
+    findings: Finding[];
+    overallScore: number | null;
+    violations: PolicyViolation[];
+    verifySummary?: {
+        fixed: number;
+        remaining: number;
+        new: number;
+        unchanged: number;
+    };
+    summary?: boolean;
+    annotations?: boolean;
+    /** Override for tests */
+    stepSummaryPath?: string | null;
+    annotationsWrite?: (text: string) => void;
+}): Promise<void>;

package/dist/reporters/github/emit.js

@@ -0,0 +1,31 @@
+import fs from "node:fs/promises";
+import { renderGithubAnnotations } from "./annotations.js";
+import { renderGithubStepSummary } from "./summary.js";
+export async function emitGithubReports(options) {
+    if (options.annotations) {
+        const text = renderGithubAnnotations(options.findings);
+        if (text.length > 0) {
+            const write = options.annotationsWrite ?? ((chunk) => process.stderr.write(chunk));
+            write(text);
+        }
+    }
+    if (!options.summary) {
+        return;
+    }
+    const markdown = renderGithubStepSummary({
+        title: options.mode === "verify" ? "AgentDoctor Verify" : "AgentDoctor Scan",
+        overallScore: options.overallScore,
+        findings: options.findings,
+        violations: options.violations,
+        mode: options.mode,
+        ...(options.verifySummary ? { verifySummary: options.verifySummary } : {}),
+    });
+    const summaryPath = options.stepSummaryPath !== undefined
+        ? options.stepSummaryPath
+        : (process.env.GITHUB_STEP_SUMMARY ?? null);
+    if (summaryPath) {
+        await fs.appendFile(summaryPath, markdown, "utf8");
+        return;
+    }
+    process.stderr.write("Note: --summary set but GITHUB_STEP_SUMMARY is unset; skipping step summary write.\n");
+}