@luizsantiago/spec-guardrails 4.2.1 → 4.5.0

package/README.md

@@ -1,13 +1,17 @@
 # Spec Guardrails
 
 [![npm version](https://img.shields.io/npm/v/@luizsantiago/spec-guardrails.svg)](https://www.npmjs.com/package/@luizsantiago/spec-guardrails)
+[![npm downloads](https://img.shields.io/npm/dm/@luizsantiago/spec-guardrails.svg)](https://www.npmjs.com/package/@luizsantiago/spec-guardrails)
+[![CI](https://github.com/luizssantiago92/spec-guardrails/actions/workflows/ci.yml/badge.svg)](https://github.com/luizssantiago92/spec-guardrails/actions/workflows/ci.yml)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
+![Spec Guardrails — governed spec-driven development for AI coding agents](https://raw.githubusercontent.com/luizssantiago92/spec-guardrails/main/.assets/banner.svg)
+
 **Governed spec-driven development for AI coding agents.**
 
 Spec Guardrails installs a working method into your repository: the agent writes down what it is going to build, gets your approval, implements in small waves, and proves the result before calling it done. Nothing about your stack changes — you get written requirements, a task plan, and verification evidence stored as files in the project.
 
-npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **4.2.x**
+npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **4.5.x**
 
 ---
 
@@ -63,64 +67,11 @@ Read more: [Quick start](docs/guide/Quick-start.md) · [Platform parity](docs/gu
 
 You describe your project or the feature you want — in chat, or by pointing the agent at a file such as `prd.md` or `docs/brief.md`. With Spec Guardrails already installed, the agent reads that material plus what is already in the repo and picks up from there if work is in progress (`STATE.md` tells it where you left off).
 
-```
-     YOU describe the project or feature
-     (chat, prd.md, docs/brief.md, kickoff paste)
-              │
-              ▼
-   ┌──────────────────────┐
-   │  READ & CLASSIFY     │   Agent reads your inputs and the repo,
-   │                      │   then sizes the change (see table below).
-   └──────────┬───────────┘
-              │
-        Still vague? ──► Requirements analysis (optional)
-              │          Up to 5 questions per round, one topic at a time,
-              │          with suggested options — never repeats what your
-              │          document already answered.
-              ▼
-   ┌──────────────────────┐
-   │  REQUIREMENTS BRIEF  │   Captured gaps and decisions in writing.
-   └──────────┬───────────┘
-              │
-        ◆ YOU APPROVE ◆        (1 of 3 — when elicitation ran)
-              │
-              ▼
-   ┌──────────────────────┐
-   │  SPECIFY             │   What must happen, what "done" means,
-   │                      │   what is out of scope → spec.md
-   └──────────┬───────────┘
-              │
-        ◆ YOU APPROVE ◆        (2 of 3)
-              │
-              ▼
-   ┌──────────────────────┐
-   │  TASKS               │   Small checkable jobs → tasks.md
-   │                      │   (+ task-graph.md when work can split)
-   └──────────┬───────────┘
-              │
-        ◆ YOU APPROVE ◆        (3 of 3)
-              │
-              ▼
-   ┌──────────────────────┐
-   │  BUILD (loop)        │   One wave at a time: test, implement,
-   │        ↺             │   check, commit — repeat until done.
-   └──────────┬───────────┘
-              ▼
-   ┌──────────────────────┐
-   │  VERIFY              │   Independent review with proof → validation.md
-   └──────────┬───────────┘
-              ▼
-   ┌──────────────────────┐
-   │  ARCHIVE             │   Fold outcome into project memory.
-   └──────────────────────┘
-
-   Tiny fix (≤3 files, no new dependency)?
-   Express lane: build → verify → commit (no spec/tasks ceremony).
-```
+![Spec Guardrails phase flow — classify, optional elicitation, three human approvals, build loop, verify, archive](https://raw.githubusercontent.com/luizssantiago92/spec-guardrails/main/.assets/flow.svg)
 
 The agent never skips your approvals on the full path. Requirements analysis is **suggested**, not forced — if the request is already clear, it goes straight to Specify.
 
-Read more: [How it works](docs/guide/How-it-works.md) · [Agent commands](docs/guide/agent-commands.md)
+Read more: [How it works](docs/guide/How-it-works.md) · [Agent commands](docs/guide/agent-commands.md) · [Glossary](docs/guide/Glossary.md)
 
 ---
 
@@ -128,6 +79,8 @@ Read more: [How it works](docs/guide/How-it-works.md) · [Agent commands](docs/g
 
 Before starting, the agent classifies the change and loads only what that change needs. A typo does not get a task graph; a payments integration does not skip review.
 
+![Complexity tiers — Quick, Simple, Medium, Complex, Parallel](https://raw.githubusercontent.com/luizssantiago92/spec-guardrails/main/.assets/tiers.svg)
+
 | Complexity | Typical scope | What gets created | Your approvals |
 | --- | --- | --- | --- |
 | **Quick** | ≤3 files, no new dependency, no auth/payments | Code + quick evidence | None (express lane) |
@@ -173,7 +126,7 @@ Instructions the agent loads **one at a time** — hub `agent-architecture.md` (
 
 → [Skills and hub](docs/guide/skills-and-hub.md)
 
-### Gates (9)
+### Gates (11)
 
 Automatic checks at step boundaries — each one blocks a specific kind of shortcut:
 
@@ -187,6 +140,8 @@ Automatic checks at step boundaries — each one blocks a specific kind of short
 | `validate-state` | Feature is declared done without evidence |
 | `validate-quick` | Quick-mode fix broke its size or shape rules |
 | `check-commit` | Commit message does not follow the agreed format |
+| `check-suppressions` | Staged diff adds `# noqa`, `eslint-disable`, `@ts-ignore`, skipped tests, or `--no-verify` |
+| `quality-checks` | Configured project commands (`npm test`, …) fail during `/verify` |
 | `lessons` | A failed verify tries to skip the lesson step |
 
 → [Gates](docs/guide/gates.md) · [Garantees matrix](docs/guide/Guarantees-matrix.md)
@@ -213,10 +168,9 @@ Implementation happens in **small waves**: pick the next runnable jobs, test, im
 
 | Capability | What it adds |
 | --- | --- |
-| **Cursor IDE hooks** | Scope check before file edits and shell-command policy on Cursor — disabled by default; requirements analysis can ask if you want them; you can also enable or disable anytime in chat |
 | **Semantic memory search** | Find past specs and decisions by meaning, not just keywords |
 
-→ [Cursor hooks and sandbox](docs/guide/Cursor-hooks-and-sandbox.md) · [Memory](docs/guide/Memory.md)
+→ [Memory](docs/guide/Memory.md)
 
 ---
 
@@ -224,7 +178,7 @@ Implementation happens in **small waves**: pick the next runnable jobs, test, im
 
 | Path | Role |
 | --- | --- |
-| `.cursor/skills/` (+ Claude, Copilot, Codex trees) | Phase instructions for the agent |
+| `.cursor/skills/` (or detected platform tree) | Phase instructions for your agent |
 | `.specs/STATE.md` | Active feature and next step |
 | `.specs/features/NNN-slug/` | Spec, tasks, and validation per feature |
 | `.specs/guardrails/scripts/` | Python checks (when Brakes mode is on) |
@@ -232,6 +186,21 @@ Implementation happens in **small waves**: pick the next runnable jobs, test, im
 
 ---
 
+## Honest limits
+
+Gates enforce **structure and evidence in `.specs/`** — not product taste, not whether your tests are clever, and not a full AST review of implementation code. A green gate means the artifact shape and cited proof look complete; you still approve specs and tasks.
+
+| Gates check | Gates do **not** check |
+| --- | --- |
+| Spec sections and `SHALL`/`MUST` criteria | Semantic alignment between tests and requirements |
+| REQ → task → validation traceability | Stub or broken source outside cited paths |
+| Commit message shape and suppression patterns | Whether coverage % equals test quality |
+| Commands you list under `quality.checks` | Commands you never configured |
+
+See [Guarantees matrix](docs/guide/Guarantees-matrix.md) for the full product view.
+
+---
+
 ## Documentation
 
 | Topic | Start here | Go deeper |
@@ -242,8 +211,7 @@ Implementation happens in **small waves**: pick the next runnable jobs, test, im
 | Enforcement | [Gates](docs/guide/gates.md) | [Gates and guarantees](docs/guide/Gates-and-guarantees.md) |
 | Requirements | [Requirements analysis](docs/guide/requirements-analysis.md) | [Agent commands → /elicit](docs/guide/agent-commands.md) |
 | Long-running projects | [Memory](docs/guide/Memory.md) | [Brownfield context](docs/guide/brownfield-context.md) |
-| Cursor IDE (optional) | [Cursor hooks and sandbox](docs/guide/Cursor-hooks-and-sandbox.md) | [Guarantees matrix](docs/guide/Guarantees-matrix.md) |
-| Questions | [FAQ](docs/guide/FAQ.md) | [Stability policy](docs/guide/Stability-policy.md) |
+| Questions | [FAQ](docs/guide/FAQ.md) | [Glossary](docs/guide/Glossary.md) · [Stability policy](docs/guide/Stability-policy.md) |
 
 Full index: [docs/guide/README.md](docs/guide/README.md)
 
@@ -251,26 +219,7 @@ Full index: [docs/guide/README.md](docs/guide/README.md)
 
 ## Contributing
 
-Focused improvements to skills, gates, CLI, docs, and tests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for repository layout, gate stability rules, and local checks.
-
-**Build your contribution with Spec Guardrails.** In your own project or fork, install the latest stable release and let the phases guide the change:
-
-```bash
-npx @luizsantiago/spec-guardrails@latest install
-npx @luizsantiago/spec-guardrails doctor
-```
-
-Describe the change in chat, approve the spec and the task plan, implement, and verify before opening the pull request — the resulting `.specs/` folder is the evidence that supports your PR.
-
-**In this source repository**, work against your branch instead of the published package:
-
-```bash
-git clone https://github.com/luizssantiago92/spec-guardrails.git
-cd spec-guardrails
-npm install
-npm run guardrails -- install
-npm run guardrails -- doctor
-```
+Focused improvements are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for layout, gate stability rules, and local checks.
 
 Edit sources under `skills/`, `lib/`, `scripts/`, and `rules/`; re-run `npm run guardrails -- install` after changing shipped assets, and run `npm test` before every PR.
 

package/index.js

@@ -28,6 +28,7 @@ import { featureInit } from "./lib/feature.js";
 import { featureStatus, formatFeatureStatus } from "./lib/feature-status.js";
 import { GATE_COMMANDS, AUX_COMMANDS, runGate, runGuardrailsScript } from "./lib/gates.js";
 import { install } from "./lib/install.js";
+import { parsePlatformArg } from "./lib/platform-detect.js";
 import {
   cleanupWorkspaces,
   formatWorkspaceList,
@@ -67,8 +68,8 @@ Commands:
   install                            Install skills, references, gates and .specs/ memory
     [--preset <name>]                Seed .specs/config.yaml from a built-in preset
     [--force-config]                 Replace existing config.yaml when using --preset
-    [--with-cursor-hooks]            Register Cursor IDE hooks (off by default)
-    [--without-cursor-hooks]         Remove shipped Cursor hooks and set cursor.hooks: false
+    [--all-platforms]                Install every skill tree (Cursor, Claude, Copilot, Codex)
+    [--platform cursor|claude|copilot|codex]  Force a platform instead of auto-detect
   init-config [--preset <name>]      Create .specs/config.yaml (default preset: default)
     [--force]                        Replace existing config.yaml
   preset list                        List built-in config presets
@@ -127,6 +128,7 @@ Commands:
   execution-policy record-run        Increment agent-run counter (blocks at budget)
   memory-index rebuild               Rebuild SQLite memory index from .specs/ artifacts
   memory-index embed [--force]       Optional semantic embeddings (requires config + provider)
+  memory-index status [--json]       Index chunk, embedding, and staleness stats
   memory-query --from <id>           Bounded context package from the knowledge graph
     [--depth N]                      Traversal depth (default 2)
     [--json]                         Machine-readable output
@@ -178,6 +180,9 @@ Commands:
   validate-req-analysis [brief.md]   Requirements brief gate before /specify (/elicit)
   validate-state [feature]           Completion gate before declaring a feature done
   check-commit --message "<msg>"     Conventional Commits gate
+    [--staged]                       Also reject empty commits and oversized staged diffs
+  check-suppressions                 Block noqa/eslint-disable/ts-ignore/skip in staged diff
+  quality-checks [--json]            Run quality.checks from .specs/config.yaml (/verify)
   lessons <add|list|penalize|prune|promote|graduate|status>  Lessons engine
   --help                             Show this message
   --version                          Print the package version
@@ -195,6 +200,7 @@ if (command === "--version" || command === "-v" || command === "version") {
 } else if (command === "install") {
   try {
     const installOptions = {};
+    let deprecatedCursorHooksFlag = false;
     for (let i = 0; i < args.length; i++) {
       const arg = args[i];
       if (arg === "--preset") {
@@ -204,15 +210,34 @@ if (command === "--version" || command === "-v" || command === "version") {
         }
       } else if (arg === "--force-config") {
         installOptions.forceConfig = true;
-      } else if (arg === "--with-cursor-hooks") {
-        installOptions.withCursorHooks = true;
-      } else if (arg === "--without-cursor-hooks") {
-        installOptions.withoutCursorHooks = true;
+      } else if (arg === "--all-platforms") {
+        installOptions.allPlatforms = true;
+      } else if (arg === "--platform") {
+        const platform = parsePlatformArg(args[++i] ?? "");
+        if (!platform) {
+          throw new Error(
+            "--platform requires cursor, claude, copilot, or codex.",
+          );
+        }
+        installOptions.platform = platform;
+      } else if (arg === "--with-cursor-hooks" || arg === "--without-cursor-hooks") {
+        deprecatedCursorHooksFlag = true;
       } else {
         throw new Error(`Unknown install flag: ${arg}`);
       }
     }
 
+    if (deprecatedCursorHooksFlag) {
+      console.warn(
+        "⚠️  --with-cursor-hooks / --without-cursor-hooks are deprecated (removed in 4.3.0). " +
+          "Running install normally; legacy hook artifacts are cleaned automatically.",
+      );
+    }
+
+    if (installOptions.allPlatforms && installOptions.platform) {
+      throw new Error("Use either --all-platforms or --platform, not both.");
+    }
+
     await install(installOptions);
   } catch (err) {
     console.error(`❌ ${err.message}`);

package/lib/adapter-registry.js

@@ -11,7 +11,6 @@ import { injectCursorRules } from "./cursorrules.js";
  *   skillsDir: string | null,
  *   entryFiles: string[],
  *   capabilities: {
- *     supports_hooks: boolean,
  *     supports_commands: boolean,
  *     supports_rules: boolean,
  *     supports_skills: boolean,
@@ -28,7 +27,6 @@ export const ADAPTER_REGISTRY = [
     skillsDir: ".cursor/skills",
     entryFiles: [".cursorrules", ".cursor/rules/engineering-baseline.mdc"],
     capabilities: {
-      supports_hooks: true,
       supports_commands: true,
       supports_rules: true,
       supports_skills: true,
@@ -41,7 +39,6 @@ export const ADAPTER_REGISTRY = [
     skillsDir: ".claude/skills",
     entryFiles: [".claude/CLAUDE.md"],
     capabilities: {
-      supports_hooks: false,
       supports_commands: true,
       supports_rules: false,
       supports_skills: true,
@@ -54,7 +51,6 @@ export const ADAPTER_REGISTRY = [
     skillsDir: ".github/skills",
     entryFiles: [".github/copilot-instructions.md"],
     capabilities: {
-      supports_hooks: false,
       supports_commands: false,
       supports_rules: false,
       supports_skills: true,
@@ -67,7 +63,6 @@ export const ADAPTER_REGISTRY = [
     skillsDir: ".codex/skills",
     entryFiles: [".codex/AGENTS.md"],
     capabilities: {
-      supports_hooks: false,
       supports_commands: false,
       supports_rules: false,
       supports_skills: true,
@@ -80,7 +75,6 @@ export const ADAPTER_REGISTRY = [
     skillsDir: null,
     entryFiles: ["AGENTS.md"],
     capabilities: {
-      supports_hooks: false,
       supports_commands: false,
       supports_rules: false,
       supports_skills: false,
@@ -124,5 +118,23 @@ export async function installAdapter(cwd, adapter) {
  * @param {string} cwd
  */
 export async function installAllAdapters(cwd) {
-  await Promise.all(ADAPTER_REGISTRY.map((adapter) => installAdapter(cwd, adapter)));
+  await installAdapters(
+    cwd,
+    ADAPTER_REGISTRY.map((adapter) => adapter.id),
+  );
+}
+
+/**
+ * Install selected platform adapters by id.
+ *
+ * @param {string} cwd
+ * @param {string[]} adapterIds
+ */
+export async function installAdapters(cwd, adapterIds) {
+  const wanted = new Set(adapterIds);
+  await Promise.all(
+    ADAPTER_REGISTRY.filter((adapter) => wanted.has(adapter.id)).map((adapter) =>
+      installAdapter(cwd, adapter),
+    ),
+  );
 }

package/lib/adapters.js

@@ -1,11 +1,15 @@
-import { installAllAdapters } from "./adapter-registry.js";
+import { installAdapters, installAllAdapters } from "./adapter-registry.js";
 
 /**
  * Install shipped platform adapter entry files (Copilot, Codex, AGENTS.md).
  * Cursor and Claude adapters are injected via the same registry during install.
  *
  * @param {string} cwd
+ * @param {{ adapterIds?: string[] }} [options]
  */
-export async function installPlatformAdapters(cwd) {
+export async function installPlatformAdapters(cwd, options = {}) {
+  if (options.adapterIds) {
+    return installAdapters(cwd, options.adapterIds);
+  }
   return installAllAdapters(cwd);
 }

package/lib/constants.js

@@ -120,6 +120,9 @@ export const SCRIPT_ASSETS = [
   { file: "code_index.py", remotePath: "scripts/code_index.py" },
   { file: "validate_req_analysis.py", remotePath: "scripts/validate_req_analysis.py" },
   { file: "req_context.py", remotePath: "scripts/req_context.py" },
+  { file: "check_suppressions.py", remotePath: "scripts/check_suppressions.py" },
+  { file: "run_quality_checks.py", remotePath: "scripts/run_quality_checks.py" },
+  { file: "_project_config.py", remotePath: "scripts/_project_config.py" },
 ];
 
 /** @type {{ file: string, remotePath: string }[]} */

package/lib/cursor-hooks-cleanup.js

@@ -0,0 +1,172 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { readFileSafe } from "./fs-utils.js";
+
+export const CURSOR_HOOK_EDIT = ".cursor/hooks/context-guard-edit.mjs";
+export const CURSOR_HOOK_SANDBOX = ".cursor/hooks/sandbox-shell.mjs";
+export const CURSOR_HOOKS_JSON = ".cursor/hooks.json";
+
+/** @type {readonly string[]} */
+const SHIPPED_HOOK_SCRIPTS = [CURSOR_HOOK_EDIT, CURSOR_HOOK_SANDBOX];
+
+/** @type {Set<string>} */
+const SHIPPED_HOOK_COMMANDS = new Set(SHIPPED_HOOK_SCRIPTS);
+
+/**
+ * @param {unknown} hooks
+ * @returns {boolean}
+ */
+function hooksObjectHasShippedEntries(hooks) {
+  if (!hooks || typeof hooks !== "object") {
+    return false;
+  }
+
+  for (const entries of Object.values(hooks)) {
+    if (!Array.isArray(entries)) {
+      continue;
+    }
+    if (entries.some((entry) => SHIPPED_HOOK_COMMANDS.has(/** @type {{ command?: string }} */ (entry).command))) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * @param {unknown} hooks
+ * @returns {boolean}
+ */
+function hooksObjectHasUserEntries(hooks) {
+  if (!hooks || typeof hooks !== "object") {
+    return false;
+  }
+
+  for (const entries of Object.values(hooks)) {
+    if (!Array.isArray(entries)) {
+      continue;
+    }
+    if (
+      entries.some(
+        (entry) =>
+          /** @type {{ command?: string }} */ (entry).command &&
+          !SHIPPED_HOOK_COMMANDS.has(/** @type {{ command?: string }} */ (entry).command),
+      )
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * @param {string} filePath
+ * @returns {Promise<boolean>}
+ */
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Remove the `cursor:` block from `.specs/config.yaml` when present.
+ *
+ * @param {string} cwd
+ * @returns {Promise<boolean>}
+ */
+async function removeCursorBlockFromConfig(cwd) {
+  const configPath = path.join(cwd, ".specs/config.yaml");
+  let text;
+  try {
+    text = await readFileSafe(configPath);
+  } catch {
+    return false;
+  }
+
+  if (!/^cursor:/m.test(text)) {
+    return false;
+  }
+
+  text = text.replace(/^cursor:\s*\n(?:[ \t#].*\n)*/m, "");
+  text = `${text.replace(/\n{3,}/g, "\n\n").trimEnd()}\n`;
+  await fs.writeFile(configPath, text, "utf8");
+  return true;
+}
+
+/**
+ * Remove legacy Cursor IDE hook artifacts shipped before 4.3.0.
+ * Idempotent and silent when nothing remains to clean.
+ *
+ * @param {string} cwd
+ * @param {{ log?: (message: string) => void }} [options]
+ * @returns {Promise<{ changed: boolean }>}
+ */
+export async function cleanupLegacyCursorHooks(cwd, options = {}) {
+  const log = options.log ?? (() => {});
+  let changed = false;
+
+  for (const script of SHIPPED_HOOK_SCRIPTS) {
+    const scriptPath = path.join(cwd, script);
+    if (await fileExists(scriptPath)) {
+      await fs.unlink(scriptPath);
+      changed = true;
+    }
+  }
+
+  const hooksJsonPath = path.join(cwd, CURSOR_HOOKS_JSON);
+  if (await fileExists(hooksJsonPath)) {
+    try {
+      const existing = JSON.parse(await readFileSafe(hooksJsonPath));
+      const hadShipped = hooksObjectHasShippedEntries(existing.hooks);
+
+      if (existing.hooks && typeof existing.hooks === "object") {
+        for (const [event, entries] of Object.entries(existing.hooks)) {
+          if (!Array.isArray(entries)) {
+            continue;
+          }
+          existing.hooks[event] = entries.filter(
+            (entry) => !SHIPPED_HOOK_COMMANDS.has(/** @type {{ command?: string }} */ (entry).command),
+          );
+        }
+      }
+
+      const userHooksRemain = hooksObjectHasUserEntries(existing.hooks);
+      const isEffectivelyEmpty =
+        !existing.hooks ||
+        Object.values(existing.hooks).every(
+          (entries) => !Array.isArray(entries) || entries.length === 0,
+        );
+
+      if (hadShipped || isEffectivelyEmpty) {
+        changed = true;
+        if (userHooksRemain) {
+          await fs.writeFile(hooksJsonPath, `${JSON.stringify(existing, null, 2)}\n`, "utf8");
+        } else {
+          await fs.unlink(hooksJsonPath);
+        }
+      }
+    } catch {
+      await fs.unlink(hooksJsonPath);
+      changed = true;
+    }
+  }
+
+  if (await removeCursorBlockFromConfig(cwd)) {
+    changed = true;
+  }
+
+  if (changed) {
+    log(
+      "ℹ️  Cursor IDE hooks removed (deprecated in 4.3.0). " +
+        "Scope and sandbox checks remain available via context-guard and sandbox CLI commands.",
+    );
+  }
+
+  return { changed };
+}

package/lib/doctor.js

@@ -6,10 +6,14 @@ import { promisify } from "node:util";
 import {
   CURSORRULES_MARKER_BEGIN,
   NPX,
-  SKILL_DIRS,
 } from "./constants.js";
+import { getAdapter } from "./adapter-registry.js";
 import { resolvePython, resolveScriptsDir } from "./gates.js";
 import { readFileSafe } from "./fs-utils.js";
+import {
+  resolveAdapterInstallTargets,
+  resolveInstalledSkillDirs,
+} from "./platform-detect.js";
 import { listFeatureIds, readActiveFeatureFromState } from "./specs-utils.js";
 import { resolveMemoryHint } from "./memory-doctor.js";
 
@@ -30,27 +34,30 @@ export const DOCTOR_BRAKES_CHECK_IDS = [
   "gate-smoke",
 ];
 
-const ADAPTER_CONTRACT_PATHS = [
-  ".cursorrules",
-  ".claude/CLAUDE.md",
-  ".github/copilot-instructions.md",
-  "AGENTS.md",
-  ".codex/AGENTS.md",
-];
-
 /**
  * @param {string} cwd
+ * @param {string[]} adapterIds
  * @returns {Promise<boolean>}
  */
-async function hasPlatformAdapterContract(cwd) {
-  for (const relativePath of ADAPTER_CONTRACT_PATHS) {
-    try {
-      const content = await readFileSafe(path.join(cwd, relativePath));
-      if (!content.includes(CURSORRULES_MARKER_BEGIN)) {
+async function hasPlatformAdapterContract(cwd, adapterIds) {
+  for (const adapterId of adapterIds) {
+    const adapter = getAdapter(adapterId);
+    if (!adapter) {
+      return false;
+    }
+
+    for (const relativePath of adapter.entryFiles) {
+      if (relativePath.endsWith(".mdc")) {
+        continue;
+      }
+      try {
+        const content = await readFileSafe(path.join(cwd, relativePath));
+        if (!content.includes(CURSORRULES_MARKER_BEGIN)) {
+          return false;
+        }
+      } catch {
         return false;
       }
-    } catch {
-      return false;
     }
   }
   return true;
@@ -107,15 +114,20 @@ export async function runDoctorChecks(cwd) {
   /** @type {DoctorCheck[]} */
   const checks = [];
 
+  const installedSkillDirs = await resolveInstalledSkillDirs(cwd);
   const hubResults = await Promise.all(
-    SKILL_DIRS.map((dir) => pathExists(cwd, path.join(dir, "agent-architecture.md"))),
+    installedSkillDirs.map((dir) =>
+      pathExists(cwd, path.join(dir, "agent-architecture.md")),
+    ),
   );
   const hubInstalled = hubResults.every(Boolean);
-  const missingHubDirs = SKILL_DIRS.filter((_dir, index) => !hubResults[index]);
+  const missingHubDirs = installedSkillDirs.filter(
+    (_dir, index) => !hubResults[index],
+  );
 
   checks.push({
     id: "skills-hub",
-    label: "Agent hub skill in all adapter trees (agent-architecture.md)",
+    label: "Agent hub skill in installed adapter trees (agent-architecture.md)",
     weight: 12,
     pass: hubInstalled,
     suggest: hubInstalled
@@ -181,11 +193,18 @@ export async function runDoctorChecks(cwd) {
     optional: true,
   });
 
+  const adapterIds = await resolveAdapterInstallTargets(cwd, {
+    skillDirs: installedSkillDirs,
+  });
+  const adapterLabels = adapterIds
+    .map((id) => getAdapter(id)?.label ?? id)
+    .join(", ");
+
   checks.push({
     id: "platform-adapters",
-    label: "Platform adapter contracts (Cursor, Claude, Copilot, Codex, AGENTS.md)",
+    label: `Platform adapter contracts (${adapterLabels})`,
     weight: 5,
-    pass: await hasPlatformAdapterContract(cwd),
+    pass: await hasPlatformAdapterContract(cwd, adapterIds),
     suggest: NPX("install"),
   });
 

package/lib/gates.js

@@ -37,6 +37,8 @@ const GATE_SCRIPTS = {
   "validate-req-analysis": "validate_req_analysis.py",
   "analyze-artifacts": "analyze_artifacts.py",
   "check-commit": "check_commit.py",
+  "check-suppressions": "check_suppressions.py",
+  "quality-checks": "run_quality_checks.py",
   lessons: "lessons.py",
 };