@yegor256/dogent 0.9.1 → 0.10.0

package/README.md

@@ -67,20 +67,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.
@@ -114,6 +124,13 @@ 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
+```
+
 ## GitHub Actions
 
 Because `dogent` runs through `npx`, no extra action is needed.

package/package.json

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

package/src/args.js

@@ -15,13 +15,22 @@ 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
- * path, never as an option.
+ * 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.
  */
 class Args {
-  constructor(argv, flags = ['sarif', 'offline', 'help', 'version']) {
+  constructor(
+    argv,
+    flags = ['sarif', 'offline', 'help', 'version'],
+    options = ['suppress']
+  ) {
     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 +44,19 @@ 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 !== '');
+  }
   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/dogent.js

@@ -14,12 +14,13 @@ 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 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,6 +32,7 @@ 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' +
     '  --version  show the version and exit\n' +
     '  --help     show this help and exit\n'
   );
@@ -49,20 +51,24 @@ 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',
@@ -78,25 +84,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/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/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;

package/src/rules/counter-example.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');
+
+/**
+ * CounterExample.
+ *
+ * Rejects "bad example" demonstrations that show the wrong form, since
+ * displaying a mistake can reinforce it. A standalone checker flags a
+ * line that opens a counterexample with an introducer phrase ("bad
+ * example", "wrong example", "for example, do not", "instead of
+ * writing", "avoid writing") and then carries a quoted or backticked
+ * sample of the wrong form. Its prompt hands subtler cases to the AI
+ * oracle, which judges whether an example shows the correct or the
+ * incorrect behavior.
+ */
+class CounterExample {
+  constructor() {
+    this.id = 'counter-example';
+  }
+  prompt() {
+    return `${this.id}: judge whether each example shows the correct behavior, and flag any example that demonstrates the incorrect form`;
+  }
+  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 regex = /bad example|wrong example|for example, do not|instead of writing|avoid writing/iu;
+    const hit = regex.exec(mask(text));
+    if (hit === null) {
+      return [];
+    }
+    const tail = text.slice(hit.index + hit[0].length);
+    if (!/["'`]/u.test(tail)) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      'counterexample may reinforce the wrong behavior, show the right form',
+      new Region(uri, line, hit.index + 1)
+    )];
+  }
+}
+
+module.exports = CounterExample;

package/src/rules/done.js

@@ -0,0 +1,53 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * Done.
+ *
+ * Demands that a SKILL.md state a verifiable completion check, symmetric
+ * to the description trigger requirement. A standalone checker can only
+ * approximate: it scans headings and prose for a verification signal. Its
+ * prompt hands the deeper judgement to the AI oracle, which weighs whether
+ * the stated check is truly pass/fail testable rather than vague.
+ */
+class Done {
+  constructor() {
+    this.id = 'done';
+  }
+  prompt() {
+    return `${this.id}: in a SKILL.md, judge whether the stated completion check is actually pass/fail testable rather than a vague gesture toward being finished`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    if (uri.replace(/^.*\//u, '') !== 'SKILL.md') {
+      return [];
+    }
+    const signals = document.walk({
+      header: (text) => [/\b(?:verify|done|check|validation|acceptance)\b/iu.test(text)],
+      prose: (text) => [/\b(?:confirm|assert|verify|the test passes|tests pass|exit code|pass\/fail)\b/iu.test(text)],
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+    if (signals.some((signal) => signal)) {
+      return [];
+    }
+    return [
+      new Violation(
+        this.id,
+        'warning',
+        'SKILL.md never says how to verify completion',
+        new Region(uri, 1, 1)
+      )
+    ];
+  }
+}
+
+module.exports = Done;

package/src/rules/emphasis.js

@@ -0,0 +1,81 @@
+/*
+ * 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');
+
+/**
+ * Emphasis.
+ *
+ * Flags shouting that tries to force compliance through volume rather
+ * than clarity: a curated all-caps word like "IMPORTANT" or "NEVER", a
+ * run of two or more consecutive all-caps words, and repeated marks like
+ * "!!" or "!?". The model gains nothing from volume, so the emphasis is
+ * pure noise. A lone short acronym such as "JSON" or "AI" is left alone.
+ * Its prompt hands the borderline emphasis and reward framing the
+ * patterns miss to the AI oracle.
+ */
+class Emphasis {
+  constructor() {
+    this.id = 'emphasis';
+    this.shout = new Set(['IMPORTANT', 'ALWAYS', 'NEVER', 'MUST', 'CRITICAL', 'REQUIRED']);
+  }
+  prompt() {
+    return `${this.id}: flag emphatic shouting the patterns miss, including borderline all-caps and reward framing, since emphasis adds no instruction`;
+  }
+  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);
+    return this.punctuation(masked, line, uri).concat(this.shouting(masked, line, uri));
+  }
+  punctuation(masked, line, uri) {
+    const found = [];
+    const regex = /!{2,}|!\?|\?!/gu;
+    let hit = regex.exec(masked);
+    while (hit !== null) {
+      found.push(this.flag(hit[0], line, hit.index, uri));
+      hit = regex.exec(masked);
+    }
+    return found;
+  }
+  shouting(masked, line, uri) {
+    const found = [];
+    const regex = /[A-Z]{2,}(?:\s+[A-Z]{2,})*/gu;
+    let hit = regex.exec(masked);
+    while (hit !== null) {
+      const tokens = hit[0].split(/\s+/u);
+      const loud = tokens.length > 1
+        ? tokens.some((token) => token.length >= 5 || this.shout.has(token))
+        : this.shout.has(tokens[0]);
+      if (loud) {
+        found.push(this.flag(hit[0], line, hit.index, uri));
+      }
+      hit = regex.exec(masked);
+    }
+    return found;
+  }
+  flag(marker, line, index, uri) {
+    return new Violation(
+      this.id,
+      'warning',
+      `emphasis marker "${marker}" adds no instruction, state it plainly`,
+      new Region(uri, line, index + 1)
+    );
+  }
+}
+
+module.exports = Emphasis;

package/src/rules/example.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');
+
+/**
+ * Example.
+ *
+ * Demands that a SKILL.md demonstrate, not only describe. A skill that
+ * states rules in prose alone leaves the agent to infer the exact shape
+ * of correct output, while a single worked example is one of the most
+ * reliable levers in prompt engineering. A standalone checker passes the
+ * skill that carries at least one fenced code block or an explicit
+ * "Example" section heading, and flags the one that has neither. Its
+ * prompt hands the deeper judgement to the AI oracle, which weighs
+ * whether a present code block is truly illustrative.
+ */
+class Example {
+  constructor() {
+    this.id = 'example';
+  }
+  prompt() {
+    return `${this.id}: in a SKILL.md, judge whether a present code block is a genuine worked example rather than a stray snippet, and flag a skill that only describes without demonstrating`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    if (uri.replace(/^.*\//u, '') !== 'SKILL.md') {
+      return [];
+    }
+    const hints = document.walk({
+      header: (text) => this.heading(text),
+      prose: () => [],
+      snippet: () => ['snippet'],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+    if (hints.length > 0) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      'SKILL.md has no example, add a worked input/output sample',
+      new Region(uri, 1, 1)
+    )];
+  }
+  heading(text) {
+    if (/^#{1,6}\s+examples?\b/iu.test(text)) {
+      return [this.id];
+    }
+    return [];
+  }
+}
+
+module.exports = Example;

package/src/rules/format.js

@@ -0,0 +1,68 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * Format.
+ *
+ * Demands that a SKILL.md which produces output pin down that output's
+ * shape. Structured-output generation grows far more reliable when the
+ * expected format is declared and shown, while leaving it implicit
+ * produces brittle, drifting output. A standalone checker flags a skill
+ * whose instructions describe producing output (verbs like "produce",
+ * "output", "return", "generate", "write", "emit") yet no section or
+ * snippet declares the output shape. This is distinct from the example
+ * rule: an example shows one case, a format spec defines the contract.
+ * Its prompt asks the AI oracle whether the declared format is concrete
+ * enough to be machine-checkable.
+ */
+class Format {
+  constructor() {
+    this.id = 'format';
+  }
+  prompt() {
+    return `${this.id}: in a SKILL.md, judge whether the declared output format is concrete and machine-checkable, and flag a generating skill that pins down no format`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    if (uri.replace(/^.*\//u, '') !== 'SKILL.md') {
+      return [];
+    }
+    const heading = /^#{1,6}\s+.*\b(?:format|schema|structure|output)\b/iu;
+    const verb = /\b(?:produces?|outputs?|returns?|generates?|writes?|emits?)\b/iu;
+    const signals = document.walk({
+      header: (text) => {
+        if (heading.test(text)) {
+          return ['declared'];
+        }
+        return [];
+      },
+      prose: (text) => {
+        if (verb.test(text)) {
+          return ['generates'];
+        }
+        return [];
+      },
+      snippet: () => ['declared'],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+    if (!signals.includes('generates') || signals.includes('declared')) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      'SKILL.md generates output but never declares its format',
+      new Region(uri, 1, 1)
+    )];
+  }
+}
+
+module.exports = Format;