codex-plugin-doctor 1.25.0 → 1.27.0

package/README.md

@@ -314,7 +314,7 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
 
 `init [path] --template ...` creates targeted starter packages. `skill-only` is the default minimal skill package, `mcp-stdio` adds a local stdio MCP config and mock server, `mcp-http` scaffolds a streamable HTTP MCP config, and `full-runtime` generates a stdio sample that passes the runtime protocol probes.
 
-`security <path>` renders a focused package security scorecard. It reuses the existing package security findings, then adds deeper MCP command-surface checks for shell wrappers, encoded shell payloads, remote pipe-to-shell startup patterns, `cwd` values outside the plugin root, and plain HTTP URLs. Security findings include structured evidence where available, such as server names, config paths, env keys, arg flags, and escaped paths. Findings also include deterministic SHA-256 fingerprints derived from the rule ID and canonical evidence, with package paths normalized for cross-machine stability. Use `--json` for automation or `--scorecard` for a compact status view.
+`security <path>` renders a focused package security scorecard. It reuses the existing package security findings, then adds deeper MCP command-surface checks for shell wrappers, encoded shell payloads, remote pipe-to-shell startup patterns, `cwd` values outside the plugin root, and plain HTTP URLs. Findings include structured, instance-specific evidence such as manifest fields, skill paths, server names, protocol methods, dependency sections, env keys, and bounded payload lengths. Deterministic SHA-256 fingerprints derive from the rule ID and canonical evidence, with package paths normalized for cross-machine stability. Secrets, prompt bodies, resource contents, tool payloads, stderr, and encoded commands are not copied into evidence. Use `--json` for automation or `--scorecard` for a compact status view.
 
 `compat --client claude-desktop` checks whether the MCP package can be added to the local Claude Desktop setup. On Windows it looks for `%APPDATA%\Claude\claude_desktop_config.json`; on macOS it looks for `~/Library/Application Support/Claude/claude_desktop_config.json`. A valid existing config returns `PASS`, a missing Claude Desktop install returns `WARN`, and a malformed local config returns `FAIL` so you do not add new servers into a broken config file. If the package server name already exists in Claude Desktop, the command returns `WARN` with the duplicate server name. Add `--install-preview` to print the JSON snippet that should be merged into `claude_desktop_config.json`; it does not modify files. Use `--apply --backup` only when you want the CLI to create a timestamped backup and merge the server config. Apply mode refuses to overwrite duplicate server names.
 
@@ -336,16 +336,27 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
 
 `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:
-
-```json
-{
-  "ignoreRules": ["plugin.heuristic.description.too_long"],
-  "failOnWarnings": true
-}
-```
-
-Run these when you want Codex Plugin Doctor to find plugins from the local Codex installation:
+Optional local policy file:
+
+```json
+{
+  "ignoreRules": ["plugin.heuristic.description.too_long"],
+  "suppressions": [
+    {
+      "fingerprint": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+      "reason": "Accepted until the upstream package layout is corrected.",
+      "expiresAt": "2026-07-31"
+    }
+  ],
+  "failOnWarnings": true
+}
+```
+
+`ignoreRules` disables every finding with a matching rule ID. Prefer `suppressions` when accepting one specific finding instance: each record requires the exact 64-character lowercase SHA-256 fingerprint shown in Doctor reports, a non-empty review reason, and a real `YYYY-MM-DD` expiration date.
+
+Active suppressions remove only the matching finding from the active result and preserve it under `suppressedFindings` for audit output. Expired or invalid records do not suppress findings; Doctor emits `suppression.expired` or `suppression.invalid` warnings instead. Duplicate active records use the first valid match.
+
+Run these when you want Codex Plugin Doctor to find plugins from the local Codex installation:
 
 ```bash
 codex-plugin-doctor list --installed
@@ -370,9 +381,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.25.0
+      - uses: Esquetta/CodexPluginDoctor@v1.27.0
         with:
-          version: "1.25.0"
+          version: "1.27.0"
           path: .
           runtime: "true"
           policy: codex-publish

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

@@ -2,6 +2,9 @@ import type { CheckResult } from "../domain/types.js";
 export interface DoctorConfig {
     ignoreRules: string[];
     failOnWarnings: boolean;
+    suppressions: unknown[];
 }
 export declare function loadDoctorConfig(targetPath: string, explicitConfigPath?: string | null): Promise<DoctorConfig>;
-export declare function applyDoctorConfig(result: CheckResult, config: DoctorConfig): CheckResult;
+export declare function applyDoctorConfig(result: CheckResult, config: DoctorConfig, options?: {
+    now?: Date;
+}): CheckResult;

package/dist/core/doctor-config.js

@@ -1,8 +1,10 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { withFindingFingerprint } from "../reporting/finding-fingerprint.js";
 const defaultConfig = {
     ignoreRules: [],
-    failOnWarnings: false
+    failOnWarnings: false,
+    suppressions: []
 };
 function isStringArray(value) {
     return Array.isArray(value) && value.every((item) => typeof item === "string");
@@ -19,15 +21,69 @@ export async function loadDoctorConfig(targetPath, explicitConfigPath) {
                 : defaultConfig.ignoreRules,
             failOnWarnings: typeof parsed.failOnWarnings === "boolean"
                 ? parsed.failOnWarnings
-                : defaultConfig.failOnWarnings
+                : defaultConfig.failOnWarnings,
+            suppressions: Array.isArray(parsed.suppressions)
+                ? parsed.suppressions
+                : defaultConfig.suppressions
         };
     }
     catch {
         return defaultConfig;
     }
 }
-export function applyDoctorConfig(result, config) {
-    const findings = result.findings.filter((finding) => !config.ignoreRules.includes(finding.id));
+export function applyDoctorConfig(result, config, options = {}) {
+    const configuredFindings = result.findings.filter((finding) => !config.ignoreRules.includes(finding.id));
+    const now = options.now ?? new Date();
+    const activeSuppressions = new Map();
+    const governanceWarnings = [];
+    const summary = {
+        applied: 0,
+        expired: 0,
+        invalid: 0
+    };
+    for (const [index, suppression] of config.suppressions.entries()) {
+        const validation = validateSuppression(suppression);
+        if (!validation.valid) {
+            summary.invalid += 1;
+            governanceWarnings.push(buildGovernanceWarning(result.targetPath, "suppression.invalid", "A targeted suppression record is invalid and was not applied.", "Invalid suppression records can create false confidence because they do not match or expire as intended.", "Fix or remove the invalid suppression record in `.codex-doctor.json`.", {
+                suppressionIndex: index,
+                field: validation.field
+            }));
+            continue;
+        }
+        if (isExpired(validation.expiresAt, now)) {
+            summary.expired += 1;
+            governanceWarnings.push(buildGovernanceWarning(result.targetPath, "suppression.expired", "A targeted suppression has expired and was not applied.", "Expired risk acceptance must be reviewed again before the finding can be suppressed.", "Remove the expired suppression or replace it with a newly reviewed expiration date.", {
+                suppressionIndex: index,
+                fingerprint: validation.fingerprint,
+                expiresAt: validation.expiresAt
+            }));
+            continue;
+        }
+        if (!activeSuppressions.has(validation.fingerprint)) {
+            activeSuppressions.set(validation.fingerprint, {
+                reason: validation.reason,
+                expiresAt: validation.expiresAt
+            });
+        }
+    }
+    const findings = [];
+    const suppressedFindings = [];
+    for (const finding of configuredFindings) {
+        const suppression = finding.fingerprint
+            ? activeSuppressions.get(finding.fingerprint)
+            : undefined;
+        if (!suppression) {
+            findings.push(finding);
+            continue;
+        }
+        summary.applied += 1;
+        suppressedFindings.push({
+            ...finding,
+            suppression
+        });
+    }
+    findings.push(...governanceWarnings);
     const hasFailures = findings.some((finding) => finding.severity === "fail");
     const hasWarnings = findings.some((finding) => finding.severity === "warn");
     const warningFailure = config.failOnWarnings && hasWarnings;
@@ -40,6 +96,63 @@ export function applyDoctorConfig(result, config) {
         ...result,
         status,
         exitCode: status === "fail" ? 1 : 0,
-        findings
+        findings,
+        ...(config.suppressions.length > 0
+            ? {
+                suppressedFindings,
+                suppressionSummary: summary
+            }
+            : {})
     };
 }
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isRealDate(value) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+    if (!match) {
+        return false;
+    }
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const date = new Date(Date.UTC(year, month - 1, day));
+    return (date.getUTCFullYear() === year &&
+        date.getUTCMonth() === month - 1 &&
+        date.getUTCDate() === day);
+}
+function validateSuppression(value) {
+    if (!isPlainObject(value)) {
+        return { valid: false, field: "record" };
+    }
+    if (typeof value.fingerprint !== "string" ||
+        !/^[a-f0-9]{64}$/.test(value.fingerprint)) {
+        return { valid: false, field: "fingerprint" };
+    }
+    if (typeof value.reason !== "string" || value.reason.trim().length === 0) {
+        return { valid: false, field: "reason" };
+    }
+    if (typeof value.expiresAt !== "string" || !isRealDate(value.expiresAt)) {
+        return { valid: false, field: "expiresAt" };
+    }
+    return {
+        valid: true,
+        fingerprint: value.fingerprint,
+        reason: value.reason.trim(),
+        expiresAt: value.expiresAt
+    };
+}
+function isExpired(expiresAt, now) {
+    const expirationBoundary = Date.parse(`${expiresAt}T00:00:00.000Z`) + 86_400_000;
+    return now.getTime() >= expirationBoundary;
+}
+function buildGovernanceWarning(targetPath, id, message, impact, suggestedFix, evidence) {
+    return withFindingFingerprint({
+        id,
+        severity: "warn",
+        message,
+        impact,
+        suggestedFix,
+        evidence
+    }, targetPath);
+}

package/dist/core/runtime-probe.js

@@ -21,22 +21,55 @@ function createRuntimeScorecard() {
         promptGet: "unsupported"
     };
 }
-function buildFailure(id, message, impact, suggestedFix) {
+function buildFailure(id, message, impact, suggestedFix, evidence) {
     return {
         id,
         severity: "fail",
         message,
         impact,
-        suggestedFix
+        suggestedFix,
+        ...(evidence ? { evidence } : {})
     };
 }
-function buildWarning(id, message, impact, suggestedFix) {
+function buildWarning(id, message, impact, suggestedFix, evidence) {
     return {
         id,
         severity: "warn",
         message,
         impact,
-        suggestedFix
+        suggestedFix,
+        ...(evidence ? { evidence } : {})
+    };
+}
+function methodForRuntimeFinding(id) {
+    if (id.includes(".initialize."))
+        return "initialize";
+    if (id.includes(".tools_list."))
+        return "tools/list";
+    if (id.includes(".tool_call."))
+        return "tools/call";
+    if (id.includes(".resources_list."))
+        return "resources/list";
+    if (id.includes(".resource_read."))
+        return "resources/read";
+    if (id.includes(".resource_templates_list."))
+        return "resources/templates/list";
+    if (id.includes(".prompts_list."))
+        return "prompts/list";
+    if (id.includes(".prompt_get."))
+        return "prompts/get";
+    if (id.includes(".startup.") || id.includes(".exited_early"))
+        return "startup";
+    return "protocol";
+}
+function withRuntimeEvidence(finding, serverName) {
+    return {
+        ...finding,
+        evidence: {
+            serverName,
+            method: methodForRuntimeFinding(finding.id),
+            ...(finding.evidence ?? {})
+        }
     };
 }
 function isPlainObject(value) {
@@ -511,55 +544,56 @@ function getContentBlockLength(content) {
     }
     return 0;
 }
-function collectOversizedToolCallWarnings(message) {
+function collectOversizedToolCallWarnings(message, evidence) {
     if (!isPlainObject(message.result) || !Array.isArray(message.result.content)) {
         return [];
     }
-    const hasOversizedContent = message.result.content.some((content) => {
-        return isPlainObject(content) && getContentBlockLength(content) > MAX_TOOL_CALL_CONTENT_LENGTH;
-    });
-    if (!hasOversizedContent) {
+    const contentLength = message.result.content.reduce((maximum, content) => {
+        return isPlainObject(content)
+            ? Math.max(maximum, getContentBlockLength(content))
+            : maximum;
+    }, 0);
+    if (contentLength <= MAX_TOOL_CALL_CONTENT_LENGTH) {
         return [];
     }
     return [
-        buildWarning("plugin.runtime.tool_call.content_too_large", "The tools/call response contains unusually large content payloads.", "Large tool call payloads increase runtime cost, transcript size, and the risk of degraded model performance.", "Keep tool responses concise or move large payloads into resource references instead of inline content.")
+        buildWarning("plugin.runtime.tool_call.content_too_large", "The tools/call response contains unusually large content payloads.", "Large tool call payloads increase runtime cost, transcript size, and the risk of degraded model performance.", "Keep tool responses concise or move large payloads into resource references instead of inline content.", { ...evidence, contentLength })
     ];
 }
-function collectOversizedResourceReadWarnings(message) {
+function collectOversizedResourceReadWarnings(message, evidence) {
     if (!isPlainObject(message.result) || !Array.isArray(message.result.contents)) {
         return [];
     }
-    const hasOversizedContent = message.result.contents.some((content) => {
+    const contentLength = message.result.contents.reduce((maximum, content) => {
         if (!isPlainObject(content)) {
-            return false;
+            return maximum;
         }
         const textLength = typeof content.text === "string" ? content.text.length : 0;
         const blobLength = typeof content.blob === "string" ? content.blob.length : 0;
-        return (textLength > MAX_RESOURCE_READ_CONTENT_LENGTH ||
-            blobLength > MAX_RESOURCE_READ_CONTENT_LENGTH);
-    });
-    if (!hasOversizedContent) {
+        return Math.max(maximum, textLength, blobLength);
+    }, 0);
+    if (contentLength <= MAX_RESOURCE_READ_CONTENT_LENGTH) {
         return [];
     }
     return [
-        buildWarning("plugin.runtime.resource_read.content_too_large", "The resources/read response contains unusually large resource payloads.", "Large resource contents increase runtime cost and can make downstream model use less reliable.", "Reduce inline resource size or break large resources into smaller references.")
+        buildWarning("plugin.runtime.resource_read.content_too_large", "The resources/read response contains unusually large resource payloads.", "Large resource contents increase runtime cost and can make downstream model use less reliable.", "Reduce inline resource size or break large resources into smaller references.", { ...evidence, contentLength })
     ];
 }
-function collectOversizedPromptGetWarnings(message) {
+function collectOversizedPromptGetWarnings(message, evidence) {
     if (!isPlainObject(message.result) || !Array.isArray(message.result.messages)) {
         return [];
     }
-    const hasOversizedContent = message.result.messages.some((promptMessage) => {
+    const contentLength = message.result.messages.reduce((maximum, promptMessage) => {
         if (!isPlainObject(promptMessage) || !isPlainObject(promptMessage.content)) {
-            return false;
+            return maximum;
         }
-        return getContentBlockLength(promptMessage.content) > MAX_PROMPT_GET_CONTENT_LENGTH;
-    });
-    if (!hasOversizedContent) {
+        return Math.max(maximum, getContentBlockLength(promptMessage.content));
+    }, 0);
+    if (contentLength <= MAX_PROMPT_GET_CONTENT_LENGTH) {
         return [];
     }
     return [
-        buildWarning("plugin.runtime.prompt_get.content_too_large", "The prompts/get response contains unusually large prompt message payloads.", "Large prompt bodies increase token cost and reduce the usefulness of prompt probing as a lightweight validation step.", "Keep prompt message content concise or move large context into resources.")
+        buildWarning("plugin.runtime.prompt_get.content_too_large", "The prompts/get response contains unusually large prompt message payloads.", "Large prompt bodies increase token cost and reduce the usefulness of prompt probing as a lightweight validation step.", "Keep prompt message content concise or move large context into resources.", { ...evidence, contentLength })
     ];
 }
 async function probeCommandServer(input) {
@@ -596,7 +630,10 @@ async function probeCommandServer(input) {
                 child.kill("SIGTERM");
             }
             resolve({
-                findings: [...warnings, ...(finding ? [finding] : [])],
+                findings: [
+                    ...warnings.map((warning) => withRuntimeEvidence(warning, serverName)),
+                    ...(finding ? [withRuntimeEvidence(finding, serverName)] : [])
+                ],
                 scorecard
             });
         };
@@ -752,14 +789,16 @@ async function probeCommandServer(input) {
                 const toolCallResponse = await sendRequest("tools/call", {
                     name: callableTool.tool.name,
                     arguments: callableTool.args
-                }, buildFailure("plugin.runtime.tool_call.timeout", `The MCP server \`${serverName}\` did not answer the tools/call request in time.`, "A server that cannot complete a basic tool invocation in time will feel broken in real Codex usage.", "Inspect the selected tool implementation and reduce its response latency."));
+                }, buildFailure("plugin.runtime.tool_call.timeout", `The MCP server \`${serverName}\` did not answer the tools/call request in time.`, "A server that cannot complete a basic tool invocation in time will feel broken in real Codex usage.", "Inspect the selected tool implementation and reduce its response latency.", { toolName: callableTool.tool.name }));
                 if (isErrorResponse(toolCallResponse) || !isValidCallToolResult(toolCallResponse)) {
                     scorecard.toolsCall = "fail";
-                    settle(buildFailure("plugin.runtime.tool_call.invalid", `The MCP server \`${serverName}\` returned an invalid tools/call result.`, "Codex cannot safely consume malformed tool call results from the server.", "Return a CallToolResult with a `content` array containing valid MCP content blocks."));
+                    settle(buildFailure("plugin.runtime.tool_call.invalid", `The MCP server \`${serverName}\` returned an invalid tools/call result.`, "Codex cannot safely consume malformed tool call results from the server.", "Return a CallToolResult with a `content` array containing valid MCP content blocks.", { toolName: callableTool.tool.name }));
                     return;
                 }
                 scorecard.toolsCall = "pass";
-                warnings.push(...collectOversizedToolCallWarnings(toolCallResponse));
+                warnings.push(...collectOversizedToolCallWarnings(toolCallResponse, {
+                    toolName: callableTool.tool.name
+                }));
             }
             if (!hasResourcesCapability(initializeResponse)) {
                 scorecard.resourcesList = "unsupported";
@@ -781,15 +820,17 @@ async function probeCommandServer(input) {
                 if (resources.length > 0) {
                     const resourceReadResponse = await sendRequest("resources/read", {
                         uri: resources[0].uri
-                    }, buildFailure("plugin.runtime.resource_read.timeout", `The MCP server \`${serverName}\` did not answer the resources/read request in time.`, "A server that lists resources but cannot read them in time will feel broken in Codex.", "Inspect the resource read path and reduce latency before returning resource contents."));
+                    }, buildFailure("plugin.runtime.resource_read.timeout", `The MCP server \`${serverName}\` did not answer the resources/read request in time.`, "A server that lists resources but cannot read them in time will feel broken in Codex.", "Inspect the resource read path and reduce latency before returning resource contents.", { resourceUri: resources[0].uri }));
                     if (isErrorResponse(resourceReadResponse) ||
                         !isValidReadResourceResult(resourceReadResponse)) {
                         scorecard.resourceRead = "fail";
-                        settle(buildFailure("plugin.runtime.resource_read.invalid", `The MCP server \`${serverName}\` returned an invalid resources/read result.`, "Codex cannot safely consume malformed resource contents from `resources/read`.", "Return a `contents` array where each entry has a string `uri` plus either string `text` or string `blob`."));
+                        settle(buildFailure("plugin.runtime.resource_read.invalid", `The MCP server \`${serverName}\` returned an invalid resources/read result.`, "Codex cannot safely consume malformed resource contents from `resources/read`.", "Return a `contents` array where each entry has a string `uri` plus either string `text` or string `blob`.", { resourceUri: resources[0].uri }));
                         return;
                     }
                     scorecard.resourceRead = "pass";
-                    warnings.push(...collectOversizedResourceReadWarnings(resourceReadResponse));
+                    warnings.push(...collectOversizedResourceReadWarnings(resourceReadResponse, {
+                        resourceUri: resources[0].uri
+                    }));
                 }
                 else {
                     scorecard.resourceRead = "skipped";
@@ -842,15 +883,17 @@ async function probeCommandServer(input) {
                         ...(buildPromptArguments(promptForGet)
                             ? { arguments: buildPromptArguments(promptForGet) }
                             : {})
-                    }, buildFailure("plugin.runtime.prompt_get.timeout", `The MCP server \`${serverName}\` did not answer the prompts/get request in time.`, "A server that lists prompts but cannot return prompt content in time will feel broken in Codex.", "Inspect the prompt retrieval path and reduce latency before returning prompt messages."));
+                    }, buildFailure("plugin.runtime.prompt_get.timeout", `The MCP server \`${serverName}\` did not answer the prompts/get request in time.`, "A server that lists prompts but cannot return prompt content in time will feel broken in Codex.", "Inspect the prompt retrieval path and reduce latency before returning prompt messages.", { promptName: promptForGet.name }));
                     if (isErrorResponse(promptGetResponse) ||
                         !isValidPromptGetResult(promptGetResponse)) {
                         scorecard.promptGet = "fail";
-                        settle(buildFailure("plugin.runtime.prompt_get.invalid", `The MCP server \`${serverName}\` returned an invalid prompts/get result.`, "Codex cannot safely consume malformed prompt messages from `prompts/get`.", "Return a `messages` array where each entry has a valid `role` and a valid MCP content block."));
+                        settle(buildFailure("plugin.runtime.prompt_get.invalid", `The MCP server \`${serverName}\` returned an invalid prompts/get result.`, "Codex cannot safely consume malformed prompt messages from `prompts/get`.", "Return a `messages` array where each entry has a valid `role` and a valid MCP content block.", { promptName: promptForGet.name }));
                         return;
                     }
                     scorecard.promptGet = "pass";
-                    warnings.push(...collectOversizedPromptGetWarnings(promptGetResponse));
+                    warnings.push(...collectOversizedPromptGetWarnings(promptGetResponse, {
+                        promptName: promptForGet.name
+                    }));
                 }
             }
             settle(null);

package/dist/core/validate-plugin.js

@@ -193,19 +193,20 @@ function isDescriptionLikelyVerbose(description, mode) {
 }
 function validateRequiredManifestFields(discoveredPackage) {
     const findings = [];
-    const { manifest } = discoveredPackage;
+    const { manifest, rootPath } = discoveredPackage;
+    const manifestPath = relativePackagePath(rootPath, discoveredPackage.manifestPath);
     if (!manifest.name) {
-        findings.push(buildFailure("plugin.manifest.name.missing", "The plugin manifest is missing a `name` field.", "Codex cannot identify the plugin reliably without a stable package name.", "Add a kebab-case `name` field to `.codex-plugin/plugin.json`."));
+        findings.push(buildFailure("plugin.manifest.name.missing", "The plugin manifest is missing a `name` field.", "Codex cannot identify the plugin reliably without a stable package name.", "Add a kebab-case `name` field to `.codex-plugin/plugin.json`.", { manifestPath, field: "name" }));
     }
     if (!manifest.version) {
-        findings.push(buildFailure("plugin.manifest.version.missing", "The plugin manifest is missing a `version` field.", "Release and compatibility workflows cannot reason about the package version.", "Add a semantic `version` field to `.codex-plugin/plugin.json`."));
+        findings.push(buildFailure("plugin.manifest.version.missing", "The plugin manifest is missing a `version` field.", "Release and compatibility workflows cannot reason about the package version.", "Add a semantic `version` field to `.codex-plugin/plugin.json`.", { manifestPath, field: "version" }));
     }
     if (!manifest.description) {
-        findings.push(buildFailure("plugin.manifest.description.missing", "The plugin manifest is missing a `description` field.", "The package will be harder to understand and present in Codex surfaces.", "Add a concise `description` field to `.codex-plugin/plugin.json`."));
+        findings.push(buildFailure("plugin.manifest.description.missing", "The plugin manifest is missing a `description` field.", "The package will be harder to understand and present in Codex surfaces.", "Add a concise `description` field to `.codex-plugin/plugin.json`.", { manifestPath, field: "description" }));
     }
     if (manifest.description &&
         isDescriptionLikelyVerbose(manifest.description, "plugin")) {
-        findings.push(buildWarning("plugin.heuristic.description.too_long", "The plugin manifest description is likely too verbose.", "Overly long metadata increases context cost and can dilute plugin discovery quality.", "Shorten the manifest description to a precise one- or two-sentence summary."));
+        findings.push(buildWarning("plugin.heuristic.description.too_long", "The plugin manifest description is likely too verbose.", "Overly long metadata increases context cost and can dilute plugin discovery quality.", "Shorten the manifest description to a precise one- or two-sentence summary.", { manifestPath, field: "description" }));
     }
     return findings;
 }
@@ -230,7 +231,12 @@ async function validateSkillsDirectory(discoveredPackage) {
         return [];
     }
     return [
-        buildFailure("plugin.skills.path.missing", "The plugin manifest points to a missing skills directory.", "Codex will not be able to load the packaged skills as expected.", `Create the skills directory at \`${skillsPath}\` or update the manifest path.`)
+        buildFailure("plugin.skills.path.missing", "The plugin manifest points to a missing skills directory.", "Codex will not be able to load the packaged skills as expected.", `Create the skills directory at \`${skillsPath}\` or update the manifest path.`, {
+            manifestPath: relativePackagePath(rootPath, discoveredPackage.manifestPath),
+            field: "skills",
+            configuredPath: manifest.skills,
+            resolvedPath: skillsPath
+        })
     ];
 }
 async function validateSkillDefinitions(discoveredPackage) {
@@ -254,27 +260,47 @@ async function validateSkillDefinitions(discoveredPackage) {
         const skillFilePath = path.join(skillRoot, "SKILL.md");
         const skillFileExists = await fileExists(skillFilePath);
         if (!skillFileExists) {
-            findings.push(buildFailure("plugin.skill.skill_md.missing", `The skill \`${skillDirectory.name}\` is missing \`SKILL.md\`.`, "Codex cannot load a skill directory that does not contain the required SKILL.md entrypoint.", `Add \`SKILL.md\` to \`${skillRoot}\` with at least \`name\` and \`description\` frontmatter.`));
+            findings.push(buildFailure("plugin.skill.skill_md.missing", `The skill \`${skillDirectory.name}\` is missing \`SKILL.md\`.`, "Codex cannot load a skill directory that does not contain the required SKILL.md entrypoint.", `Add \`SKILL.md\` to \`${skillRoot}\` with at least \`name\` and \`description\` frontmatter.`, {
+                skillName: skillDirectory.name,
+                skillPath: relativePackagePath(rootPath, skillFilePath)
+            }));
             continue;
         }
         const skillContent = await readFile(skillFilePath, "utf8");
         const frontmatter = parseSkillFrontmatter(skillContent);
         if (!frontmatter?.name) {
-            findings.push(buildFailure("plugin.skill.name.missing", `The skill \`${skillDirectory.name}\` is missing a \`name\` field in frontmatter.`, "Codex cannot expose skill metadata correctly without a stable skill name.", `Add a \`name\` field to the frontmatter in \`${skillFilePath}\`.`));
+            findings.push(buildFailure("plugin.skill.name.missing", `The skill \`${skillDirectory.name}\` is missing a \`name\` field in frontmatter.`, "Codex cannot expose skill metadata correctly without a stable skill name.", `Add a \`name\` field to the frontmatter in \`${skillFilePath}\`.`, {
+                skillName: skillDirectory.name,
+                skillPath: relativePackagePath(rootPath, skillFilePath),
+                field: "name"
+            }));
         }
         if (!frontmatter?.description) {
-            findings.push(buildFailure("plugin.skill.description.missing", `The skill \`${skillDirectory.name}\` is missing a \`description\` field in frontmatter.`, "Codex uses skill descriptions for discovery and implicit matching, so missing descriptions reduce skill usability.", `Add a scoped \`description\` field to the frontmatter in \`${skillFilePath}\`.`));
+            findings.push(buildFailure("plugin.skill.description.missing", `The skill \`${skillDirectory.name}\` is missing a \`description\` field in frontmatter.`, "Codex uses skill descriptions for discovery and implicit matching, so missing descriptions reduce skill usability.", `Add a scoped \`description\` field to the frontmatter in \`${skillFilePath}\`.`, {
+                skillName: skillDirectory.name,
+                skillPath: relativePackagePath(rootPath, skillFilePath),
+                field: "description"
+            }));
         }
         if (frontmatter?.description &&
             isDescriptionLikelyVerbose(frontmatter.description, "skill")) {
-            findings.push(buildWarning("plugin.heuristic.skill_description.too_long", `The skill \`${skillDirectory.name}\` description is likely too verbose.`, "Overly long skill descriptions increase context cost and reduce the precision of skill matching.", `Shorten the \`description\` field in \`${skillFilePath}\` to a tightly scoped summary.`));
+            findings.push(buildWarning("plugin.heuristic.skill_description.too_long", `The skill \`${skillDirectory.name}\` description is likely too verbose.`, "Overly long skill descriptions increase context cost and reduce the precision of skill matching.", `Shorten the \`description\` field in \`${skillFilePath}\` to a tightly scoped summary.`, {
+                skillName: skillDirectory.name,
+                skillPath: relativePackagePath(rootPath, skillFilePath),
+                field: "description"
+            }));
         }
         for (const supportReference of extractSupportAssetReferences(skillContent)) {
             const supportPath = path.resolve(skillRoot, supportReference);
             const supportFileExists = await fileExists(supportPath);
             const supportDirectoryExists = await directoryExists(supportPath);
             if (!supportFileExists && !supportDirectoryExists) {
-                findings.push(buildWarning("plugin.skill.asset_reference.missing", `The skill \`${skillDirectory.name}\` references missing support asset \`${supportReference}\`.`, "Skills that point to missing scripts, templates, assets, or examples are harder to execute and can fail when an agent follows the instructions.", `Create \`${supportPath}\` or update the reference in \`${skillFilePath}\`.`));
+                findings.push(buildWarning("plugin.skill.asset_reference.missing", `The skill \`${skillDirectory.name}\` references missing support asset \`${supportReference}\`.`, "Skills that point to missing scripts, templates, assets, or examples are harder to execute and can fail when an agent follows the instructions.", `Create \`${supportPath}\` or update the reference in \`${skillFilePath}\`.`, {
+                    skillName: skillDirectory.name,
+                    skillPath: relativePackagePath(rootPath, skillFilePath),
+                    assetReference: supportReference,
+                    assetPath: relativePackagePath(rootPath, supportPath)
+                }));
             }
         }
     }
@@ -299,7 +325,12 @@ async function validateMcpConfig(discoveredPackage) {
     const mcpConfigExists = await fileExists(mcpConfigPath);
     if (!mcpConfigExists) {
         return [
-            buildFailure("plugin.mcp.path.missing", "The plugin manifest points to a missing `.mcp.json` file.", "Codex cannot load bundled MCP server definitions if the referenced config file does not exist.", `Create \`${mcpConfigPath}\` or update the manifest \`mcpServers\` path.`)
+            buildFailure("plugin.mcp.path.missing", "The plugin manifest points to a missing `.mcp.json` file.", "Codex cannot load bundled MCP server definitions if the referenced config file does not exist.", `Create \`${mcpConfigPath}\` or update the manifest \`mcpServers\` path.`, {
+                manifestPath: relativePackagePath(rootPath, discoveredPackage.manifestPath),
+                field: "mcpServers",
+                configuredPath: manifest.mcpServers,
+                configPath: relativePackagePath(rootPath, mcpConfigPath)
+            })
         ];
     }
     let parsedConfig;
@@ -308,31 +339,42 @@ async function validateMcpConfig(discoveredPackage) {
     }
     catch {
         return [
-            buildFailure("plugin.mcp.invalid_json", "The referenced `.mcp.json` file is not valid JSON.", "Codex will not be able to parse bundled MCP server configuration.", `Fix the JSON syntax in \`${mcpConfigPath}\`.`)
+            buildFailure("plugin.mcp.invalid_json", "The referenced `.mcp.json` file is not valid JSON.", "Codex will not be able to parse bundled MCP server configuration.", `Fix the JSON syntax in \`${mcpConfigPath}\`.`, { configPath: relativePackagePath(rootPath, mcpConfigPath), field: "json" })
         ];
     }
     if (!isPlainObject(parsedConfig)) {
         return [
-            buildFailure("plugin.mcp.invalid_shape", "The referenced `.mcp.json` file must contain a JSON object.", "Codex expects bundled MCP configuration to be object-shaped so server entries can be resolved reliably.", `Wrap the MCP configuration in a top-level object inside \`${mcpConfigPath}\`.`)
+            buildFailure("plugin.mcp.invalid_shape", "The referenced `.mcp.json` file must contain a JSON object.", "Codex expects bundled MCP configuration to be object-shaped so server entries can be resolved reliably.", `Wrap the MCP configuration in a top-level object inside \`${mcpConfigPath}\`.`, { configPath: relativePackagePath(rootPath, mcpConfigPath), field: "root" })
         ];
     }
     const servers = parsedConfig.mcpServers;
     if (!isPlainObject(servers) || Object.keys(servers).length === 0) {
         return [
-            buildFailure("plugin.mcp.invalid_shape", "The referenced `.mcp.json` file must contain a non-empty `mcpServers` object.", "Without a valid `mcpServers` object, Codex cannot discover the bundled MCP server definitions.", `Define bundled servers under \`mcpServers\` in \`${mcpConfigPath}\`.`)
+            buildFailure("plugin.mcp.invalid_shape", "The referenced `.mcp.json` file must contain a non-empty `mcpServers` object.", "Without a valid `mcpServers` object, Codex cannot discover the bundled MCP server definitions.", `Define bundled servers under \`mcpServers\` in \`${mcpConfigPath}\`.`, {
+                configPath: relativePackagePath(rootPath, mcpConfigPath),
+                field: "mcpServers"
+            })
         ];
     }
     const findings = [];
     for (const [serverName, serverConfig] of Object.entries(servers)) {
         if (!isPlainObject(serverConfig)) {
-            findings.push(buildFailure("plugin.mcp.server.invalid", `The MCP server \`${serverName}\` must be configured as an object.`, "Codex cannot interpret a server entry unless it is represented as an object with server options.", `Change the \`${serverName}\` entry in \`${mcpConfigPath}\` to an object.`));
+            findings.push(buildFailure("plugin.mcp.server.invalid", `The MCP server \`${serverName}\` must be configured as an object.`, "Codex cannot interpret a server entry unless it is represented as an object with server options.", `Change the \`${serverName}\` entry in \`${mcpConfigPath}\` to an object.`, {
+                configPath: relativePackagePath(rootPath, mcpConfigPath),
+                serverName,
+                field: "server"
+            }));
             continue;
         }
         const command = serverConfig.command;
         const url = serverConfig.url;
         const env = serverConfig.env;
         if (typeof command !== "string" && typeof url !== "string") {
-            findings.push(buildFailure("plugin.mcp.server.transport.missing", `The MCP server \`${serverName}\` must define either \`command\` or \`url\`.`, "Codex needs a process command for STDIO servers or a URL for streamable HTTP servers.", `Add either \`command\` or \`url\` to the \`${serverName}\` entry in \`${mcpConfigPath}\`.`));
+            findings.push(buildFailure("plugin.mcp.server.transport.missing", `The MCP server \`${serverName}\` must define either \`command\` or \`url\`.`, "Codex needs a process command for STDIO servers or a URL for streamable HTTP servers.", `Add either \`command\` or \`url\` to the \`${serverName}\` entry in \`${mcpConfigPath}\`.`, {
+                configPath: relativePackagePath(rootPath, mcpConfigPath),
+                serverName,
+                field: "transport"
+            }));
         }
         if (isPlainObject(env)) {
             for (const [envKey, envValue] of Object.entries(env)) {

package/dist/domain/types.d.ts

@@ -10,11 +10,25 @@ export interface Finding {
     evidence?: FindingEvidence;
     fingerprint?: string;
 }
+export interface FindingSuppression {
+    reason: string;
+    expiresAt: string;
+}
+export interface SuppressedFinding extends Finding {
+    suppression: FindingSuppression;
+}
+export interface SuppressionSummary {
+    applied: number;
+    expired: number;
+    invalid: number;
+}
 export interface CheckResult {
     targetPath: string;
     status: "pass" | "warn" | "fail";
     exitCode: 0 | 1;
     findings: Finding[];
+    suppressedFindings?: SuppressedFinding[];
+    suppressionSummary?: SuppressionSummary;
     runtimeScorecard?: RuntimeScorecard;
 }
 export interface CheckOptions {
@@ -50,6 +64,8 @@ export interface JsonReport {
     generatedAt: string;
     summary: JsonReportSummary;
     findings: Finding[];
+    suppressedFindings?: SuppressedFinding[];
+    suppressionSummary?: SuppressionSummary;
 }
 export type RuntimeCapabilityStatus = "pass" | "fail" | "warn" | "skipped" | "unsupported";
 export interface RuntimeScorecard {

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import type { CheckOptions, CheckResult } from "./domain/types.js";
+export { applyDoctorConfig, loadDoctorConfig, type DoctorConfig } from "./core/doctor-config.js";
 export { buildFindingFingerprint, formatFindingFingerprintLine, withFindingFingerprint, withFindingFingerprints } from "./reporting/finding-fingerprint.js";
 export { buildSecurityAudit, renderSecurityAuditJson, renderSecurityScorecard, type SecurityAudit } from "./security/security-audit.js";
 export { buildTrustScore, renderTrustScore, renderTrustScoreJson, type BuildTrustScoreOptions, type TrustScoreReport } from "./security/trust-score.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 import { validatePlugin } from "./core/validate-plugin.js";
+export { applyDoctorConfig, loadDoctorConfig } from "./core/doctor-config.js";
 export { buildFindingFingerprint, formatFindingFingerprintLine, withFindingFingerprint, withFindingFingerprints } from "./reporting/finding-fingerprint.js";
 export { buildSecurityAudit, renderSecurityAuditJson, renderSecurityScorecard } from "./security/security-audit.js";
 export { buildTrustScore, renderTrustScore, renderTrustScoreJson } from "./security/trust-score.js";

package/dist/mcp/generic-mcp-doctor.js

@@ -4,13 +4,14 @@ import { buildCompatibilityMatrix, readMcpConfigPath } from "../compatibility/co
 import { readJsonFile } from "../core/read-json-file.js";
 import { formatFindingFingerprintLine, withFindingFingerprints } from "../reporting/finding-fingerprint.js";
 import { auditMcpServerConfig, buildSecurityAuditFromFindings } from "../security/security-audit.js";
-function buildFinding(severity, id, message, impact, suggestedFix) {
+function buildFinding(severity, id, message, impact, suggestedFix, evidence) {
     return {
         id,
         severity,
         message,
         impact,
-        suggestedFix
+        suggestedFix,
+        ...(evidence ? { evidence } : {})
     };
 }
 function isPlainObject(value) {
@@ -30,12 +31,12 @@ function isPathWithinRoot(rootPath, candidatePath) {
     return (relativePath === "" ||
         (!relativePath.startsWith("..") && !path.isAbsolute(relativePath)));
 }
-function buildStaticMcpFindings(mcpConfigPath, parsedConfig) {
-    if (!mcpConfigPath) {
+function buildStaticMcpFindings(configPath, parsedConfig) {
+    if (!configPath) {
         return {
             serverCount: 0,
             findings: [
-                buildFinding("fail", "mcp.config.missing", "No MCP config was found for this target.", "A generic MCP package needs a `.mcp.json` file or a Codex manifest `mcpServers` reference before clients can discover servers.", "Add `.mcp.json` with a non-empty top-level `mcpServers` object.")
+                buildFinding("fail", "mcp.config.missing", "No MCP config was found for this target.", "A generic MCP package needs a `.mcp.json` file or a Codex manifest `mcpServers` reference before clients can discover servers.", "Add `.mcp.json` with a non-empty top-level `mcpServers` object.", { configPath: ".mcp.json", field: "mcpServers" })
             ]
         };
     }
@@ -43,7 +44,7 @@ function buildStaticMcpFindings(mcpConfigPath, parsedConfig) {
         return {
             serverCount: 0,
             findings: [
-                buildFinding("fail", "mcp.config.invalid_shape", "The MCP config must be a JSON object.", "MCP clients expect object-shaped configuration so server entries can be resolved deterministically.", `Wrap the MCP config in a top-level object inside \`${mcpConfigPath}\`.`)
+                buildFinding("fail", "mcp.config.invalid_shape", "The MCP config must be a JSON object.", "MCP clients expect object-shaped configuration so server entries can be resolved deterministically.", `Wrap the MCP config in a top-level object inside \`${configPath}\`.`, { configPath, field: "root" })
             ]
         };
     }
@@ -52,18 +53,18 @@ function buildStaticMcpFindings(mcpConfigPath, parsedConfig) {
         return {
             serverCount: 0,
             findings: [
-                buildFinding("fail", "mcp.config.invalid_shape", "The MCP config must contain a non-empty `mcpServers` object.", "Without server entries, MCP clients cannot discover any package capabilities.", `Define MCP servers under \`mcpServers\` in \`${mcpConfigPath}\`.`)
+                buildFinding("fail", "mcp.config.invalid_shape", "The MCP config must contain a non-empty `mcpServers` object.", "Without server entries, MCP clients cannot discover any package capabilities.", `Define MCP servers under \`mcpServers\` in \`${configPath}\`.`, { configPath, field: "mcpServers" })
             ]
         };
     }
     const findings = [];
     for (const [serverName, serverConfig] of Object.entries(servers)) {
         if (!isPlainObject(serverConfig)) {
-            findings.push(buildFinding("fail", "mcp.server.invalid", `The MCP server \`${serverName}\` must be configured as an object.`, "MCP clients cannot interpret a server entry unless it is represented as an object with server options.", `Change the \`${serverName}\` entry in \`${mcpConfigPath}\` to an object.`));
+            findings.push(buildFinding("fail", "mcp.server.invalid", `The MCP server \`${serverName}\` must be configured as an object.`, "MCP clients cannot interpret a server entry unless it is represented as an object with server options.", `Change the \`${serverName}\` entry in \`${configPath}\` to an object.`, { configPath, serverName, field: "server" }));
             continue;
         }
         if (typeof serverConfig.command !== "string" && typeof serverConfig.url !== "string") {
-            findings.push(buildFinding("fail", "mcp.server.transport.missing", `The MCP server \`${serverName}\` must define either \`command\` or \`url\`.`, "MCP clients need a process command for stdio servers or a URL for remote servers.", `Add either \`command\` or \`url\` to the \`${serverName}\` entry in \`${mcpConfigPath}\`.`));
+            findings.push(buildFinding("fail", "mcp.server.transport.missing", `The MCP server \`${serverName}\` must define either \`command\` or \`url\`.`, "MCP clients need a process command for stdio servers or a URL for remote servers.", `Add either \`command\` or \`url\` to the \`${serverName}\` entry in \`${configPath}\`.`, { configPath, serverName, field: "transport" }));
         }
     }
     return {
@@ -92,19 +93,26 @@ export async function buildGenericMcpDoctor(targetPath, environment = {}) {
     }
     else if (!isPathWithinRoot(rootPath, mcpConfigPath)) {
         staticFindings = [
-            buildFinding("fail", "mcp.config.path_outside_root", "The MCP config path resolves outside the target root.", "A package that reads MCP configuration outside its root is harder to audit and can depend on unreviewed local files.", "Keep `.mcp.json` or the manifest `mcpServers` reference inside the package root.")
+            buildFinding("fail", "mcp.config.path_outside_root", "The MCP config path resolves outside the target root.", "A package that reads MCP configuration outside its root is harder to audit and can depend on unreviewed local files.", "Keep `.mcp.json` or the manifest `mcpServers` reference inside the package root.", {
+                configPath: path.relative(rootPath, mcpConfigPath).replaceAll("\\", "/"),
+                resolvedPath: mcpConfigPath,
+                field: "configPath"
+            })
         ];
     }
     else {
         try {
             parsedConfig = await readJsonFile(mcpConfigPath);
-            const staticResult = buildStaticMcpFindings(mcpConfigPath, parsedConfig);
+            const staticResult = buildStaticMcpFindings(path.relative(rootPath, mcpConfigPath).replaceAll("\\", "/"), parsedConfig);
             staticFindings = staticResult.findings;
             serverCount = staticResult.serverCount;
         }
         catch {
             staticFindings = [
-                buildFinding("fail", "mcp.config.invalid_json", "The MCP config is not valid JSON.", "MCP clients cannot parse server configuration until the JSON syntax is valid.", `Fix the JSON syntax in \`${mcpConfigPath}\`.`)
+                buildFinding("fail", "mcp.config.invalid_json", "The MCP config is not valid JSON.", "MCP clients cannot parse server configuration until the JSON syntax is valid.", `Fix the JSON syntax in \`${mcpConfigPath}\`.`, {
+                    configPath: path.relative(rootPath, mcpConfigPath).replaceAll("\\", "/"),
+                    field: "json"
+                })
             ];
         }
     }

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

@@ -18,7 +18,13 @@ export function buildJsonReport(result, options) {
                 total: result.findings.length
             }
         },
-        findings: result.findings
+        findings: result.findings,
+        ...(result.suppressedFindings
+            ? { suppressedFindings: result.suppressedFindings }
+            : {}),
+        ...(result.suppressionSummary
+            ? { suppressionSummary: result.suppressionSummary }
+            : {})
     };
 }
 export function renderJsonReport(result, options) {

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

@@ -16,7 +16,10 @@ export function buildMarkdownReport(result, options) {
         `| Warn Findings | ${warnCount} |`,
         `| Total Findings | ${result.findings.length} |`
     ];
-    if (result.findings.length === 0) {
+    if (result.suppressionSummary) {
+        lines.push(`| Suppressions Applied | ${result.suppressionSummary.applied} |`, `| Suppressions Expired | ${result.suppressionSummary.expired} |`, `| Suppressions Invalid | ${result.suppressionSummary.invalid} |`);
+    }
+    if (result.findings.length === 0 && !result.suppressedFindings?.length) {
         lines.push("", "No findings.");
         return lines.join("\n");
     }
@@ -33,22 +36,39 @@ export function buildMarkdownReport(result, options) {
         lines.push(`| prompts/list | ${result.runtimeScorecard.promptsList.toUpperCase()} |`);
         lines.push(`| prompts/get | ${result.runtimeScorecard.promptGet.toUpperCase()} |`);
     }
-    lines.push("", "## Findings", "");
-    for (const finding of result.findings) {
-        lines.push(`### ${finding.severity.toUpperCase()} \`${finding.id}\``);
-        lines.push("");
-        lines.push(`- Message: ${finding.message}`);
-        lines.push(`- Impact: ${finding.impact}`);
-        lines.push(`- Suggested fix: ${finding.suggestedFix}`);
-        const fingerprint = formatFindingFingerprintLine(finding);
-        if (fingerprint) {
-            lines.push(`- Fingerprint: \`${fingerprint}\``);
+    if (result.findings.length > 0) {
+        lines.push("", "## Findings", "");
+        for (const finding of result.findings) {
+            lines.push(`### ${finding.severity.toUpperCase()} \`${finding.id}\``);
+            lines.push("");
+            lines.push(`- Message: ${finding.message}`);
+            lines.push(`- Impact: ${finding.impact}`);
+            lines.push(`- Suggested fix: ${finding.suggestedFix}`);
+            const fingerprint = formatFindingFingerprintLine(finding);
+            if (fingerprint) {
+                lines.push(`- Fingerprint: \`${fingerprint}\``);
+            }
+            const evidence = formatFindingEvidenceLine(finding);
+            if (evidence) {
+                lines.push(`- Evidence: ${evidence}`);
+            }
+            lines.push("");
         }
-        const evidence = formatFindingEvidenceLine(finding);
-        if (evidence) {
-            lines.push(`- Evidence: ${evidence}`);
+    }
+    else {
+        lines.push("", "No active findings.");
+    }
+    if (result.suppressedFindings?.length) {
+        lines.push("", "## Suppressed Findings", "");
+        for (const finding of result.suppressedFindings) {
+            lines.push(`### ${finding.severity.toUpperCase()} \`${finding.id}\``);
+            lines.push("");
+            lines.push(`- Message: ${finding.message}`);
+            lines.push(`- Fingerprint: \`${finding.fingerprint ?? "unavailable"}\``);
+            lines.push(`- Reason: ${finding.suppression.reason}`);
+            lines.push(`- Expires: ${finding.suppression.expiresAt}`);
+            lines.push("");
         }
-        lines.push("");
     }
     return lines.join("\n");
 }

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

@@ -55,7 +55,15 @@ export function renderSarifReport(result) {
                         }
                         : {}),
                     ...(finding.evidence ? { properties: { evidence: finding.evidence } } : {})
-                }))
+                })),
+                ...(result.suppressionSummary
+                    ? {
+                        properties: {
+                            suppressionSummary: result.suppressionSummary,
+                            suppressedFindings: result.suppressedFindings ?? []
+                        }
+                    }
+                    : {})
             }
         ]
     };

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

@@ -35,7 +35,10 @@ export function renderTextReport(result, options = {}) {
         `Target: ${result.targetPath}`,
         `Summary: ${failCount} fail, ${warnCount} warn, ${totalCount} total`
     ];
-    if (result.findings.length === 0) {
+    if (result.suppressionSummary) {
+        lines.push(`Suppressions: ${result.suppressionSummary.applied} applied, ${result.suppressionSummary.expired} expired, ${result.suppressionSummary.invalid} invalid`);
+    }
+    if (result.findings.length === 0 && !result.suppressedFindings?.length) {
         if (result.runtimeScorecard) {
             lines.push("", "Runtime Scorecard", "----------------");
             lines.push(`initialize: ${result.runtimeScorecard.initialize}`);
@@ -82,6 +85,16 @@ export function renderTextReport(result, options = {}) {
     };
     appendSection("Failures", failures, glyphs.fail);
     appendSection("Warnings", warnings, glyphs.warn);
+    if (result.suppressedFindings?.length) {
+        lines.push("", "Suppressed Findings", "-------------------");
+        for (const finding of result.suppressedFindings) {
+            lines.push(`- ${finding.id}`);
+            lines.push(`  Message: ${finding.message}`);
+            lines.push(`  Fingerprint: ${finding.fingerprint ?? "unavailable"}`);
+            lines.push(`  Reason: ${finding.suppression.reason}`);
+            lines.push(`  Expires: ${finding.suppression.expiresAt}`);
+        }
+    }
     if (result.runtimeScorecard) {
         lines.push("", "Runtime Scorecard", "----------------");
         lines.push(`initialize: ${result.runtimeScorecard.initialize}`);

package/dist/rules/rule-catalog.d.ts

@@ -1,4 +1,4 @@
-export type RuleCategory = "package" | "skill" | "mcp" | "runtime" | "security";
+export type RuleCategory = "package" | "skill" | "mcp" | "runtime" | "security" | "configuration";
 export type RuleSeverity = "fail" | "warn";
 export interface RuleDefinition {
     id: string;

package/dist/rules/rule-catalog.js

@@ -1,4 +1,22 @@
 export const ruleCatalog = [
+    {
+        id: "suppression.invalid",
+        category: "configuration",
+        defaultSeverity: "warn",
+        summary: "A targeted suppression record is invalid.",
+        why: "Invalid suppression records are not applied and can create false confidence about accepted findings.",
+        fix: "Fix or remove the invalid suppression record in `.codex-doctor.json`.",
+        example: '{ "fingerprint": "<64 lowercase hex characters>", "reason": "Reviewed exception.", "expiresAt": "2026-07-31" }'
+    },
+    {
+        id: "suppression.expired",
+        category: "configuration",
+        defaultSeverity: "warn",
+        summary: "A targeted suppression has expired.",
+        why: "Expired risk acceptance must be reviewed again before the finding can be suppressed.",
+        fix: "Remove the expired record or replace it with a newly reviewed expiration date.",
+        example: '{ "fingerprint": "<fingerprint>", "reason": "Reviewed again.", "expiresAt": "2026-08-31" }'
+    },
     {
         id: "plugin.manifest.missing",
         category: "package",

package/dist/security/security-audit.js

@@ -331,7 +331,7 @@ export async function buildSecurityAudit(targetPath) {
     const discoveredPackage = await discoverPackage(targetPath);
     if (!discoveredPackage) {
         const findings = [
-            buildFinding("fail", "plugin.security.audit_unavailable", "The target directory is missing `.codex-plugin/plugin.json`, so the package security audit cannot run.", "Without a Codex plugin manifest, the audit cannot resolve packaged skills or MCP server configuration safely.", "Run the audit against a Codex plugin package root.", { targetPath: path.resolve(targetPath) })
+            buildFinding("fail", "plugin.security.audit_unavailable", "The target directory is missing `.codex-plugin/plugin.json`, so the package security audit cannot run.", "Without a Codex plugin manifest, the audit cannot resolve packaged skills or MCP server configuration safely.", "Run the audit against a Codex plugin package root.", { manifestPath: ".codex-plugin/plugin.json" })
         ];
         return buildSecurityAuditFromFindings(targetPath, findings);
     }

package/dist/security/trust-score.js

@@ -11,13 +11,14 @@ const lifecycleScripts = new Set([
     "prepublish",
     "prepare"
 ]);
-function buildFinding(severity, id, message, impact, suggestedFix) {
+function buildFinding(severity, id, message, impact, suggestedFix, evidence) {
     return {
         id,
         severity,
         message,
         impact,
-        suggestedFix
+        suggestedFix,
+        ...(evidence ? { evidence } : {})
     };
 }
 async function fileExists(targetPath) {
@@ -61,10 +62,10 @@ function auditScripts(packageJson) {
         }
         scriptsChecked += 1;
         if (containsRemotePipeInstall(scriptValue)) {
-            findings.push(buildFinding("fail", "trust.package.remote_pipe_install", `The package lifecycle script \`${scriptName}\` pipes remote content into a shell.`, "Remote download-and-execute scripts can run unreviewed code during install or publish workflows.", "Replace remote pipe execution with pinned package dependencies or a checked-in reviewed setup script."));
+            findings.push(buildFinding("fail", "trust.package.remote_pipe_install", `The package lifecycle script \`${scriptName}\` pipes remote content into a shell.`, "Remote download-and-execute scripts can run unreviewed code during install or publish workflows.", "Replace remote pipe execution with pinned package dependencies or a checked-in reviewed setup script.", { packageJsonPath: "package.json", scriptName }));
             continue;
         }
-        findings.push(buildFinding("warn", "trust.package.lifecycle_script", `The package defines lifecycle script \`${scriptName}\`.`, "Lifecycle scripts execute automatically during package manager workflows and increase supply-chain review scope.", "Keep lifecycle scripts minimal, documented, and covered by release review."));
+        findings.push(buildFinding("warn", "trust.package.lifecycle_script", `The package defines lifecycle script \`${scriptName}\`.`, "Lifecycle scripts execute automatically during package manager workflows and increase supply-chain review scope.", "Keep lifecycle scripts minimal, documented, and covered by release review.", { packageJsonPath: "package.json", scriptName }));
     }
     return {
         findings,
@@ -73,26 +74,41 @@ function auditScripts(packageJson) {
 }
 function dependencySections(packageJson) {
     return [
-        packageJson.dependencies,
-        packageJson.devDependencies,
-        packageJson.optionalDependencies,
-        packageJson.peerDependencies
-    ].filter(isPlainObject);
+        { name: "dependencies", dependencies: packageJson.dependencies },
+        { name: "devDependencies", dependencies: packageJson.devDependencies },
+        { name: "optionalDependencies", dependencies: packageJson.optionalDependencies },
+        { name: "peerDependencies", dependencies: packageJson.peerDependencies }
+    ]
+        .filter((entry) => isPlainObject(entry.dependencies))
+        .map((entry) => ({
+        name: entry.name,
+        dependencies: entry.dependencies
+    }));
 }
 function auditDependencies(packageJson) {
     const findings = [];
     let dependenciesChecked = 0;
-    for (const dependencies of dependencySections(packageJson)) {
+    for (const { name: dependencySection, dependencies } of dependencySections(packageJson)) {
         for (const [dependencyName, versionSpec] of Object.entries(dependencies)) {
             if (typeof versionSpec !== "string") {
                 continue;
             }
             dependenciesChecked += 1;
             if (versionSpec === "*" || versionSpec.toLowerCase() === "latest") {
-                findings.push(buildFinding("warn", "trust.package.unpinned_dependency", `The dependency \`${dependencyName}\` uses broad version spec \`${versionSpec}\`.`, "Broad dependency ranges make package resolution less reproducible across installs and releases.", "Pin the dependency to a specific compatible range or exact version."));
+                findings.push(buildFinding("warn", "trust.package.unpinned_dependency", `The dependency \`${dependencyName}\` uses broad version spec \`${versionSpec}\`.`, "Broad dependency ranges make package resolution less reproducible across installs and releases.", "Pin the dependency to a specific compatible range or exact version.", {
+                    packageJsonPath: "package.json",
+                    dependencyName,
+                    dependencySection,
+                    versionSpec
+                }));
             }
             if (/^(git\+|github:|http:\/\/|https:\/\/)/i.test(versionSpec)) {
-                findings.push(buildFinding("warn", "trust.package.remote_dependency", `The dependency \`${dependencyName}\` resolves from remote spec \`${versionSpec}\`.`, "Remote dependency specs can change outside the npm registry's normal version and integrity workflow.", "Prefer registry-published dependencies with pinned semver ranges."));
+                findings.push(buildFinding("warn", "trust.package.remote_dependency", `The dependency \`${dependencyName}\` resolves from remote spec \`${versionSpec}\`.`, "Remote dependency specs can change outside the npm registry's normal version and integrity workflow.", "Prefer registry-published dependencies with pinned semver ranges.", {
+                    packageJsonPath: "package.json",
+                    dependencyName,
+                    dependencySection,
+                    versionSpec
+                }));
             }
         }
     }
@@ -104,7 +120,7 @@ function auditDependencies(packageJson) {
 function dedupeFindings(findings) {
     const seen = new Set();
     return findings.filter((finding) => {
-        const key = `${finding.id}\n${finding.message}`;
+        const key = `${finding.id}\n${JSON.stringify(finding.evidence ?? {})}`;
         if (seen.has(key)) {
             return false;
         }

package/package.json

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