@hiro-c/agent-gate 1.3.0 → 1.5.0

package/README.md

@@ -74,7 +74,7 @@ Full options: see [docs/config.md](docs/config.md) (TODO) or `AgentGatePluginCon
 |---|---|
 | `agent-gate` | Run as hook (reads stdin, used internally) |
 | `agent-gate install` / `uninstall` | Register or remove the Claude Code hook |
-| `agent-gate lint` | Audit instruction files for ambiguity, emptiness, missing rules |
+| `agent-gate lint [--ai]` | Audit instruction files for ambiguity, emptiness, missing rules. `--ai` adds AI-driven contradiction / ambiguity / missing-imperative checks |
 | `agent-gate stats` | Summarize the decision log (after `AGENT_GATE_LOG=1`) |
 | `agent-gate daemon` | Long-lived server on a Unix socket (opt-in speedup, set `AGENT_GATE_DAEMON=1`) |
 

package/dist/cli/agent-gate.d.ts

@@ -7,6 +7,7 @@ interface ParsedArgs {
     agentId: string;
     showHelp: boolean;
     showVersion: boolean;
+    ai: boolean;
 }
 export declare function parseArgs(args: string[]): ParsedArgs;
 export {};

package/dist/cli/agent-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-gate.d.ts","sourceRoot":"","sources":["../../src/cli/agent-gate.ts"],"names":[],"mappings":";AAIA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAA;AAYtE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAuC7C,wBAAsB,GAAG,CACvB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,OAAO,GAChB,OAAO,CAAC,gBAAgB,CAAC,CAE3B;AAuHD,UAAU,UAAU;IAClB,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,OAAO,CAAA;IACjB,WAAW,EAAE,OAAO,CAAA;CACrB;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAgCpD"}
+{"version":3,"file":"agent-gate.d.ts","sourceRoot":"","sources":["../../src/cli/agent-gate.ts"],"names":[],"mappings":";AAIA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAA;AAYtE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AA4C7C,wBAAsB,GAAG,CACvB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,OAAO,GAChB,OAAO,CAAC,gBAAgB,CAAC,CAE3B;AAuHD,UAAU,UAAU;IAClB,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,OAAO,CAAA;IACjB,WAAW,EAAE,OAAO,CAAA;IACpB,EAAE,EAAE,OAAO,CAAA;CACZ;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAqCpD"}

package/dist/cli/agent-gate.js

@@ -11,7 +11,11 @@ const stats_1 = require("../observability/stats");
 const decisionLogger_1 = require("../observability/decisionLogger");
 const collectRuleSources_1 = require("../collector/collectRuleSources");
 const lintRuleSources_1 = require("../doctor/lintRuleSources");
+const lintRuleSourcesWithAi_1 = require("../doctor/lintRuleSourcesWithAi");
 const formatFindings_1 = require("../doctor/formatFindings");
+const Config_1 = require("../config/Config");
+const AnthropicApi_1 = require("../validation/models/AnthropicApi");
+const ClaudeCli_1 = require("../validation/models/ClaudeCli");
 const server_1 = require("../daemon/server");
 const client_1 = require("../daemon/client");
 const protocol_1 = require("../daemon/protocol");
@@ -24,7 +28,8 @@ Usage:
   agent-gate install                Register the hook in ~/.claude/settings.json
   agent-gate uninstall              Remove the hook from ~/.claude/settings.json
   agent-gate stats                  Summarize decisions from the log file
-  agent-gate lint                   Audit CLAUDE.md / AGENTS.md / etc. for AI-friendliness
+  agent-gate lint [--ai]            Audit CLAUDE.md / AGENTS.md / etc. for AI-friendliness
+                                    (--ai adds AI-driven contradiction / ambiguity / missing-imperative checks)
   agent-gate daemon                 Start the long-lived daemon (Unix socket)
   agent-gate --help                 Show this help
   agent-gate --version              Show version
@@ -146,6 +151,7 @@ function parseArgs(args) {
     let agentId = adapters_1.DEFAULT_ADAPTER_ID;
     let showHelp = false;
     let showVersion = false;
+    let ai = false;
     const positional = [];
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
@@ -161,6 +167,10 @@ function parseArgs(args) {
             agentId = a.slice('--agent='.length);
             continue;
         }
+        if (a === '--ai') {
+            ai = true;
+            continue;
+        }
         if (a === '--help' || a === '-h' || a === 'help') {
             showHelp = true;
             continue;
@@ -171,7 +181,7 @@ function parseArgs(args) {
         }
         positional.push(a);
     }
-    return { positional, agentId, showHelp, showVersion };
+    return { positional, agentId, showHelp, showVersion, ai };
 }
 function main() {
     const parsedArgs = parseArgs(process.argv.slice(2));
@@ -203,7 +213,7 @@ function main() {
             runStats();
             return;
         case 'lint':
-            runLint();
+            void runLint(parsedArgs.ai);
             return;
         case 'daemon':
             void runDaemon();
@@ -218,13 +228,22 @@ function runStats() {
     const stats = (0, stats_1.readStats)((0, decisionLogger_1.defaultLogPath)());
     console.log((0, stats_1.formatStats)(stats));
 }
-function runLint() {
-    const sources = (0, collectRuleSources_1.collectRuleSources)(process.cwd());
+async function runLint(useAi) {
+    const cwd = process.cwd();
+    const sources = (0, collectRuleSources_1.collectRuleSources)(cwd);
     if (sources.length === 0) {
         console.log('No instruction files found (looked for CLAUDE.md, AGENTS.md, .cursorrules, .cursor/rules/*.mdc, .clinerules/*.md, .windsurf/rules/*.md, .github/copilot-instructions.md, CONVENTIONS.md).');
         return;
     }
     const findings = (0, lintRuleSources_1.lintRuleSources)(sources);
+    if (useAi) {
+        const config = new Config_1.Config();
+        const client = config.useApi
+            ? new AnthropicApi_1.AnthropicApi(config)
+            : new ClaudeCli_1.ClaudeCli(config, cwd);
+        const aiFindings = await (0, lintRuleSourcesWithAi_1.lintRuleSourcesWithAi)(sources, client);
+        findings.push(...aiFindings);
+    }
     console.log((0, formatFindings_1.formatFindings)(findings));
     const hasError = findings.some((f) => f.severity === 'error');
     if (hasError) {

package/dist/deterministic/bashAnalysis.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Light-weight bash analysis utilities used by deterministic rules to
+ * see past common obfuscation patterns. This is intentionally not a
+ * full shell parser; it handles the cases that matter for guardrails
+ * (separators, quoting, heredoc redirects, command substitution
+ * markers) and stays small.
+ */
+/**
+ * Split a command line into top-level statements separated by `;`,
+ * `&&`, `||`, `|`, or newline. Respects single- and double-quoted
+ * regions so separators inside strings are preserved as part of the
+ * statement.
+ *
+ * Trims and drops empty results.
+ */
+export declare function splitStatements(command: string): string[];
+/**
+ * Return any redirect targets that follow a heredoc operator. Each
+ * `cat <<EOF > target` (or `>> target`) anywhere in the command
+ * contributes one entry. Returns the raw target token without quote
+ * stripping.
+ */
+export declare function extractHeredocTargets(command: string): string[];
+/**
+ * True when the command uses command substitution `$(...)` / backticks,
+ * or a non-literal variable reference (anything other than the well-
+ * known `$HOME` / `$USER` / `$PWD` which the catastrophic-path rule
+ * already understands).
+ */
+export declare function hasObfuscation(command: string): boolean;
+//# sourceMappingURL=bashAnalysis.d.ts.map

package/dist/deterministic/bashAnalysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bashAnalysis.d.ts","sourceRoot":"","sources":["../../src/deterministic/bashAnalysis.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CA2CzD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAS/D;AAWD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAYvD"}

package/dist/deterministic/bashAnalysis.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * Light-weight bash analysis utilities used by deterministic rules to
+ * see past common obfuscation patterns. This is intentionally not a
+ * full shell parser; it handles the cases that matter for guardrails
+ * (separators, quoting, heredoc redirects, command substitution
+ * markers) and stays small.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitStatements = splitStatements;
+exports.extractHeredocTargets = extractHeredocTargets;
+exports.hasObfuscation = hasObfuscation;
+/**
+ * Split a command line into top-level statements separated by `;`,
+ * `&&`, `||`, `|`, or newline. Respects single- and double-quoted
+ * regions so separators inside strings are preserved as part of the
+ * statement.
+ *
+ * Trims and drops empty results.
+ */
+function splitStatements(command) {
+    const out = [];
+    let buf = '';
+    let i = 0;
+    let quote = null;
+    while (i < command.length) {
+        const c = command[i];
+        if (quote) {
+            buf += c;
+            if (c === quote)
+                quote = null;
+            i++;
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            quote = c;
+            buf += c;
+            i++;
+            continue;
+        }
+        if (c === ';' || c === '\n' || c === '|') {
+            // `||` collapses with `|`; `&&` handled below.
+            out.push(buf);
+            buf = '';
+            i++;
+            // collapse a trailing | of `||`
+            if (c === '|' && command[i] === '|')
+                i++;
+            continue;
+        }
+        if (c === '&' && command[i + 1] === '&') {
+            out.push(buf);
+            buf = '';
+            i += 2;
+            continue;
+        }
+        buf += c;
+        i++;
+    }
+    out.push(buf);
+    return out.map((s) => s.trim()).filter((s) => s.length > 0);
+}
+/**
+ * Return any redirect targets that follow a heredoc operator. Each
+ * `cat <<EOF > target` (or `>> target`) anywhere in the command
+ * contributes one entry. Returns the raw target token without quote
+ * stripping.
+ */
+function extractHeredocTargets(command) {
+    const targets = [];
+    // `<<` or `<<-`, optional `'TAG'` or `"TAG"` or bare TAG, then a redirect.
+    // We are permissive about whitespace.
+    const re = /<<-?\s*(?:['"]?\w+['"]?)\s*(?:>>?)\s*([^\s;|&<>]+)/g;
+    for (const m of command.matchAll(re)) {
+        if (m[1])
+            targets.push(m[1]);
+    }
+    return targets;
+}
+const KNOWN_LITERAL_VARS = new Set([
+    '$HOME',
+    '${HOME}',
+    '$PWD',
+    '${PWD}',
+    '$USER',
+    '${USER}',
+]);
+/**
+ * True when the command uses command substitution `$(...)` / backticks,
+ * or a non-literal variable reference (anything other than the well-
+ * known `$HOME` / `$USER` / `$PWD` which the catastrophic-path rule
+ * already understands).
+ */
+function hasObfuscation(command) {
+    if (/\$\([^)]*\)/.test(command))
+        return true;
+    if (/`[^`]*`/.test(command))
+        return true;
+    // Match each $VAR / ${VAR} occurrence and decide whether it is one
+    // of the literal allowlist.
+    const re = /\$\{?[A-Za-z_][A-Za-z0-9_]*\}?/g;
+    for (const m of command.matchAll(re)) {
+        const tok = m[0];
+        if (!KNOWN_LITERAL_VARS.has(tok))
+            return true;
+    }
+    return false;
+}

package/dist/deterministic/rules/preventBashSecretWrite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preventBashSecretWrite.d.ts","sourceRoot":"","sources":["../../../src/deterministic/rules/preventBashSecretWrite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAe,MAAM,UAAU,CAAA;AAwDzD,eAAO,MAAM,sBAAsB,EAAE,iBAkBpC,CAAA"}
+{"version":3,"file":"preventBashSecretWrite.d.ts","sourceRoot":"","sources":["../../../src/deterministic/rules/preventBashSecretWrite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAe,MAAM,UAAU,CAAA;AA6DzD,eAAO,MAAM,sBAAsB,EAAE,iBAsBpC,CAAA"}

package/dist/deterministic/rules/preventBashSecretWrite.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.preventBashSecretWrite = void 0;
+const bashAnalysis_1 = require("../bashAnalysis");
 const TEMPLATE_SUFFIXES = ['.example', '.sample', '.template', '.dist'];
 function basename(path) {
     const cleaned = path.replace(/[\s'"]+$/, '');
@@ -30,18 +31,18 @@ function isSecretTargetPath(rawPath) {
     return false;
 }
 /**
- * Extracts files that the command writes to via redirect (>, >>) or `tee`.
- * Conservative: matches the next non-flag token after the operator/word.
+ * Extracts every file the command writes to:
+ *   1. Standard redirects (`>`, `>>`, `1>`, `2>`, `&>`)
+ *   2. `tee [-a] FILE [FILE ...]`
+ *   3. Heredoc redirects (`cat <<EOF > file`)
  */
 function extractWriteTargets(command) {
     const targets = [];
-    // Redirect operators: >, >>, &>, &>>, 1>, 2> etc.
     const redirectRe = /[12&]?>>?\s*([^\s;|&<>]+)/g;
     for (const m of command.matchAll(redirectRe)) {
         if (m[1])
             targets.push(m[1]);
     }
-    // tee [-a] FILE [FILE ...]
     const teeRe = /\btee\b(?:\s+-[A-Za-z]+)*\s+([^\s;|&<>]+(?:\s+[^\s;|&<>]+)*)/g;
     for (const m of command.matchAll(teeRe)) {
         if (m[1]) {
@@ -51,6 +52,9 @@ function extractWriteTargets(command) {
             }
         }
     }
+    for (const t of (0, bashAnalysis_1.extractHeredocTargets)(command)) {
+        targets.push(t);
+    }
     return targets;
 }
 exports.preventBashSecretWrite = {
@@ -61,13 +65,17 @@ exports.preventBashSecretWrite = {
         const command = toolInput.command;
         if (typeof command !== 'string')
             return { kind: 'allow' };
-        const targets = extractWriteTargets(command);
-        for (const target of targets) {
-            if (isSecretTargetPath(target)) {
-                return {
-                    kind: 'block',
-                    reason: `Refusing to write to a likely secret/credential file via shell redirect: ${target}. If this is intentional, run the command manually outside of the agent.`,
-                };
+        // Inspect each top-level statement; heredoc spans newlines so the
+        // statement splitter preserves the heredoc body inside its segment.
+        for (const stmt of (0, bashAnalysis_1.splitStatements)(command)) {
+            const targets = extractWriteTargets(stmt);
+            for (const target of targets) {
+                if (isSecretTargetPath(target)) {
+                    return {
+                        kind: 'block',
+                        reason: `Refusing to write to a likely secret/credential file via shell redirect: ${target}. If this is intentional, run the command manually outside of the agent.`,
+                    };
+                }
             }
         }
         return { kind: 'allow' };

package/dist/deterministic/rules/preventRmRfRoot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preventRmRfRoot.d.ts","sourceRoot":"","sources":["../../../src/deterministic/rules/preventRmRfRoot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAe,MAAM,UAAU,CAAA;AA+CzD,eAAO,MAAM,eAAe,EAAE,iBAmB7B,CAAA"}
+{"version":3,"file":"preventRmRfRoot.d.ts","sourceRoot":"","sources":["../../../src/deterministic/rules/preventRmRfRoot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAe,MAAM,UAAU,CAAA;AA0EzD,eAAO,MAAM,eAAe,EAAE,iBAa7B,CAAA"}

package/dist/deterministic/rules/preventRmRfRoot.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.preventRmRfRoot = void 0;
+const bashAnalysis_1 = require("../bashAnalysis");
 const CATASTROPHIC_TARGETS = new Set([
     '/',
     '$HOME',
@@ -44,6 +45,29 @@ function extractTargets(command) {
     const tokens = trimmed.split(/\s+/);
     return tokens.slice(1).filter((t) => !t.startsWith('-'));
 }
+function evaluateStatement(stmt) {
+    if (!isRecursiveForceRm(stmt))
+        return { kind: 'allow' };
+    // Substitution / unresolved variable targets cannot be evaluated
+    // statically. Treat them as suspicious: we cannot prove they are not
+    // catastrophic, so block.
+    if ((0, bashAnalysis_1.hasObfuscation)(stmt)) {
+        return {
+            kind: 'block',
+            reason: 'Refusing recursive rm whose target is a command substitution or unresolved variable. The target cannot be evaluated statically, so the operation is rejected as a safety precaution.',
+        };
+    }
+    const targets = extractTargets(stmt);
+    for (const target of targets) {
+        if (CATASTROPHIC_TARGETS.has(target)) {
+            return {
+                kind: 'block',
+                reason: `Refusing to run recursive rm on a catastrophic path: ${target}. If this is genuinely intended, run the command manually outside of the agent.`,
+            };
+        }
+    }
+    return { kind: 'allow' };
+}
 exports.preventRmRfRoot = {
     id: 'prevent-rm-rf-root',
     check(toolName, toolInput) {
@@ -52,16 +76,10 @@ exports.preventRmRfRoot = {
         const command = toolInput.command;
         if (typeof command !== 'string')
             return { kind: 'allow' };
-        if (!isRecursiveForceRm(command))
-            return { kind: 'allow' };
-        const targets = extractTargets(command);
-        for (const target of targets) {
-            if (CATASTROPHIC_TARGETS.has(target)) {
-                return {
-                    kind: 'block',
-                    reason: `Refusing to run recursive rm on a catastrophic path: ${target}. If this is genuinely intended, run the command manually outside of the agent.`,
-                };
-            }
+        for (const stmt of (0, bashAnalysis_1.splitStatements)(command)) {
+            const v = evaluateStatement(stmt);
+            if (v.kind === 'block')
+                return v;
         }
         return { kind: 'allow' };
     },

package/dist/doctor/findings.d.ts

@@ -1,6 +1,6 @@
 import { RuleSourceKind } from '../contracts/types/RuleSource';
 export type Severity = 'info' | 'warning' | 'error';
-export type FindingCode = 'empty-file' | 'ambiguous-modifier' | 'no-concrete-rules';
+export type FindingCode = 'empty-file' | 'ambiguous-modifier' | 'no-concrete-rules' | 'ambiguity' | 'contradiction' | 'missing-imperative';
 export interface Finding {
     ruleSourcePath: string;
     ruleSourceKind: RuleSourceKind;

package/dist/doctor/findings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"findings.d.ts","sourceRoot":"","sources":["../../src/doctor/findings.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAE9D,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAA;AAEnD,MAAM,MAAM,WAAW,GACnB,YAAY,GACZ,oBAAoB,GACpB,mBAAmB,CAAA;AAEvB,MAAM,WAAW,OAAO;IACtB,cAAc,EAAE,MAAM,CAAA;IACtB,cAAc,EAAE,cAAc,CAAA;IAC9B,QAAQ,EAAE,QAAQ,CAAA;IAClB,IAAI,EAAE,WAAW,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB"}
+{"version":3,"file":"findings.d.ts","sourceRoot":"","sources":["../../src/doctor/findings.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAE9D,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAA;AAEnD,MAAM,MAAM,WAAW,GACnB,YAAY,GACZ,oBAAoB,GACpB,mBAAmB,GACnB,WAAW,GACX,eAAe,GACf,oBAAoB,CAAA;AAExB,MAAM,WAAW,OAAO;IACtB,cAAc,EAAE,MAAM,CAAA;IACtB,cAAc,EAAE,cAAc,CAAA;IAC9B,QAAQ,EAAE,QAAQ,CAAA;IAClB,IAAI,EAAE,WAAW,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB"}

package/dist/doctor/lintRuleSourcesWithAi.d.ts

@@ -0,0 +1,5 @@
+import { RuleSource } from '../contracts/types/RuleSource';
+import { IModelClient } from '../contracts/types/ModelClient';
+import { Finding } from './findings';
+export declare function lintRuleSourcesWithAi(sources: RuleSource[], client: IModelClient): Promise<Finding[]>;
+//# sourceMappingURL=lintRuleSourcesWithAi.d.ts.map

package/dist/doctor/lintRuleSourcesWithAi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lintRuleSourcesWithAi.d.ts","sourceRoot":"","sources":["../../src/doctor/lintRuleSourcesWithAi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAkB,MAAM,+BAA+B,CAAA;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAA;AAC7D,OAAO,EAAE,OAAO,EAAyB,MAAM,YAAY,CAAA;AA8E3D,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,UAAU,EAAE,EACrB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,OAAO,EAAE,CAAC,CA4CpB"}

package/dist/doctor/lintRuleSourcesWithAi.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lintRuleSourcesWithAi = lintRuleSourcesWithAi;
+const PROMPT_HEADER = `You are auditing AI agent instruction files for issues that
+make rules hard for an AI to enforce reliably. Look at the sources below
+and report any of the following:
+
+- "contradiction": two or more rules across one or more files that
+  conflict. Cite both/all sides in the excerpt.
+- "ambiguity": a rule that uses vague language (e.g. "where possible",
+  "as needed", "appropriately") with no concrete threshold or condition.
+- "missing-imperative": a rule expressed as a wish or description rather
+  than an imperative the AI can act on.
+
+Respond as a JSON array of objects with this shape:
+[
+  {
+    "code": "contradiction" | "ambiguity" | "missing-imperative",
+    "ruleSourcePath": "<one of the paths shown>",
+    "line": <1-indexed line number in that file, or null>,
+    "message": "<concise explanation>",
+    "excerpt": "<short literal text from the file>"
+  }
+]
+
+If there are no issues, respond with []. Output ONLY the JSON array. No
+markdown, no prose, no commentary.`;
+const ALLOWED_CODES = [
+    'ambiguity',
+    'contradiction',
+    'missing-imperative',
+];
+const CODE_SEVERITY = {
+    'empty-file': 'warning',
+    'ambiguous-modifier': 'info',
+    'no-concrete-rules': 'warning',
+    ambiguity: 'info',
+    contradiction: 'warning',
+    'missing-imperative': 'info',
+};
+function buildPrompt(sources) {
+    const blocks = sources.map((s) => `--- path: ${s.path} (kind: ${s.kind}) ---\n${s.content}`);
+    return `${PROMPT_HEADER}\n\n${blocks.join('\n\n')}`;
+}
+function extractJsonArray(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.startsWith('['))
+        return trimmed;
+    // Code fence variants
+    const fenced = trimmed.match(/```(?:json)?\s*\n([\s\S]*?)\n```/);
+    if (fenced)
+        return fenced[1].trim();
+    // Plain extraction: first [ to last ]
+    const start = trimmed.indexOf('[');
+    const end = trimmed.lastIndexOf(']');
+    if (start !== -1 && end > start)
+        return trimmed.slice(start, end + 1);
+    return null;
+}
+function pathToKind(path, sources) {
+    const match = sources.find((s) => s.path === path);
+    return match ? match.kind : null;
+}
+async function lintRuleSourcesWithAi(sources, client) {
+    if (sources.length === 0)
+        return [];
+    let response;
+    try {
+        response = await client.ask(buildPrompt(sources));
+    }
+    catch {
+        return [];
+    }
+    const jsonStr = extractJsonArray(response);
+    if (!jsonStr)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonStr);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const findings = [];
+    for (const raw of parsed) {
+        if (!raw || typeof raw !== 'object')
+            continue;
+        const code = raw.code;
+        if (!code || !ALLOWED_CODES.includes(code))
+            continue;
+        if (typeof raw.ruleSourcePath !== 'string')
+            continue;
+        const kind = pathToKind(raw.ruleSourcePath, sources);
+        if (!kind)
+            continue;
+        findings.push({
+            ruleSourcePath: raw.ruleSourcePath,
+            ruleSourceKind: kind,
+            severity: CODE_SEVERITY[code],
+            code,
+            message: typeof raw.message === 'string' ? raw.message : '',
+            line: typeof raw.line === 'number' && Number.isFinite(raw.line)
+                ? raw.line
+                : undefined,
+            excerpt: typeof raw.excerpt === 'string' ? raw.excerpt : undefined,
+        });
+    }
+    return findings;
+}

package/dist/index.d.ts

@@ -23,6 +23,7 @@ export type { CompositeModelClientOptions } from './validation/models/CompositeM
 export { AgentSdkClient } from './validation/models/AgentSdkClient';
 export type { AgentSdkClientOptions, AgentSdkQueryFn, } from './validation/models/AgentSdkClient';
 export { lintRuleSources } from './doctor/lintRuleSources';
+export { lintRuleSourcesWithAi } from './doctor/lintRuleSourcesWithAi';
 export { formatFindings } from './doctor/formatFindings';
 export type { Finding, FindingCode, Severity, } from './doctor/findings';
 export { DecisionCache } from './cache/DecisionCache';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.processHookData = exports.validator = exports.collectRuleSources = exports.JsonlFileSink = exports.EventBus = exports.defaultDaemonSocketPath = exports.sendToDaemon = exports.DaemonServer = exports.DecisionCache = exports.formatFindings = exports.lintRuleSources = exports.AgentSdkClient = exports.CompositeModelClient = exports.cursorAdapter = exports.claudeCodeAdapter = exports.buildDefaultDeterministicRules = exports.defaultDeterministicRules = exports.forbidFilePathPattern = exports.forbidContentPattern = exports.forbidCommandPattern = exports.HookDataSchema = exports.loadPluginConfig = exports.loadAgentGateConfig = exports.defineConfig = exports.Config = void 0;
+exports.processHookData = exports.validator = exports.collectRuleSources = exports.JsonlFileSink = exports.EventBus = exports.defaultDaemonSocketPath = exports.sendToDaemon = exports.DaemonServer = exports.DecisionCache = exports.formatFindings = exports.lintRuleSourcesWithAi = exports.lintRuleSources = exports.AgentSdkClient = exports.CompositeModelClient = exports.cursorAdapter = exports.claudeCodeAdapter = exports.buildDefaultDeterministicRules = exports.defaultDeterministicRules = exports.forbidFilePathPattern = exports.forbidContentPattern = exports.forbidCommandPattern = exports.HookDataSchema = exports.loadPluginConfig = exports.loadAgentGateConfig = exports.defineConfig = exports.Config = void 0;
 // Config
 var Config_1 = require("./config/Config");
 Object.defineProperty(exports, "Config", { enumerable: true, get: function () { return Config_1.Config; } });
@@ -33,6 +33,8 @@ Object.defineProperty(exports, "AgentSdkClient", { enumerable: true, get: functi
 // Doctor (CLAUDE.md linter)
 var lintRuleSources_1 = require("./doctor/lintRuleSources");
 Object.defineProperty(exports, "lintRuleSources", { enumerable: true, get: function () { return lintRuleSources_1.lintRuleSources; } });
+var lintRuleSourcesWithAi_1 = require("./doctor/lintRuleSourcesWithAi");
+Object.defineProperty(exports, "lintRuleSourcesWithAi", { enumerable: true, get: function () { return lintRuleSourcesWithAi_1.lintRuleSourcesWithAi; } });
 var formatFindings_1 = require("./doctor/formatFindings");
 Object.defineProperty(exports, "formatFindings", { enumerable: true, get: function () { return formatFindings_1.formatFindings; } });
 // Cache

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hiro-c/agent-gate",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Runtime rule enforcer for AI coding agents. Reads CLAUDE.md / AGENTS.md / .cursorrules and enforces them via Claude Code and Cursor hooks, with a deterministic safety baseline.",
   "author": "Hiro-Chiba",
   "license": "MIT",