@yegor256/dogent 0.9.1 → 0.10.0

package/src/rules/index.js

@@ -21,6 +21,7 @@ const NameMatchesDir = require('./name-matches-dir');
 const Polite = require('./polite');
 const Unfinished = require('./unfinished');
 const Crowded = require('./crowded');
+const Budget = require('./budget');
 const DescriptionTriggers = require('./description-triggers');
 const Atomic = require('./atomic');
 const Hedging = require('./hedging');
@@ -29,6 +30,25 @@ const Unique = require('./unique');
 const Consistent = require('./consistent');
 const Simple = require('./simple');
 const SectionLevel = require('./section-level');
+const Format = require('./format');
+const Untrusted = require('./untrusted');
+const Ordered = require('./ordered');
+const Emphasis = require('./emphasis');
+const Persona = require('./persona');
+const Concise = require('./concise');
+const Example = require('./example');
+const Referential = require('./referential');
+const Vague = require('./vague');
+const Positive = require('./positive');
+const Done = require('./done');
+const Terms = require('./terms');
+const Jargon = require('./jargon');
+const PseudoHeading = require('./pseudo-heading');
+const Stale = require('./stale');
+const ToolClarity = require('./tool-clarity');
+const CounterExample = require('./counter-example');
+const Rationale = require('./rationale');
+const SelfContained = require('./self-contained');
 
 module.exports = () => [
   new Grouped(),
@@ -37,6 +57,7 @@ module.exports = () => [
   new SectionLevel(),
   new LineLength(80),
   new TokenCount(4000),
+  new Concise(200),
   new NoArticles(),
   new Command(),
   new Punctuation(),
@@ -44,14 +65,33 @@ module.exports = () => [
   new Redundant(),
   new Consistent(),
   new Simple(),
+  new Referential(),
   new NameMatchesDir(),
   new Polite(),
   new Unfinished(),
   new Crowded(10),
+  new Budget(60),
   new DescriptionTriggers(),
+  new Example(),
+  new Format(),
   new Atomic(),
+  new Ordered(),
   new Hedging(),
+  new Vague(),
+  new ToolClarity(),
   new Passive(),
+  new Untrusted(),
+  new Emphasis(),
+  new Persona(),
+  new Positive(),
+  new Done(),
+  new Terms(),
+  new Jargon(),
+  new PseudoHeading(),
+  new Stale(),
+  new CounterExample(),
+  new Rationale(),
+  new SelfContained(),
   new Unique(),
   new Frontmatter(
     'SKILL.md',

package/src/rules/jargon.js

@@ -0,0 +1,105 @@
+/*
+ * 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');
+
+const ALLOWLIST = new Set([
+  'AI',
+  'CI',
+  'CD',
+  'CLI',
+  'API',
+  'URL',
+  'URI',
+  'HTTP',
+  'HTTPS',
+  'JSON',
+  'YAML',
+  'XML',
+  'HTML',
+  'CSS',
+  'SQL',
+  'ID',
+  'OK',
+  'OS',
+  'IO',
+  'NPM',
+  'PR',
+  'MIT',
+  'SARIF',
+  'SKILL',
+  'CLAUDE'
+]);
+
+const defined = (masked) => {
+  const found = new Set();
+  const regex = /\b(?<acronym>[A-Z]{2,})\s*\(/gu;
+  let hit = regex.exec(masked);
+  while (hit !== null) {
+    found.add(hit.groups.acronym);
+    hit = regex.exec(masked);
+  }
+  return found;
+};
+
+const undefining = (acronym, scope) => !scope.known.has(acronym) &&
+  !ALLOWLIST.has(acronym);
+
+/**
+ * Jargon.
+ *
+ * Flags an acronym that lands in prose without ever being expanded. An
+ * acronym counts as defined when the document, anywhere, follows it with
+ * a parenthetical gloss, as in "RBAC (role-based access control)", so a
+ * single expansion licenses every later mention. Well-known acronyms sit
+ * in a built-in allowlist and pass untouched. Only the first unexpanded
+ * occurrence of each acronym is reported. Its prompt hands non-acronym
+ * domain jargon, the rare nouns a reader cannot parse, to the AI oracle.
+ */
+class Jargon {
+  constructor() {
+    this.id = 'jargon';
+  }
+  prompt() {
+    return `${this.id}: flag non-acronym domain jargon, rare nouns a fresh reader cannot parse, and ask for a plain-word definition on first use`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    const known = defined(mask(document.text()));
+    const seen = new Set();
+    return document.walk({
+      header: () => [],
+      prose: (text, line) => this.scan(text, line, {uri, known, seen}),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  scan(text, line, scope) {
+    const hits = [...mask(text).matchAll(/\b[A-Z]{2,}\b/gu)];
+    return hits.reduce((found, hit) => {
+      const [acronym] = hit;
+      const novel = !scope.seen.has(acronym) && undefining(acronym, scope);
+      scope.seen.add(acronym);
+      return novel
+        ? found.concat(this.flag(acronym, new Region(scope.uri, line, hit.index + 1)))
+        : found;
+    }, []);
+  }
+  flag(acronym, region) {
+    return new Violation(
+      this.id,
+      'warning',
+      `acronym "${acronym}" never expanded, define it on first use`,
+      region
+    );
+  }
+}
+
+module.exports = Jargon;

package/src/rules/ordered.js

@@ -0,0 +1,57 @@
+/*
+ * 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');
+
+/**
+ * Ordered.
+ *
+ * Demands a numbered list when order matters. Models follow numbered,
+ * sequentially ordered steps far more reliably than unordered bullets,
+ * and shuffling steps drops accuracy sharply. A standalone checker flags
+ * an unordered bullet item that carries a sequence marker like "first",
+ * "then", "next", "after that", "finally", or "step 2", since the order
+ * is real but the structure hides it. Its prompt hands implicit ordering
+ * with no marker word to the AI oracle.
+ */
+class Ordered {
+  constructor() {
+    this.id = 'ordered';
+  }
+  prompt() {
+    return `${this.id}: flag an implied sequence that no marker word signals, demanding a numbered list whenever the order of steps matters`;
+  }
+  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) {
+    if (!/^\s*[-*+]\s+/u.test(text)) {
+      return [];
+    }
+    const markers = /\b(?:first|second|third|then|next|after that|afterwards|finally|lastly|step\s+\d+)\b/iu;
+    if (!markers.test(mask(text))) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      'sequence detected, use a numbered list to fix the order',
+      new Region(uri, line, 1)
+    )];
+  }
+}
+
+module.exports = Ordered;

package/src/rules/persona.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');
+
+/**
+ * Persona.
+ *
+ * Flags gratuitous role-play that opens a manifesto with a persona:
+ * "You are a senior engineer", "Act as an expert reviewer", and the
+ * like. The largest controlled study finds personas do not improve task
+ * performance and can hurt, so a role-play line is pure context bloat
+ * that adds no instruction. A standalone checker flags the line whose
+ * head assigns the agent a role; its prompt hands the indirect persona
+ * framing the regex misses to the AI oracle.
+ */
+class Persona {
+  constructor() {
+    this.id = 'persona';
+  }
+  prompt() {
+    return `${this.id}: flag indirect persona or role-play framing that assigns the agent a role with no fixed keyword, since a persona 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 regex = /^(?<marker>\s*(?:[-*+]|\d+\.)\s+)?(?:you are an? |act as |imagine you are |pretend to be |as an? \w+,)/iu;
+    const hit = regex.exec(mask(text));
+    if (hit === null) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      'persona assignment adds no instruction, delete it',
+      new Region(uri, line, (hit.groups.marker || '').length + 1)
+    )];
+  }
+}
+
+module.exports = Persona;

package/src/rules/positive.js

@@ -0,0 +1,57 @@
+/*
+ * 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');
+
+/**
+ * Positive.
+ *
+ * Demands positive, goal-oriented imperatives over bans. A standalone
+ * checker flags a line whose head is an obvious prohibition: "do not",
+ * "don't", "never", "avoid", "refrain from", "must not", or "no longer".
+ * A ban forces the model to process the forbidden concept first, so
+ * "Only use real data" beats "Don't use mock data". Its prompt hands
+ * subtler bans, those carrying no head keyword, to the AI
+ * oracle, which rewrites a prohibition with no keyword as a positive
+ * command.
+ */
+class Positive {
+  constructor() {
+    this.id = 'positive';
+  }
+  prompt() {
+    return `${this.id}: flag any instruction phrased as a prohibition, including bans carrying no fixed keyword, and rewrite each as a positive imperative`;
+  }
+  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 = /^(?<marker>\s*(?:[-*+]|\d+\.)\s+)?(?:do not|don't|never|avoid|refrain from|must not|no longer)\b/iu;
+    const hit = regex.exec(mask(text));
+    if (hit === null) {
+      return [];
+    }
+    const marker = hit.groups.marker || '';
+    return [new Violation(
+      this.id,
+      'warning',
+      'negative phrasing detected, state the positive command instead',
+      new Region(uri, line, marker.length + 1)
+    )];
+  }
+}
+
+module.exports = Positive;

package/src/rules/pseudo-heading.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');
+
+/**
+ * PseudoHeading.
+ *
+ * Rejects a bold line posing as a section heading, such as
+ * "**Setup:**" standing alone. The whole line, once an optional list
+ * marker drops, must sit inside one emphasis run, wrapped by "**" or
+ * "__" and ending in an optional colon. A line carrying only inline
+ * bold inside other words, like "Use **bold** sparingly.", stays free,
+ * since the emphasis wraps a fragment, not the whole label.
+ *
+ * Its prompt hands borderline label-versus-instruction calls to the AI
+ * oracle.
+ */
+class PseudoHeading {
+  constructor() {
+    this.id = 'pseudo-heading';
+  }
+  prompt() {
+    return `${this.id}: flag any bold line posing as a section heading, deferring borderline label-versus-instruction calls to the oracle, and demand a real level-2 "##" heading`;
+  }
+  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 body = text.trim().replace(/^(?:[-*+]|\d+\.)\s+/u, '');
+    if (!/^(?<fence>\*\*|__)(?!\s)(?:.+?)(?<!\s)\k<fence>:?$/u.test(body)) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      'bold pseudo-heading found, use a level-2 "##" heading',
+      new Region(uri, line, 1)
+    )];
+  }
+}
+
+module.exports = PseudoHeading;

package/src/rules/rationale.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');
+const mask = require('../mask');
+
+/**
+ * Rationale.
+ *
+ * Demands orders, not explanations. A standalone checker flags a line
+ * that opens with a justification marker such as "because", "the
+ * reason", "this keeps", "this ensures", "this helps", "so that", or
+ * "in order to", since such a line argues a point instead of issuing a
+ * command. Justification belongs in commit messages and design docs, so
+ * its prompt hands subtler explanation-only lines to the AI oracle.
+ */
+class Rationale {
+  constructor() {
+    this.id = 'rationale';
+  }
+  prompt() {
+    return `${this.id}: flag any line that explains a reason, motivation, or benefit instead of issuing a direct order, even when it carries no fixed marker, and convert each into a command or delete it`;
+  }
+  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 clean = mask(text).replace(/^\s*(?:[-*+]|\d+\.)\s+/u, '');
+    const regex = /^(?:because|the reason|this keeps|this ensures|this helps|so that|in order to)\b/iu;
+    if (!regex.test(clean)) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      'rationale carries no command, delete or convert to an order',
+      new Region(uri, line, 1)
+    )];
+  }
+}
+
+module.exports = Rationale;

package/src/rules/referential.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');
+const mask = require('../mask');
+
+/**
+ * Referential.
+ *
+ * Demands that every line name its own subject. A standalone checker
+ * flags a line that opens with a bare pronoun acting as the subject:
+ * "it", "they", and "them" always, and "this", "that", "these", or
+ * "those" only when a verb follows rather than a noun, so a determiner
+ * like "These rules stay final" stays clean. Such a pronoun points at a
+ * previous line, breaking the "one line, one instruction" contract. Its
+ * prompt hands the subtler mid-line dangling references to the AI oracle.
+ */
+class Referential {
+  constructor() {
+    this.id = 'referential';
+    this.verbs = new RegExp(
+      '^(?:is|are|was|were|be|been|being|will|would|can|could|shall|' +
+      'should|must|may|might|has|have|had|do|does|did|only|then|runs|' +
+      'run|applies|apply|happens|happen|means|requires|needs|comes|' +
+      'goes|makes|breaks|points|refers)$',
+      'iu'
+    );
+  }
+  prompt() {
+    return `${this.id}: flag any line whose subject is a pronoun with no antecedent on the same line, including mid-line dangling references a head pattern misses`;
+  }
+  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 = /^(?<marker>\s*(?:[-*+]|\d+\.)\s+)?(?<pro>it|this|that|they|them|these|those)\b\s+(?<next>[\w']+)/iu;
+    const hit = regex.exec(mask(text));
+    if (hit === null) {
+      return [];
+    }
+    const pronoun = hit.groups.pro.toLowerCase();
+    const ambiguous = /^(?:this|that|these|those)$/u.test(pronoun);
+    if (ambiguous && !this.verbs.test(hit.groups.next)) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      `pronoun "${hit.groups.pro}" has no antecedent on this line, name the subject`,
+      new Region(uri, line, (hit.groups.marker || '').length + 1)
+    )];
+  }
+}
+
+module.exports = Referential;

package/src/rules/self-contained.js

@@ -0,0 +1,66 @@
+/*
+ * 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');
+
+/**
+ * SelfContained.
+ *
+ * Demands that every line stand on its own without leaning on its
+ * neighbours. A standalone checker flags a relative cross-reference
+ * phrase like "see above", "as mentioned below", or "the previous
+ * step" that breaks the moment the file is reordered or chunked. A
+ * line pointing somewhere concrete through a markdown link stays
+ * clean. Distinct from referential, which targets bare pronouns; this
+ * one targets positional cross-references. Its prompt hands subtler
+ * dangling references to the AI oracle.
+ */
+class SelfContained {
+  constructor() {
+    this.id = 'self-contained';
+    this.phrase = new RegExp(
+      'mentioned above|mentioned below|see above|see below|' +
+      'as discussed|the section above|the section below|' +
+      'the previous step|as stated earlier|mentioned earlier|' +
+      'refer to the guide',
+      'iu'
+    );
+  }
+  prompt() {
+    return `${this.id}: flag any line leaning on a relative cross-reference such as "see above" that breaks when the file is reordered or chunked, deferring subtler dangling references to the oracle`;
+  }
+  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 clean = mask(text);
+    if (clean.includes('](')) {
+      return [];
+    }
+    const hit = this.phrase.exec(clean);
+    if (hit === null) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      `relative reference "${hit[0]}" breaks when reordered, name the target`,
+      new Region(uri, line, hit.index + 1)
+    )];
+  }
+}
+
+module.exports = SelfContained;

package/src/rules/stale.js

@@ -0,0 +1,62 @@
+/*
+ * 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');
+
+/**
+ * Stale.
+ *
+ * Flags volatile time and version references that rot over time:
+ * words like "currently", "now", "today", "recently", and hardcoded
+ * version literals such as "18.17.0". Each pins an instruction to a
+ * moment or release that drifts, so the manifesto silently ages. The
+ * rule scans only prose, never fenced snippets, so version pins inside
+ * code blocks survive untouched. Its prompt hands implicit time-bound
+ * claims with no keyword to the AI oracle.
+ */
+class Stale {
+  constructor() {
+    this.id = 'stale';
+  }
+  prompt() {
+    return `${this.id}: flag any implicit time-bound or version-bound claim that carries no keyword, and propose a durable rule that never rots`;
+  }
+  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 found = [];
+    const regex = new RegExp(
+      '\\b(?:currently|now|today|recently|lately|at present|as of|' +
+      'the latest)\\b|\\bv?\\d+\\.\\d+(?:\\.\\d+)?\\b',
+      'giu'
+    );
+    const masked = mask(text);
+    let hit = regex.exec(masked);
+    while (hit !== null) {
+      found.push(new Violation(
+        this.id,
+        'warning',
+        `volatile reference "${hit[0]}" will rot, state a durable rule`,
+        new Region(uri, line, hit.index + 1)
+      ));
+      hit = regex.exec(masked);
+    }
+    return found;
+  }
+}
+
+module.exports = Stale;