@yegor256/dogent 0.9.1 → 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
@@ -67,20 +91,30 @@ The command exits with a non-zero status when problems are found,
 - Every section must be a level-2 (`##`) heading, below the lone `#` title.
 - Every line must be no longer than 80 symbols.
 - The whole file must stay under 4000 tokens.
+- The whole file must stay short; split detail into referenced files.
 - Every line must sound like a command.
 - Every sentence must start with a capital and end with a period.
 - No articles, no noise, no bloated text.
 - Simple grammar, no ambiguity.
+- No bare pronoun subjects; name the subject on the line.
 - No tangled, multi-clause instructions.
+- Sequential steps must be a numbered list, not bullets.
 - A `SKILL.md` `name` must equal its parent directory.
 - No courtesy or scaffolding words.
 - No leftover markers or unfilled placeholders.
 - A section must hold at most ten instructions.
 - A `SKILL.md` `description` must say when to use the skill.
+- A `SKILL.md` must carry at least one worked example.
+- A `SKILL.md` that produces output must declare its format.
 - Every line must carry exactly one instruction.
 - No hedging or soft wording.
+- No vague qualifiers; demand a measurable criterion.
 - No passive voice; use the active imperative.
+- No ALL-CAPS shouting or "!!" markers; state it plainly.
+- No persona or role-play; it adds no instruction.
+- No negative phrasing; state the positive command instead.
 - No instruction may repeat another.
+- No unguarded consumption of untrusted external input.
 - `SKILL.md` must open with valid frontmatter.
 - Frontmatter must declare only allowed keys.
 - A `SKILL.md` `name` must be kebab-case.
@@ -96,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`.
@@ -105,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:
 
@@ -114,6 +162,50 @@ npx @yegor256/dogent --offline CLAUDE.md
 
 Pass `--sarif` to print the report as SARIF instead of plain text.
 
+Pass `--suppress` to silence a rule by its id. Repeat the option or
+  join several ids with commas to silence many at once:
+
+```bash
+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.
@@ -159,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,8 +40,9 @@
     "lint": "eslint .",
     "test": "mocha 'test/**/*.js' --timeout 60000"
   },
-  "version": "0.9.1",
+  "version": "0.11.0",
   "dependencies": {
-    "minimist": "^1.2.8"
+    "minimist": "^1.2.8",
+    "pretty-ms": "^7.0.1"
   }
 }

package/src/args.js

@@ -15,13 +15,24 @@ const minimist = require('minimist');
  * The `--sarif` flag switches the report to SARIF, while `--offline` forbids
  * 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. Everything after a `--` separator counts as a
+ * 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. 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']) {
+  constructor(
+    argv,
+    flags = ['sarif', 'offline', 'help', 'version'],
+    options = ['suppress', 'openai-http-header']
+  ) {
     this.flags = flags;
-    this.parsed = minimist(argv, {boolean: flags, alias: {help: 'h'}, '--': true});
+    this.options = options;
+    this.parsed = minimist(
+      argv,
+      {boolean: flags, string: options, alias: {help: 'h'}, '--': true}
+    );
   }
   sarif() {
     return this.parsed.sarif === true;
@@ -35,12 +46,32 @@ class Args {
   version() {
     return this.parsed.version === true;
   }
+  suppress() {
+    return [].concat(this.parsed.suppress || [])
+      .flatMap((item) => String(item).split(','))
+      .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);
   }
   unknown() {
     return Object.keys(this.parsed)
-      .filter((key) => key !== '_' && key !== '--' && key !== 'h' && !this.flags.includes(key))
+      .filter((key) => key !== '_' && key !== '--' && key !== 'h' &&
+        !this.flags.includes(key) && !this.options.includes(key))
       .map((key) => `${key.length === 1 ? '-' : '--'}${key}`);
   }
 }

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,18 +8,20 @@
 
 const fs = require('fs');
 const Args = require('./args');
+const Defaults = require('./defaults');
 const Markdown = require('./markdown');
 const Report = require('./report');
 const Sources = require('./sources');
 const Openai = require('./openai');
 const Oracle = require('./oracle');
 const Usage = require('./usage');
+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] <file.md|dir>...';
+const banner = 'Usage: dogent [--sarif] [--offline] [--suppress=RULE,...] <file.md|dir>...';
 if (args.version()) {
   process.stdout.write(`${version}\n`);
   process.exit(0);
@@ -31,8 +33,13 @@ if (args.help()) {
     'Options:\n' +
     '  --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);
 }
@@ -42,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`);
@@ -49,24 +63,32 @@ if (paths.length === 0) {
 }
 const scanned = new Sources(paths).files();
 scanned.forEach((file) => process.stderr.write(`Scanning ${file}\n`));
-process.stderr.write(`${scanned.length} files scanned\n`);
+const checks = rules();
+process.stderr.write(`${scanned.length} files scanned, ${checks.length} rules applied\n`);
 const documents = scanned.map(
   (file) => new Markdown(file, fs.readFileSync(file, 'utf8')).document()
 );
+const started = Date.now();
+const suppressed = args.suppress();
+const allowed = (violation) => !suppressed.includes(violation.rule);
 const found = [];
 documents.forEach((document) => {
-  rules().forEach((rule) => {
-    rule.violations(document).forEach((violation) => found.push(violation));
+  checks.forEach((rule) => {
+    rule.violations(document).filter(allowed).forEach((violation) => found.push(violation));
   });
 });
 const key = process.env.OPENAI_API_KEY;
 const audit = async (docs) => {
   const oracle = new Oracle(
-    rules(),
+    checks,
     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)));
@@ -78,25 +100,29 @@ const audit = async (docs) => {
     {extra: [], usage: new Usage('', 0, 0)}
   );
 };
-const finish = (usage) => {
-  const report = new Report('dogent', found);
+const finish = (usage, aiMillis) => {
+  const report = new Report('dogent', found, Date.now() - started);
   process.stdout.write(`${sarif ? JSON.stringify(report.sarif(), null, 2) : report.text()}\n`);
   if (usage !== null) {
-    process.stderr.write(`${usage.text()}\n`);
+    process.stderr.write(`${usage.text()}, analysed in ${prettyMs(aiMillis)}\n`);
   }
   process.exit(report.count() > 0 ? 1 : 0);
 };
+const verify = async () => {
+  const clock = Date.now();
+  const result = await audit(documents);
+  result.extra.filter(allowed).forEach((violation) => found.push(violation));
+  return {usage: result.usage, aiMillis: Date.now() - clock};
+};
 (async () => {
-  let usage = null;
+  let outcome = {aiMillis: 0, usage: null};
   if (found.length === 0 && key && !args.offline()) {
     try {
-      const result = await audit(documents);
-      result.extra.forEach((violation) => found.push(violation));
-      ({usage} = result);
+      outcome = await verify();
     } catch (error) {
       process.stderr.write(`AI verification failed: ${error.message}\n`);
       process.exit(2);
     }
   }
-  finish(usage);
+  finish(outcome.usage, outcome.aiMillis);
 })();

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/report.js

@@ -5,24 +5,30 @@
 
 'use strict';
 
+const prettyMs = require('pretty-ms');
+
 /**
  * Report.
  *
  * The whole verdict of a run: the tool that produced it and every
  * violation it gathered. Renders itself for humans or as a SARIF log.
+ * When handed the analysis duration in milliseconds, the human text
+ * closes with a friendly "in 340ms" rendered through pretty-ms.
  */
 class Report {
-  constructor(tool, violations) {
+  constructor(tool, violations, millis = null) {
     this.tool = tool;
     this.bag = violations;
+    this.millis = millis;
   }
   count() {
     return this.bag.length;
   }
   text() {
+    const suffix = this.millis === null ? '' : ` in ${prettyMs(this.millis)}`;
     return this.bag
       .map((violation) => violation.text())
-      .concat(`${this.bag.length} problems found`)
+      .concat(`${this.bag.length} problems found${suffix}`)
       .join('\n');
   }
   sarif() {

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/budget.js

@@ -0,0 +1,50 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * Budget.
+ *
+ * Demands that a whole manifesto stay short enough to stay readable,
+ * holding no more instructions than the cap allows. Counts every prose
+ * line plus every bullet item across the file and complains once with a
+ * single file-level violation when the total exceeds the cap.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
+ */
+class Budget {
+  constructor(cap) {
+    this.id = 'budget';
+    this.cap = cap;
+  }
+  prompt() {
+    return '';
+  }
+  violations(document) {
+    const count = document.walk({
+      header: () => [],
+      prose: () => [1],
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    }).length;
+    if (count <= this.cap) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'error',
+      `file holds ${count} instructions, budget ${this.cap}, split the manifesto`,
+      new Region(document.uri(), 1, 1)
+    )];
+  }
+}
+
+module.exports = Budget;

package/src/rules/concise.js

@@ -0,0 +1,48 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * Concise.
+ *
+ * Bounds a manifesto by structure, not only by token volume. Models read
+ * the start and end of a long context and skip the middle, so a manifesto
+ * that runs past a line budget silently buries its middle instructions.
+ * Counts physical lines and warns once the file crosses a configurable
+ * ceiling, recommending a split into referenced detail files in the
+ * spirit of progressive disclosure. This is distinct from token-count: it
+ * measures structure and position risk, not raw token volume. Its prompt
+ * hands the deeper split judgement to the AI oracle.
+ */
+class Concise {
+  constructor(max) {
+    this.id = 'concise';
+    this.max = max;
+  }
+  prompt() {
+    return `${this.id}: flag a manifesto so long its middle instructions risk being lost, and recommend splitting detail into referenced files`;
+  }
+  violations(document) {
+    const lines = document.text().split('\n');
+    while (lines.length > 0 && lines[lines.length - 1] === '') {
+      lines.pop();
+    }
+    if (lines.length <= this.max) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      `file too long (${lines.length} lines), split detail into referenced files`,
+      new Region(document.uri(), this.max + 1, 1)
+    )];
+  }
+}
+
+module.exports = Concise;