@yegor256/dogent 0.10.0 → 0.12.0

package/src/rules/hedging.js

@@ -22,6 +22,9 @@ class Hedging {
   constructor() {
     this.id = 'hedging';
   }
+  hint() {
+    return 'Remove hedging words such as should, just, or usually and state the order firmly, since timid wording weakens the command.';
+  }
   prompt() {
     return `${this.id}: flag soft, non-committal, or hedging wording, including conditional escape hatches and vague scope that carry no fixed hedge word`;
   }

package/src/rules/hidden-char.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');
+
+/**
+ * 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;
+  }
+  hint() {
+    return 'Delete the invisible or control character named by its codepoint, since hidden characters can corrupt parsing or smuggle instructions.';
+  }
+  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,85 @@
+/*
+ * 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;
+  }
+  hint() {
+    return 'Replace the mixed-script look-alike character with its plain ASCII equivalent, since a foreign codepoint hidden inside a word breaks tooling.';
+  }
+  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,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');
+
+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';
+  }
+  hint() {
+    return 'Wrap a bare literal token, such as a command, path, filename, or flag, in backticks so the model treats it as a literal and never rewords it.';
+  }
+  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.
@@ -66,6 +76,9 @@ class Jargon {
   constructor() {
     this.id = 'jargon';
   }
+  hint() {
+    return 'Expand each acronym on first use with a parenthetical gloss, and replace rare domain jargon with plain words a fresh reader can parse.';
+  }
   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`;
   }

package/src/rules/line-length.js

@@ -22,6 +22,9 @@ class LineLength {
     this.id = 'line-length';
     this.max = max;
   }
+  hint() {
+    return 'Shorten the line below the width cap, splitting it into separate instructions if needed so each stays easy to read.';
+  }
   prompt() {
     return '';
   }

package/src/rules/meta-reference.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');
+
+/**
+ * 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;
+  }
+  hint() {
+    return 'Delete self-referential framing such as as an AI or this prompt, since it narrates the setup instead of issuing a command.';
+  }
+  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;

package/src/rules/name-format.js

@@ -23,6 +23,9 @@ class NameFormat {
   constructor() {
     this.id = 'name-format';
   }
+  hint() {
+    return 'Write the SKILL.md frontmatter name in kebab-case, using only lowercase letters and digits joined by single hyphens.';
+  }
   prompt() {
     return '';
   }

package/src/rules/name-matches-dir.js

@@ -24,6 +24,9 @@ class NameMatchesDir {
   constructor() {
     this.id = 'name-matches-dir';
   }
+  hint() {
+    return 'Rename the SKILL.md frontmatter name so it matches the name of the directory that holds the file.';
+  }
   prompt() {
     return '';
   }

package/src/rules/no-articles.js

@@ -19,6 +19,9 @@ class NoArticles {
   constructor() {
     this.id = 'no-articles';
   }
+  hint() {
+    return 'Remove filler articles such as a, an, and the, since they add noise without changing the instruction.';
+  }
   prompt() {
     return `${this.id}: flag filler or noise words that add nothing to an instruction`;
   }

package/src/rules/ordered.js

@@ -24,6 +24,9 @@ class Ordered {
   constructor() {
     this.id = 'ordered';
   }
+  hint() {
+    return 'Convert a sequence of steps into a numbered list, since models follow numbered ordered steps far more reliably than unordered bullets.';
+  }
   prompt() {
     return `${this.id}: flag an implied sequence that no marker word signals, demanding a numbered list whenever the order of steps matters`;
   }

package/src/rules/passive.js

@@ -21,6 +21,9 @@ class Passive {
   constructor() {
     this.id = 'passive';
   }
+  hint() {
+    return 'Rewrite the line in active imperative voice, naming the action to take instead of describing what gets done.';
+  }
   prompt() {
     return `${this.id}: flag any instruction written in passive voice, judging true grammatical voice including irregular past participles a fixed pattern misses`;
   }

package/src/rules/persona.js

@@ -24,6 +24,9 @@ class Persona {
   constructor() {
     this.id = 'persona';
   }
+  hint() {
+    return 'Delete the role-play persona such as You are a senior engineer, since assigning a role adds no instruction and can hurt performance.';
+  }
   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`;
   }

package/src/rules/placement.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');
+
+/**
+ * Placement.
+ *
+ * Transformers attend most to the start and the end of their input and
+ * skim the middle, so a critical section buried in the middle third of a
+ * manifesto sits exactly where the model is least likely to use it. This
+ * standalone check spots a critical section by a heading keyword (Safety,
+ * Security, Mission, Critical, Constraints) and warns when it lands in
+ * the middle third rather than near the top or bottom. The generic word
+ * "Rules" is left out on purpose: it names a neutral section in many
+ * manifestos and would misfire. Its prompt hands the deeper judgement to
+ * the AI oracle, which weighs which instruction matters most and whether
+ * it is well placed.
+ */
+class Placement {
+  constructor() {
+    this.id = 'placement';
+    this.keyword = /^#{1,6}\s+.*\b(?:safety|security|mission|critical|constraints?)\b/iu;
+  }
+  hint() {
+    return 'Move the critical section to the top or bottom of the file, since models attend least to the buried middle of a long context.';
+  }
+  prompt() {
+    return `${this.id}: identify the single most important instruction and judge whether it sits near the top or bottom of the file rather than buried in the middle`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    const total = document.text().split('\n').length;
+    return document.walk({
+      header: (text, row) => this.check(text, row, total, uri),
+      prose: () => [],
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  check(text, row, total, uri) {
+    if (!this.keyword.test(text)) {
+      return [];
+    }
+    const ratio = row / total;
+    if (ratio <= 1 / 3 || ratio >= 2 / 3) {
+      return [];
+    }
+    const name = text.replace(/^#+\s*/u, '').trim();
+    return [new Violation(
+      this.id,
+      'warning',
+      `critical section "${name}" is buried, move it to the top or bottom`,
+      new Region(uri, row, 1)
+    )];
+  }
+}
+
+module.exports = Placement;

package/src/rules/polite.js

@@ -24,6 +24,9 @@ class Polite {
   constructor() {
     this.id = 'polite';
   }
+  hint() {
+    return 'Remove courtesy and scaffolding phrases such as please or make sure to, since they waste tokens and weaken the command.';
+  }
   prompt() {
     return '';
   }

package/src/rules/positive.js

@@ -25,6 +25,9 @@ class Positive {
   constructor() {
     this.id = 'positive';
   }
+  hint() {
+    return 'Rewrite a prohibition as a positive imperative stating what to do, since a ban forces the model to process the forbidden idea first.';
+  }
   prompt() {
     return `${this.id}: flag any instruction phrased as a prohibition, including bans carrying no fixed keyword, and rewrite each as a positive imperative`;
   }

package/src/rules/pseudo-heading.js

@@ -25,6 +25,9 @@ class PseudoHeading {
   constructor() {
     this.id = 'pseudo-heading';
   }
+  hint() {
+    return 'Replace a bold line posing as a heading with a real level-2 heading marked by two hashes.';
+  }
   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`;
   }

package/src/rules/punctuation.js

@@ -19,6 +19,9 @@ class Punctuation {
   constructor() {
     this.id = 'punctuation';
   }
+  hint() {
+    return 'Write each instruction as one complete sentence that opens with a capital letter and closes with a period.';
+  }
   prompt() {
     return `${this.id}: flag any instruction that is not one complete, grammatical sentence`;
   }

package/src/rules/quantifier.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');
+
+/**
+ * Quantifier.
+ *
+ * Flags vague quantity words that leave the count to the agent: "some",
+ * "several", "a few", "many", "multiple", and the like. Models track
+ * exact quantifiers well yet diverge from human intent on vague ones,
+ * whose meaning is an underspecified distribution rather than a number,
+ * so a command manifesto should state the exact count or threshold. The
+ * list is kept apart from the vague qualifiers so the two rules never
+ * double-report. Its prompt hands implicit vagueness, where no listed
+ * word appears, to the AI oracle.
+ */
+class Quantifier {
+  constructor() {
+    this.id = 'quantifier';
+  }
+  hint() {
+    return 'Replace a vague quantity word such as some or several with an exact number or threshold the agent can act on.';
+  }
+  prompt() {
+    return `${this.id}: flag a vague amount that names no exact count even without a listed word, and propose a concrete number or threshold to replace 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 found = [];
+    const regex = new RegExp(
+      '\\b(?:some|several|a few|a couple|many|multiple|various|' +
+      'numerous|a lot of|plenty of)\\b',
+      'giu'
+    );
+    const masked = mask(text);
+    let hit = regex.exec(masked);
+    while (hit !== null) {
+      found.push(new Violation(
+        this.id,
+        'warning',
+        `vague quantity "${hit[0]}", state an exact number or threshold`,
+        new Region(uri, line, hit.index + 1)
+      ));
+      hit = regex.exec(masked);
+    }
+    return found;
+  }
+}
+
+module.exports = Quantifier;

package/src/rules/rationale.js

@@ -23,6 +23,9 @@ class Rationale {
   constructor() {
     this.id = 'rationale';
   }
+  hint() {
+    return 'Delete the explanation or convert it into a direct order, since a manifesto carries commands, not justifications.';
+  }
   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`;
   }

package/src/rules/redundant.js

@@ -54,6 +54,9 @@ class Redundant {
     this.id = 'redundant';
     this.phrases = phrases;
   }
+  hint() {
+    return 'Delete the line that restates default model behavior, since generic advice the model already knows wastes the context budget.';
+  }
   prompt() {
     return `${this.id}: flag any line that restates default agent behavior already known to the model, not a project-specific instruction, including reworded paraphrases that match no fixed phrase list`;
   }