@yegor256/dogent 0.10.0 → 0.12.0

package/src/rules/conditional.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');
+
+/**
+ * Conditional.
+ *
+ * Demands that branching never collapse onto one line. A line carrying
+ * more than one condition keyword (if, unless, when, else, otherwise)
+ * spells out a whole branch tree at once, so each case must split into
+ * its own command. Distinct from simple, which weighs clause depth, and
+ * from atomic, which counts instructions; this one targets branching
+ * alone. A lone guard keeps just one keyword and stays clean.
+ */
+class Conditional {
+  constructor() {
+    this.id = 'conditional';
+  }
+  hint() {
+    return 'Break a line that packs several conditions into one case per line, so the agent never has to untangle a whole decision tree welded onto a single line.';
+  }
+  prompt() {
+    return `${this.id}: flag implicit branching that carries no keyword, and split each case into its own command`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: () => [],
+      prose: (text, line) => this.judge(text, line, uri),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  judge(text, line, uri) {
+    const clean = mask(text);
+    const hits = clean.match(/\b(?:if|unless|when|else|otherwise)\b/giu);
+    if (hits === null || hits.length < 2) {
+      return [];
+    }
+    const column = clean.search(/\b(?:if|unless|when|else|otherwise)\b/iu);
+    return [new Violation(
+      this.id,
+      'warning',
+      'multi-branch conditional, split each case into its own command',
+      new Region(uri, line, column + 1)
+    )];
+  }
+}
+
+module.exports = Conditional;

package/src/rules/consistent.js

@@ -19,8 +19,11 @@ class Consistent {
   constructor() {
     this.id = 'consistent';
   }
+  hint() {
+    return 'Delete the duplicate instruction or reconcile the contradictory pair, so each instruction is stated once and never both ordered and forbidden across two lines.';
+  }
   prompt() {
-    return `${this.id}: flag an instruction that repeats another instruction word for word, or that directly contradicts another instruction in the same file`;
+    return `${this.id}: flag an instruction that repeats another instruction word for word, or that logically contradicts another instruction about the very same subject, where one line orders exactly what another forbids; ignore lines that merely share a theme but govern different concerns, since complementary instructions never clash`;
   }
   violations() {
     return [];

package/src/rules/counter-example.js

@@ -25,6 +25,9 @@ class CounterExample {
   constructor() {
     this.id = 'counter-example';
   }
+  hint() {
+    return 'Remove the demonstration of the wrong form and show only the correct form, since displaying a mistake can teach the agent to repeat it.';
+  }
   prompt() {
     return `${this.id}: judge whether each example shows the correct behavior, and flag any example that demonstrates the incorrect form`;
   }

package/src/rules/crowded.js

@@ -25,6 +25,9 @@ class Crowded {
     this.id = 'crowded';
     this.limit = limit;
   }
+  hint() {
+    return 'Split an overcrowded section into smaller sections, each holding only a handful of related instructions under its own short heading.';
+  }
   prompt() {
     return '';
   }

package/src/rules/dead-import.js

@@ -57,6 +57,9 @@ class DeadImport {
     this.id = 'dead-import';
     this.depth = 5;
   }
+  hint() {
+    return 'Fix or remove the @path import so it points to a real file, and break any circular or overly deep import chain the host tool cannot resolve.';
+  }
   prompt() {
     return `${this.id}: flag any @path/to/file import that points to no file on disk`;
   }

package/src/rules/default.js

@@ -0,0 +1,63 @@
+/*
+ * 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');
+
+/**
+ * Default.
+ *
+ * Demands that optional behavior names its default. A line marking work
+ * as optional through "optionally", "you may", or "feel free to" leaves
+ * the agent guessing what happens when it declines, so the line must
+ * state a default. A line that already declares one through "by
+ * default", "defaults to", or "otherwise" passes untouched. Its prompt
+ * hands subtler optionality with no stated default to the AI oracle.
+ */
+class Default {
+  constructor() {
+    this.id = 'default';
+  }
+  hint() {
+    return 'State the default outcome whenever you mark behavior optional, telling the agent exactly what to do when it declines the option.';
+  }
+  prompt() {
+    return `${this.id}: flag optionality that names no default even without a listed marker, and state the default`;
+  }
+  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);
+    if ((/\b(?:by default|default to|defaults to|otherwise)\b/iu).test(masked)) {
+      return [];
+    }
+    const found = [];
+    const regex = /\b(?:optionally|you may|you can|if you want|feel free to|as an option)\b/giu;
+    let hit = regex.exec(masked);
+    while (hit !== null) {
+      found.push(new Violation(
+        this.id,
+        'warning',
+        `optional behavior "${hit[0]}" has no default, state it`,
+        new Region(uri, line, hit.index + 1)
+      ));
+      hit = regex.exec(masked);
+    }
+    return found;
+  }
+}
+
+module.exports = Default;

package/src/rules/description-length.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');
+
+/**
+ * DescriptionLength.
+ *
+ * Demands that a SKILL.md description stay within a sane size. The
+ * loader keeps every description in context, so an overgrown one wastes
+ * the budget that the instructions need. Flags a value longer than the
+ * ceiling and a value that is empty, leaving the wording itself to
+ * sibling rules.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
+ */
+class DescriptionLength {
+  constructor() {
+    this.id = 'description-length';
+    this.ceiling = 1024;
+  }
+  hint() {
+    return 'Write a SKILL.md description that is neither empty nor bloated, stating the capability concisely so it fits the loader budget.';
+  }
+  prompt() {
+    return '';
+  }
+  violations(document) {
+    const uri = document.uri();
+    if (uri.replace(/^.*\//u, '') !== 'SKILL.md') {
+      return [];
+    }
+    const pairs = document.walk({
+      header: () => [],
+      prose: () => [],
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: (keys) => keys
+    });
+    const found = pairs.filter((pair) => pair.key === 'description');
+    if (found.length === 0) {
+      return [];
+    }
+    return this.judge(found[0], uri);
+  }
+  judge(pair, uri) {
+    const {value} = pair;
+    if (value.trim() === '') {
+      return [this.flag('description is empty, write a concise capability statement', pair.row, uri)];
+    }
+    if (value.length > this.ceiling) {
+      return [this.flag(`description is ${value.length} chars, keep it under ${this.ceiling}`, pair.row, uri)];
+    }
+    return [];
+  }
+  flag(message, row, uri) {
+    return new Violation(this.id, 'warning', message, new Region(uri, row, 1));
+  }
+}
+
+module.exports = DescriptionLength;

package/src/rules/description-triggers.js

@@ -22,6 +22,9 @@ class DescriptionTriggers {
     this.id = 'description-triggers';
     this.minimum = 20;
   }
+  hint() {
+    return 'Name the concrete situations and user phrases that should activate the skill in its description, so the loader knows exactly when to invoke it.';
+  }
   prompt() {
     return `${this.id}: in a SKILL.md, flag a description that is too short or fails to name the concrete situations and user phrases that should activate the skill, even when it contains the word "when"`;
   }

package/src/rules/description-voice.js

@@ -0,0 +1,70 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * DescriptionVoice.
+ *
+ * Demands that a SKILL.md description stay in the third person, reading
+ * as a capability statement like "Extracts tables ..." rather than a
+ * first- or second-person sentence like "I extract ..." or "You can
+ * use ...". A standalone checker flags first- and second-person
+ * pronouns as whole words, after dropping the trigger clause that opens
+ * with "Use when" so a legitimate "Use when ..." phrase stays clean.
+ * Distinct from description-triggers, which checks that a "when" clause
+ * exists, and from description-length, which checks the size; this one
+ * checks the grammatical voice. Its prompt hands subtler voice
+ * judgement to the AI oracle.
+ */
+class DescriptionVoice {
+  constructor() {
+    this.id = 'description-voice';
+    this.pronoun = /\b(?:I|we|you|your|my|our)\b/giu;
+  }
+  hint() {
+    return 'Write the SKILL.md description as a third-person capability statement such as Extracts tables, never in first or second person.';
+  }
+  prompt() {
+    return `${this.id}: in a SKILL.md, flag a description written in first or second person and demand a third-person capability statement`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    if (uri.replace(/^.*\//u, '') !== 'SKILL.md') {
+      return [];
+    }
+    const pairs = document.walk({
+      header: () => [],
+      prose: () => [],
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: (keys) => keys
+    });
+    const found = pairs.filter((pair) => pair.key === 'description');
+    if (found.length === 0) {
+      return [];
+    }
+    return this.judge(found[0], uri);
+  }
+  judge(pair, uri) {
+    const text = pair.value.replace(/use when.*$/isu, '');
+    this.pronoun.lastIndex = 0;
+    const hit = this.pronoun.exec(text);
+    if (hit === null) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      `description must be third person, not "${hit[0]}"`,
+      new Region(uri, pair.row, 1)
+    )];
+  }
+}
+
+module.exports = DescriptionVoice;

package/src/rules/done.js

@@ -21,6 +21,9 @@ class Done {
   constructor() {
     this.id = 'done';
   }
+  hint() {
+    return 'Add a verifiable, pass-or-fail completion check to the SKILL.md so the agent knows exactly how to confirm the work is finished.';
+  }
   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`;
   }

package/src/rules/duplicate-section.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');
+
+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';
+  }
+  hint() {
+    return 'Give every section a distinct heading, merging or renaming any two sections that share the same name.';
+  }
+  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,63 @@
+/*
+ * 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;
+  }
+  hint() {
+    return 'Delete decorative emoji and pictographic symbols, since they add token noise without carrying any instruction, and keep the text plain.';
+  }
+  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/emphasis.js

@@ -25,6 +25,9 @@ class Emphasis {
     this.id = 'emphasis';
     this.shout = new Set(['IMPORTANT', 'ALWAYS', 'NEVER', 'MUST', 'CRITICAL', 'REQUIRED']);
   }
+  hint() {
+    return 'Drop shouting such as all-caps words or repeated exclamation marks and state the instruction plainly, since volume adds no meaning for the model.';
+  }
   prompt() {
     return `${this.id}: flag emphatic shouting the patterns miss, including borderline all-caps and reward framing, since emphasis adds no instruction`;
   }

package/src/rules/empty.js

@@ -23,6 +23,9 @@ class Empty {
   constructor() {
     this.id = 'empty';
   }
+  hint() {
+    return 'Fill the hollow section with at least one instruction, or delete the heading, so no section declares itself without a body.';
+  }
   prompt() {
     return '';
   }

package/src/rules/example-format.js

@@ -0,0 +1,35 @@
+/*
+ * 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';
+  }
+  hint() {
+    return 'Make the example in the SKILL.md conform exactly to the declared output format, since a mismatched example teaches the agent the wrong shape.';
+  }
+  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/example.js

@@ -24,6 +24,9 @@ class Example {
   constructor() {
     this.id = 'example';
   }
+  hint() {
+    return 'Add at least one concrete worked input and output example to the SKILL.md, since a single demonstration guides the agent far better than prose alone.';
+  }
   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`;
   }

package/src/rules/external-link.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');
+
+/**
+ * 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';
+  }
+  hint() {
+    return 'Inline the durable guidance instead of linking to an external URL, since the page may rot or smuggle hidden instructions at run time.';
+  }
+  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,58 @@
+/*
+ * 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;
+  }
+  hint() {
+    return 'Declare a language right after the opening fence of every code block so readers and tooling know the snippet syntax.';
+  }
+  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/format.js

@@ -26,6 +26,9 @@ class Format {
   constructor() {
     this.id = 'format';
   }
+  hint() {
+    return 'Declare and show the exact output format whenever the skill generates output, since a pinned-down contract makes structured output far more reliable.';
+  }
   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`;
   }

package/src/rules/frontmatter.js

@@ -22,6 +22,9 @@ class Frontmatter {
     this.required = required;
     this.allowed = allowed;
   }
+  hint() {
+    return 'Open the file with a YAML frontmatter block that declares every required key with a real value and carries no key outside the allowed set.';
+  }
   prompt() {
     return `${this.id}: in a ${this.name} file, flag any required key whose value is empty, vague, or a leftover placeholder`;
   }

package/src/rules/grouped.js

@@ -21,6 +21,9 @@ class Grouped {
   constructor() {
     this.id = 'grouped';
   }
+  hint() {
+    return 'Move every loose instruction under a section heading, since prose before the first heading belongs to no section.';
+  }
   prompt() {
     return '';
   }