@yegor256/dogent 0.4.0 → 0.5.1

package/README.md

@@ -14,16 +14,22 @@ Vague, bloated, or ambiguous instructions make agents behave unpredictably.
   so every line earns its place.
 
 We respect [agent-sh/agnix](https://github.com/agent-sh/agnix)
-  as a prototype of this idea.
-`dogent` goes further: it is stricter, more opinionated,
-  and aims for extreme quality with no compromise.
+  as a prototype of this idea, but the two lint different layers.
+`agnix` validates the harness around a prompt — frontmatter schema,
+  hook JSON, MCP config, tool wiring — asking whether the configuration
+  is well-formed and correctly wired.
+`dogent` lints the prose of the instructions themselves,
+  asking whether every line is a tight, unambiguous command.
+In short: `agnix` lints the harness, `dogent` lints the prompt.
+`dogent` is the stricter, more opinionated of the two,
+  aiming for extreme quality with no compromise.
 
 ## Usage
 
 Run it on any manifesto file, no installation required:
 
 ```bash
-npx @yegor256/dogent@0.3.0 CLAUDE.md
+npx @yegor256/dogent@0.5.0 CLAUDE.md
 ```
 
 Lint several files at once:
@@ -33,7 +39,10 @@ npx @yegor256/dogent SKILL.md CLAUDE.md AGENTS.md
 ```
 
 Point it at a directory to lint the default manifestos it holds
-  (`AGENTS.md`, `CLAUDE.md`, `SKILL.md`, `SKILLS.md`):
+  (`AGENTS.md`, `CLAUDE.md`, `SKILL.md`, `SKILLS.md`).
+The directory is scanned recursively through every subfolder
+  (skipping `node_modules` and `.git`),
+  and each scanned file is announced on the standard error stream:
 
 ```bash
 npx @yegor256/dogent .
@@ -74,12 +83,16 @@ The command exits with a non-zero status when problems are found,
 
 `dogent` works standalone by default,
   using fast deterministic checks with no network access.
-When `OPENAI_API_KEY` or `CLAUDE_TOKEN` is present in the environment,
-  it additionally uses AI to verify the text for ambiguity,
-  weak phrasing, and instructions that only pretend to be commands:
+When `OPENAI_API_KEY` is present in the environment,
+  and only after the standalone rules find nothing,
+  `dogent` asks OpenAI for a second, deeper opinion.
+It sends the manifesto together with one instruction per rule,
+  then prints any violation the model reports for ambiguity,
+  weak phrasing, and instructions that only pretend to be commands.
+The model defaults to `gpt-4o-mini`; override it with `OPENAI_MODEL`.
 
 ```bash
-export CLAUDE_TOKEN=...
+export OPENAI_API_KEY=...
 npx @yegor256/dogent CLAUDE.md
 ```
 
@@ -109,7 +122,7 @@ To enable AI verification in CI, expose a token as a secret:
 ```yaml
       - run: npx @yegor256/dogent CLAUDE.md
         env:
-          CLAUDE_TOKEN: ${{ secrets.CLAUDE_TOKEN }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
 ```
 
 ## Pre-commit hook
@@ -128,7 +141,7 @@ Reference `dogent` as a remote hook in `.pre-commit-config.yaml`:
 ```yaml
 repos:
   - repo: https://github.com/yegor256/dogent
-    rev: 0.3.0
+    rev: 0.5.0
     hooks:
       - id: dogent
 ```

package/package.json

@@ -40,5 +40,5 @@
     "lint": "eslint .",
     "test": "mocha 'test/**/*.js' --timeout 60000"
   },
-  "version": "0.4.0"
+  "version": "0.5.1"
 }

package/src/answer.js

@@ -0,0 +1,47 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('./violation');
+const Region = require('./region');
+
+/**
+ * Answer.
+ *
+ * The oracle's raw reply, treated as untrusted input. Parses the JSON
+ * object it carries and turns every well-formed SARIF result back into a
+ * native violation, ignoring any result it cannot read.
+ */
+class Answer {
+  constructor(raw) {
+    this.raw = raw;
+  }
+  violations() {
+    return this.results().flatMap((result) => {
+      const spot = result?.locations?.[0]?.physicalLocation;
+      const line = spot?.region?.startLine;
+      const text = result?.message?.text;
+      if (typeof line !== 'number' || typeof text !== 'string' || !spot.artifactLocation) {
+        return [];
+      }
+      return [new Violation(
+        result.ruleId || 'oracle',
+        result.level || 'warning',
+        text,
+        new Region(spot.artifactLocation.uri, line, spot.region.startColumn || 1)
+      )];
+    });
+  }
+  results() {
+    try {
+      return JSON.parse(this.raw).results || [];
+    } catch (error) {
+      throw new Error(`oracle returned malformed JSON: ${error.message}`, {cause: error});
+    }
+  }
+}
+
+module.exports = Answer;

package/src/document.js

@@ -9,12 +9,14 @@
  * Document.
  *
  * An entire manifesto already parsed into an ordered collection of
- * fragments, ready to be walked by a rule that hunts for violations.
+ * fragments, ready to be walked by a rule that hunts for violations. It
+ * also keeps the raw text, which the AI oracle reads verbatim.
  */
 class Document {
-  constructor(uri, fragments) {
+  constructor(uri, fragments, content) {
     this.address = uri;
     this.pieces = fragments;
+    this.body = content;
   }
   uri() {
     return this.address;
@@ -22,6 +24,9 @@ class Document {
   fragments() {
     return this.pieces;
   }
+  text() {
+    return this.body;
+  }
   walk(visitor) {
     return this.pieces.reduce((all, piece) => all.concat(piece.accept(visitor)), []);
   }

package/src/dogent.js

@@ -10,6 +10,8 @@ const fs = require('fs');
 const Markdown = require('./markdown');
 const Report = require('./report');
 const Sources = require('./sources');
+const Openai = require('./openai');
+const Oracle = require('./oracle');
 const rules = require('./rules');
 
 const argv = process.argv.slice(2);
@@ -19,13 +21,40 @@ if (paths.length === 0) {
   process.stderr.write('Usage: dogent [--sarif] <file.md|dir>...\n');
   process.exit(2);
 }
+const scanned = new Sources(paths).files();
+scanned.forEach((file) => process.stderr.write(`Scanning ${file}\n`));
+process.stderr.write(`${scanned.length} files scanned\n`);
+const documents = scanned.map(
+  (file) => new Markdown(file, fs.readFileSync(file, 'utf8')).document()
+);
 const found = [];
-new Sources(paths).files().forEach((file) => {
-  const document = new Markdown(file, fs.readFileSync(file, 'utf8')).document();
+documents.forEach((document) => {
   rules().forEach((rule) => {
     rule.violations(document).forEach((violation) => found.push(violation));
   });
 });
-const report = new Report('dogent', found);
-process.stdout.write(`${sarif ? JSON.stringify(report.sarif(), null, 2) : report.text()}\n`);
-process.exit(report.count() > 0 ? 1 : 0);
+const key = process.env.OPENAI_API_KEY;
+(async () => {
+  if (found.length === 0 && key) {
+    try {
+      const oracle = new Oracle(
+        rules(),
+        new Openai(
+          key,
+          process.env.OPENAI_MODEL || 'gpt-4o-mini',
+          (url, options) => globalThis.fetch(url, options)
+        )
+      );
+      const extra = await Promise.all(
+        documents.map((document) => oracle.violations(document))
+      );
+      extra.forEach((bag) => bag.forEach((violation) => found.push(violation)));
+    } catch (error) {
+      process.stderr.write(`AI verification failed: ${error.message}\n`);
+      process.exit(2);
+    }
+  }
+  const report = new Report('dogent', found);
+  process.stdout.write(`${sarif ? JSON.stringify(report.sarif(), null, 2) : report.text()}\n`);
+  process.exit(report.count() > 0 ? 1 : 0);
+})();

package/src/markdown.js

@@ -98,7 +98,7 @@ class Markdown {
     if (fence !== '') {
       pieces.push(new Snippet(block.join('\n'), opened));
     }
-    return new Document(this.address, pieces);
+    return new Document(this.address, pieces, this.content);
   }
 }
 

package/src/openai.js

@@ -0,0 +1,45 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+/**
+ * Openai.
+ *
+ * A thin adapter over the OpenAI chat-completions endpoint. Sends one
+ * prompt, demands a JSON object back, and returns the assistant text.
+ * The transport is injected so the class runs in tests without a socket.
+ */
+class Openai {
+  constructor(key, model, transport) {
+    this.key = key;
+    this.model = model;
+    this.transport = transport;
+  }
+  async answer(prompt) {
+    const response = await this.transport(
+      'https://api.openai.com/v1/chat/completions',
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${this.key}`
+        },
+        body: JSON.stringify({
+          model: this.model,
+          temperature: 0,
+          response_format: {type: 'json_object'},
+          messages: [{role: 'user', content: prompt}]
+        })
+      }
+    );
+    if (!response.ok) {
+      throw new Error(`OpenAI request rejected with status ${response.status}`);
+    }
+    return (await response.json()).choices[0].message.content;
+  }
+}
+
+module.exports = Openai;

package/src/oracle.js

@@ -0,0 +1,30 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Prompt = require('./prompt');
+const Answer = require('./answer');
+
+/**
+ * Oracle.
+ *
+ * The AI second opinion. Wraps the rules and a chat endpoint, builds one
+ * prompt from a document, asks the endpoint, and parses the reply into
+ * violations. Mirrors a rule, but consults a model instead of guessing.
+ */
+class Oracle {
+  constructor(rules, chat) {
+    this.rules = rules;
+    this.chat = chat;
+  }
+  async violations(document) {
+    return new Answer(
+      await this.chat.answer(new Prompt(this.rules, document).text())
+    ).violations();
+  }
+}
+
+module.exports = Oracle;

package/src/prompt.js

@@ -0,0 +1,54 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+/**
+ * Prompt.
+ *
+ * The full request handed to the AI oracle: a header fixing the task and
+ * the reply shape, one fragment per rule, and the manifesto itself with
+ * every line numbered so the oracle can cite an exact row.
+ */
+class Prompt {
+  constructor(rules, document) {
+    this.rules = rules;
+    this.doc = document;
+  }
+  text() {
+    return [this.header(), this.fragments(), this.body()].join('\n\n');
+  }
+  header() {
+    const uri = this.doc.uri();
+    return [
+      'You are a strict linter for an AI-agent manifesto.',
+      `The file under review is "${uri}".`,
+      'Apply only the checks listed below this header.',
+      'Report a violation only when it is clear and certain.',
+      'When in doubt, stay silent and report nothing.',
+      'Reply with one JSON object and nothing else, shaped as',
+      '{"results":[ ... ]}, where each item is a SARIF result with',
+      'keys ruleId, level "warning", message.text, and locations.',
+      'Set ruleId to the rule name and startLine to the printed',
+      'line number; locations[0].physicalLocation must carry',
+      `artifactLocation.uri "${uri}" and region.startColumn 1.`
+    ].join('\n');
+  }
+  fragments() {
+    return this.rules
+      .map((rule) => rule.prompt())
+      .filter((fragment) => fragment !== '')
+      .join('\n');
+  }
+  body() {
+    return this.doc
+      .text()
+      .split('\n')
+      .map((line, index) => `${index + 1}: ${line}`)
+      .join('\n');
+  }
+}
+
+module.exports = Prompt;

package/src/rules/command.js

@@ -13,15 +13,16 @@ const Region = require('../region');
  *
  * Demands that every instruction sound like a command. A standalone
  * checker can only guess: it flags lines that open with a pronoun or
- * end with a question mark, both signs of description, not order.
- *
- * @todo #1:90min Replace this heuristic with a real imperative-mood check
- *  driven by an AI oracle when a token is present in the environment.
+ * end with a question mark, both signs of description, not order. Its
+ * prompt hands the subtler imperative-mood judgement to the AI oracle.
  */
 class Command {
   constructor() {
     this.id = 'command';
   }
+  prompt() {
+    return `${this.id}: flag any line that reads as a description, a question, or a plain statement rather than a direct order`;
+  }
   violations(document) {
     const uri = document.uri();
     return document.walk({

package/src/rules/empty.js

@@ -0,0 +1,54 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * Empty.
+ *
+ * Flags any heading that declares a section but carries no body.
+ * A heading is empty when it is immediately followed by another
+ * heading or by end-of-file — no prose, bullets, or snippet sits
+ * between them.
+ */
+class Empty {
+  constructor() {
+    this.id = 'empty';
+  }
+  prompt() {
+    return `${this.id}: flag any section heading that carries no instructions beneath it`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    const marks = document.walk({
+      header: (text, line) => [{header: true, line}],
+      prose: (text, line) => [{header: false, line}],
+      bullets: (row) => [{header: false, line: row}],
+      snippet: (text, line) => [{header: false, line}],
+      frontmatter: () => []
+    });
+    const result = [];
+    marks.forEach((mark, index) => {
+      if (!mark.header) {
+        return;
+      }
+      const next = marks[index + 1];
+      if (!next || next.header) {
+        result.push(new Violation(
+          this.id,
+          'error',
+          'hollow section, no instructions found',
+          new Region(uri, mark.line, 1)
+        ));
+      }
+    });
+    return result;
+  }
+}
+
+module.exports = Empty;

package/src/rules/frontmatter.js

@@ -22,6 +22,9 @@ class Frontmatter {
     this.required = required;
     this.allowed = allowed;
   }
+  prompt() {
+    return `${this.id}: in a ${this.name} file, flag any required key whose value is empty, vague, or a leftover placeholder`;
+  }
   violations(document) {
     const uri = document.uri();
     if (uri.replace(/^.*\//u, '') !== this.name) {

package/src/rules/grouped.js

@@ -18,6 +18,9 @@ class Grouped {
   constructor() {
     this.id = 'grouped';
   }
+  prompt() {
+    return `${this.id}: flag any instruction that sits under a section where it does not belong`;
+  }
   violations(document) {
     const uri = document.uri();
     const marks = document.walk({

package/src/rules/index.js

@@ -9,6 +9,7 @@ const LineLength = require('./line-length');
 const TokenCount = require('./token-count');
 const ShortSections = require('./short-sections');
 const Grouped = require('./grouped');
+const Empty = require('./empty');
 const NoArticles = require('./no-articles');
 const Command = require('./command');
 const Punctuation = require('./punctuation');
@@ -16,6 +17,7 @@ const Frontmatter = require('./frontmatter');
 
 module.exports = () => [
   new Grouped(),
+  new Empty(),
   new ShortSections(),
   new LineLength(80),
   new TokenCount(4000),

package/src/rules/line-length.js

@@ -19,6 +19,9 @@ class LineLength {
     this.id = 'line-length';
     this.max = max;
   }
+  prompt() {
+    return `${this.id}: flag any instruction too wordy to grasp in a single read`;
+  }
   violations(document) {
     const uri = document.uri();
     return document.walk({

package/src/rules/no-articles.js

@@ -18,6 +18,9 @@ class NoArticles {
   constructor() {
     this.id = 'no-articles';
   }
+  prompt() {
+    return `${this.id}: flag filler or noise words that add nothing to an instruction`;
+  }
   violations(document) {
     const uri = document.uri();
     return document.walk({

package/src/rules/punctuation.js

@@ -19,6 +19,9 @@ class Punctuation {
   constructor() {
     this.id = 'punctuation';
   }
+  prompt() {
+    return `${this.id}: flag any instruction that is not one complete, grammatical sentence`;
+  }
   violations(document) {
     const uri = document.uri();
     return document.walk({

package/src/rules/short-sections.js

@@ -18,6 +18,9 @@ class ShortSections {
   constructor() {
     this.id = 'short-sections';
   }
+  prompt() {
+    return `${this.id}: flag any section heading that is not a short, noun-style label`;
+  }
   violations(document) {
     const uri = document.uri();
     return document.walk({

package/src/rules/token-count.js

@@ -21,6 +21,9 @@ class TokenCount {
     this.id = 'token-count';
     this.cap = cap;
   }
+  prompt() {
+    return `${this.id}: flag bloated wording that wastes the context budget`;
+  }
   violations(document) {
     const count = (document.walk({
       header: (text) => [text],

package/src/sources.js

@@ -8,13 +8,15 @@
 const fs = require('fs');
 const path = require('path');
 
+const PRUNED = ['node_modules', '.git'];
+
 /**
  * Sources.
  *
  * The paths passed on the command line. Each path names either one
  * manifesto file or one directory. A directory expands into the default
- * manifesto files it actually contains, so `dogent .` lints every known
- * manifesto in the current folder.
+ * manifesto files it holds, scanned recursively through every subfolder,
+ * so `dogent .` lints every known manifesto in the whole tree.
  */
 class Sources {
   constructor(paths, defaults = ['AGENTS.md', 'CLAUDE.md', 'SKILL.md', 'SKILLS.md']) {
@@ -25,18 +27,26 @@ class Sources {
     const found = [];
     this.paths.forEach((entry) => {
       if (fs.statSync(entry).isDirectory()) {
-        this.defaults.forEach((name) => {
-          const file = path.join(entry, name);
-          if (fs.existsSync(file)) {
-            found.push(file);
-          }
-        });
+        this.scan(entry, found);
       } else {
         found.push(entry);
       }
     });
     return found;
   }
+  scan(dir, found) {
+    this.defaults.forEach((name) => {
+      const file = path.join(dir, name);
+      if (fs.existsSync(file) && fs.statSync(file).isFile()) {
+        found.push(file);
+      }
+    });
+    fs.readdirSync(dir, {withFileTypes: true}).forEach((entry) => {
+      if (entry.isDirectory() && !PRUNED.includes(entry.name)) {
+        this.scan(path.join(dir, entry.name), found);
+      }
+    });
+  }
 }
 
 module.exports = Sources;