@devinnn/docdrift 0.1.0 → 0.1.2

package/README.md

@@ -3,45 +3,71 @@
 Docs that never lie: detect drift between merged code and docs, then open low-noise, evidence-grounded remediation via Devin sessions.
 
 ## Deliverables
-- TypeScript CLI package (`docdrift`)
+
+- **npm package**: [@devinnn/docdrift](https://www.npmjs.com/package/@devinnn/docdrift) — TypeScript CLI (`docdrift`)
   - `validate`
   - `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
 - PR template + Loom script
 
 ## 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
-- Tier 0: docs checks (`npm run docs:check`)
-- Tier 1: OpenAPI drift (`openapi/generated.json` vs `docs/reference/openapi.json`)
-- Tier 2: heuristic path impacts (e.g. `apps/api/src/auth/**` -> `docs/guides/auth.md`)
+## Detection and gate
+
+- **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/`):
+
 - `drift_report.json`
 - `metrics.json` (after `run`)
 
 When you run docdrift as a package (e.g. `npx docdrift` or from another repo), all of this is written to **that repo’s** `.docdrift/` — i.e. the current working directory where the CLI is invoked, not inside the package. Add `.docdrift/` to the consuming repo’s `.gitignore` if you don’t want to commit run artifacts.
 
 ## 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)
+
+| Path                                       | Purpose                                                                 |
+| ------------------------------------------ | ----------------------------------------------------------------------- |
+| `apps/docs-site/openapi/openapi.json`      | Published OpenAPI spec (docdrift updates this when drift is detected).  |
+| `apps/docs-site/docs/api/`                 | API reference MDX generated from the spec (`npm run docs:gen`).        |
+| `apps/docs-site/docs/guides/auth.md`       | Conceptual auth guide (updated only for conceptual drift).              |
+
+The docsite is a Docusaurus app with `docusaurus-plugin-openapi-docs`. The **generated** spec from code lives at `openapi/generated.json` (from `npm run openapi:export`). Drift = generated vs published differ. Verification runs `docs:gen` and `docs:build` so the docsite actually builds.
+
+## How Devin updates them
+
+1. **Evidence bundle** — Docdrift builds a tarball with the drift report, OpenAPI diff, and impacted doc snippets, and uploads it to the Devin API as session attachments.
+2. **Devin session** — Devin is prompted (see `src/devin/prompts.ts`) to update only files under the allowlist (`openapi/**`, `apps/docs-site/**`), make minimal correct edits, run verification (`npm run docs:gen`, `npm run docs:build`), and open **one PR** per doc area with a clear description.
+3. **PR** — Devin updates `apps/docs-site/openapi/openapi.json` to match the current API, runs `docs:gen` to regenerate API reference MDX, and opens a pull request. You review and merge; the docsite builds and the docs are updated.
+
+So the “fix” is a **PR opened by Devin** that you merge; the repo’s docs don’t change until that PR is merged.
 
 ## Local usage
+
 ```bash
 npm install
 npx tsx src/cli.ts validate
@@ -54,25 +80,29 @@ DEVIN_API_KEY=... GITHUB_TOKEN=... GITHUB_REPOSITORY=owner/repo GITHUB_SHA=<sha>
 
 You can run a full end-to-end demo locally with no remote repo. Ensure `.env` has `DEVIN_API_KEY` (and optionally `GITHUB_TOKEN` only when you have a real repo).
 
-1. **One-time setup (already done if you have two commits with drift)**  
-   - Git is inited; baseline commit has docs in sync with API.  
+1. **One-time setup (already done if you have two commits with drift)**
+   - Git is inited; baseline commit has docs in sync with API.
    - A later commit changes `apps/api/src/model.ts` (e.g. `name` → `fullName`) and runs `npm run openapi:export`, so `openapi/generated.json` drifts from `docs/reference/openapi.json`.
 
 2. **Run the pipeline**
+
    ```bash
    npm install
    npx tsx src/cli.ts validate
    npx tsx src/cli.ts detect --base b0f624f --head 6030902
    ```
+
    - Use your own `git log --oneline -3` to get `base` (older) and `head` (newer) SHAs if you recreated the demo.
 
 3. **Run with Devin (no GitHub calls)**  
    Omit `GITHUB_TOKEN` so the CLI does not post comments or create issues. Devin session still runs; results are printed to stdout and written to `.docdrift/state.json` and `metrics.json`.
+
    ```bash
    export $(grep -v '^#' .env | xargs)
    unset GITHUB_TOKEN GITHUB_REPOSITORY GITHUB_SHA
    npx tsx src/cli.ts run --base b0f624f --head 6030902
    ```
+
    - `run` can take 1–3 minutes while the Devin session runs.
 
 4. **What you’ll see**
@@ -93,14 +123,15 @@ You can run a full end-to-end demo locally with no remote repo. Ensure `.env` ha
 ## Run on GitHub
 
 1. **Create a repo** on GitHub (e.g. `your-org/docdrift`), then add the remote and push:
+
    ```bash
    git remote add origin https://github.com/your-org/docdrift.git
    git push -u origin main
    ```
 
 2. **Add secret**  
-   Repo → **Settings** → **Secrets and variables** → **Actions** → **New repository secret**  
-   - Name: `DEVIN_API_KEY`  
+   Repo → **Settings** → **Secrets and variables** → **Actions** → **New repository secret**
+   - Name: `DEVIN_API_KEY`
    - Value: your Devin API key (same as in `.env` locally)
 
    `GITHUB_TOKEN` is provided automatically; the workflow uses it for commit comments and issues.
@@ -109,6 +140,25 @@ You can run a full end-to-end demo locally with no remote repo. Ensure `.env` ha
    - **Push to `main`** — runs on every push (compares previous commit vs current).
    - **Manual run** — **Actions** tab → **devin-doc-drift** → **Run workflow** (uses `HEAD` and `HEAD^` as head/base).
 
+## See it work (demo on GitHub)
+
+This repo has **intentional drift**: the API has been expanded (new fields `fullName`, `avatarUrl`, `createdAt`, `role` and new endpoint `GET /v1/users` with pagination), but **docs are unchanged** (`docs/reference/openapi.json` and `docs/reference/api.md` still describe the old single-endpoint, `id`/`name`/`email` only). Running docdrift will detect that and hand a large diff to Devin to fix via a PR. To see it:
+
+1. **Create a new GitHub repo** (e.g. `docdrift-demo`) so you have a clean place to run the workflow.
+2. **Push this project with full history** (so both commits are on `main`):
+   ```bash
+   git remote add origin https://github.com/YOUR_ORG/docdrift-demo.git
+   git push -u origin main
+   ```
+3. **Add secret** in that repo: **Settings** → **Secrets and variables** → **Actions** → `DEVIN_API_KEY` = your Devin API key.
+4. **Trigger the workflow**
+   - Either push another small commit (e.g. README tweak), or
+   - **Actions** → **devin-doc-drift** → **Run workflow**.
+5. **Where to look**
+   - **Actions** → open the run → **Run Doc Drift** step: the step logs print JSON with `sessionUrl`, `prUrl`, and `outcome` per doc area. Open any `sessionUrl` in your browser to see the Devin session.
+   - **Artifacts**: download **docdrift-artifacts** for `.docdrift/drift_report.json`, `.docdrift/metrics.json`, and evidence.
+   - **Devin dashboard**: sessions are tagged `docdrift`; you’ll see the run there once the step completes (often 1–3 minutes).
+
 ## Using in another repo (published package)
 
 Once published to npm, any repo can use the CLI locally or in GitHub Actions.
@@ -116,14 +166,14 @@ Once published to npm, any repo can use the CLI locally or in GitHub Actions.
 1. **In the consuming repo** add a `docdrift.yaml` at the root (see this repo’s `docdrift.yaml` and `docdrift-yml.md`).
 2. **CLI**
    ```bash
-   npx docdrift@latest validate
-   npx docdrift@latest detect --base <base-sha> --head <head-sha>
+   npx @devinnn/docdrift validate
+   npx @devinnn/docdrift detect --base <base-sha> --head <head-sha>
    # With env for run:
-   DEVIN_API_KEY=... GITHUB_TOKEN=... GITHUB_REPOSITORY=owner/repo GITHUB_SHA=<sha> npx docdrift@latest run --base <base-sha> --head <head-sha>
+   DEVIN_API_KEY=... GITHUB_TOKEN=... GITHUB_REPOSITORY=owner/repo GITHUB_SHA=<sha> npx @devinnn/docdrift run --base <base-sha> --head <head-sha>
    ```
 3. **GitHub Actions** — add a step that runs the CLI (e.g. after checkout and setting base/head):
    ```yaml
-   - run: npx docdrift@latest run --base ${{ steps.shas.outputs.base }} --head ${{ steps.shas.outputs.head }}
+   - run: npx @devinnn/docdrift run --base ${{ steps.shas.outputs.base }} --head ${{ steps.shas.outputs.head }}
      env:
        DEVIN_API_KEY: ${{ secrets.DEVIN_API_KEY }}
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -140,8 +190,10 @@ Once published to npm, any repo can use the CLI locally or in GitHub Actions.
 - Only the `dist/` directory is included (`files` in `package.json`). Consumers get the built CLI; they provide their own `docdrift.yaml` in their repo.
 
 ## Demo scenario
+
 - Autogen drift: rename a field in `apps/api/src/model.ts`, merge to `main`, observe docs PR path.
 - Conceptual drift: change auth behavior under `apps/api/src/auth/**`, merge to `main`, observe single escalation issue.
 
 ## Loom
+
 See `/Users/cameronking/Desktop/sideproject/docdrift/loom.md` for the minute-by-minute recording script.

package/dist/src/cli.js

@@ -1,6 +1,11 @@
 #!/usr/bin/env node
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
 const index_1 = require("./index");
 function getArg(args, flag) {
     const index = args.indexOf(flag);
@@ -12,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": {
@@ -32,6 +37,9 @@ async function main() {
             const headSha = (0, index_1.requireSha)(getArg(args, "--head"), "--head");
             const trigger = (0, index_1.resolveTrigger)(process.env.GITHUB_EVENT_NAME);
             const results = await (0, index_1.runDocDrift)({ baseSha, headSha, trigger });
+            const outPath = node_path_1.default.resolve(".docdrift", "run-output.json");
+            node_fs_1.default.mkdirSync(node_path_1.default.dirname(outPath), { recursive: true });
+            node_fs_1.default.writeFileSync(outPath, JSON.stringify(results, null, 2), "utf-8");
             console.log(JSON.stringify(results, null, 2));
             return;
         }
@@ -41,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);
@@ -21,5 +23,23 @@ function loadConfig(configPath = "docdrift.yaml") {
             .join("\n");
         throw new Error(`Invalid config:\n${message}`);
     }
-    return result.data;
+    const data = result.data;
+    if (data.devin.customInstructions?.length) {
+        const configDir = node_path_1.default.dirname(resolved);
+        const contents = [];
+        for (const p of data.devin.customInstructions) {
+            const fullPath = node_path_1.default.resolve(configDir, p);
+            if (!node_fs_1.default.existsSync(fullPath)) {
+                throw new Error(`Custom instructions file not found: ${fullPath}`);
+            }
+            contents.push(node_fs_1.default.readFileSync(fullPath, "utf8"));
+        }
+        data.devin.customInstructionContent = contents.join("\n\n");
+    }
+    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,55 +1,85 @@
 "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),
-    impacts: zod_1.z.array(zod_1.z.string().min(1)).min(1)
+    impacts: zod_1.z.array(zod_1.z.string().min(1)).min(1),
 });
 const openApiDetectSchema = zod_1.z.object({
     exportCmd: zod_1.z.string().min(1),
     generatedPath: zod_1.z.string().min(1),
-    publishedPath: 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"]),
     owners: zod_1.z.object({
-        reviewers: zod_1.z.array(zod_1.z.string().min(1)).min(1)
+        reviewers: zod_1.z.array(zod_1.z.string().min(1)).min(1),
     }),
     detect: zod_1.z
         .object({
         openapi: openApiDetectSchema.optional(),
-        paths: zod_1.z.array(pathRuleSchema).optional()
+        paths: zod_1.z.array(pathRuleSchema).optional(),
     })
         .refine((v) => Boolean(v.openapi) || Boolean(v.paths?.length), {
-        message: "docArea.detect must include openapi or paths"
+        message: "docArea.detect must include openapi or paths",
     }),
     patch: zod_1.z.object({
         targets: zod_1.z.array(zod_1.z.string().min(1)).optional(),
-        requireHumanConfirmation: zod_1.z.boolean().optional().default(false)
-    })
+        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),
         maxAcuLimit: zod_1.z.number().int().positive().default(2),
-        tags: zod_1.z.array(zod_1.z.string().min(1)).default(["docdrift"])
+        tags: zod_1.z.array(zod_1.z.string().min(1)).default(["docdrift"]),
+        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/docsCheck.js

@@ -21,7 +21,7 @@ async function runDocsChecks(commands, evidenceDir) {
             "\n--- stdout ---",
             result.stdout,
             "\n--- stderr ---",
-            result.stderr
+            result.stderr,
         ].join("\n"), "utf8");
         logs.push(logPath);
         commandResults.push({ command, exitCode: result.exitCode, logPath });
@@ -31,7 +31,7 @@ async function runDocsChecks(commands, evidenceDir) {
         return {
             logs,
             commandResults,
-            summary: "Docs checks passed"
+            summary: "Docs checks passed",
         };
     }
     return {
@@ -42,7 +42,7 @@ async function runDocsChecks(commands, evidenceDir) {
             kind: "docs_check_failed",
             tier: 0,
             confidence: 0.99,
-            evidence: failed.map((result) => result.logPath)
-        }
+            evidence: failed.map((result) => result.logPath),
+        },
     };
 }

package/dist/src/detect/heuristics.js

@@ -38,7 +38,7 @@ function detectHeuristicImpacts(docArea, changedPaths, evidenceDir) {
             kind: "heuristic_path_impact",
             tier: 2,
             confidence: 0.67,
-            evidence: [evidencePath]
-        }
+            evidence: [evidencePath],
+        },
     };
 }

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()}`,
@@ -26,32 +16,47 @@ async function buildDriftReport(input) {
         baseSha: input.baseSha,
         headSha: input.headSha,
         trigger: input.trigger,
-        timestamp: new Date().toISOString()
+        timestamp: new Date().toISOString(),
     };
     const evidenceRoot = node_path_1.default.resolve(".docdrift", "evidence", runInfo.runId);
     (0, fs_1.ensureDir)(evidenceRoot);
     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,33 +65,37 @@ 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,
             baseSha: input.baseSha,
             headSha: input.headSha,
             trigger: input.trigger,
-            timestamp: runInfo.timestamp
+            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,
+    };
 }