@yegor256/dogent 0.10.0 → 0.11.0

package/src/rules/duplicate-section.js

@@ -0,0 +1,65 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+const bare = (text) => text.replace(/^#{1,6}\s*/u, '').trim();
+
+const normalize = (text) => bare(text).toLowerCase().replace(/\s+/gu, ' ');
+
+/**
+ * DuplicateSection.
+ *
+ * Rejects two headings that carry the same name, so each section owns
+ * a distinct title. It collects every heading in order, normalizes it
+ * by case and whitespace, then flags the second and any later twin
+ * while leaving the first occurrence clean. Distinct from unique,
+ * which targets repeated prose instructions, and from short-sections,
+ * which targets heading length; this one targets repeated heading
+ * names. Its prompt stays empty since the check is fully
+ * deterministic.
+ */
+class DuplicateSection {
+  constructor() {
+    this.id = 'duplicate-section';
+  }
+  prompt() {
+    return '';
+  }
+  violations(document) {
+    const uri = document.uri();
+    const headers = document.walk({
+      header: (text, row) => [{text, row}],
+      prose: () => [],
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+    return this.repeats(uri, headers);
+  }
+  repeats(uri, headers) {
+    const seen = new Set();
+    const found = [];
+    headers.forEach((header) => {
+      const norm = normalize(header.text);
+      if (seen.has(norm)) {
+        found.push(new Violation(
+          this.id,
+          'warning',
+          `duplicate section "${bare(header.text)}", give each section a distinct name`,
+          new Region(uri, header.row, 1)
+        ));
+      } else {
+        seen.add(norm);
+      }
+    });
+    return found;
+  }
+}
+
+module.exports = DuplicateSection;

package/src/rules/emoji.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');
+
+/**
+ * Emoji.
+ *
+ * Flags any emoji or decorative pictographic symbol that adds token
+ * noise without instruction. Inline code is masked first, so a fenced
+ * or inline example may keep a needed glyph. Distinct from homoglyph,
+ * which targets letters borrowed from other scripts; this one stays to
+ * pictographs, symbols, and dingbats only and never flags a foreign
+ * letter.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
+ */
+class Emoji {
+  constructor() {
+    this.id = 'emoji';
+    this.glyph = /[\p{Extended_Pictographic}\u{2190}-\u{21FF}\u{2300}-\u{27BF}\u{2B00}-\u{2BFF}]/gu;
+  }
+  prompt() {
+    return '';
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: (text, line) => this.scan(text, line, uri),
+      prose: (text, line) => this.scan(text, line, uri),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  scan(text, line, uri) {
+    const masked = mask(text);
+    const result = [];
+    let hit = this.glyph.exec(masked);
+    while (hit !== null) {
+      result.push(new Violation(
+        this.id,
+        'warning',
+        `decorative character "${hit[0]}" adds token noise, use plain text`,
+        new Region(uri, line, hit.index + 1)
+      ));
+      hit = this.glyph.exec(masked);
+    }
+    return result;
+  }
+}
+
+module.exports = Emoji;

package/src/rules/example-format.js

@@ -0,0 +1,32 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+/**
+ * Example format.
+ *
+ * A few-shot demonstration regulates the shape of the output more
+ * strongly than any prose, so an example that disagrees with the
+ * declared format teaches the agent the wrong shape. This rule ties the
+ * `example` and `format` rules together by checking their consistency:
+ * when one SKILL.md both shows an example and declares an output format,
+ * the two must agree. The mismatch hides between two distant fragments,
+ * so this check is pure judgement: prompt() hands the comparison to the
+ * AI oracle and violations() finds nothing on its own.
+ */
+class ExampleFormat {
+  constructor() {
+    this.id = 'example-format';
+  }
+  prompt() {
+    return `${this.id}: in a SKILL.md that both shows an example and declares an output format, judge whether the example conforms to the declared format and flag any mismatch`;
+  }
+  violations() {
+    return [];
+  }
+}
+
+module.exports = ExampleFormat;

package/src/rules/external-link.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');
+
+/**
+ * ExternalLink.
+ *
+ * Flags a bare http(s):// URL sitting in prose or a bullet item, where
+ * the page behind it may rot or inject hidden instructions. Durable
+ * guidance belongs inlined, not fetched at run time. A URL inside
+ * inline code or a fenced snippet is exempt, since those are examples.
+ * Distinct from dead-import, which targets local @path imports; this
+ * one complements untrusted and stale.
+ */
+class ExternalLink {
+  constructor() {
+    this.id = 'external-link';
+  }
+  prompt() {
+    return `${this.id}: judge whether an external link is load-bearing, and flag durable guidance that should be inlined instead`;
+  }
+  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 = /(?:https?:\/\/)\S+/giu;
+    const masked = mask(text);
+    let hit = regex.exec(masked);
+    while (hit !== null) {
+      found.push(new Violation(
+        this.id,
+        'warning',
+        'external URL may rot or inject, encode durable guidance instead',
+        new Region(uri, line, hit.index + 1)
+      ));
+      hit = regex.exec(masked);
+    }
+    return found;
+  }
+}
+
+module.exports = ExternalLink;

package/src/rules/fence-language.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');
+
+/**
+ * FenceLanguage.
+ *
+ * Demands that every fenced code block declare a language right after
+ * its opening fence. A bare fence of backticks or tildes with no info
+ * string leaves readers and tooling guessing at the snippet's syntax,
+ * so it earns a warning. A fence that names a language stays clean.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
+ */
+class FenceLanguage {
+  constructor() {
+    this.id = 'fence-language';
+    this.fence = /^\s*(?:```|~~~)\s*(?<lang>\S*)/u;
+  }
+  prompt() {
+    return '';
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: () => [],
+      prose: () => [],
+      snippet: (content, row) => this.scan(content, row, uri),
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  scan(content, row, uri) {
+    const [first] = content.split('\n');
+    const hit = this.fence.exec(first);
+    if (hit !== null && hit.groups.lang !== '') {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      'fenced block has no language tag, declare one',
+      new Region(uri, row, 1)
+    )];
+  }
+}
+
+module.exports = FenceLanguage;

package/src/rules/hidden-char.js

@@ -0,0 +1,61 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * HiddenChar.
+ *
+ * Demands that every line carry only visible characters, rejecting any
+ * invisible or control codepoint that hides inside the text. Scans every
+ * fragment, including snippets, because a zero-width space, a bidirectional
+ * override, or a variation selector tucked into code is just as dangerous as
+ * one tucked into prose. Flags zero-width characters, bidi controls, and
+ * variation selectors, naming each by its hex codepoint so it can be deleted.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
+ */
+class HiddenChar {
+  constructor() {
+    this.id = 'hidden-char';
+    this.hidden = /[\u200B-\u200D\uFEFF\u202A-\u202E\u2066-\u2069\uFE00-\uFE0F\u{E0100}-\u{E01EF}]/gu;
+  }
+  prompt() {
+    return '';
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: (text, line) => this.scan(text, line, uri),
+      prose: (text, line) => this.scan(text, line, uri),
+      snippet: (text, line) => this.scan(text, line, uri),
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  scan(text, line, uri) {
+    const found = [];
+    this.hidden.lastIndex = 0;
+    let hit = this.hidden.exec(text);
+    while (hit !== null) {
+      const hex = hit[0].codePointAt(0).toString(16).toUpperCase();
+      const code = hex.padStart(4, '0');
+      found.push(new Violation(
+        this.id,
+        'error',
+        `invisible character U+${code} found, delete it`,
+        new Region(uri, line, hit.index + 1)
+      ));
+      hit = this.hidden.exec(text);
+    }
+    return found;
+  }
+}
+
+module.exports = HiddenChar;

package/src/rules/homoglyph.js

@@ -0,0 +1,82 @@
+/*
+ * 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');
+
+/**
+ * Homoglyph.
+ *
+ * Rejects mixed-script look-alike characters that masquerade as plain
+ * ASCII. A token mixing an ASCII Latin letter with a confusable from
+ * Cyrillic, Greek, or full-width Latin reads as one word yet hides a
+ * foreign codepoint, so it slips past humans while breaking tools. The
+ * check flags every such confusable character at its own column. Inline
+ * code is masked first, so a deliberately quoted example stays clean.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
+ */
+class Homoglyph {
+  constructor() {
+    this.id = 'homoglyph';
+    this.latin = /[A-Za-z]/u;
+    this.confusable = /[Ѐ-ӿͰ-Ͽ＀-￯]/u;
+  }
+  prompt() {
+    return '';
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: (text, line) => this.scan(text, line, uri),
+      prose: (text, line) => this.scan(text, line, uri),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  scan(text, line, uri) {
+    const clean = mask(text);
+    const result = [];
+    const token = /\S+/gu;
+    let match = token.exec(clean);
+    while (match !== null) {
+      const [word] = match;
+      if (this.latin.test(word) && this.confusable.test(word)) {
+        this.flag(word, match.index).forEach((spot) => {
+          result.push(new Violation(
+            this.id,
+            'error',
+            `mixed-script character "${spot.char}" (U+${spot.point}) found, use plain ASCII`,
+            new Region(uri, line, spot.column)
+          ));
+        });
+      }
+      match = token.exec(clean);
+    }
+    return result;
+  }
+  flag(word, start) {
+    const spots = [];
+    [...word].forEach((char, offset) => {
+      if (!this.confusable.test(char)) {
+        return;
+      }
+      const point = char
+        .codePointAt(0)
+        .toString(16)
+        .toUpperCase()
+        .padStart(4, '0');
+      spots.push({char, point, column: start + offset + 1});
+    });
+    return spots;
+  }
+}
+
+module.exports = Homoglyph;

package/src/rules/index.js

@@ -49,6 +49,26 @@ const ToolClarity = require('./tool-clarity');
 const CounterExample = require('./counter-example');
 const Rationale = require('./rationale');
 const SelfContained = require('./self-contained');
+const Quantifier = require('./quantifier');
+const WeakVerb = require('./weak-verb');
+const Default = require('./default');
+const MetaReference = require('./meta-reference');
+const AmbiguousOr = require('./ambiguous-or');
+const ExternalLink = require('./external-link');
+const Conditional = require('./conditional');
+const Transition = require('./transition');
+const Placement = require('./placement');
+const InlineCode = require('./inline-code');
+const Emoji = require('./emoji');
+const Homoglyph = require('./homoglyph');
+const DuplicateSection = require('./duplicate-section');
+const DescriptionVoice = require('./description-voice');
+const ExampleFormat = require('./example-format');
+const DescriptionLength = require('./description-length');
+const Scope = require('./scope');
+const HiddenChar = require('./hidden-char');
+const Units = require('./units');
+const FenceLanguage = require('./fence-language');
 
 module.exports = () => [
   new Grouped(),
@@ -92,6 +112,26 @@ module.exports = () => [
   new CounterExample(),
   new Rationale(),
   new SelfContained(),
+  new Quantifier(),
+  new WeakVerb(),
+  new Default(),
+  new MetaReference(),
+  new AmbiguousOr(),
+  new ExternalLink(),
+  new Conditional(),
+  new Transition(),
+  new Placement(),
+  new InlineCode(),
+  new Emoji(),
+  new Homoglyph(),
+  new DuplicateSection(),
+  new DescriptionVoice(),
+  new ExampleFormat(),
+  new DescriptionLength(),
+  new Scope(),
+  new HiddenChar(),
+  new Units(),
+  new FenceLanguage(),
   new Unique(),
   new Frontmatter(
     'SKILL.md',

package/src/rules/inline-code.js

@@ -0,0 +1,79 @@
+/*
+ * 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 PATTERNS = [
+  /\b(?:npm|npx|node|git|eslint|mocha|yarn|pnpm|cd|rm|mkdir|chmod|cat|sed|grep|curl|docker)\s+[\w./-]+/gu,
+  /(?<![\w/.@])[\w-]+(?:\/[\w.-]+)+/gu,
+  /(?<![\w/.@])[\w-]+\.(?:js|ts|jsx|tsx|json|md|ya?ml|sh|py|rb|go|rs|toml|cfg|lock|txt|xml|html|css)\b/gu,
+  /(?<![\w-])(?:--[A-Za-z][\w-]*|-[A-Za-z])(?![\w])/gu
+];
+
+/**
+ * InlineCode.
+ *
+ * When a command, path, filename, or flag sits bare in prose, the model
+ * cannot cleanly tell the literal token from the surrounding words and
+ * may reword or reformat it. Markdown inline code marks such a token as
+ * literal, and consistent code-versus-prose marking measurably lowers
+ * misinterpretation. This standalone check flags a bare literal — a
+ * slashed path, a filename carrying a known extension, a CLI flag, or a
+ * known shell command followed by an argument — once its inline-code
+ * spans are masked away, so an already-backticked literal passes. It
+ * leaves @-imports to the dead-import rule. Its prompt hands borderline
+ * literals to the AI oracle.
+ */
+class InlineCode {
+  constructor() {
+    this.id = 'inline-code';
+  }
+  prompt() {
+    return `${this.id}: flag a bare literal token (command, path, filename, or flag) that should be wrapped in backticks, judging borderline cases`;
+  }
+  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 spans = [];
+    PATTERNS.forEach((pattern) => {
+      let hit = pattern.exec(masked);
+      while (hit !== null) {
+        spans.push({token: hit[0], from: hit.index, to: hit.index + hit[0].length});
+        hit = pattern.exec(masked);
+      }
+    });
+    return InlineCode.prune(spans).map((span) => new Violation(
+      this.id,
+      'warning',
+      `literal "${span.token}" must be wrapped in backticks`,
+      new Region(uri, line, span.from + 1)
+    ));
+  }
+  static prune(spans) {
+    const ordered = spans.slice().sort((one, two) => one.from - two.from || two.to - one.to);
+    const kept = [];
+    ordered.forEach((span) => {
+      if (!kept.some((other) => span.from >= other.from && span.to <= other.to)) {
+        kept.push(span);
+      }
+    });
+    return kept;
+  }
+}
+
+module.exports = InlineCode;

package/src/rules/jargon.js

@@ -37,12 +37,20 @@ const ALLOWLIST = new Set([
   'CLAUDE'
 ]);
 
+const initials = (gloss) => (gloss.match(/[A-Za-z]+/gu) || [])
+  .map((word) => word[0].toUpperCase())
+  .join('');
+
 const defined = (masked) => {
   const found = new Set();
-  const regex = /\b(?<acronym>[A-Z]{2,})\s*\(/gu;
+  const regex = /\b(?<acronym>[A-Z]{2,})\s*\(|\((?<gloss>[^)]+)\)/gu;
   let hit = regex.exec(masked);
   while (hit !== null) {
-    found.add(hit.groups.acronym);
+    if (hit.groups.acronym) {
+      found.add(hit.groups.acronym);
+    } else {
+      found.add(initials(hit.groups.gloss));
+    }
     hit = regex.exec(masked);
   }
   return found;
@@ -56,8 +64,10 @@ const undefining = (acronym, scope) => !scope.known.has(acronym) &&
  *
  * 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
+ * a parenthetical gloss, as in "RBAC (role-based access control)", or when
+ * a parenthetical's word initials spell it, as in "AAA pattern
+ * (Arrange-Act-Assert)", 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.

package/src/rules/meta-reference.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');
+
+/**
+ * MetaReference.
+ *
+ * Flags self-referential framing of the model or the document, such as
+ * "as an AI", "you are a model", "this prompt", or "these instructions".
+ * Such framing narrates the setup instead of issuing a command, so it
+ * adds no instruction and earns deletion. Distinct from persona, which
+ * targets role assignment like "Act as a reviewer"; this one targets
+ * the model talking about itself or the document talking about itself.
+ */
+class MetaReference {
+  constructor() {
+    this.id = 'meta-reference';
+    this.phrase = /\b(?:as an ai|as a language model|you are an ai|you are a model|this prompt|these instructions|this manifesto|the system prompt)\b/giu;
+  }
+  prompt() {
+    return `${this.id}: flag self-referential framing of the model or document beyond the fixed list, and 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 masked = mask(text);
+    const out = [];
+    let hit = this.phrase.exec(masked);
+    while (hit !== null) {
+      out.push(new Violation(
+        this.id,
+        'warning',
+        `meta self-reference "${hit[0]}" issues no command, delete it`,
+        new Region(uri, line, hit.index + 1)
+      ));
+      hit = this.phrase.exec(masked);
+    }
+    return out;
+  }
+}
+
+module.exports = MetaReference;