codex-plugin-doctor 1.43.0 → 1.45.0

package/README.md

@@ -287,8 +287,10 @@ codex-plugin-doctor check . --ascii
 codex-plugin-doctor check . --no-animations
 codex-plugin-doctor check . --runtime
 codex-plugin-doctor check . --runtime --require-runtime-approval --runtime-approval-digest sha256:<approved-plan-digest>
-codex-plugin-doctor check . --config .codex-doctor.json
-codex-plugin-doctor check . --history validation-history.jsonl
+codex-plugin-doctor check . --config .codex-doctor.json
+codex-plugin-doctor baseline create . --output .codex-doctor-baseline.json
+codex-plugin-doctor check . --baseline .codex-doctor-baseline.json
+codex-plugin-doctor check . --history validation-history.jsonl
 codex-plugin-doctor history validation-history.jsonl
 codex-plugin-doctor history validation-history.jsonl --json
 codex-plugin-doctor history validation-history.jsonl --fail-on-regression
@@ -334,9 +336,11 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
 
 `check --badge-json` emits Shields endpoint-compatible JSON such as `{"schemaVersion":1,"label":"doctor","message":"PASS","color":"brightgreen"}`. `check --badge-markdown` emits a static shields.io Markdown badge for README or release notes. Badge output is intentionally limited to single package checks, not `check --installed`.
 
-`check --history <path>` appends a compact JSONL validation snapshot after a single package check. `history <path>` reads the JSONL file and compares the latest run to the previous run, including status, finding-count deltas, and whether the latest run regressed. Add `history --json` for automation output or `history --fail-on-regression` when CI should fail after a worse latest run.
-
-`fix --dry-run` renders safe automatic fix plans without changing files. `fix --interactive --backup` shows the same numbered plan, then applies everything after `yes` or only selected action numbers such as `1,3`. `fix --apply --backup` applies supported safe fixes, such as manifest defaults and missing skills directories, after creating backups.
+`check --history <path>` appends a compact JSONL validation snapshot after a single package check. `history <path>` reads the JSONL file and compares the latest run to the previous run, including status, finding-count deltas, and whether the latest run regressed. Add `history --json` for automation output or `history --fail-on-regression` when CI should fail after a worse latest run.
+
+`baseline create <path> --output <path>` records the current fingerprinted findings for gradual CI adoption. A later `check <path> --baseline <path>` keeps matched findings visible in baseline metadata but gates only new active findings; reports summarize new, matched, and resolved counts. Commit the baseline for review and regenerate it deliberately after accepted findings change.
+
+`fix --dry-run` renders safe automatic fix plans without changing files. `fix --interactive --backup` shows the same numbered plan, then applies everything after `yes` or only selected action numbers such as `1,3`. `fix --apply --backup` applies supported safe fixes, such as manifest defaults and missing skills directories, after creating backups.
 
 Optional local policy file:
 
@@ -402,9 +406,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.43.0
+      - uses: Esquetta/CodexPluginDoctor@v1.45.0
         with:
-          version: "1.43.0"
+          version: "1.45.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/config-validate.d.ts

@@ -0,0 +1,13 @@
+export interface ConfigValidationFinding {
+    field: string;
+    message: string;
+    severity: "fail" | "warn";
+}
+export interface ConfigValidationReport {
+    configPath: string;
+    status: "pass" | "fail";
+    findings: ConfigValidationFinding[];
+}
+export declare function validateConfigFile(configPath: string): Promise<ConfigValidationReport>;
+export declare function renderConfigValidation(report: ConfigValidationReport): string;
+export declare function renderConfigValidationJson(report: ConfigValidationReport): string;

package/dist/core/config-validate.js

@@ -0,0 +1,133 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+const knownFields = ["ignoreRules", "failOnWarnings", "suppressions"];
+export async function validateConfigFile(configPath) {
+    const resolvedPath = path.resolve(configPath);
+    const findings = [];
+    try {
+        await stat(resolvedPath);
+    }
+    catch {
+        return {
+            configPath: resolvedPath,
+            status: "fail",
+            findings: [
+                { field: "file", message: `Config file not found: ${resolvedPath}`, severity: "fail" }
+            ]
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(resolvedPath, "utf8"));
+    }
+    catch (error) {
+        return {
+            configPath: resolvedPath,
+            status: "fail",
+            findings: [
+                { field: "json", message: `Invalid JSON: ${error.message}`, severity: "fail" }
+            ]
+        };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return {
+            configPath: resolvedPath,
+            status: "fail",
+            findings: [
+                { field: "root", message: "Config must be a JSON object.", severity: "fail" }
+            ]
+        };
+    }
+    const config = parsed;
+    for (const key of Object.keys(config)) {
+        if (!knownFields.includes(key)) {
+            findings.push({
+                field: key,
+                message: `Unknown field: "${key}". Known fields: ${knownFields.join(", ")}`,
+                severity: "warn"
+            });
+        }
+    }
+    if ("ignoreRules" in config) {
+        const ignoreRules = config.ignoreRules;
+        if (!Array.isArray(ignoreRules)) {
+            findings.push({ field: "ignoreRules", message: "Must be an array of strings.", severity: "fail" });
+        }
+        else if (!ignoreRules.every((r) => typeof r === "string")) {
+            findings.push({ field: "ignoreRules", message: "All entries must be strings.", severity: "fail" });
+        }
+    }
+    if ("failOnWarnings" in config) {
+        if (typeof config.failOnWarnings !== "boolean") {
+            findings.push({ field: "failOnWarnings", message: "Must be a boolean.", severity: "fail" });
+        }
+    }
+    if ("suppressions" in config) {
+        const suppressions = config.suppressions;
+        if (!Array.isArray(suppressions)) {
+            findings.push({ field: "suppressions", message: "Must be an array.", severity: "fail" });
+        }
+        else {
+            for (let i = 0; i < suppressions.length; i += 1) {
+                const entry = suppressions[i];
+                if (!entry || typeof entry !== "object") {
+                    findings.push({ field: `suppressions[${i}]`, message: "Must be an object.", severity: "fail" });
+                    continue;
+                }
+                if (typeof entry.fingerprint !== "string" || !/^[a-f0-9]{64}$/.test(entry.fingerprint)) {
+                    findings.push({
+                        field: `suppressions[${i}].fingerprint`,
+                        message: "Must be a 64-character lowercase hex string.",
+                        severity: "fail"
+                    });
+                }
+                if (typeof entry.reason !== "string" || entry.reason.trim().length === 0) {
+                    findings.push({
+                        field: `suppressions[${i}].reason`,
+                        message: "Must be a non-empty string.",
+                        severity: "fail"
+                    });
+                }
+                if (typeof entry.expiresAt !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(entry.expiresAt)) {
+                    findings.push({
+                        field: `suppressions[${i}].expiresAt`,
+                        message: "Must be a YYYY-MM-DD date string.",
+                        severity: "fail"
+                    });
+                }
+            }
+        }
+    }
+    const hasFail = findings.some((f) => f.severity === "fail");
+    return {
+        configPath: resolvedPath,
+        status: hasFail ? "fail" : findings.length === 0 ? "pass" : "warn",
+        findings
+    };
+}
+export function renderConfigValidation(report) {
+    const lines = [
+        "Codex Plugin Doctor Config Validation",
+        "=====================================",
+        `Path: ${report.configPath}`,
+        `Status: ${report.status.toUpperCase()}`,
+        ""
+    ];
+    if (report.findings.length === 0) {
+        lines.push("Config is valid.");
+        return lines.join("\n");
+    }
+    for (const finding of report.findings) {
+        const tag = finding.severity === "fail" ? "FAIL" : "WARN";
+        lines.push(`${tag}  ${finding.field}: ${finding.message}`);
+    }
+    return lines.join("\n");
+}
+export function renderConfigValidationJson(report) {
+    return JSON.stringify({
+        schemaVersion: "1.0.0",
+        configPath: report.configPath,
+        status: report.status,
+        findings: report.findings
+    }, null, 2);
+}

package/dist/core/shell-completion.d.ts

@@ -0,0 +1,2 @@
+export type CompletionShell = "bash" | "zsh" | "fish";
+export declare function generateCompletion(shell: CompletionShell): string;

package/dist/core/shell-completion.js

@@ -0,0 +1,97 @@
+const topLevelCommands = [
+    "check",
+    "audit",
+    "mcp",
+    "security",
+    "compat",
+    "suppress",
+    "fix",
+    "history",
+    "watch",
+    "doctor",
+    "init",
+    "init-ci",
+    "init-git-hooks",
+    "self-test",
+    "list",
+    "explain",
+    "config"
+];
+function bashCompletion() {
+    return [
+        "_codex_plugin_doctor() {",
+        "  local cur prev",
+        "  COMPREPLY=()",
+        "  cur=\"${COMP_WORDS[COMP_CWORD]}\"",
+        "  prev=\"${COMP_WORDS[COMP_CWORD-1]}\"",
+        "",
+        `  local commands="${topLevelCommands.join(" ")}"`,
+        "",
+        "  case \"${prev}\" in",
+        "    codex-plugin-doctor)",
+        "      COMPREPLY=( $(compgen -W \"${commands}\" -- \"${cur}\") )",
+        "      return 0",
+        "      ;;",
+        "  esac",
+        "",
+        "  case \"${cur}\" in",
+        "    --*)",
+        "      local flags=\"--json --output --runtime --policy --help\"",
+        "      COMPREPLY=( $(compgen -W \"${flags}\" -- \"${cur}\") )",
+        "      return 0",
+        "      ;;",
+        "    *)",
+        "      COMPREPLY=( $(compgen -W \"${commands}\" -- \"${cur}\") )",
+        "      return 0",
+        "      ;;",
+        "  esac",
+        "}",
+        "",
+        "complete -F _codex_plugin_doctor codex-plugin-doctor",
+        ""
+    ].join("\n");
+}
+function zshCompletion() {
+    return [
+        "#compdef codex-plugin-doctor",
+        "",
+        "_codex_plugin_doctor() {",
+        "  local context state line",
+        "  typeset -A opt_args",
+        "",
+        `  local commands=(${topLevelCommands.join(" ")})`,
+        "",
+        "  _arguments -C \\",
+        "    '1:command:(${commands})' \\",
+        "    '*--json[Output as JSON]' \\",
+        "    '*--output[Write to file]:file:_files' \\",
+        "    '*--runtime[Enable runtime probes]' \\",
+        "    '*--policy[Apply policy]:policy:(codex-publish mcp-strict security)'",
+        "}",
+        "",
+        "_codex_plugin_doctor \"$@\"",
+        ""
+    ].join("\n");
+}
+function fishCompletion() {
+    return [
+        "complete -c codex-plugin-doctor -f",
+        `complete -c codex-plugin-doctor -n "not __fish_seen_subcommand_from ${topLevelCommands.join(" ")}" -a "${topLevelCommands.join(" ")}"`,
+        "complete -c codex-plugin-doctor -s h -l help -d 'Show help'",
+        "complete -c codex-plugin-doctor -l json -d 'Output as JSON'",
+        "complete -c codex-plugin-doctor -l output -d 'Write to file' -r",
+        "complete -c codex-plugin-doctor -l runtime -d 'Enable runtime probes'",
+        "complete -c codex-plugin-doctor -l policy -d 'Apply policy' -x -a 'codex-publish mcp-strict security'",
+        ""
+    ].join("\n");
+}
+export function generateCompletion(shell) {
+    switch (shell) {
+        case "bash":
+            return bashCompletion();
+        case "zsh":
+            return zshCompletion();
+        case "fish":
+            return fishCompletion();
+    }
+}

package/dist/core/validation-baseline.d.ts

@@ -0,0 +1,17 @@
+import type { CheckResult, FindingSeverity } from "../domain/types.js";
+export interface ValidationBaselineFinding {
+    id: string;
+    severity: FindingSeverity;
+    fingerprint: string;
+}
+export interface ValidationBaseline {
+    schemaVersion: "1.0.0";
+    generatedAt: string;
+    findings: ValidationBaselineFinding[];
+}
+export declare function buildValidationBaseline(result: CheckResult): ValidationBaseline;
+export declare function writeValidationBaseline(baselinePath: string, baseline: ValidationBaseline): Promise<void>;
+export declare function readValidationBaseline(baselinePath: string): Promise<ValidationBaseline>;
+export declare function applyValidationBaseline(result: CheckResult, baseline: ValidationBaseline, options: {
+    failOnWarnings: boolean;
+}): CheckResult;

package/dist/core/validation-baseline.js

@@ -0,0 +1,83 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+const fingerprintPattern = /^[a-f0-9]{64}$/;
+export function buildValidationBaseline(result) {
+    const findings = new Map();
+    for (const finding of result.findings) {
+        if (finding.fingerprint && !findings.has(finding.fingerprint)) {
+            findings.set(finding.fingerprint, {
+                id: finding.id,
+                severity: finding.severity,
+                fingerprint: finding.fingerprint
+            });
+        }
+    }
+    return {
+        schemaVersion: "1.0.0",
+        generatedAt: new Date().toISOString(),
+        findings: [...findings.values()]
+    };
+}
+export async function writeValidationBaseline(baselinePath, baseline) {
+    const absolutePath = path.resolve(baselinePath);
+    await mkdir(path.dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, JSON.stringify(baseline, null, 2), "utf8");
+}
+export async function readValidationBaseline(baselinePath) {
+    const value = JSON.parse(await readFile(path.resolve(baselinePath), "utf8"));
+    if (!isValidationBaseline(value)) {
+        throw new Error("expected schemaVersion 1.0.0 and valid fingerprinted findings");
+    }
+    return value;
+}
+export function applyValidationBaseline(result, baseline, options) {
+    const baselineFingerprints = new Set(baseline.findings.map((finding) => finding.fingerprint));
+    const currentFingerprints = new Set(result.findings.flatMap((finding) => finding.fingerprint ? [finding.fingerprint] : []));
+    const baselinedFindings = [];
+    const findings = [];
+    for (const finding of result.findings) {
+        if (finding.fingerprint && baselineFingerprints.has(finding.fingerprint)) {
+            baselinedFindings.push(finding);
+        }
+        else {
+            findings.push(finding);
+        }
+    }
+    const hasFailures = findings.some((finding) => finding.severity === "fail");
+    const hasWarnings = findings.some((finding) => finding.severity === "warn");
+    const status = hasFailures || (options.failOnWarnings && hasWarnings)
+        ? "fail"
+        : hasWarnings
+            ? "warn"
+            : "pass";
+    return {
+        ...result,
+        status,
+        exitCode: status === "fail" ? 1 : 0,
+        findings,
+        baselinedFindings,
+        baselineSummary: {
+            matched: baselinedFindings.length,
+            new: findings.length,
+            resolved: baseline.findings.filter((finding) => !currentFingerprints.has(finding.fingerprint)).length
+        }
+    };
+}
+function isValidationBaseline(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const candidate = value;
+    return candidate.schemaVersion === "1.0.0"
+        && typeof candidate.generatedAt === "string"
+        && !Number.isNaN(Date.parse(candidate.generatedAt))
+        && Array.isArray(candidate.findings)
+        && candidate.findings.every((finding) => finding
+            && typeof finding.id === "string"
+            && finding.id.length > 0
+            && (finding.severity === "warn" || finding.severity === "fail")
+            && typeof finding.fingerprint === "string"
+            && fingerprintPattern.test(finding.fingerprint))
+        && new Set(candidate.findings.map((finding) => finding.fingerprint)).size
+            === candidate.findings.length;
+}

package/dist/domain/types.d.ts

@@ -30,6 +30,13 @@ export interface CheckResult {
     suppressedFindings?: SuppressedFinding[];
     suppressionSummary?: SuppressionSummary;
     runtimeScorecard?: RuntimeScorecard;
+    baselinedFindings?: Finding[];
+    baselineSummary?: BaselineSummary;
+}
+export interface BaselineSummary {
+    matched: number;
+    new: number;
+    resolved: number;
 }
 export interface CheckOptions {
     runtime?: boolean;
@@ -59,6 +66,7 @@ export interface JsonReportSummary {
         warn: number;
         total: number;
     };
+    baseline?: BaselineSummary;
 }
 export interface JsonReport {
     schemaVersion: "1.0.0";
@@ -67,6 +75,7 @@ export interface JsonReport {
     findings: Finding[];
     suppressedFindings?: SuppressedFinding[];
     suppressionSummary?: SuppressionSummary;
+    baselinedFindings?: Finding[];
 }
 export type RuntimeCapabilityStatus = "pass" | "fail" | "warn" | "skipped" | "unsupported";
 export interface RuntimeScorecard {

package/dist/index.d.ts

@@ -27,4 +27,6 @@ export { buildGenericMcpDoctor, renderGenericMcpDoctor, renderGenericMcpDoctorJs
 export { watchPlugin, type WatchPluginOptions, type WatchPluginResult } from "./core/watch-plugin.js";
 export { buildDepAudit, buildDepAuditRecommendations, renderDepAudit, renderDepAuditJson, renderDepAuditSarif, type DepAuditRecommendation, type DepAuditReport, type DepAuditVulnerability } from "./core/dep-audit.js";
 export { initGitHooks, removeGitHooks, type InitGitHooksResult, type RemoveGitHooksResult } from "./core/init-git-hooks.js";
+export { generateCompletion, type CompletionShell } from "./core/shell-completion.js";
+export { validateConfigFile, renderConfigValidation, renderConfigValidationJson, type ConfigValidationFinding, type ConfigValidationReport } from "./core/config-validate.js";
 export declare function runCheck(targetPath: string, options?: CheckOptions): Promise<CheckResult>;

package/dist/index.js

@@ -27,6 +27,8 @@ export { buildGenericMcpDoctor, renderGenericMcpDoctor, renderGenericMcpDoctorJs
 export { watchPlugin } from "./core/watch-plugin.js";
 export { buildDepAudit, buildDepAuditRecommendations, renderDepAudit, renderDepAuditJson, renderDepAuditSarif } from "./core/dep-audit.js";
 export { initGitHooks, removeGitHooks } from "./core/init-git-hooks.js";
+export { generateCompletion } from "./core/shell-completion.js";
+export { validateConfigFile, renderConfigValidation, renderConfigValidationJson } from "./core/config-validate.js";
 export async function runCheck(targetPath, options = {}) {
     return validatePlugin(targetPath, options);
 }

package/dist/reporting/render-json-report.js

@@ -16,7 +16,8 @@ export function buildJsonReport(result, options) {
                 fail: failCount,
                 warn: warnCount,
                 total: result.findings.length
-            }
+            },
+            ...(result.baselineSummary ? { baseline: result.baselineSummary } : {})
         },
         findings: result.findings,
         ...(result.suppressedFindings
@@ -24,6 +25,9 @@ export function buildJsonReport(result, options) {
             : {}),
         ...(result.suppressionSummary
             ? { suppressionSummary: result.suppressionSummary }
+            : {}),
+        ...(result.baselinedFindings
+            ? { baselinedFindings: result.baselinedFindings }
             : {})
     };
 }

package/dist/reporting/render-markdown-report.js

@@ -20,8 +20,11 @@ export function buildMarkdownReport(result, options) {
     if (result.suppressionSummary) {
         lines.push(`| Suppressions Applied | ${result.suppressionSummary.applied} |`, `| Suppressions Expired | ${result.suppressionSummary.expired} |`, `| Suppressions Invalid | ${result.suppressionSummary.invalid} |`);
     }
+    if (result.baselineSummary) {
+        lines.push(`| Baseline New | ${result.baselineSummary.new} |`, `| Baseline Matched | ${result.baselineSummary.matched} |`, `| Baseline Resolved | ${result.baselineSummary.resolved} |`);
+    }
     if (result.findings.length === 0 && !result.suppressedFindings?.length) {
-        lines.push("", "No findings.");
+        lines.push("", result.baselineSummary ? "No new findings." : "No findings.");
         return lines.join("\n");
     }
     if (result.runtimeScorecard) {

package/dist/reporting/render-text-report.js

@@ -39,6 +39,9 @@ export function renderTextReport(result, options = {}) {
     if (result.suppressionSummary) {
         lines.push(`Suppressions: ${result.suppressionSummary.applied} applied, ${result.suppressionSummary.expired} expired, ${result.suppressionSummary.invalid} invalid`);
     }
+    if (result.baselineSummary) {
+        lines.push(`Baseline: ${result.baselineSummary.new} new, ${result.baselineSummary.matched} matched, ${result.baselineSummary.resolved} resolved`);
+    }
     if (result.findings.length === 0 && !result.suppressedFindings?.length) {
         if (result.runtimeScorecard) {
             lines.push("", "Runtime Scorecard", "----------------");
@@ -51,7 +54,7 @@ export function renderTextReport(result, options = {}) {
             lines.push(`prompts/list: ${result.runtimeScorecard.promptsList}`);
             lines.push(`prompts/get: ${result.runtimeScorecard.promptGet}`);
         }
-        lines.push("", "No findings.");
+        lines.push("", result.baselineSummary ? "No new findings." : "No findings.");
         return lines.join("\n");
     }
     const failures = result.findings.filter((finding) => finding.severity === "fail");

package/dist/run-cli.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import { discoverInstalledPlugins, filterInstalledPlugins } from "./core/discover-installed-plugins.js";
 import { buildEcosystemAudit, renderEcosystemAudit, renderEcosystemAuditJson } from "./audit/ecosystem-audit.js";
 import { appendValidationHistoryEntry, readValidationHistory, summarizeValidationHistory } from "./core/validation-history.js";
+import { applyValidationBaseline, buildValidationBaseline, readValidationBaseline, writeValidationBaseline } from "./core/validation-baseline.js";
 import { buildCompatibilityMatrix, matrixExitCode } from "./compatibility/compatibility-matrix.js";
 import { applyInstallPreview, renderApplyInstallResult } from "./compatibility/apply-install-preview.js";
 import { buildClaudeDesktopInstallPreview, renderClaudeDesktopInstallPreview } from "./compatibility/claude-desktop-install-preview.js";
@@ -33,6 +34,8 @@ import { initCiWorkflow } from "./core/init-ci.js";
 import { watchPlugin } from "./core/watch-plugin.js";
 import { buildDepAudit, renderDepAudit, renderDepAuditJson, renderDepAuditSarif } from "./core/dep-audit.js";
 import { initGitHooks, removeGitHooks } from "./core/init-git-hooks.js";
+import { generateCompletion } from "./core/shell-completion.js";
+import { renderConfigValidation, renderConfigValidationJson, validateConfigFile } from "./core/config-validate.js";
 import { initPluginPackage, initPluginTemplates, isInitPluginTemplate } from "./core/init-plugin.js";
 import { runCheck } from "./index.js";
 import { buildGenericMcpDoctor, renderGenericMcpDoctor, renderGenericMcpDoctorJson } from "./mcp/generic-mcp-doctor.js";
@@ -78,8 +81,9 @@ const defaultIo = {
     }
 };
 function printUsage(io) {
-    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--policy codex-publish|mcp-strict|security] [--compat] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime] [--require-runtime-approval --runtime-approval-digest <digest>] [--verbose-runtime] [--explain] [--no-animations] [--ascii] [--changed-since <ref>]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor audit deps <path> [--policy codex-publish|mcp-strict|security] [--recommend] [--json|--sarif] [--output <path>]\n       codex-plugin-doctor mcp <path> [--json] [--output <path>]\n       codex-plugin-doctor security <path> [--policy security] [--json|--scorecard]\n       codex-plugin-doctor compat <path> [--all|--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor suppress add <path> [--fingerprint <sha256> --reason <text> --expires-at YYYY-MM-DD] [--config <path>] [--json]\n       codex-plugin-doctor suppress list <path> [--config <path>] [--json]\n       codex-plugin-doctor suppress remove <path> [--fingerprint <sha256>|--index <n>] [--config <path>] [--json]\n       codex-plugin-doctor fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor watch <path> [--runtime] [--json] [--output <path>] [--debounce-ms <ms>] [--max-iterations <n>] [--fail-fast] [--accumulate-json <path>]\n       codex-plugin-doctor doctor [npm <package>|contract|corpus|runtime-plan <path> [--json|--markdown] [--output <path>]|runtime-policy <path> [--json] [--output <path>]|review-bundle <path> --output <dir> --sign-key-env NAME [--json] [--allow-dirty] [--allow-untagged]|review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME [--json] [--output <path>] [--failures-only]|review-bundle diff --before <dir> --after <dir> [--json]|attest <path> [--sign-key-env NAME]|attest verify <attestation.json> --target <path> --sign-key-env NAME|release-evidence <path> --sign-key-env NAME [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>]|release-evidence verify <evidence.json> --target <path> --sign-key-env NAME|release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME [--upload]|mcp <path>|inspector <path>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path> [--max-total-ms <ms>] [--max-stage-ms stage=ms]|export --bundle <path>|snapshot|clients|--json|--update-check]\n       codex-plugin-doctor init [path] [--template skill-only|mcp-stdio|mcp-http|full-runtime]\n       codex-plugin-doctor init-ci [path]\n       codex-plugin-doctor init-git-hooks [path] [--force] [--json]\n       codex-plugin-doctor init-git-hooks [path] --remove [--json]\n       codex-plugin-doctor self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version\n\nFirst run:\n       codex-plugin-doctor doctor\n       codex-plugin-doctor self-test\n       codex-plugin-doctor init my-plugin\n       codex-plugin-doctor check . --runtime --explain");
+    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--policy codex-publish|mcp-strict|security] [--compat] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime] [--require-runtime-approval --runtime-approval-digest <digest>] [--verbose-runtime] [--explain] [--no-animations] [--ascii] [--changed-since <ref>]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor audit deps <path> [--policy codex-publish|mcp-strict|security] [--recommend] [--json|--sarif] [--output <path>]\n       codex-plugin-doctor mcp <path> [--json] [--output <path>]\n       codex-plugin-doctor security <path> [--policy security] [--json|--scorecard]\n       codex-plugin-doctor compat <path> [--all|--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor suppress add <path> [--fingerprint <sha256> --reason <text> --expires-at YYYY-MM-DD] [--config <path>] [--json]\n       codex-plugin-doctor suppress list <path> [--config <path>] [--json]\n       codex-plugin-doctor suppress remove <path> [--fingerprint <sha256>|--index <n>] [--config <path>] [--json]\n       codex-plugin-doctor fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor watch <path> [--runtime] [--json] [--output <path>] [--debounce-ms <ms>] [--max-iterations <n>] [--fail-fast] [--accumulate-json <path>]\n       codex-plugin-doctor doctor [npm <package>|contract|corpus|runtime-plan <path> [--json|--markdown] [--output <path>]|runtime-policy <path> [--json] [--output <path>]|review-bundle <path> --output <dir> --sign-key-env NAME [--json] [--allow-dirty] [--allow-untagged]|review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME [--json] [--output <path>] [--failures-only]|review-bundle diff --before <dir> --after <dir> [--json]|attest <path> [--sign-key-env NAME]|attest verify <attestation.json> --target <path> --sign-key-env NAME|release-evidence <path> --sign-key-env NAME [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>]|release-evidence verify <evidence.json> --target <path> --sign-key-env NAME|release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME [--upload]|mcp <path>|inspector <path>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path> [--max-total-ms <ms>] [--max-stage-ms stage=ms]|export --bundle <path>|snapshot|clients|--json|--update-check]\n       codex-plugin-doctor init [path] [--template skill-only|mcp-stdio|mcp-http|full-runtime]\n       codex-plugin-doctor init-ci [path]\n       codex-plugin-doctor init-git-hooks [path] [--force] [--json]\n       codex-plugin-doctor init-git-hooks [path] --remove [--json]\n       codex-plugin-doctor completion bash|zsh|fish\n       codex-plugin-doctor config validate <path> [--json]\n       codex-plugin-doctor self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version\n\nFirst run:\n       codex-plugin-doctor doctor\n       codex-plugin-doctor self-test\n       codex-plugin-doctor init my-plugin\n       codex-plugin-doctor check . --runtime --explain");
     io.writeStderr("Suppression governance: codex-plugin-doctor suppress list <path> [--fail-on-expired] [--fail-on-invalid] [--warn-expiring-within-days <days>]\n       codex-plugin-doctor suppress prune <path> [--apply] [--json]");
+    io.writeStderr("Baseline gating: codex-plugin-doctor baseline create <path> --output <path> [--runtime]\n       codex-plugin-doctor check <path> --baseline <path>");
 }
 const suppressUsageText = [
     "Usage:",
@@ -817,6 +821,31 @@ export async function runCli(args, io = defaultIo, options = {}) {
         io.writeStdout(renderInstalledPlugins(installedPlugins));
         return 0;
     }
+    if (command === "baseline") {
+        if (maybePath !== "create") {
+            io.writeStderr("Usage: codex-plugin-doctor baseline create <path> --output <path> [--runtime]");
+            return 2;
+        }
+        const targetPath = remainingArgs[0];
+        const baselineFlags = remainingArgs.slice(1);
+        const outputIndex = baselineFlags.indexOf("--output");
+        const outputPath = outputIndex === -1 ? null : baselineFlags[outputIndex + 1];
+        if (!targetPath || targetPath.startsWith("--")) {
+            io.writeStderr("Missing target path for baseline create.");
+            return 2;
+        }
+        if (!outputPath || outputPath.startsWith("--")) {
+            io.writeStderr("baseline create requires --output <path>.");
+            return 2;
+        }
+        const result = await (options.runCheckImpl ?? runCheck)(targetPath, {
+            runtime: baselineFlags.includes("--runtime")
+        });
+        const baseline = buildValidationBaseline(result);
+        await writeValidationBaseline(outputPath, baseline);
+        io.writeStdout(`Baseline created: ${path.resolve(outputPath)}\nFindings: ${baseline.findings.length}`);
+        return 0;
+    }
     if (command === "doctor") {
         const doctorFlags = maybePath?.startsWith("--")
             ? [maybePath, ...remainingArgs]
@@ -2193,6 +2222,33 @@ export async function runCli(args, io = defaultIo, options = {}) {
         io.writeStdout(report);
         return matrixExitCode(matrix);
     }
+    if (command === "completion") {
+        const shell = maybePath;
+        if (!shell || !["bash", "zsh", "fish"].includes(shell)) {
+            io.writeStderr("Usage: codex-plugin-doctor completion bash|zsh|fish");
+            return 2;
+        }
+        io.writeStdout(generateCompletion(shell));
+        return 0;
+    }
+    if (command === "config") {
+        const subCommand = maybePath;
+        if (subCommand !== "validate") {
+            io.writeStderr("Usage: codex-plugin-doctor config validate <path> [--json]");
+            return 2;
+        }
+        const configPath = remainingArgs[0] && !remainingArgs[0].startsWith("--") ? remainingArgs[0] : ".codex-doctor.json";
+        const configFlags = remainingArgs[0] && remainingArgs[0].startsWith("--")
+            ? remainingArgs
+            : remainingArgs.slice(1);
+        const jsonOutput = configFlags.includes("--json");
+        const report = await validateConfigFile(configPath);
+        const output = jsonOutput
+            ? renderConfigValidationJson(report)
+            : renderConfigValidation(report);
+        io.writeStdout(output);
+        return report.status === "fail" ? 1 : 0;
+    }
     if (command === "suppress") {
         const parsedSuppressCommand = parseSuppressCommand([maybePath ?? "", ...remainingArgs]);
         if ("message" in parsedSuppressCommand) {
@@ -2256,6 +2312,8 @@ export async function runCli(args, io = defaultIo, options = {}) {
         : normalizedFlags[runtimeApprovalDigestIndex + 1];
     const changedSinceIndex = normalizedFlags.indexOf("--changed-since");
     const changedSinceRef = changedSinceIndex === -1 ? null : normalizedFlags[changedSinceIndex + 1];
+    const baselineIndex = normalizedFlags.indexOf("--baseline");
+    const baselinePath = baselineIndex === -1 ? null : normalizedFlags[baselineIndex + 1];
     if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
         io.writeStderr("Missing path after --output.");
         return 2;
@@ -2292,6 +2350,18 @@ export async function runCli(args, io = defaultIo, options = {}) {
         io.writeStderr("--changed-since requires a single package target.");
         return 2;
     }
+    if (baselineIndex !== -1 && (!baselinePath || baselinePath.startsWith("--"))) {
+        io.writeStderr("Missing path after --baseline.");
+        return 2;
+    }
+    if (baselinePath && checkInstalled) {
+        io.writeStderr("Baseline gating requires a single package target.");
+        return 2;
+    }
+    if (baselinePath && changedSinceRef) {
+        io.writeStderr("Use either --baseline or --changed-since, not both.");
+        return 2;
+    }
     if (runtimeApprovalDigestIndex !== -1 &&
         (!runtimeApprovalDigest || runtimeApprovalDigest.startsWith("--"))) {
         io.writeStderr("Missing digest after --runtime-approval-digest.");
@@ -2316,6 +2386,16 @@ export async function runCli(args, io = defaultIo, options = {}) {
         io.writeStderr("Runtime approval gating requires a single package target, not --installed.");
         return 2;
     }
+    let baseline = null;
+    if (baselinePath) {
+        try {
+            baseline = await readValidationBaseline(baselinePath);
+        }
+        catch (error) {
+            io.writeStderr(`Invalid baseline file: ${error.message}`);
+            return 2;
+        }
+    }
     const outputPolicy = determineOutputPolicy({
         jsonOutput: jsonOutput || badgeJsonOutput,
         markdownOutput: markdownOutput || badgeMarkdownOutput,
@@ -2447,12 +2527,18 @@ export async function runCli(args, io = defaultIo, options = {}) {
             return 2;
         }
     }
-    const result = applyDoctorConfig(await runCheckImpl(targetPath, {
+    const doctorConfig = applyPolicyToDoctorConfig(applyCheckProfile(await loadDoctorConfig(targetPath, configPath), checkProfile), policy);
+    const configuredResult = applyDoctorConfig(await runCheckImpl(targetPath, {
         runtime: effectiveRuntimeProbeEnabled,
         runtimeTranscript: effectiveRuntimeProbeEnabled && verboseRuntime
             ? (line) => io.writeStderr(line)
             : undefined
-    }), applyPolicyToDoctorConfig(applyCheckProfile(await loadDoctorConfig(targetPath, configPath), checkProfile), policy));
+    }), doctorConfig);
+    const result = baseline
+        ? applyValidationBaseline(configuredResult, baseline, {
+            failOnWarnings: doctorConfig.failOnWarnings
+        })
+        : configuredResult;
     if (renderer) {
         if (result.status === "fail") {
             renderer.stopFailure("Validation failed");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-plugin-doctor",
-  "version": "1.43.0",
+  "version": "1.45.0",
   "description": "CLI-first validator for Codex plugins, skills, and MCP package surfaces with runtime MCP protocol validation.",
   "type": "module",
   "main": "./dist/index.js",