@yegor256/dogent 0.10.0 → 0.11.0

package/README.md

@@ -13,23 +13,47 @@ Vague, bloated, or ambiguous instructions make agents behave unpredictably.
 `dogent` enforces a clear, command-style discipline
   so every line earns its place.
 
-We respect [agent-sh/agnix](https://github.com/agent-sh/agnix)
-  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.
+## Alternatives
+
+Several tools sit near this problem, yet none lint manifesto prose
+  the way we do.
+Most rewrite prompts for you or score a file, while we enforce
+  line-level discipline and fail the build when one line breaks it.
+
+- [agent-sh/agnix](https://github.com/agent-sh/agnix)
+  validates the harness — frontmatter schema, hook JSON, MCP config, tools —
+    while we lint the prose, asking if each line is a tight command.
+
+- [AgentLinter](https://agentlinter.com)
+  lints the same files but scores them 0–100 across eight dimensions,
+    while we run a strict pass/fail gate, not a scorer.
+
+- [microsoft/SkillOpt](https://github.com/microsoft/SkillOpt)
+  rewrites `skill.md` against benchmarks to raise an agent's task score,
+    while we never rewrite, need no benchmarks, and judge discipline.
+
+- [linshenkx/prompt-optimizer](https://github.com/linshenkx/prompt-optimizer)
+  rewrites a prompt through an LLM in the browser, round by round,
+    while we lint manifesto files offline in CI.
+
+- [DSPy](https://github.com/stanfordnlp/dspy)
+  tunes prompts as programs to maximize a metric on a dataset,
+    while we lint hand-written manifestos, demanding clarity over a score.
+
+- Prompt platforms like [LangSmith](https://www.langchain.com/langsmith),
+    [PromptLayer](https://www.promptlayer.com), and
+    [Braintrust](https://www.braintrust.dev)
+  version, trace, and evaluate prompts from runtime data,
+    while we lint statically and offline, needing no traces or account.
 
 ## Usage
 
+[Watch the demo](https://github.com/user-attachments/assets/0f05c975-2bc8-4a95-9c3a-76a78fe5d655)
+
 Run it on any manifesto file, no installation required:
 
 ```bash
-npx @yegor256/dogent@0.7.2 SKILL.md
+npx @yegor256/dogent@0.10.0 SKILL.md
 ```
 
 Point it at a directory to lint the default manifestos it holds
@@ -106,6 +130,11 @@ 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`.
+Requests go to `https://api.openai.com/v1` by default;
+  set `OPENAI_BASE_URL` to any OpenAI-compatible endpoint instead,
+  such as a local vLLM, Ollama, or LocalAI server, or a private gateway.
+For a keyless local server, set `OPENAI_API_KEY` to any placeholder,
+  since the server ignores it yet `dogent` calls the LLM only when it is set.
 After the report, `dogent` prints a one-line usage summary to standard error,
   naming the model, the tokens sent and received, and an estimated cost,
   for example `OpenAI: gpt-4o-mini, 1234 sent, 567 received, ~$0.0005`.
@@ -115,6 +144,15 @@ export OPENAI_API_KEY=...
 npx @yegor256/dogent CLAUDE.md
 ```
 
+Point it at a local model the same way:
+
+```bash
+export OPENAI_BASE_URL=http://localhost:11434/v1
+export OPENAI_MODEL=llama3
+export OPENAI_API_KEY=dummy
+npx @yegor256/dogent CLAUDE.md
+```
+
 Pass `--offline` to keep `dogent` away from the LLM,
   even when `OPENAI_API_KEY` is present in the environment:
 
@@ -131,6 +169,43 @@ Pass `--suppress` to silence a rule by its id. Repeat the option or
 npx @yegor256/dogent --suppress=name-matches-dir,line-length CLAUDE.md
 ```
 
+Pass `--openai-http-header` to add one `Name: Value` header to every OpenAI
+  call, handy for a gateway that wants its own token beside the API key.
+Repeat the option to add several headers:
+
+```bash
+npx @yegor256/dogent \
+  --openai-http-header='X-Api-Key: secret' \
+  --openai-http-header='X-Tenant: acme' \
+  CLAUDE.md
+```
+
+A header value often holds a secret, so keep it out of your shell history
+  by listing the option in a `.dogent` file (see below) instead.
+
+## Defaults file
+
+Tired of repeating the same flags on every run?
+Drop a `.dogent` file beside your project, and `dogent` reads its options
+  as defaults before it touches the command line.
+The file holds one option per line, written exactly as you would type it,
+  with the value after a space (for example `--suppress name-matches-dir`).
+A blank line is ignored, and a line that starts with `#` is a comment:
+
+```text
+# project defaults for dogent
+--offline
+--suppress name-matches-dir
+--suppress line-length
+```
+
+`dogent` looks first in the current directory, then in your home directory,
+  and reads the first `.dogent` it finds.
+The file only supplies defaults, so any option you type on the command line
+  overrides the same option in the file.
+Thus `npx @yegor256/dogent --sarif .` still prints SARIF even when the file
+  says nothing about it, and a hand-typed flag always wins.
+
 ## GitHub Actions
 
 Because `dogent` runs through `npx`, no extra action is needed.
@@ -176,7 +251,7 @@ Reference `dogent` as a remote hook in `.pre-commit-config.yaml`:
 ```yaml
 repos:
   - repo: https://github.com/yegor256/dogent
-    rev: 0.7.2
+    rev: 0.10.0
     hooks:
       - id: dogent
 ```

package/package.json

@@ -40,7 +40,7 @@
     "lint": "eslint .",
     "test": "mocha 'test/**/*.js' --timeout 60000"
   },
-  "version": "0.10.0",
+  "version": "0.11.0",
   "dependencies": {
     "minimist": "^1.2.8",
     "pretty-ms": "^7.0.1"

package/src/args.js

@@ -16,14 +16,16 @@ const minimist = require('minimist');
  * any talk to the LLM even when a token sits in the environment. The `--help`
  * flag, also spelled `-h`, asks for the usage banner. The `--version` flag
  * asks for the release number. The `--suppress` option names a rule to
- * silence; repeat it or join names with commas to silence many at once.
- * Everything after a `--` separator counts as a path, never as an option.
+ * silence; repeat it or join names with commas to silence many at once. The
+ * `--openai-http-header` option adds one `Name: Value` header to every OpenAI
+ * call; repeat it to add many. Everything after a `--` separator counts as a
+ * path, never as an option.
  */
 class Args {
   constructor(
     argv,
     flags = ['sarif', 'offline', 'help', 'version'],
-    options = ['suppress']
+    options = ['suppress', 'openai-http-header']
   ) {
     this.flags = flags;
     this.options = options;
@@ -50,6 +52,19 @@ class Args {
       .map((name) => name.trim())
       .filter((name) => name !== '');
   }
+  headers() {
+    return [].concat(this.parsed['openai-http-header'] || [])
+      .map(String)
+      .map((line) => line.trim())
+      .filter((line) => line !== '')
+      .reduce((acc, line) => {
+        const at = line.indexOf(':');
+        if (at < 0) {
+          throw new Error(`Malformed header "${line}", expected "Name: Value"`);
+        }
+        return {...acc, [line.slice(0, at).trim()]: line.slice(at + 1).trim()};
+      }, {});
+  }
   paths() {
     return this.parsed._.concat(this.parsed['--']).map(String);
   }

package/src/defaults.js

@@ -0,0 +1,47 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+/**
+ * Defaults.
+ *
+ * The default command-line options pulled from a `.dogent` file. Dogent looks
+ * first in the current directory, then in the user home, and reads the first
+ * file it finds. Each line names one option, written exactly as typed on the
+ * command line, with its value after a space. A blank line vanishes, and a
+ * line that opens with `#` reads as a comment. These options sit ahead of the
+ * real argv, so any flag typed by hand overrides the file.
+ */
+class Defaults {
+  constructor(
+    dirs = [process.cwd(), os.homedir()],
+    exists = (file) => fs.existsSync(file),
+    reader = (file) => fs.readFileSync(file, 'utf8')
+  ) {
+    this.dirs = dirs;
+    this.exists = exists;
+    this.reader = reader;
+  }
+  argv() {
+    const file = this.dirs
+      .map((dir) => path.join(dir, '.dogent'))
+      .find((candidate) => this.exists(candidate));
+    if (!file) {
+      return [];
+    }
+    return this.reader(file)
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line !== '' && !line.startsWith('#'))
+      .flatMap((line) => line.split(/\s+/u));
+  }
+}
+
+module.exports = Defaults;

package/src/dogent.js

@@ -8,6 +8,7 @@
 
 const fs = require('fs');
 const Args = require('./args');
+const Defaults = require('./defaults');
 const Markdown = require('./markdown');
 const Report = require('./report');
 const Sources = require('./sources');
@@ -18,7 +19,7 @@ const prettyMs = require('pretty-ms');
 const version = require('./version');
 const rules = require('./rules');
 
-const args = new Args(process.argv.slice(2));
+const args = new Args(new Defaults().argv().concat(process.argv.slice(2)));
 const sarif = args.sarif();
 const banner = 'Usage: dogent [--sarif] [--offline] [--suppress=RULE,...] <file.md|dir>...';
 if (args.version()) {
@@ -33,8 +34,12 @@ if (args.help()) {
     '  --sarif    render the report as SARIF JSON\n' +
     '  --offline  never call the LLM, even when a token exists\n' +
     '  --suppress silence a rule by id; repeat or comma-join to silence many\n' +
+    '  --openai-http-header  add a "Name: Value" header to OpenAI calls\n' +
     '  --version  show the version and exit\n' +
-    '  --help     show this help and exit\n'
+    '  --help     show this help and exit\n\n' +
+    'Defaults:\n' +
+    '  A .dogent file in the current directory or home holds default\n' +
+    '  options, one per line; options typed by hand override it.\n'
   );
   process.exit(0);
 }
@@ -44,6 +49,13 @@ if (unknown.length > 0) {
   process.stderr.write(`${banner}\n`);
   process.exit(2);
 }
+let headers = {};
+try {
+  headers = args.headers();
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exit(2);
+}
 const paths = args.paths();
 if (paths.length === 0) {
   process.stderr.write(`${banner}\n`);
@@ -72,7 +84,11 @@ const audit = async (docs) => {
     new Openai(
       key,
       process.env.OPENAI_MODEL || 'gpt-4o-mini',
-      (url, options) => globalThis.fetch(url, options)
+      process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1',
+      (url, options) => globalThis.fetch(
+        url,
+        {...options, headers: {...options.headers, ...headers}}
+      )
     )
   );
   const replies = await Promise.all(docs.map((doc) => oracle.violations(doc)));

package/src/openai.js

@@ -10,20 +10,23 @@ const Usage = require('./usage');
 /**
  * Openai.
  *
- * A thin adapter over the OpenAI chat-completions endpoint. Sends one
- * prompt, demands a JSON object back, and returns the assistant text
- * paired with a Usage tally of the model and the tokens it consumed.
+ * A thin adapter over an OpenAI-compatible chat-completions endpoint.
+ * Sends one prompt, demands a JSON object back, and returns the assistant
+ * text paired with a Usage tally of the model and the tokens it consumed.
+ * The base URL is configurable, so the same adapter reaches OpenAI itself
+ * or any compatible server, such as vLLM, Ollama, or a private gateway.
  * The transport is injected so the class runs in tests without a socket.
  */
 class Openai {
-  constructor(key, model, transport) {
+  constructor(key, model, base, transport) {
     this.key = key;
     this.model = model;
+    this.base = base;
     this.transport = transport;
   }
   async answer(prompt) {
     const response = await this.transport(
-      'https://api.openai.com/v1/chat/completions',
+      `${this.base.replace(/\/+$/u, '')}/chat/completions`,
       {
         method: 'POST',
         headers: {

package/src/prompt.js

@@ -41,10 +41,6 @@ class Prompt {
       'report nothing and return {"results": []}. Never invent a',
       'violation to seem useful, and never flag a line merely for',
       'sitting in a plain, on-topic section.',
-      'One clash is never a false alarm: when two lines give the same',
-      'order twice, or demand opposite things, report each offending',
-      'line with high confidence, even while every other check stays',
-      'conservative. A clean file has no such clash and stays silent.',
       'Report a violation only when you are certain it breaks a check.',
       'Give every result a "confidence" number from 0 to 1, your own',
       'probability that the violation is real, and omit any result you',

package/src/rules/ambiguous-or.js

@@ -0,0 +1,58 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+const mask = require('../mask');
+
+/**
+ * AmbiguousOr.
+ *
+ * An "either-or" choice left to the reader is an instruction the agent
+ * cannot follow without guessing. This flags the literal "and/or" and a
+ * two-term slashed alternative like "tabs/spaces", each demanding the
+ * author pick one branch and state exactly which option applies. Inline
+ * code is masked first, so a backticked path such as `src/app` never
+ * matches. Subtler ambiguities stay with the oracle; prompt() defers
+ * the open-ended either-or judgement to it.
+ */
+class AmbiguousOr {
+  constructor() {
+    this.id = 'ambiguous-or';
+  }
+  prompt() {
+    return `${this.id}: flag either-or ambiguity beyond "and/or" and slashed alternatives, and state exactly which option applies`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: () => [],
+      prose: (text, line) => this.scan(text, line, uri),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  scan(text, line, uri) {
+    const masked = mask(text);
+    const pattern = /\band\/or\b|(?<![\w./])[A-Za-z]{2,}\/[A-Za-z]{2,}(?![\w/]|\.\w)/giu;
+    const found = [];
+    let hit = pattern.exec(masked);
+    while (hit !== null) {
+      found.push(new Violation(
+        this.id,
+        'warning',
+        `ambiguous "${hit[0]}", state exactly which option applies`,
+        new Region(uri, line, hit.index + 1)
+      ));
+      hit = pattern.exec(masked);
+    }
+    return found;
+  }
+}
+
+module.exports = AmbiguousOr;

package/src/rules/conditional.js

@@ -0,0 +1,55 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+const mask = require('../mask');
+
+/**
+ * Conditional.
+ *
+ * Demands that branching never collapse onto one line. A line carrying
+ * more than one condition keyword (if, unless, when, else, otherwise)
+ * spells out a whole branch tree at once, so each case must split into
+ * its own command. Distinct from simple, which weighs clause depth, and
+ * from atomic, which counts instructions; this one targets branching
+ * alone. A lone guard keeps just one keyword and stays clean.
+ */
+class Conditional {
+  constructor() {
+    this.id = 'conditional';
+  }
+  prompt() {
+    return `${this.id}: flag implicit branching that carries no keyword, and split each case into its own command`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: () => [],
+      prose: (text, line) => this.judge(text, line, uri),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  judge(text, line, uri) {
+    const clean = mask(text);
+    const hits = clean.match(/\b(?:if|unless|when|else|otherwise)\b/giu);
+    if (hits === null || hits.length < 2) {
+      return [];
+    }
+    const column = clean.search(/\b(?:if|unless|when|else|otherwise)\b/iu);
+    return [new Violation(
+      this.id,
+      'warning',
+      'multi-branch conditional, split each case into its own command',
+      new Region(uri, line, column + 1)
+    )];
+  }
+}
+
+module.exports = Conditional;

package/src/rules/consistent.js

@@ -20,7 +20,7 @@ class Consistent {
     this.id = 'consistent';
   }
   prompt() {
-    return `${this.id}: flag an instruction that repeats another instruction word for word, or that directly contradicts another instruction in the same file`;
+    return `${this.id}: flag an instruction that repeats another instruction word for word, or that logically contradicts another instruction about the very same subject, where one line orders exactly what another forbids; ignore lines that merely share a theme but govern different concerns, since complementary instructions never clash`;
   }
   violations() {
     return [];

package/src/rules/default.js

@@ -0,0 +1,60 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+const mask = require('../mask');
+
+/**
+ * Default.
+ *
+ * Demands that optional behavior names its default. A line marking work
+ * as optional through "optionally", "you may", or "feel free to" leaves
+ * the agent guessing what happens when it declines, so the line must
+ * state a default. A line that already declares one through "by
+ * default", "defaults to", or "otherwise" passes untouched. Its prompt
+ * hands subtler optionality with no stated default to the AI oracle.
+ */
+class Default {
+  constructor() {
+    this.id = 'default';
+  }
+  prompt() {
+    return `${this.id}: flag optionality that names no default even without a listed marker, and state the default`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: () => [],
+      prose: (text, line) => this.scan(text, line, uri),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  scan(text, line, uri) {
+    const masked = mask(text);
+    if ((/\b(?:by default|default to|defaults to|otherwise)\b/iu).test(masked)) {
+      return [];
+    }
+    const found = [];
+    const regex = /\b(?:optionally|you may|you can|if you want|feel free to|as an option)\b/giu;
+    let hit = regex.exec(masked);
+    while (hit !== null) {
+      found.push(new Violation(
+        this.id,
+        'warning',
+        `optional behavior "${hit[0]}" has no default, state it`,
+        new Region(uri, line, hit.index + 1)
+      ));
+      hit = regex.exec(masked);
+    }
+    return found;
+  }
+}
+
+module.exports = Default;

package/src/rules/description-length.js

@@ -0,0 +1,64 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * DescriptionLength.
+ *
+ * Demands that a SKILL.md description stay within a sane size. The
+ * loader keeps every description in context, so an overgrown one wastes
+ * the budget that the instructions need. Flags a value longer than the
+ * ceiling and a value that is empty, leaving the wording itself to
+ * sibling rules.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
+ */
+class DescriptionLength {
+  constructor() {
+    this.id = 'description-length';
+    this.ceiling = 1024;
+  }
+  prompt() {
+    return '';
+  }
+  violations(document) {
+    const uri = document.uri();
+    if (uri.replace(/^.*\//u, '') !== 'SKILL.md') {
+      return [];
+    }
+    const pairs = document.walk({
+      header: () => [],
+      prose: () => [],
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: (keys) => keys
+    });
+    const found = pairs.filter((pair) => pair.key === 'description');
+    if (found.length === 0) {
+      return [];
+    }
+    return this.judge(found[0], uri);
+  }
+  judge(pair, uri) {
+    const {value} = pair;
+    if (value.trim() === '') {
+      return [this.flag('description is empty, write a concise capability statement', pair.row, uri)];
+    }
+    if (value.length > this.ceiling) {
+      return [this.flag(`description is ${value.length} chars, keep it under ${this.ceiling}`, pair.row, uri)];
+    }
+    return [];
+  }
+  flag(message, row, uri) {
+    return new Violation(this.id, 'warning', message, new Region(uri, row, 1));
+  }
+}
+
+module.exports = DescriptionLength;

package/src/rules/description-voice.js

@@ -0,0 +1,67 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * DescriptionVoice.
+ *
+ * Demands that a SKILL.md description stay in the third person, reading
+ * as a capability statement like "Extracts tables ..." rather than a
+ * first- or second-person sentence like "I extract ..." or "You can
+ * use ...". A standalone checker flags first- and second-person
+ * pronouns as whole words, after dropping the trigger clause that opens
+ * with "Use when" so a legitimate "Use when ..." phrase stays clean.
+ * Distinct from description-triggers, which checks that a "when" clause
+ * exists, and from description-length, which checks the size; this one
+ * checks the grammatical voice. Its prompt hands subtler voice
+ * judgement to the AI oracle.
+ */
+class DescriptionVoice {
+  constructor() {
+    this.id = 'description-voice';
+    this.pronoun = /\b(?:I|we|you|your|my|our)\b/giu;
+  }
+  prompt() {
+    return `${this.id}: in a SKILL.md, flag a description written in first or second person and demand a third-person capability statement`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    if (uri.replace(/^.*\//u, '') !== 'SKILL.md') {
+      return [];
+    }
+    const pairs = document.walk({
+      header: () => [],
+      prose: () => [],
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: (keys) => keys
+    });
+    const found = pairs.filter((pair) => pair.key === 'description');
+    if (found.length === 0) {
+      return [];
+    }
+    return this.judge(found[0], uri);
+  }
+  judge(pair, uri) {
+    const text = pair.value.replace(/use when.*$/isu, '');
+    this.pronoun.lastIndex = 0;
+    const hit = this.pronoun.exec(text);
+    if (hit === null) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      `description must be third person, not "${hit[0]}"`,
+      new Region(uri, pair.row, 1)
+    )];
+  }
+}
+
+module.exports = DescriptionVoice;