@devinnn/docdrift 0.1.1 → 0.1.2

package/README.md

@@ -9,6 +9,7 @@ Docs that never lie: detect drift between merged code and docs, then open low-no
   - `detect --base <sha> --head <sha>`
   - `run --base <sha> --head <sha>`
   - `status --since 24h`
+  - `sla-check` — Check for doc-drift PRs open 7+ days and open a reminder issue
 - GitHub Action: `/Users/cameronking/Desktop/sideproject/docdrift/.github/workflows/devin-doc-drift.yml`
 - Repo-local config: `/Users/cameronking/Desktop/sideproject/docdrift/docdrift.yaml`
 - Demo API + OpenAPI exporter + driftable docs
@@ -16,17 +17,18 @@ Docs that never lie: detect drift between merged code and docs, then open low-no
 
 ## Why this is low-noise
 
-- One PR per doc area per day (bundling rule).
-- Global PR/day cap.
-- Confidence gating and allowlist enforcement.
-- Conceptual docs default to issue escalation with targeted questions.
+- **Single session, single PR** — One Devin session handles the whole docsite (API reference + guides).
+- **Gate on API spec diff** — We only run when OpenAPI drift is detected; no session for docs-check-only failures.
+- **requireHumanReview** — When the PR touches guides/prose, we open an issue after the PR to direct attention.
+- **7-day SLA** — If a doc-drift PR is open 7+ days, we open a reminder issue (configurable `slaDays`; use `sla-check` CLI or cron workflow).
+- Confidence gating and allowlist/exclude enforcement.
 - Idempotency key prevents duplicate actions for same repo/SHAs/action.
 
-## Detection tiers
+## Detection and gate
 
-- Tier 0: docsite verification (`npm run docs:gen` then `npm run docs:build`)
-- Tier 1: OpenAPI drift (`openapi/generated.json` vs `apps/docs-site/openapi/openapi.json`)
-- Tier 2: heuristic path impacts (e.g. `apps/api/src/auth/**` -> `apps/docs-site/docs/guides/auth.md`)
+- **Gate:** We only run a Devin session when **OpenAPI drift** is detected. No drift → no session.
+- Tier 1: OpenAPI drift (`openapi/generated.json` vs published spec)
+- Tier 2: Heuristic path impacts from docAreas (e.g. `apps/api/src/auth/**` → guides)
 
 Output artifacts (under `.docdrift/`):
 
@@ -38,13 +40,13 @@ When you run docdrift as a package (e.g. `npx docdrift` or from another repo), a
 ## Core flow (`docdrift run`)
 
 1. Validate config and command availability.
-2. Build drift report.
+2. Build drift report. **Gate:** If no OpenAPI drift, exit (no session).
 3. Policy decision (`OPEN_PR | UPDATE_EXISTING_PR | OPEN_ISSUE | NOOP`).
-4. Build evidence bundle (`.docdrift/evidence/<runId>/<docArea>` + tarball).
-5. Upload attachments to Devin v1 and create session.
-6. Poll session to terminal status.
+4. Build one aggregated evidence bundle for the whole docsite.
+5. One Devin session with whole-docsite prompt; poll to terminal status.
+6. If PR opened and touches `requireHumanReview` paths → create issue to direct attention.
 7. Surface result via GitHub commit comment; open issue on blocked/low-confidence paths.
-8. Persist state in `.docdrift/state.json` and write `.docdrift/metrics.json`.
+8. Persist state (including `lastDocDriftPrUrl` for SLA); write `.docdrift/metrics.json`.
 
 ## Where the docs are (this repo)
 

package/dist/src/cli.js

@@ -17,7 +17,7 @@ function getArg(args, flag) {
 async function main() {
     const [, , command, ...args] = process.argv;
     if (!command) {
-        throw new Error("Usage: docdrift <validate|detect|run|status> [options]");
+        throw new Error("Usage: docdrift <validate|detect|run|status|sla-check> [options]");
     }
     switch (command) {
         case "validate": {
@@ -49,6 +49,10 @@ async function main() {
             await (0, index_1.runStatus)(sinceHours);
             return;
         }
+        case "sla-check": {
+            await (0, index_1.runSlaCheck)();
+            return;
+        }
         default:
             throw new Error(`Unknown command: ${command}`);
     }

package/dist/src/config/load.js

@@ -4,9 +4,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadConfig = loadConfig;
+exports.loadNormalizedConfig = loadNormalizedConfig;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const js_yaml_1 = __importDefault(require("js-yaml"));
+const normalize_1 = require("./normalize");
 const schema_1 = require("./schema");
 function loadConfig(configPath = "docdrift.yaml") {
     const resolved = node_path_1.default.resolve(configPath);
@@ -36,3 +38,8 @@ function loadConfig(configPath = "docdrift.yaml") {
     }
     return data;
 }
+/** Load and normalize config for use by detection/run (always has openapi, docsite, etc.) */
+function loadNormalizedConfig(configPath = "docdrift.yaml") {
+    const config = loadConfig(configPath);
+    return (0, normalize_1.normalizeConfig)(config);
+}

package/dist/src/config/normalize.js

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeConfig = normalizeConfig;
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Produce a normalized config that the rest of the app consumes.
+ * Derives openapi/docsite/exclude/requireHumanReview from docAreas when using legacy config.
+ */
+function normalizeConfig(config) {
+    let openapi;
+    let docsite;
+    let exclude = config.exclude ?? [];
+    let requireHumanReview = config.requireHumanReview ?? [];
+    if (config.openapi && config.docsite) {
+        // Simple config
+        openapi = config.openapi;
+        docsite = Array.isArray(config.docsite) ? config.docsite : [config.docsite];
+    }
+    else if (config.docAreas && config.docAreas.length > 0) {
+        // Legacy: derive from docAreas
+        const firstOpenApiArea = config.docAreas.find((a) => a.detect.openapi);
+        if (!firstOpenApiArea?.detect.openapi) {
+            throw new Error("Legacy config requires at least one docArea with detect.openapi");
+        }
+        const o = firstOpenApiArea.detect.openapi;
+        openapi = {
+            export: o.exportCmd,
+            generated: o.generatedPath,
+            published: o.publishedPath,
+        };
+        const allPaths = [o.publishedPath];
+        for (const area of config.docAreas) {
+            area.patch.targets?.forEach((t) => allPaths.push(t));
+            area.detect.paths?.forEach((p) => p.impacts.forEach((i) => allPaths.push(i)));
+        }
+        const roots = new Set();
+        for (const p of allPaths) {
+            const parts = p.split("/").filter(Boolean);
+            if (parts.length >= 2)
+                roots.add(parts[0] + "/" + parts[1]);
+            else if (parts.length === 1)
+                roots.add(parts[0]);
+        }
+        docsite = roots.size > 0 ? [...roots] : [node_path_1.default.dirname(o.publishedPath) || "."];
+        // Derive requireHumanReview from areas with requireHumanConfirmation or conceptual mode
+        const reviewPaths = new Set();
+        for (const area of config.docAreas) {
+            if (area.patch.requireHumanConfirmation || area.mode === "conceptual") {
+                area.patch.targets?.forEach((t) => reviewPaths.add(t));
+                area.detect.paths?.forEach((p) => p.impacts.forEach((i) => reviewPaths.add(i)));
+            }
+        }
+        requireHumanReview = [...reviewPaths];
+    }
+    else {
+        throw new Error("Config must include (openapi + docsite) or docAreas");
+    }
+    return {
+        ...config,
+        openapi,
+        docsite,
+        exclude,
+        requireHumanReview,
+    };
+}

package/dist/src/config/schema.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.docDriftConfigSchema = void 0;
+exports.docDriftConfigSchema = exports.openApiSimpleSchema = void 0;
 const zod_1 = require("zod");
 const pathRuleSchema = zod_1.z.object({
     match: zod_1.z.string().min(1),
@@ -11,6 +11,12 @@ const openApiDetectSchema = zod_1.z.object({
     generatedPath: zod_1.z.string().min(1),
     publishedPath: zod_1.z.string().min(1),
 });
+/** Simple config: short field names for openapi block */
+exports.openApiSimpleSchema = zod_1.z.object({
+    export: zod_1.z.string().min(1),
+    generated: zod_1.z.string().min(1),
+    published: zod_1.z.string().min(1),
+});
 const docAreaSchema = zod_1.z.object({
     name: zod_1.z.string().min(1),
     mode: zod_1.z.enum(["autogen", "conceptual"]),
@@ -30,8 +36,40 @@ const docAreaSchema = zod_1.z.object({
         requireHumanConfirmation: zod_1.z.boolean().optional().default(false),
     }),
 });
-exports.docDriftConfigSchema = zod_1.z.object({
+const policySchema = zod_1.z.object({
+    prCaps: zod_1.z.object({
+        maxPrsPerDay: zod_1.z.number().int().positive().default(1),
+        maxFilesTouched: zod_1.z.number().int().positive().default(12),
+    }),
+    confidence: zod_1.z.object({
+        autopatchThreshold: zod_1.z.number().min(0).max(1).default(0.8),
+    }),
+    allowlist: zod_1.z.array(zod_1.z.string().min(1)).min(1),
+    verification: zod_1.z.object({
+        commands: zod_1.z.array(zod_1.z.string().min(1)).min(1),
+    }),
+    /** Days before opening SLA issue for unmerged doc-drift PRs. 0 = disabled. */
+    slaDays: zod_1.z.number().int().min(0).optional().default(7),
+    /** Label to identify doc-drift PRs for SLA check (only these PRs count). */
+    slaLabel: zod_1.z.string().min(1).optional().default("docdrift"),
+    /**
+     * If false (default): Devin may only edit existing files. No new articles, no new folders.
+     * If true: Devin may add new articles, create folders, change information architecture.
+     * Gives teams control to prevent doc sprawl; mainly applies to conceptual/guides.
+     */
+    allowNewFiles: zod_1.z.boolean().optional().default(false),
+});
+exports.docDriftConfigSchema = zod_1.z
+    .object({
     version: zod_1.z.literal(1),
+    /** Simple config: openapi block (API spec = gate for run) */
+    openapi: exports.openApiSimpleSchema.optional(),
+    /** Simple config: docsite root path(s) */
+    docsite: zod_1.z.union([zod_1.z.string().min(1), zod_1.z.array(zod_1.z.string().min(1))]).optional(),
+    /** Paths we never touch (glob patterns) */
+    exclude: zod_1.z.array(zod_1.z.string().min(1)).optional().default([]),
+    /** Paths that require human review when touched (we create issue post-PR) */
+    requireHumanReview: zod_1.z.array(zod_1.z.string().min(1)).optional().default([]),
     devin: zod_1.z.object({
         apiVersion: zod_1.z.literal("v1"),
         unlisted: zod_1.z.boolean().default(true),
@@ -40,18 +78,8 @@ exports.docDriftConfigSchema = zod_1.z.object({
         customInstructions: zod_1.z.array(zod_1.z.string().min(1)).optional(),
         customInstructionContent: zod_1.z.string().optional(),
     }),
-    policy: zod_1.z.object({
-        prCaps: zod_1.z.object({
-            maxPrsPerDay: zod_1.z.number().int().positive().default(1),
-            maxFilesTouched: zod_1.z.number().int().positive().default(12),
-        }),
-        confidence: zod_1.z.object({
-            autopatchThreshold: zod_1.z.number().min(0).max(1).default(0.8),
-        }),
-        allowlist: zod_1.z.array(zod_1.z.string().min(1)).min(1),
-        verification: zod_1.z.object({
-            commands: zod_1.z.array(zod_1.z.string().min(1)).min(1),
-        }),
-    }),
-    docAreas: zod_1.z.array(docAreaSchema).min(1),
-});
+    policy: policySchema,
+    /** Legacy: doc areas (optional when openapi+docsite present) */
+    docAreas: zod_1.z.array(docAreaSchema).optional().default([]),
+})
+    .refine((v) => (v.openapi && v.docsite) || v.docAreas.length >= 1, { message: "Config must include (openapi + docsite) or docAreas" });

package/dist/src/config/validate.js

@@ -13,9 +13,8 @@ async function validateRuntimeConfig(config) {
     }
     const commandSet = new Set([
         ...config.policy.verification.commands,
-        ...config.docAreas
-            .map((area) => area.detect.openapi?.exportCmd)
-            .filter((value) => Boolean(value)),
+        ...(config.openapi ? [config.openapi.export] : []),
+        ...(config.docAreas ?? []).map((area) => area.detect.openapi?.exportCmd).filter((value) => Boolean(value)),
     ]);
     for (const command of commandSet) {
         const binary = commandBinary(command);
@@ -24,7 +23,7 @@ async function validateRuntimeConfig(config) {
             errors.push(`Command not found for '${command}' (binary: ${binary})`);
         }
     }
-    for (const area of config.docAreas) {
+    for (const area of config.docAreas ?? []) {
         if (area.mode === "autogen" && !area.patch.targets?.length) {
             warnings.push(`docArea '${area.name}' is autogen but has no patch.targets`);
         }

package/dist/src/detect/index.js

@@ -7,18 +7,8 @@ exports.buildDriftReport = buildDriftReport;
 const node_path_1 = __importDefault(require("node:path"));
 const fs_1 = require("../utils/fs");
 const git_1 = require("../utils/git");
-const docsCheck_1 = require("./docsCheck");
 const heuristics_1 = require("./heuristics");
 const openapi_1 = require("./openapi");
-function defaultRecommendation(mode, signals) {
-    if (!signals.length) {
-        return "NOOP";
-    }
-    if (mode === "autogen") {
-        return signals.some((s) => s.tier <= 1) ? "OPEN_PR" : "OPEN_ISSUE";
-    }
-    return "OPEN_ISSUE";
-}
 async function buildDriftReport(input) {
     const runInfo = {
         runId: `${Date.now()}`,
@@ -33,25 +23,40 @@ async function buildDriftReport(input) {
     const changedPaths = await (0, git_1.gitChangedPaths)(input.baseSha, input.headSha);
     const diffSummary = await (0, git_1.gitDiffSummary)(input.baseSha, input.headSha);
     const commits = await (0, git_1.gitCommitList)(input.baseSha, input.headSha);
-    const docsCheck = await (0, docsCheck_1.runDocsChecks)(input.config.policy.verification.commands, evidenceRoot);
-    const items = [];
-    const checkSummaries = [docsCheck.summary];
+    (0, fs_1.writeJsonFile)(node_path_1.default.join(evidenceRoot, "changeset.json"), {
+        changedPaths,
+        diffSummary,
+        commits,
+    });
+    // Gate: run OpenAPI detection first. If no OpenAPI drift, exit (no session).
+    const openapiResult = await (0, openapi_1.detectOpenApiDriftFromNormalized)(input.config, evidenceRoot);
+    if (!openapiResult.signal) {
+        // No OpenAPI drift — gate closed. Return empty.
+        const report = {
+            run: {
+                repo: input.repo,
+                baseSha: input.baseSha,
+                headSha: input.headSha,
+                trigger: input.trigger,
+                timestamp: runInfo.timestamp,
+            },
+            items: [],
+        };
+        (0, fs_1.writeJsonFile)(node_path_1.default.resolve(".docdrift", "drift_report.json"), report);
+        return {
+            report,
+            aggregated: null,
+            changedPaths,
+            evidenceRoot,
+            runInfo,
+            hasOpenApiDrift: false,
+        };
+    }
+    // Gate passed: aggregate signals and impacted docs.
+    const signals = [openapiResult.signal];
+    const impactedDocs = new Set(openapiResult.impactedDocs);
+    const summaries = [openapiResult.summary];
     for (const docArea of input.config.docAreas) {
-        const signals = [];
-        const impactedDocs = new Set(docArea.patch.targets ?? []);
-        const summaries = [];
-        if (docsCheck.signal) {
-            signals.push(docsCheck.signal);
-            summaries.push(docsCheck.summary);
-        }
-        if (docArea.detect.openapi) {
-            const openapiResult = await (0, openapi_1.detectOpenApiDrift)(docArea, evidenceRoot);
-            if (openapiResult.signal) {
-                signals.push(openapiResult.signal);
-            }
-            openapiResult.impactedDocs.forEach((doc) => impactedDocs.add(doc));
-            summaries.push(openapiResult.summary);
-        }
         if (docArea.detect.paths?.length) {
             const heuristicResult = (0, heuristics_1.detectHeuristicImpacts)(docArea, changedPaths, evidenceRoot);
             if (heuristicResult.signal) {
@@ -60,18 +65,20 @@ async function buildDriftReport(input) {
             heuristicResult.impactedDocs.forEach((doc) => impactedDocs.add(doc));
             summaries.push(heuristicResult.summary);
         }
-        if (!signals.length) {
-            continue;
-        }
-        items.push({
-            docArea: docArea.name,
-            mode: docArea.mode,
-            signals,
-            impactedDocs: [...impactedDocs],
-            recommendedAction: defaultRecommendation(docArea.mode, signals),
-            summary: summaries.filter(Boolean).join(" | "),
-        });
     }
+    const aggregated = {
+        signals,
+        impactedDocs: [...impactedDocs],
+        summary: summaries.filter(Boolean).join(" | "),
+    };
+    const item = {
+        docArea: "docsite",
+        mode: "autogen",
+        signals: aggregated.signals,
+        impactedDocs: aggregated.impactedDocs,
+        recommendedAction: aggregated.signals.some((s) => s.tier <= 1) ? "OPEN_PR" : "OPEN_ISSUE",
+        summary: aggregated.summary,
+    };
     const report = {
         run: {
             repo: input.repo,
@@ -80,13 +87,15 @@ async function buildDriftReport(input) {
             trigger: input.trigger,
             timestamp: runInfo.timestamp,
         },
-        items,
+        items: [item],
     };
     (0, fs_1.writeJsonFile)(node_path_1.default.resolve(".docdrift", "drift_report.json"), report);
-    (0, fs_1.writeJsonFile)(node_path_1.default.join(evidenceRoot, "changeset.json"), {
+    return {
+        report,
+        aggregated,
         changedPaths,
-        diffSummary,
-        commits,
-    });
-    return { report, changedPaths, evidenceRoot, runInfo, checkSummaries };
+        evidenceRoot,
+        runInfo,
+        hasOpenApiDrift: true,
+    };
 }

package/dist/src/detect/openapi.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectOpenApiDrift = detectOpenApiDrift;
+exports.detectOpenApiDriftFromNormalized = detectOpenApiDriftFromNormalized;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const exec_1 = require("../utils/exec");
@@ -121,3 +122,85 @@ async function detectOpenApiDrift(docArea, evidenceDir) {
         },
     };
 }
+/** Run OpenAPI drift detection from normalized config (simple openapi block). Used as gate. */
+async function detectOpenApiDriftFromNormalized(config, evidenceDir) {
+    const openapi = config.openapi;
+    const exportLogPath = node_path_1.default.join(evidenceDir, "openapi-export.log");
+    const exportResult = await (0, exec_1.execCommand)(openapi.export);
+    node_fs_1.default.writeFileSync(exportLogPath, [
+        `$ ${openapi.export}`,
+        `exitCode: ${exportResult.exitCode}`,
+        "\n--- stdout ---",
+        exportResult.stdout,
+        "\n--- stderr ---",
+        exportResult.stderr,
+    ].join("\n"), "utf8");
+    if (exportResult.exitCode !== 0) {
+        return {
+            impactedDocs: [openapi.published],
+            evidenceFiles: [exportLogPath],
+            summary: "OpenAPI export command failed",
+            signal: {
+                kind: "weak_evidence",
+                tier: 2,
+                confidence: 0.35,
+                evidence: [exportLogPath],
+            },
+        };
+    }
+    if (!node_fs_1.default.existsSync(openapi.generated) || !node_fs_1.default.existsSync(openapi.published)) {
+        return {
+            impactedDocs: [openapi.generated, openapi.published],
+            evidenceFiles: [exportLogPath],
+            summary: "OpenAPI file(s) missing",
+            signal: {
+                kind: "weak_evidence",
+                tier: 2,
+                confidence: 0.35,
+                evidence: [exportLogPath],
+            },
+        };
+    }
+    const generatedRaw = node_fs_1.default.readFileSync(openapi.generated, "utf8");
+    const publishedRaw = node_fs_1.default.readFileSync(openapi.published, "utf8");
+    const generatedJson = JSON.parse(generatedRaw);
+    const publishedJson = JSON.parse(publishedRaw);
+    const normalizedGenerated = (0, json_1.stableStringify)(generatedJson);
+    const normalizedPublished = (0, json_1.stableStringify)(publishedJson);
+    if (normalizedGenerated === normalizedPublished) {
+        return {
+            impactedDocs: [openapi.published],
+            evidenceFiles: [exportLogPath],
+            summary: "No OpenAPI drift detected",
+        };
+    }
+    const summary = summarizeSpecDelta(publishedJson, generatedJson);
+    const diffPath = node_path_1.default.join(evidenceDir, "openapi.diff.txt");
+    node_fs_1.default.writeFileSync(diffPath, [
+        "# OpenAPI Drift Summary",
+        summary,
+        "",
+        "# Published (normalized)",
+        normalizedPublished,
+        "",
+        "# Generated (normalized)",
+        normalizedGenerated,
+    ].join("\n"), "utf8");
+    const impactedDocs = [
+        ...new Set([
+            openapi.published,
+            ...config.docAreas.flatMap((a) => a.patch.targets ?? []).filter(Boolean),
+        ]),
+    ].filter(Boolean);
+    return {
+        impactedDocs,
+        evidenceFiles: [exportLogPath, diffPath],
+        summary,
+        signal: {
+            kind: "openapi_diff",
+            tier: 1,
+            confidence: 0.95,
+            evidence: [diffPath],
+        },
+    };
+}

package/dist/src/devin/prompts.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildAutogenPrompt = buildAutogenPrompt;
 exports.buildConceptualPrompt = buildConceptualPrompt;
+exports.buildWholeDocsitePrompt = buildWholeDocsitePrompt;
 function attachmentBlock(attachmentUrls) {
     return attachmentUrls.map((url, index) => `- ATTACHMENT ${index + 1}: ${url}`).join("\n");
 }
@@ -61,3 +62,45 @@ function buildConceptualPrompt(input) {
     }
     return base;
 }
+/** Whole-docsite prompt for single-session runs */
+function buildWholeDocsitePrompt(input) {
+    const excludeNote = input.config.exclude?.length > 0
+        ? `\n6) NEVER modify files matching these patterns: ${input.config.exclude.join(", ")}`
+        : "";
+    const requireReviewNote = input.config.requireHumanReview?.length > 0
+        ? `\n7) If you touch files under: ${input.config.requireHumanReview.join(", ")} — note it in the PR description (a follow-up issue will flag for human review).`
+        : "";
+    const allowNewFiles = input.config.policy.allowNewFiles ?? false;
+    const newFilesRule = allowNewFiles
+        ? "8) You MAY add new articles, create new folders, and change information architecture when warranted."
+        : "8) You may ONLY edit existing files. Do NOT create new files, new articles, or new folders. Do NOT change information architecture.";
+    const base = [
+        "You are Devin. Task: update the entire docsite to match the API and code changes.",
+        "",
+        "EVIDENCE (attachments):",
+        input.attachmentUrls.map((url, i) => `- ATTACHMENT ${i + 1}: ${url}`).join("\n"),
+        "",
+        "Rules (hard):",
+        `1) Only modify files under: ${input.config.policy.allowlist.join(", ")}`,
+        "2) Make the smallest change that makes docs correct.",
+        "3) Update API reference (OpenAPI) and any impacted guides in one PR.",
+        "4) Run verification commands and record results:",
+        ...input.config.policy.verification.commands.map((c) => `   - ${c}`),
+        "5) Open exactly ONE pull request with a clear title and reviewer-friendly description.",
+        `6) Docsite scope: ${input.config.docsite.join(", ")}` +
+            excludeNote +
+            requireReviewNote +
+            `\n${newFilesRule}`,
+        "",
+        "Structured Output:",
+        "- Maintain structured output in the provided JSON schema.",
+        "- Update it at: planning, editing, verifying, open-pr, blocked, done.",
+        "- If blocked, fill blocked.questions with concrete questions.",
+        "",
+        "Goal: Produce ONE PR that updates the whole docsite (API reference + guides) using only the evidence.",
+    ].join("\n");
+    if (input.config.devin.customInstructionContent) {
+        return base + "\n\n---\n\nCustom instructions:\n\n" + input.config.devin.customInstructionContent;
+    }
+    return base;
+}

package/dist/src/github/client.js

@@ -1,9 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRepo = parseRepo;
 exports.postCommitComment = postCommitComment;
 exports.createIssue = createIssue;
 exports.renderRunComment = renderRunComment;
 exports.renderBlockedIssueBody = renderBlockedIssueBody;
+exports.renderRequireHumanReviewIssueBody = renderRequireHumanReviewIssueBody;
+exports.renderSlaIssueBody = renderSlaIssueBody;
+exports.isPrOpen = isPrOpen;
+exports.listOpenPrsWithLabel = listOpenPrsWithLabel;
 const rest_1 = require("@octokit/rest");
 function parseRepo(full) {
     const [owner, repo] = full.split("/");
@@ -84,3 +89,73 @@ function renderBlockedIssueBody(input) {
     }
     return lines.join("\n");
 }
+function renderRequireHumanReviewIssueBody(input) {
+    const lines = [];
+    lines.push("## Why this issue");
+    lines.push("");
+    lines.push("This doc-drift PR touches paths that require human review (guides, prose, or other non-technical docs).");
+    lines.push("");
+    lines.push("## What to do");
+    lines.push("");
+    lines.push(`1. Review the PR: ${input.prUrl}`);
+    lines.push("2. Confirm the changes are correct or request modifications.");
+    lines.push("3. Merge or close the PR.");
+    lines.push("");
+    if (input.touchedPaths.length > 0) {
+        lines.push("## Touched paths (require review)");
+        lines.push("");
+        for (const p of input.touchedPaths.slice(0, 20)) {
+            lines.push(`- \`${p}\``);
+        }
+        if (input.touchedPaths.length > 20) {
+            lines.push(`- ... and ${input.touchedPaths.length - 20} more`);
+        }
+    }
+    return lines.join("\n");
+}
+function renderSlaIssueBody(input) {
+    const lines = [];
+    lines.push("## Why this issue");
+    lines.push("");
+    lines.push(`Doc-drift PR(s) have been open for ${input.slaDays}+ days. Docs may be out of sync.`);
+    lines.push("");
+    lines.push("## What to do");
+    lines.push("");
+    lines.push("Please review and merge or close the following PR(s):");
+    lines.push("");
+    for (const url of input.prUrls) {
+        lines.push(`- ${url}`);
+    }
+    lines.push("");
+    lines.push("If the PR is no longer needed, close it to resolve this reminder.");
+    return lines.join("\n");
+}
+/** Check if a PR is still open. URL format: https://github.com/owner/repo/pull/123 */
+async function isPrOpen(token, prUrl) {
+    const match = prUrl.match(/github\.com[/]([^/]+)[/]([^/]+)[/]pull[/](\d+)/);
+    if (!match)
+        return { open: false };
+    const [, owner, repo, numStr] = match;
+    const number = parseInt(numStr ?? "0", 10);
+    if (!owner || !repo || !Number.isFinite(number))
+        return { open: false };
+    const octokit = new rest_1.Octokit({ auth: token });
+    const { data } = await octokit.pulls.get({ owner, repo, pull_number: number });
+    return { open: data.state === "open", number: data.number };
+}
+/** List open PRs with a given label */
+async function listOpenPrsWithLabel(token, repository, label) {
+    const octokit = new rest_1.Octokit({ auth: token });
+    const { owner, repo } = parseRepo(repository);
+    const { data } = await octokit.pulls.list({
+        owner,
+        repo,
+        state: "open",
+        labels: label,
+    });
+    return data.map((pr) => ({
+        url: pr.html_url ?? "",
+        number: pr.number,
+        created_at: pr.created_at ?? "",
+    }));
+}

package/dist/src/index.js

@@ -7,6 +7,7 @@ exports.STATE_PATH = void 0;
 exports.runDetect = runDetect;
 exports.runDocDrift = runDocDrift;
 exports.runValidate = runValidate;
+exports.runSlaCheck = runSlaCheck;
 exports.runStatus = runStatus;
 exports.resolveTrigger = resolveTrigger;
 exports.parseDurationHours = parseDurationHours;
@@ -21,6 +22,7 @@ const engine_1 = require("./policy/engine");
 const state_1 = require("./policy/state");
 const log_1 = require("./utils/log");
 const prompts_1 = require("./devin/prompts");
+const glob_1 = require("./utils/glob");
 const schemas_1 = require("./devin/schemas");
 const v1_1 = require("./devin/v1");
 function parseStructured(session) {
@@ -48,29 +50,17 @@ function inferQuestions(structured) {
         "What are the exact user-visible semantics after this merge?",
     ];
 }
-async function executeSession(input) {
+async function executeSessionSingle(input) {
     const attachmentUrls = [];
     for (const attachmentPath of input.attachmentPaths) {
         const url = await (0, v1_1.devinUploadAttachment)(input.apiKey, attachmentPath);
         attachmentUrls.push(url);
     }
-    const prompt = input.item.mode === "autogen"
-        ? (0, prompts_1.buildAutogenPrompt)({
-            item: input.item,
-            attachmentUrls,
-            verificationCommands: input.config.policy.verification.commands,
-            allowlist: input.config.policy.allowlist,
-            confidenceThreshold: input.config.policy.confidence.autopatchThreshold,
-            customAppend: input.config.devin.customInstructionContent ?? undefined,
-        })
-        : (0, prompts_1.buildConceptualPrompt)({
-            item: input.item,
-            attachmentUrls,
-            verificationCommands: input.config.policy.verification.commands,
-            allowlist: input.config.policy.allowlist,
-            confidenceThreshold: input.config.policy.confidence.autopatchThreshold,
-            customAppend: input.config.devin.customInstructionContent ?? undefined,
-        });
+    const prompt = (0, prompts_1.buildWholeDocsitePrompt)({
+        aggregated: input.aggregated,
+        config: input.config,
+        attachmentUrls,
+    });
     const session = await (0, v1_1.devinCreateSession)(input.apiKey, {
         prompt,
         unlisted: input.config.devin.unlisted,
@@ -132,14 +122,15 @@ async function runDetect(options) {
         throw new Error(`Config validation failed:\n${runtimeValidation.errors.join("\n")}`);
     }
     const repo = process.env.GITHUB_REPOSITORY ?? "local/docdrift";
-    const { report } = await (0, detect_1.buildDriftReport)({
-        config,
+    const normalized = (0, load_1.loadNormalizedConfig)();
+    const { report, hasOpenApiDrift } = await (0, detect_1.buildDriftReport)({
+        config: normalized,
         repo,
         baseSha: options.baseSha,
         headSha: options.headSha,
         trigger: options.trigger ?? "manual",
     });
-    (0, log_1.logInfo)(`Drift items detected: ${report.items.length}`);
+    (0, log_1.logInfo)(`Drift items detected: ${report.items.length} (hasOpenApiDrift: ${hasOpenApiDrift})`);
     return { hasDrift: report.items.length > 0 };
 }
 async function runDocDrift(options) {
@@ -148,183 +139,233 @@ async function runDocDrift(options) {
     if (runtimeValidation.errors.length) {
         throw new Error(`Config validation failed:\n${runtimeValidation.errors.join("\n")}`);
     }
+    const normalized = (0, load_1.loadNormalizedConfig)();
     const repo = process.env.GITHUB_REPOSITORY ?? "local/docdrift";
     const commitSha = process.env.GITHUB_SHA ?? options.headSha;
     const githubToken = process.env.GITHUB_TOKEN;
     const devinApiKey = process.env.DEVIN_API_KEY;
-    const { report, runInfo, evidenceRoot } = await (0, detect_1.buildDriftReport)({
-        config,
+    const { report, aggregated, runInfo, evidenceRoot, hasOpenApiDrift } = await (0, detect_1.buildDriftReport)({
+        config: normalized,
         repo,
         baseSha: options.baseSha,
         headSha: options.headSha,
         trigger: options.trigger ?? "manual",
     });
-    const docAreaByName = new Map(config.docAreas.map((area) => [area.name, area]));
+    // Gate: no OpenAPI drift — exit early, no session
+    if (!hasOpenApiDrift || report.items.length === 0) {
+        (0, log_1.logInfo)("No OpenAPI drift; skipping session");
+        return [];
+    }
+    const item = report.items[0];
+    const docAreaConfig = {
+        name: "docsite",
+        mode: "autogen",
+        owners: { reviewers: [] },
+        detect: { openapi: { exportCmd: normalized.openapi.export, generatedPath: normalized.openapi.generated, publishedPath: normalized.openapi.published }, paths: [] },
+        patch: { targets: [], requireHumanConfirmation: false },
+    };
     let state = (0, state_1.loadState)();
     const startedAt = Date.now();
     const results = [];
     const metrics = {
-        driftItemsDetected: report.items.length,
+        driftItemsDetected: 1,
         prsOpened: 0,
         issuesOpened: 0,
         blockedCount: 0,
         timeToSessionTerminalMs: [],
-        docAreaCounts: {},
+        docAreaCounts: { docsite: 1 },
         noiseRateProxy: 0,
     };
-    for (const item of report.items) {
-        metrics.docAreaCounts[item.docArea] = (metrics.docAreaCounts[item.docArea] ?? 0) + 1;
-        const areaConfig = docAreaByName.get(item.docArea);
-        if (!areaConfig) {
-            continue;
-        }
-        const decision = (0, engine_1.decidePolicy)({
-            item,
-            docAreaConfig: areaConfig,
-            config,
+    const decision = (0, engine_1.decidePolicy)({
+        item,
+        docAreaConfig,
+        config,
+        state,
+        repo,
+        baseSha: options.baseSha,
+        headSha: options.headSha,
+    });
+    if (decision.action === "NOOP") {
+        results.push({
+            docArea: item.docArea,
+            decision,
+            outcome: "NO_CHANGE",
+            summary: decision.reason,
+        });
+        (0, bundle_1.writeMetrics)(metrics);
+        return results;
+    }
+    if (decision.action === "UPDATE_EXISTING_PR") {
+        const existingPr = state.areaLatestPr["docsite"];
+        results.push({
+            docArea: item.docArea,
+            decision,
+            outcome: existingPr ? "NO_CHANGE" : "BLOCKED",
+            summary: existingPr ? `Bundled into existing PR: ${existingPr}` : "PR cap reached",
+            prUrl: existingPr,
+        });
+        state = (0, engine_1.applyDecisionToState)({
             state,
-            repo,
-            baseSha: options.baseSha,
-            headSha: options.headSha,
+            decision,
+            docArea: "docsite",
+            outcome: existingPr ? "NO_CHANGE" : "BLOCKED",
+            link: existingPr,
         });
-        if (decision.action === "NOOP") {
-            results.push({
-                docArea: item.docArea,
-                decision,
-                outcome: "NO_CHANGE",
-                summary: decision.reason,
-            });
-            continue;
-        }
-        if (decision.action === "UPDATE_EXISTING_PR") {
-            const existingPr = state.areaLatestPr[item.docArea];
-            const summary = existingPr
-                ? `Bundled into existing PR: ${existingPr}`
-                : "PR cap reached and no existing area PR; escalated";
-            const outcome = existingPr ? "NO_CHANGE" : "BLOCKED";
-            results.push({
-                docArea: item.docArea,
-                decision,
-                outcome,
-                summary,
-                prUrl: existingPr,
-            });
-            state = (0, engine_1.applyDecisionToState)({
-                state,
-                decision,
-                docArea: item.docArea,
-                outcome,
-                link: existingPr,
-            });
-            continue;
-        }
-        const bundle = await (0, bundle_1.buildEvidenceBundle)({ runInfo, item, evidenceRoot });
-        const attachmentPaths = [...new Set([bundle.archivePath, ...bundle.attachmentPaths])];
-        let sessionOutcome = {
-            outcome: "NO_CHANGE",
-            summary: "Skipped Devin session",
-            verification: config.policy.verification.commands.map((command) => ({
+        (0, state_1.saveState)(state);
+        (0, bundle_1.writeMetrics)(metrics);
+        return results;
+    }
+    const bundle = await (0, bundle_1.buildEvidenceBundle)({ runInfo, item, evidenceRoot });
+    const attachmentPaths = [...new Set([bundle.archivePath, ...bundle.attachmentPaths])];
+    let sessionOutcome = {
+        outcome: "NO_CHANGE",
+        summary: "Skipped Devin session",
+        verification: normalized.policy.verification.commands.map((command) => ({
+            command,
+            result: "not run",
+        })),
+    };
+    if (devinApiKey) {
+        const sessionStart = Date.now();
+        sessionOutcome = await executeSessionSingle({
+            apiKey: devinApiKey,
+            repository: repo,
+            item,
+            aggregated: aggregated,
+            attachmentPaths,
+            config: normalized,
+        });
+        metrics.timeToSessionTerminalMs.push(Date.now() - sessionStart);
+    }
+    else {
+        (0, log_1.logWarn)("DEVIN_API_KEY not set; running fallback behavior", { docArea: item.docArea });
+        sessionOutcome = {
+            outcome: "BLOCKED",
+            summary: "DEVIN_API_KEY missing; cannot start Devin session",
+            questions: ["Set DEVIN_API_KEY in environment or GitHub Actions secrets"],
+            verification: normalized.policy.verification.commands.map((command) => ({
                 command,
                 result: "not run",
             })),
         };
-        if (devinApiKey) {
-            const sessionStart = Date.now();
-            sessionOutcome = await executeSession({
-                apiKey: devinApiKey,
-                repository: repo,
-                item,
-                attachmentPaths,
-                config,
-            });
-            metrics.timeToSessionTerminalMs.push(Date.now() - sessionStart);
-        }
-        else {
-            (0, log_1.logWarn)("DEVIN_API_KEY not set; running fallback behavior", { docArea: item.docArea });
-            sessionOutcome = {
-                outcome: "BLOCKED",
-                summary: "DEVIN_API_KEY missing; cannot start Devin session",
-                questions: ["Set DEVIN_API_KEY in environment or GitHub Actions secrets"],
-                verification: config.policy.verification.commands.map((command) => ({
-                    command,
-                    result: "not run",
-                })),
-            };
-        }
-        let issueUrl;
-        if (githubToken &&
-            (decision.action === "OPEN_ISSUE" ||
-                sessionOutcome.outcome === "BLOCKED" ||
-                sessionOutcome.outcome === "NO_CHANGE")) {
+    }
+    let issueUrl;
+    if (sessionOutcome.outcome === "PR_OPENED" && sessionOutcome.prUrl) {
+        metrics.prsOpened += 1;
+        state.lastDocDriftPrUrl = sessionOutcome.prUrl;
+        state.lastDocDriftPrOpenedAt = new Date().toISOString();
+        const touchedRequireReview = (item.impactedDocs ?? []).filter((p) => normalized.requireHumanReview.some((glob) => (0, glob_1.matchesGlob)(glob, p)));
+        if (githubToken && touchedRequireReview.length > 0) {
             issueUrl = await (0, client_1.createIssue)({
                 token: githubToken,
                 repository: repo,
                 issue: {
-                    title: `[docdrift] ${item.docArea}: docs drift requires input`,
-                    body: (0, client_1.renderBlockedIssueBody)({
-                        docArea: item.docArea,
-                        evidenceSummary: item.summary,
-                        questions: sessionOutcome.questions ?? [
-                            "Please confirm intended behavior and doc wording.",
-                        ],
-                        sessionUrl: sessionOutcome.sessionUrl,
+                    title: "[docdrift] Docs out of sync — review doc drift PR",
+                    body: (0, client_1.renderRequireHumanReviewIssueBody)({
+                        prUrl: sessionOutcome.prUrl,
+                        touchedPaths: touchedRequireReview,
                     }),
                     labels: ["docdrift"],
                 },
             });
             metrics.issuesOpened += 1;
-            sessionOutcome.outcome = "ISSUE_OPENED";
         }
-        if (sessionOutcome.outcome === "PR_OPENED") {
-            metrics.prsOpened += 1;
-        }
-        if (sessionOutcome.outcome === "BLOCKED") {
-            metrics.blockedCount += 1;
+    }
+    else if (githubToken &&
+        (decision.action === "OPEN_ISSUE" ||
+            sessionOutcome.outcome === "BLOCKED" ||
+            sessionOutcome.outcome === "NO_CHANGE")) {
+        issueUrl = await (0, client_1.createIssue)({
+            token: githubToken,
+            repository: repo,
+            issue: {
+                title: "[docdrift] docsite: docs drift requires input",
+                body: (0, client_1.renderBlockedIssueBody)({
+                    docArea: item.docArea,
+                    evidenceSummary: item.summary,
+                    questions: sessionOutcome.questions ?? [
+                        "Please confirm intended behavior and doc wording.",
+                    ],
+                    sessionUrl: sessionOutcome.sessionUrl,
+                }),
+                labels: ["docdrift"],
+            },
+        });
+        metrics.issuesOpened += 1;
+        if (sessionOutcome.outcome !== "PR_OPENED") {
+            sessionOutcome.outcome = "ISSUE_OPENED";
         }
-        const result = {
+    }
+    if (sessionOutcome.outcome === "BLOCKED") {
+        metrics.blockedCount += 1;
+    }
+    const result = {
+        docArea: item.docArea,
+        decision,
+        outcome: sessionOutcome.outcome,
+        summary: sessionOutcome.summary,
+        sessionUrl: sessionOutcome.sessionUrl,
+        prUrl: sessionOutcome.prUrl,
+        issueUrl,
+    };
+    results.push(result);
+    state = (0, engine_1.applyDecisionToState)({
+        state,
+        decision,
+        docArea: "docsite",
+        outcome: sessionOutcome.outcome,
+        link: sessionOutcome.prUrl ?? issueUrl,
+    });
+    if (sessionOutcome.outcome === "PR_OPENED" && sessionOutcome.prUrl) {
+        state.lastDocDriftPrUrl = sessionOutcome.prUrl;
+        state.lastDocDriftPrOpenedAt = new Date().toISOString();
+    }
+    (0, state_1.saveState)(state);
+    if (githubToken) {
+        const body = (0, client_1.renderRunComment)({
             docArea: item.docArea,
-            decision,
-            outcome: sessionOutcome.outcome,
             summary: sessionOutcome.summary,
+            decision: decision.action,
+            outcome: sessionOutcome.outcome,
             sessionUrl: sessionOutcome.sessionUrl,
             prUrl: sessionOutcome.prUrl,
             issueUrl,
-        };
-        results.push(result);
-        if (githubToken) {
-            const body = (0, client_1.renderRunComment)({
-                docArea: item.docArea,
-                summary: sessionOutcome.summary,
-                decision: decision.action,
-                outcome: sessionOutcome.outcome,
-                sessionUrl: sessionOutcome.sessionUrl,
-                prUrl: sessionOutcome.prUrl,
-                issueUrl,
-                validation: sessionOutcome.verification,
-            });
-            await (0, client_1.postCommitComment)({
+            validation: sessionOutcome.verification,
+        });
+        await (0, client_1.postCommitComment)({
+            token: githubToken,
+            repository: repo,
+            commitSha,
+            body,
+        });
+    }
+    const slaDays = normalized.policy.slaDays ?? 0;
+    if (githubToken && slaDays > 0 && state.lastDocDriftPrUrl && state.lastDocDriftPrOpenedAt) {
+        const openedAt = Date.parse(state.lastDocDriftPrOpenedAt);
+        const daysOld = (Date.now() - openedAt) / (24 * 60 * 60 * 1000);
+        const lastSla = state.lastSlaIssueOpenedAt ? Date.parse(state.lastSlaIssueOpenedAt) : 0;
+        const slaCooldown = 6 * 24 * 60 * 60 * 1000;
+        if (daysOld >= slaDays && Date.now() - lastSla > slaCooldown) {
+            const slaIssueUrl = await (0, client_1.createIssue)({
                 token: githubToken,
                 repository: repo,
-                commitSha,
-                body,
+                issue: {
+                    title: "[docdrift] Docs out of sync — merge doc drift PR(s)",
+                    body: (0, client_1.renderSlaIssueBody)({
+                        prUrls: [state.lastDocDriftPrUrl],
+                        slaDays,
+                    }),
+                    labels: ["docdrift"],
+                },
             });
+            state.lastSlaIssueOpenedAt = new Date().toISOString();
+            (0, state_1.saveState)(state);
         }
-        state = (0, engine_1.applyDecisionToState)({
-            state,
-            decision,
-            docArea: item.docArea,
-            outcome: sessionOutcome.outcome,
-            link: sessionOutcome.prUrl ?? issueUrl,
-        });
     }
-    (0, state_1.saveState)(state);
-    metrics.noiseRateProxy =
-        metrics.driftItemsDetected === 0
-            ? 0
-            : Number((metrics.prsOpened / metrics.driftItemsDetected).toFixed(4));
+    metrics.noiseRateProxy = metrics.prsOpened;
     (0, bundle_1.writeMetrics)(metrics);
     (0, log_1.logInfo)("Run complete", {
-        items: report.items.length,
+        items: 1,
         elapsedMs: Date.now() - startedAt,
     });
     return results;
@@ -338,6 +379,54 @@ async function runValidate() {
     runtimeValidation.warnings.forEach((warning) => (0, log_1.logWarn)(warning));
     (0, log_1.logInfo)("Config is valid");
 }
+async function runSlaCheck() {
+    const githubToken = process.env.GITHUB_TOKEN;
+    if (!githubToken) {
+        throw new Error("GITHUB_TOKEN is required for sla-check command");
+    }
+    const repo = process.env.GITHUB_REPOSITORY;
+    if (!repo) {
+        throw new Error("GITHUB_REPOSITORY is required for sla-check command");
+    }
+    const normalized = (0, load_1.loadNormalizedConfig)();
+    const slaDays = normalized.policy.slaDays ?? 0;
+    const slaLabel = normalized.policy.slaLabel ?? "docdrift";
+    if (slaDays <= 0) {
+        (0, log_1.logInfo)("SLA check disabled (slaDays <= 0)");
+        return { issueOpened: false };
+    }
+    const cutoff = new Date(Date.now() - slaDays * 24 * 60 * 60 * 1000);
+    const openPrs = await (0, client_1.listOpenPrsWithLabel)(githubToken, repo, slaLabel);
+    const stalePrs = openPrs.filter((pr) => {
+        const created = pr.created_at ? Date.parse(pr.created_at) : Date.now();
+        return Number.isFinite(created) && created <= cutoff.getTime();
+    });
+    if (stalePrs.length === 0) {
+        (0, log_1.logInfo)("No doc-drift PRs open longer than slaDays; nothing to do");
+        return { issueOpened: false };
+    }
+    let state = (0, state_1.loadState)();
+    const lastSla = state.lastSlaIssueOpenedAt ? Date.parse(state.lastSlaIssueOpenedAt) : 0;
+    const slaCooldown = 6 * 24 * 60 * 60 * 1000;
+    if (Date.now() - lastSla < slaCooldown) {
+        (0, log_1.logInfo)("SLA issue cooldown; skipping");
+        return { issueOpened: false };
+    }
+    const prUrls = stalePrs.map((p) => p.url).filter(Boolean);
+    await (0, client_1.createIssue)({
+        token: githubToken,
+        repository: repo,
+        issue: {
+            title: "[docdrift] Docs out of sync — merge doc drift PR(s)",
+            body: (0, client_1.renderSlaIssueBody)({ prUrls, slaDays }),
+            labels: ["docdrift"],
+        },
+    });
+    state.lastSlaIssueOpenedAt = new Date().toISOString();
+    (0, state_1.saveState)(state);
+    (0, log_1.logInfo)(`Opened SLA issue for ${prUrls.length} stale PR(s)`);
+    return { issueOpened: true };
+}
 async function runStatus(sinceHours = 24) {
     const apiKey = process.env.DEVIN_API_KEY;
     if (!apiKey) {

package/dist/src/policy/engine.js

@@ -21,7 +21,8 @@ function decidePolicy(input) {
     const capReached = prCountToday >= config.policy.prCaps.maxPrsPerDay;
     const areaDailyKey = `${today}:${item.docArea}`;
     const exceedsFileCap = item.impactedDocs.length > config.policy.prCaps.maxFilesTouched;
-    const hasPathOutsideAllowlist = item.impactedDocs.some((filePath) => filePath && !(0, glob_1.isPathAllowed)(filePath, config.policy.allowlist));
+    const exclude = "exclude" in config && Array.isArray(config.exclude) ? config.exclude : [];
+    const hasPathOutsideAllowlist = item.impactedDocs.some((filePath) => filePath && !(0, glob_1.isPathAllowedAndNotExcluded)(filePath, config.policy.allowlist, exclude));
     let action = "NOOP";
     let reason = "No action needed";
     if (hasPathOutsideAllowlist) {

package/dist/src/utils/glob.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.globToRegExp = globToRegExp;
 exports.matchesGlob = matchesGlob;
 exports.isPathAllowed = isPathAllowed;
+exports.isPathExcluded = isPathExcluded;
+exports.isPathAllowedAndNotExcluded = isPathAllowedAndNotExcluded;
 function escapeRegex(input) {
     return input.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
 }
@@ -19,3 +21,14 @@ function matchesGlob(glob, value) {
 function isPathAllowed(path, allowlist) {
     return allowlist.some((glob) => matchesGlob(glob, path));
 }
+function isPathExcluded(path, exclude) {
+    if (!exclude?.length)
+        return false;
+    return exclude.some((glob) => matchesGlob(glob, path));
+}
+/** Path is allowed by allowlist AND not excluded */
+function isPathAllowedAndNotExcluded(path, allowlist, exclude = []) {
+    if (isPathExcluded(path, exclude))
+        return false;
+    return isPathAllowed(path, allowlist);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devinnn/docdrift",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "private": false,
   "description": "Detect and remediate documentation drift with Devin sessions",
   "main": "dist/src/index.js",